Claude 子代理规范工作流系统

基于 Claude Code 的子代理功能构建的全面 AI 驱动开发工作流系统。该系统通过协调运作的专用 AI 代理，将项目创意转化为可投入生产的代码。

目录

• 概述
• 系统架构
• 安装
• 快速入门
• 斜杠命令使用方法
• 工作原理
• 代理参考
• 使用示例
• 质量门控
• 最佳实践
• 高级用法
• 故障排除

概述

规范工作流系统利用 Claude Code 的子代理能力，创建了一个多代理开发流水线。每个代理都是专注于软件开发生命周期特定环节的专业专家，从需求分析到最终验证。

核心特性

• 自动化工作流：从创意到生产代码的完整开发流程
• 专业化分工：各代理专注于各自的专业领域
• 质量门控：自动化的检查点确保质量标准
• 灵活集成：可与现有专业代理协同工作
• 全面文档化：每个阶段都会生成详细的产出物

优势

• 从概念到代码的开发速度提升 10 倍
• 通过自动化验证实现一致的质量
• 自动生成全面的文档
• 通过系统化流程减少错误
• 清晰的工作流促进更好的协作

系统架构

graph TD
    A[项目创意] --> B[spec-orchestrator]
    B --> C[规划阶段]
    C --> D[spec-analyst<br/>需求分析]
    D --> E[spec-architect<br/>系统设计]
    E --> F[spec-planner<br/>任务分解]
    
    F --> G{质量门控1}
    G -->|通过| H[开发阶段]
    G -->|未通过| D
    
    H --> I[spec-developer<br/>实现]
    I --> J[spec-tester<br/>测试]
    
    J --> K{质量门控2}
    K -->|通过| L[验证阶段]
    K -->|未通过| I
    
    L --> M[spec-reviewer<br/>代码评审]
    M --> N[spec-validator<br/>最终检查]
    
    N --> O{质量门控3}
    O -->|通过| P[已准备好投入生产]
    O -->|未通过| Q[反馈循环]
    
    style B fill:#1a73e8,color:#fff
    style G fill:#f9ab00,color:#fff
    style K fill:#f9ab00,color:#fff
    style O fill:#f9ab00,color:#fff
    style P fill:#34a853,color:#fff

安装

先决条件

• Claude Code（最新版本）
• 已初始化的项目目录
• 对 AI 辅助开发的基本了解

设置步骤

1. 下载代理

   # 方法一：克隆仓库
   git clone https://github.com/zhsama/claude-sub-agent.git
   cd claude-sub-agent
   
   # 方法二：下载所需的具体代理
   # 单个代理文件可在 agents/ 目录下找到
   

2. 将代理和斜杠命令复制到项目的 Claude Code 目录中

   # 在项目中创建 .claude 目录结构
   mkdir -p .claude/agents .claude/commands
   
   # 复制分类目录下的所有代理
   cp -r agents/*/*.md .claude/agents/
   
   # 复制斜杠命令
   cp commands/agent-workflow.md .claude/commands/
   

3. 在 CLAUDE.md 中添加规则

   ## 项目文档规范（重要）
   
   **文档文件：** 所有新文档或任务文件必须保存在本仓库的 `docs/` 文件夹下。例如：
   
   - **任务与待办事项**：保存在 `docs/{YYYY_MM_DD}/tasks/` 目录中（如 `docs/t2025_08_08/asks/ReleaseTodo.md` 用于发布清单）。
   - **需求/规格说明**：保存在 `docs/{YYYY_MM_DD}/specs/` 目录中（如 `docs/2025_08_08/specs/AuthModuleRequirements.md`）。
   - **设计文档**：保存在 `docs/{YYYY_MM_DD}/design/` 目录中（如 `docs/2025_08_08/design/ArchitectureOverview.md`）。
   - **代码文件：** 遵循项目结构（按照讨论结果将新代码放置在相应的 src/module 文件夹中）。
   - **测试：** 新测试文件应放在 `tests/` 目录下，并与代码结构保持一致。
   
   > **重要提示：** 创建新文件时，请确保目标目录存在，否则请先创建。切勿将这些文件默认保存在根目录下。
   

4. 验证安装

   仓库结构：

   claude-sub-agent/
   ├── agents/
   │   ├── spec-agents/         # 核心工作流代理
   │   │   ├── spec-analyst.md
   │   │   ├── spec-architect.md
   │   │   ├── spec-developer.md
   │   │   ├── spec-orchestrator.md
   │   │   ├── spec-planner.md
   │   │   ├── spec-reviewer.md
   │   │   ├── spec-tester.md
   │   │   └── spec-validator.md
   │   ├── backend/             # 后端专家
   │   │   └── senior-backend-architect.md
   │   ├── frontend/            # 前端专家
   │   │   └── senior-frontend-architect.md
   │   ├── ui-ux/              # 设计专家
   │   │   └── ui-ux-master.md
   │   └── utility/             # 工具类代理
   │       └── refactor-agent.md
   └── commands/
       └── agent-workflow.md    # 斜杠命令
   ├── CLAUDE.md
   

   安装后的项目结构：

   your-project/
   ├── .claude/
   │   ├── commands/
   │   │   └── agent-workflow.md   # 斜杠命令
   │   └── agents/
   │       ├── spec-analyst.md
   │       ├── spec-architect.md
   │       ├── spec-developer.md
   │       ├── spec-orchestrator.md
   │       ├── spec-planner.md
   │       ├── spec-reviewer.md
   │       ├── spec-tester.md
   │       ├── spec-validator.md
   │       ├── senior-backend-architect.md
   │       ├── senior-frontend-architect.md
   │       ├── ui-ux-master.md
   │       └── refactor-agent.md
   ├── CLAUDE.md
   └── ... (您的项目文件)
   

快速入门

基本用法

# 启动新的项目工作流
向 Claude 提问：“使用 spec-orchestrator 代理创建一个待办事项 Web 应用程序”

# Orchestrator 将自动完成以下步骤：
# 1. 分析需求
# 2. 设计架构
# 3. 制定任务计划
# 4. 实现代码
# 5. 编写测试
# 6. 进行评审和验证

简单示例

您：使用 spec-orchestrator 创建一个个人博客平台

Claude（spec-orchestrator）：开始个人博客平台的工作流...

[规划阶段 - 45 分钟]
✓ 需求已分析
✓ 架构已设计
✓ 任务已规划
✓ 质量门控 1：通过（96/100）

[开发阶段 - 2 小时]
✓ 15 项任务已完成
✓ 测试已编写
✓ 质量门控 2：通过（88/100）

[验证阶段 - 30 分钟]
✓ 代码已评审
✓ 最终验证完成
✓ 质量门控 3：通过（91/100）

项目完成！生成的成果包括：
- requirements.md
- architecture.md
- 源代码（15 个文件）
- 测试套件（覆盖率 85%）
- 文档

斜杠命令使用方法

要以最快的方式启动完整的工作流，请使用我们的自定义斜杠命令：

基本用法

/agent-workflow "创建一个带有用户认证和实时更新的任务管理Web应用"

高级用法

# 高质量企业级项目
/agent-workflow "开发具有客户管理和分析功能的CRM系统" --quality=95

# 快速原型开发  
/agent-workflow "简单的个人博客网站" --quality=75 --skip-agent=spec-tester

# 从现有需求出发
/agent-workflow "基于现有需求的移动应用" --skip-agent=spec-analyst

# 仅执行特定阶段
/agent-workflow "微服务架构的电商平台" --phase=planning

命令选项

• --quality=[75-95]: 设置质量门限
• --skip-agent=[agent-name]: 跳过指定代理
• --phase=[planning|development|validation|all]: 执行特定阶段
• --output-dir=[path]: 指定输出目录
• --language=[zh|en]: 文档语言

📖 完整的斜杠命令文档，请参阅 commands/agent-workflow.md

工作原理

1. Claude Code子代理集成

根据Claude Code的文档，子代理的工作方式如下：

• 在隔离的上下文窗口中运行
• 防止污染主对话
• 允许专业、专注的交互
• 根据任务上下文自动选择

我们的系统利用这些特性，为每个开发阶段创建专门的代理。

2. 工作流阶段

规划阶段

1. spec-analyst: 分析需求并创建用户故事
2. spec-architect: 设计系统架构
3. spec-planner: 将工作分解为任务
4. 质量门1: 验证规划完整性

开发阶段

1. spec-developer: 根据任务实现代码
2. spec-tester: 编写全面的测试
3. 质量门2: 验证代码质量

验证阶段

1. spec-reviewer: 检查代码是否符合最佳实践
2. spec-validator: 最终生产就绪检查
3. 质量门3: 确保部署就绪

3. 代理间通信

代理通过结构化产物进行沟通：

• 每个代理生成特定文档
• 下一代理以先前输出为输入
• 协调器管理流程
• 质量门确保一致性

代理参考

代理分类体系

我们的代理按专业类别组织，以便更好地管理和领域专长：

• spec-agents/: 核心工作流协调代理
• backend/: 后端系统专家
• frontend/: 前端开发专家
• ui-ux/: 用户体验与设计专家
• utility/: 通用工具代理

核心工作流代理 (spec-agents/)

代理	目的	输入	输出
spec-orchestrator	工作流协调	项目描述	状态报告、路由
spec-analyst	需求分析	用户描述	requirements.md, user-stories.md
spec-architect	系统设计	需求	architecture.md, api-spec.md
spec-planner	任务规划	架构	tasks.md, test-plan.md
spec-developer	实现	任务	源代码、单元测试
spec-tester	测试	代码	测试套件、覆盖率报告
spec-reviewer	代码审查	代码	审查报告、改进建议
spec-validator	最终验证	所有产物	验证报告、质量评分

按类别划分的专家代理

后端专家 (backend/)

代理	领域	整合点
senior-backend-architect	后端系统与架构	架构/开发阶段

前端专家 (frontend/)

代理	领域	整合点
senior-frontend-architect	前端系统与架构	开发阶段

UI/UX专家 (ui-ux/)

代理	领域	整合点
ui-ux-master	用户体验与界面设计	规划/开发阶段

工具代理 (utility/)

代理	领域	整合点
refactor-agent	代码质量与重构	任何阶段

使用示例

示例1：企业应用

# 高质量的企业系统
使用质量阈值为95的spec-orchestrator：
创建一个企业级CRM系统，具备以下功能：
- 多租户支持
- 基于角色的访问控制
- RESTful API
- 实时仪表盘
- 审计日志

示例2：快速原型

# 低质量阈值的快速原型
使用质量阈值为75且跳过分析师的spec-orchestrator：
创建一个简单的邮件捕获着陆页

示例3：现有需求

# 从现有文档开始
使用从需求开始的spec-orchestrator：
加载./docs/requirements.md中的需求，并继续工作流

示例4：仅执行特定阶段

# 仅对现有代码执行验证
仅使用spec-orchestrator的验证阶段：
验证./my-app/中的项目

质量门

第1道门：规划质量（95%阈值）

• 需求完整性
• 架构可行性
• 任务分解质量
• 用户故事清晰度

第2道门：开发质量（80%阈值）

• 测试覆盖率
• 代码质量指标
• 安全扫描结果
• 性能基准测试

第3道门：生产就绪（85%阈值）

• 整体质量评分
• 文档完整性
• 部署准备情况
• 运营要求

最佳实践

1. 项目准备

• 编写清晰的项目描述
• 包括约束条件和需求
• 明确质量期望
• 提供现有文档

2. 与代理协作

• 让每个代理完成其阶段
• 在各阶段之间审查产物
• 有效利用反馈循环
• 相信质量门的作用

3. 自定义

• 根据需求调整质量阈值
• 对于简单项目可跳过某些代理
• 添加自定义验证标准
• 与现有工作流整合

4. 性能优化

• 对大型项目启用并行执行
• 对迭代开发进行结果缓存
• 使用分阶段执行
• 监控资源使用情况

高级用法

自定义工作流

# 创建自定义工作流配置
workflow_config = {
    "quality_threshold": 90,
    "skip_agents": ["spec-analyst"],  # 如果已有需求
    "parallel": True,
    "custom_validators": ["security-scan", "performance-test"],
    "output_format": "markdown"
}

# 使用自定义配置执行
"使用spec-orchestrator并配置：" + json.dumps(workflow_config)

与CI/CD集成

# GitHub Actions 示例
名称: AI 工作流验证
触发条件: [pull_request]
作业:
  validate:
    运行在: ubuntu-latest
    步骤:
      - 使用: actions/checkout@v3
      - 名称: 运行规范验证
        运行: |
          # 使用 Claude Code CLI（如果可用）
          claude-code run spec-orchestrator \
            --phase validation \
            --project-path .

### 系统扩展

1. **添加新代理**
   - 使用 YAML 前置元数据创建代理
   - 明确职责范围
   - 指定输入输出格式
   - 更新编排器路由逻辑

2. **自定义质量门控**
   - 定义新的评估标准
   - 设置合适的阈值
   - 实现验证逻辑
   - 添加到工作流中

3. **领域特定工作流**
   - 创建专用的编排器
   - 定义领域模式
   - 自定义质量标准
   - 针对特定需求进行优化

## 故障排除

### 常见问题

1. **未找到代理**
   - 确认代理文件位于正确目录
   - 检查 YAML 前置元数据格式
   - 确保文件权限设置正确

2. **质量门控失败**
   - 仔细检查失败的具体标准
   - 核实生成的工件是否完整
   - 允许代理重新修改工作
   - 考虑调整阈值

3. **工作流卡住**
   - 检查编排器状态
   - 查看上一个代理的输出
   - 寻找错误信息
   - 从最近的检查点重新启动

### 调试模式

```bash
# 启用详细日志记录
使用带有调试模式的 spec-orchestrator：
创建测试项目并展示所有代理交互

贡献说明

我们欢迎各位贡献！请：

1. 遵循现有代理格式
2. 提供详尽的文档
3. 包含使用示例
4. 使用编排器进行测试
5. 提交带有说明的拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

致谢

• 基于 Claude Code 的子代理功能构建
• 受 BMAD 方法论启发
• 欢迎社区贡献

---

更多信息请参阅：

• Claude Code 文档
• 子代理指南
• 项目问题

claude-sub-agent 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 核心工具：已安装最新版本的 Claude Code。
• 项目基础：已初始化一个项目目录。
• 知识储备：对 AI 辅助开发流程有基本了解。

注意：本工具依赖 Claude Code 的原生子代理（Sub-Agents）功能，无需额外安装 Python 包或 Node.js 依赖。

安装步骤

1. 获取源码

克隆仓库到本地：

git clone https://github.com/zhsama/claude-sub-agent.git
cd claude-sub-agent

2. 配置项目结构

在项目根目录下创建 .claude 配置目录，并复制代理定义文件和斜杠命令：

# 创建必要的目录结构
mkdir -p .claude/agents .claude/commands

# 复制所有分类下的代理定义文件 (.md)
cp -r agents/*/*.md .claude/agents/

# 复制工作流斜杠命令
cp commands/agent-workflow.md .claude/commands/

3. 配置文档规范 (CLAUDE.md)

在项目根目录的 CLAUDE.md 文件中添加以下规则，以确保生成的文档和代码存放在正确位置：

## Project Documentation Conventions (Important)

**Documentation Files:** All new documentation or task files must be saved under the `docs/` folder in this repository.For example:

- **Tasks & TODOs**: Save in `docs/{YYYY_MM_DD}/tasks/` (e.g., `docs/t2025_08_08/asks/ReleaseTodo.md` for a release checklist).
- **Requirements/Specs**: Save in `docs/{YYYY_MM_DD}/specs/` (e.g., `docs/2025_08_08/specs/AuthModuleRequirements.md`).
- **Design Docs**: Save in `docs/{YYYY_MM_DD}/design/` (e.g., `docs/2025_08_08/design/ArchitectureOverview.md`).
- **Code Files:** Follow the project structure (place new code in the appropriate src/module folder as discussed).
- **Tests:** Put new test files under the `tests/` directory, mirroring the code structure.

> **Important:** When creating a new file, ensure the directory exists or create it. Never default to the root directory for these files.

4. 验证安装

确认您的项目结构如下所示：

your-project/
├── .claude/
│   ├── commands/
│   │   └── agent-workflow.md
│   └── agents/
│       ├── spec-analyst.md
│       ├── spec-architect.md
│       ├── spec-developer.md
│       ├── spec-orchestrator.md
│       ├── spec-planner.md
│       ├── spec-reviewer.md
│       ├── spec-tester.md
│       ├── spec-validator.md
│       └── ... (其他专业代理)
├── CLAUDE.md
└── ... (您的其他项目文件)

基本使用

方式一：使用斜杠命令（推荐）

这是启动完整开发工作流最快捷的方式。直接在 Claude Code 对话框中输入：

/agent-workflow "Create a task management web application with user authentication"

高级用法示例：

• 指定高质量标准（阈值 95）：

  /agent-workflow "Develop a CRM system" --quality=95
  

• 仅运行规划阶段：

  /agent-workflow "Microservices platform" --phase=planning
  

• 跳过特定代理（如跳过测试以快速原型开发）：

  /agent-workflow "Simple blog" --skip-agent=spec-tester
  

方式二：自然语言指令

您也可以直接通过自然语言调用协调器代理：

Use the spec-orchestrator agent to create a personal blog platform

执行流程预览： 一旦启动，系统将自动按顺序执行以下阶段：

1. 规划阶段：需求分析 -> 架构设计 -> 任务拆解 -> 质量门禁 1
2. 开发阶段：代码实现 -> 单元测试 -> 质量门禁 2
3. 验证阶段：代码审查 -> 最终验收 -> 质量门禁 3

完成后，您将得到包含需求文档、架构设计、源代码、测试套件及完整文档的生产级项目。