⚡

Quetrex开发工作流技能Skill quetrex-development-workflow

Quetrex开发工作流技能是一个AI智能体自动化开发框架，专为语音优先的AI控制中心项目设计。该技能提供完整的项目上下文引导、问题驱动开发流程、自动化AI智能体执行、质量门控系统和开发标准规范。关键词：AI智能体开发、自动化工作流、Claude Code、GitHub Actions、语音AI控制中心、开发效率工具、TDD测试驱动开发、项目上下文管理。

DevOps 0 次安装 0 次浏览 更新于 3/2/2026

name: quetrex-development-workflow description: 每个项目卡片都应显示当前月的API成本，并带有小型趋势指示器（向上/向下箭头）。

Quetrex 开发工作流程技能

目的： 为新的Claude Code会话提供完整的Quetrex项目上下文，并支持高效的问题驱动开发。

使用时机：

  • 开始任何新的Claude Code会话处理Quetrex项目时
  • 需要了解待处理工作时
  • 为AI智能体自动化创建问题时
  • 决定下一步工作时

快速参考

关键命令

# 查询待处理问题
gh issue list --label "ai-feature" --state open

# 查询最近完成的工作
gh pr list --state merged --limit 10

# 为AI智能体创建问题
gh issue create --template ai-feature.md --label ai-feature

# 手动触发工作流程
gh workflow run "Quetrex AI Agent Worker" -f issue_number=123

关键文件

文件 用途
CLAUDE.md 项目上下文（每个会话加载）
.quetrex/status.yml 当前路线图位置
docs/PROJECT-CHECKLIST.md 全面任务清单
.github/workflows/ai-agent.yml 智能体自动化工作流程
.claude/scripts/ai-agent-worker.py 智能体执行脚本

1. 什么是Quetrex？

Quetrex 是一个语音优先的AI智能体控制中心 - 用于管理多个AI驱动项目的任务控制仪表板。

核心能力

  • 语音驱动需求收集（OpenAI实时API）
  • 自动规范生成（Claude AI）
  • 带版本控制的规范审批工作流程
  • 通过GitHub Actions自动生成智能体
  • 实时监控和分析
  • 成本跟踪和控制
  • 安全优先架构（3阶段模型）

技术栈

  • 前端： Next.js 15.5, React 19, TypeScript（严格模式）, TailwindCSS, ShadCN UI
  • 后端： Next.js API路由, Drizzle ORM, PostgreSQL
  • AI/语音： Claude Sonnet 4.5, OpenAI实时API, Whisper, TTS
  • 基础设施： Vercel边缘运行时, Docker容器, GitHub Actions

2. 自动化工作原理

触发流程

1. 创建GitHub问题
   └─> 使用"AI功能请求"模板
   └─> 添加"ai-feature"标签

2. GitHub Actions触发
   └─> .github/workflows/ai-agent.yml激活
   └─> 在安全的Docker容器中运行

3. 智能体工作器执行
   └─> 获取问题详情
   └─> 从.quetrex/memory/加载项目上下文
   └─> 构建全面的提示
   └─> 通过Claude Code CLI执行

4. 实施阶段
   └─> 智能体使用专门的子智能体：
       - 协调器（复杂功能）
       - 测试编写器（TDD优先）
       - 实施者（代码）
       - 代码审查员（质量）

5. 质量门
   └─> PreToolUse：阻止危险命令
   └─> PostToolUse：验证每个文件更改
   └─> Stop：不可绕过的最终门
   └─> 测试、覆盖率、代码检查、构建

6. 创建拉取请求
   └─> 推送功能分支
   └─> 带详细描述的PR
   └─> 准备人工审查

每个问题的约束

  • 最大执行时间： 45分钟
  • 最大API调用： 150次
  • 最大文件更改： 75个
  • 测试要求： 可配置（当前为false）

3. 创建有效的问题

问题模板位置

.github/ISSUE_TEMPLATE/ai-feature.md

什么是好的AI智能体问题

应该做：

  • 具体说明需要构建什么
  • 以复选框形式列出验收标准
  • 参考现有文件/模式
  • 指定测试要求
  • 包含优先级级别

不应该做：

  • 模糊（“让它更好”）
  • 组合多个不相关的任务
  • 跳过验收标准
  • 忘记添加ai-feature标签

结构良好的示例问题

## 摘要
在仪表板项目卡片中添加成本跟踪显示

## 描述
每个项目卡片应显示当前月的API成本
并带有小型趋势指示器（向上/向下箭头）。

## 验收标准
- [ ] 以美元格式显示成本（$X.XX）
- [ ] 趋势箭头显示与上周相比的增加/减少
- [ ] 工具提示显示按提供商（OpenAI/Anthropic）的细分
- [ ] 通过React Query每5分钟更新一次

## 技术上下文
**相关文件：**
- `src/components/ProjectCard.tsx` - 添加成本显示
- `src/services/cost-tracker.ts` - 使用现有服务
- `src/hooks/useDashboard.ts` - 添加成本查询

**遵循的模式：**
- 使用仪表板标题中的现有统计显示模式
- 遵循SettingsPanel中的成本格式化

## 测试要求
- [x] 需要单元测试（成本格式化）
- [x] 需要集成测试（API集成）
- [ ] 需要E2E测试
- [ ] 需要视觉回归测试

## 优先级
- [x] P1 - 高（很快需要）

4. 当前项目状态

如何查询实时状态

# 准备由AI智能体处理的开放问题
gh issue list --label "ai-feature" --state open --json number,title,labels

# 最近完成的工作
gh pr list --state merged --limit 5 --json number,title,mergedAt

# 当前分支状态
git status
git log --oneline -5

状态文件位置

.quetrex/status.yml - 维护的快照：

  • 当前阶段
  • 活跃关注领域
  • 完成百分比
  • 最近里程碑

项目清单

docs/PROJECT-CHECKLIST.md - 全面跟踪：

  • 按类别划分的功能完成情况
  • 阻碍和依赖关系
  • 优先级级别
  • 时间估计

5. 架构决策

需要了解的关键ADR

ADR 决策 状态
ADR-001 浏览器原生回声消除 已接受
ADR-002 用于边缘运行时的Drizzle ORM 已接受
ADR-006 Claude Code CLI而非Anthropic SDK 活跃

安全架构（3阶段）

  1. 阶段1（完成）： Docker容器化

    • 只读文件系统，非root用户
    • 资源限制，能力删除

  2. 阶段2（生产中）： 凭据代理

    • 容器环境中无凭据
    • Unix套接字验证，审计日志

  3. 阶段3（2026年第一季度）： gVisor迁移

    • 用户空间内核以实现最大隔离

智能体执行架构

我们使用Claude Code CLI，而不是直接的Anthropic SDK。

原因：

  • 内置专门的智能体（协调器、测试编写器、代码审查员）
  • 质量钩子（PreToolUse、PostToolUse、Stop）
  • 来自Anthropic的自动更新
  • 工具执行无维护负担

参见：.claude/docs/ARCHITECTURE-AGENT-WORKER.md

6. 质量执行

6层防御系统

  1. PreToolUse钩子 - 阻止危险命令
  2. PostToolUse钩子 - 验证每个文件更改
  3. Stop钩子 - 不可绕过的质量门
  4. TypeScript严格模式 - 无any，无@ts-ignore
  5. 测试覆盖率 - 整体75%+，服务90%+
  6. CI/CD - 如果任何检查失败则阻止合并

测试要求

整体：        75%+（强制执行）
src/services/: 90%+（强制执行）
src/utils/:    90%+（强制执行）
组件：        60%+（强制执行）

TDD工作流程（强制）

  1. 编写描述行为的测试
  2. 验证测试失败（红色）
  3. 编写通过的最小代码
  4. 验证测试通过（绿色）
  5. 在保持绿色的同时重构

7. 开发模式

文件组织

src/
├── app/           # Next.js应用路由器页面
├── components/    # React组件
├── services/      # 业务逻辑（90%+覆盖率）
├── hooks/         # 自定义React钩子
├── lib/           # 第三方集成
├── db/            # 数据库模式（Drizzle）
└── schemas/       # Zod验证模式

命名约定

  • 组件：PascalCase.tsx
  • 服务：kebab-case.ts
  • 钩子：useCamelCase.ts
  • 类型：相邻的types.ts或内联

导入顺序

  1. 外部包
  2. 内部组件（@/components/）
  3. 钩子（@/hooks/）
  4. 服务（@/services/）
  5. 类型

8. 常见工作流程

开始新功能

# 1. 检查待处理事项
gh issue list --label "ai-feature" --state open

# 2. 如果没有合适的，创建新问题
gh issue create --template ai-feature.md

# 3. 添加标签以触发自动化
gh issue edit <number> --add-label "ai-feature"

# 4. 或直接从这里处理
# （用于复杂功能或想要更多控制时）

审查AI智能体工作

# 检查最近的PR
gh pr list --author "github-actions[bot]" --state open

# 审查特定PR
gh pr view <number>
gh pr diff <number>

# 如果批准则合并
gh pr merge <number> --squash

调试失败运行

# 列出最近的工作流程运行
gh run list --workflow="ai-agent.yml" --limit 5

# 查看特定运行
gh run view <run-id>

# 下载日志
gh run download <run-id> -n agent-logs-<issue-number>

9. 内存系统

位置：.quetrex/memory/

文件 用途
patterns.md 要遵循的架构模式
project-overview.md 高级项目上下文
PHASE_3_EVOLVER.md 阶段3文档
ARCHITECTURE-INTELLIGENCE-SYSTEM.md 架构智能

状态跟踪：.quetrex/status.yml

每个会话后更新：

  • 当前关注领域
  • 最近完成情况
  • 待处理优先级
  • 阻碍

10. 获取帮助

文档位置

  • 架构： docs/architecture/
  • 功能： docs/features/
  • 路线图： docs/roadmap/
  • ADR： docs/decisions/

关键文档

文档 用途
CLAUDE.md 主要项目上下文
docs/PROJECT-CHECKLIST.md 全面任务列表
docs/AI-AGENT-AUTOMATION-STATUS.md 智能体系统状态
docs/CONTRIBUTING.md 开发标准

会话清单

开始新会话时：

  • [ ] 运行/new-context加载此技能并查询状态
  • [ ] 审查待处理问题（gh issue list --label ai-feature）
  • [ ] 检查最近的PR以了解最近工作的上下文
  • [ ] 决定：为智能体创建问题或直接工作
  • [ ] 遵循TDD：首先编写测试
  • [ ] 对复杂功能使用专门的智能体
  • [ ] 在结束会话前更新.quetrex/status.yml

最后更新：2025-11-26 由Glen Barnhardt在Claude Code的帮助下创建