Claude Code Workflow 实战指南：让 AI 军团为你写代码

为什么需要 CCW？

我们先聊聊痛点。传统的 AI 编程助手（比如 Copilot）本质上是 “单兵作战”：你问一个问题，它给一个答案。但真实的软件开发是什么样的？

• 架构设计 需要系统思维
• 代码实现 需要工程能力
• 测试验证 需要质量意识
• Bug 修复 需要调试经验

一个 AI 很难同时扮演这么多角色。CCW 的解决方案是：让不同的 AI 模型扮演不同的角色，协同完成任务。

第一章. 快速开始

1.1. 安装与验证

打开终端，一行命令搞定：

1
2

npm install -g claude-code-workflow
ccw install -m Global

验证安装：

1
2

ccw --version
# 输出：v6.3.33

看到版本号就成功了。

1.2. CLI 工具选装（可选）

CCW 支持调用多种 AI 模型。这些工具是 可选的，你可以根据需要安装：

1.3. 5 分钟上手

我们用一个真实场景快速体验 CCW。

场景：用户反馈 “登录按钮点了没反应”，你怀疑是事件绑定问题。

指令：

1

/workflow:lite-fix "登录按钮点击无响应"

产出：

1. AI 自动分析相关代码
2. 生成诊断报告（5 个阶段）
3. 提供修复方案
4. 自动执行修复

价值：

• 自动诊断根因
• 无需手动查日志
• 修复后自动运行测试

第二章. 主干工作流：5 个层级

2.1. 层级速查表

CCW 提供 5 个层级工作流，按需选择，能用低级不用高级，不确定时从 Level 2 开始。

2.2. Level 1：即时执行 (lite-lite-lite)

最快工作流，零产物，秒级响应。

场景 1：修改配置文件
指令：/workflow:lite-lite-lite "将 API 超时时间改为 60 秒"

1
2
3
4
5
6

> Executing...
> Modifying config/app.yaml... Done (0.8s)

- timeout: 30
+ timeout: 60

场景 2：批量重命名
指令：/workflow:lite-lite-lite "将所有 user_id 重命名为 userId"

1
2
3
4

> Scanning files... Found 12 occurrences.
> Applying changes to 4 files... Done.
> No intermediate plan generated. Direct execution.

2.3. Level 2：轻量规划

2.3.1. lite-plan（明确需求）
场景：添加用户头像功能
指令：/workflow:lite-plan "在用户资料页添加头像上传功能"

1
2
3
4
5
6
7
8
9

> Generating Plan (in-memory)...
1. Modify UserSchema to add avatarUrl.
2. Create API endpoint POST /user/avatar.
3. Update UserProfile.vue UI.

> Executing code generation...
> Created: src/components/AvatarUpload.vue
> Updated: src/backend/user_routes.js

场景：实现 API 接口（带探索）
指令：/workflow:lite-plan -e "实现获取用户订单列表 API"

1
2
3
4

> Analyzing codebase structure...
> Context found: existing OrderService and DB schema.
> Generating implementation based on existing patterns...

2.3.2. lite-fix（Bug 修复）
场景：登录超时问题
指令：/workflow:lite-fix "用户登录时经常超时"

1
2
3
4
5
6
7
8
9
10

> Phase 1: Diagnosis
  [v] Network latency check... OK
  [!] DB Connection Pool... Full (Root Cause Identified)

> Phase 3: Fix Plan
  - Increase max_connections in db_config.
  - Implement connection timeout retry logic.

> Phase 5: Applying Fix... Done.

2.3.3. multi-cli-plan（多视角分析）
场景：技术选型 (OAuth vs JWT)
指令：/workflow:multi-cli-plan "比较 OAuth 和 JWT"

1
2
3
4
5
6

> Convening Agents: Gemini, Claude, Codex...
[Gemini] Argues for OAuth2 (Security standard).
[Claude] Points out JWT simplicity for this scale.
> Synthesis: Use JWT for internal APIs, OAuth2 for external integrations.
> Output: decision_matrix.md Generated.

2.4. Level 3：标准规划

2.4.1. plan（多模块开发）
场景：支付网关集成
指令：/workflow:plan "集成支付宝和微信支付"

1
2
3
4
5
6
7
8
9
10
11

> Session Created: WFS-payment-001 (Persisted)
> Context Collected: 14 files related to Order module.

> Generated Task List (IMPL_PLAN.md):
  [ ] Task 1: Create generic PaymentStrategy interface
  [ ] Task 2: Implement AlipayServiceAdapter
  [ ] Task 3: Implement WeChatPayServiceAdapter
  [ ] Task 4: Update CheckoutController

> Ready for /workflow:execute

2.4.2. tdd-plan（测试驱动）
场景：用户注册功能 (TDD)
指令：/workflow:tdd-plan "实现用户注册"

1
2
3
4
5
6
7

> Session: TDD-auth-002
> Cycle Started:
  1. [RED] Created test_user_register.py (Test Fails)
  2. [GREEN] Implemented User.register() (Test Passes)
  3. [REFACTOR] Extracted password hashing logic.
> Coverage Check: 100%. Task Complete.

2.4.3. test-fix-gen（测试修复）
场景：修复集成测试失败
指令：/workflow:test-fix-gen "修复测试失败"

1
2
3
4
5
6
7
8
9
10

> Parsing test report... 3 failures found.
> Cycle 1:
  - Analyzing failure logs...
  - Attempting fix on OrderService.java...
  - Re-running tests...
> Result: 1 failure remaining.
> Cycle 2:
  - Refining fix...
> Result: All tests passed.

2.5. Level 4：头脑风暴 (brainstorm)

场景：设计实时协作系统
指令：/workflow:brainstorm:auto-parallel "设计协作系统" --count 5

1
2
3
4
5
6
7
8

> Initializing 5 Roles: Architect, Frontend Lead, Security Expert, DB Admin, Product Owner.
> Phase: Parallel Analysis
  [Architect] Drafting WebSocket state synchronization...
  [DB Admin] Designing CRDT data structure...
  [Security] Evaluating WSS encryption...
> Phase: Synthesis
  > Merging 5 perspectives into: synthesis-specification.md

2.6. Level 5：智能编排 (ccw-coordinator)

场景：不知道用什么命令
指令：/ccw-coordinator "实现 OAuth2 认证"

1
2
3
4
5
6
7
8
9
10
11
12

> Analyzing Request...
  - Complexity: High
  - Type: New Feature/Security
  
> Recommended Workflow Chain:
  1. brainstorm (Design Architecture)
  2. plan (Break down tasks)
  3. execute (Implement)
  4. test-fix-gen (Verify)

> Auto-executing Step 1: Brainstorming...

2.7. 本章小结

第三章. 核心概念

3.1. 最小执行单元

很多人问：“为什么我执行了 /workflow:plan，但没有生成代码？”

答案是：plan 只负责规划，你还需要执行 /workflow:execute。

什么是最小执行单元：

一组必须一起执行的原子命令组合，分割后会破坏逻辑流程。

为什么需要最小单元：

• 防止不完整状态（只规划不执行）
• 保证用户体验（获得完整结果）
• 保持工作流完整性

所有最小单元速查：

3.2. 命令端口系统

把命令想象成 “乐高积木”，每个积木有 “凸起”（输出端口）和 “凹槽”（输入端口）。只有端口匹配的积木才能拼接在一起。

端口定义示例：

任务类型到端口流映射：

管道可视化：

1
2

需求 → 【lite-plan → lite-execute】→ 代码 → 【test-fix-gen → test-cycle-execute】→ 测试通过
       └──── Quick Implementation ────┘         └────── Test Validation ──────┘

3.3. Session 与状态持久化

什么是 Session：

一个持久化的开发任务，包含完整的上下文和进度。

Session 文件结构：

1
2
3
4
5
6
7
8
9

.workflow/active/WFS-payment-001/
├── workflow-session.json      # Session 元数据
├── IMPL_PLAN.md               # 实现计划
├── TODO_LIST.md               # 任务清单
├── .task/
│   ├── IMPL-001.json          # 任务 1
│   └── IMPL-002.json          # 任务 2
└── .process/
    └── context-package.json   # 上下文包

中断恢复：

1
2
3
4
5

# 查看所有 Session
ls .workflow/active/

# 恢复 Session
/workflow:session resume WFS-payment-001

价值：

• 跨天任务可恢复
• 完整上下文保留
• 进度追踪清晰

3.4. 依赖分析与并行执行

为什么主干工作流不需要 Worktree：

CCW 通过 依赖分析 解决并行问题：

1. 规划阶段执行依赖分析
2. 自动识别任务依赖和关键路径
3. 划分 并行组（独立任务）和 串行链（依赖任务）
4. Agent 并行执行独立任务，无需文件系统隔离

依赖分析流程：

1
2
3
4
5
6
7
8
9
10
11
12
13

┌─────────────────────────────────────────────────┐
│         Dependency Analysis (依赖分析)           │
│                                                 │
│  Task A ─────┐                                  │
│              ├──→ Parallel Group 1 ──→ Agent 1  │
│  Task B ─────┘                                  │
│                                                 │
│  Task C ────────→ Serial Chain ──────→ Agent 2  │
│       ↓                                         │
│  Task D ────────→                               │
│                                                 │
│  同一 worktree，通过调度实现并行                   │
└─────────────────────────────────────────────────┘

价值：

• 无需 Worktree 复杂性
• 自动并行优化
• 降低冲突风险

第四章. 代码审查与优化

4.1. 基础审查

场景 19：审查当前代码

需求：审查刚写完的代码，看看有没有问题。

指令：

1

/workflow:review

产出：审查报告（代码规范、潜在 Bug、性能问题）。

价值：只审查不修改，适合先看报告。

场景 20：审查并修复

需求：审查代码并自动修复问题。

指令：

1

/workflow:review-fix

产出：审查 + 自动修复。

价值：一步到位。

4.2. 专项审查

场景 21：安全审查

需求：检查代码中的安全漏洞。

指令：

1

/workflow:review --type security

产出：安全漏洞报告（SQL 注入、XSS、CSRF 等）。

价值：专注安全问题。

场景 22：性能审查

需求：检查代码性能瓶颈。

指令：

1

/workflow:review --type performance

产出：性能优化建议（N+1 查询、内存泄漏等）。

价值：专注性能问题。

4.3. Session 审查

场景 23：审查整个 Session

需求：审查整个开发 Session 的代码质量。

指令：

1
2

/workflow:review-session-cycle
/workflow:review-fix

产出：完整审查循环（多维度审查 + 修复）。

价值：覆盖整个 Session 的所有改动。

第五章. 调试与冲突解决

5.1. 调试模式

场景 24：程序报错

需求：程序抛出 NullPointerException，不知道原因。

指令：

1

/workflow:debug "用户登录时抛出 NullPointerException"

产出：

• 错误堆栈分析
• 根因定位
• 修复建议

价值：自动分析堆栈，无需手动查日志。

场景 25：特定文件调试

需求：怀疑 login.js 有问题，需要聚焦调试。

指令：

1

/workflow:debug-with-file src/auth/login.js

产出：聚焦文件的调试分析。

价值：精准定位，节省时间。

5.2. 冲突解决

场景 26：Git 合并冲突

需求：合并分支时出现大面积冲突。

指令：

1

/workflow:tools:conflict-resolution

产出：语义化冲突解决方案。

价值：根据上下文判断该保留哪部分代码。

第六章. 项目记忆与文档

6.1. 更新记忆

场景 27：提交前更新记忆

需求：刚完成一个功能，需要让 AI 记住这次改动。

指令：

1

/memory:update-related

产出：更新最近修改的文件记忆。

价值：

• 高频使用
• 只更新相关文件，速度快
• 让 AI 越用越懂你的代码

场景 28：全量重建记忆

需求：新项目初始化，或者记忆损坏需要重建。

指令：

1

/memory:update-full

产出：扫描整个项目，重建记忆。

价值：完整重建，适合新项目或记忆损坏。

6.2. 生成文档

场景 29：生成项目文档

需求：项目要交付，需要一份用户手册。

指令：

1

/memory:docs

产出：自动生成项目文档（Markdown/HTML/Docsify）。

价值：

• 自动提取代码注释
• 自动提取函数签名
• 支持多种格式

场景 30：生成 API 文档

需求：为 RESTful API 生成 Swagger 文档。

指令：

1

/memory:swagger-docs

产出：Swagger API 文档。

价值：自动提取 API 路由和参数。

6.3. 技能包

场景 31：加载技能包

需求：需要 AI 学会微信小程序开发规范。

指令：

1

/memory:load-skill-memory

产出：加载预设的技能包。

价值：领域知识注入，AI 理解特定领域规范。

常见技能包：

第七章. 高级特性

7.1. 语义化 CLI 调用

CCW 支持用自然语言指定 AI 模型，系统自动调用对应的 CLI。

单 CLI 调用：

多 CLI 协同：

自定义 CLI 注册：

通过 Dashboard 注册任意 API 为自定义 CLI：

1

ccw view  # 打开 Dashboard → Status → API Settings → 添加自定义 CLI

注册一次，永久语义调用。

7.2. Dashboard 可视化

启动 Dashboard：

1

ccw view

浏览器自动打开 http://127.0.0.1:3456/。

核心功能：

7.3. ACE Tool 配置

ACE (Augment Context Engine) 提供语义代码搜索能力。

配置方式：

前往 ACE Relay 获取 Token 后，在控制台配置 ACE MCP

第八章. 本笔记总结

8.1. 场景速查表

8.2. 命令速查表

主干工作流：

执行与验证：

审查与调试：

记忆与文档：

8.3. 决策树

如何选择工作流：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

开始
  │
  ├─ 是 Bug 修复？
  │     ├─ 是 → lite-fix
  │     └─ 否 ↓
  │
  ├─ 需求是否明确？
  │     ├─ 不明确 → brainstorm:auto-parallel
  │     └─ 明确 ↓
  │
  ├─ 是否需要持久化 Session？
  │     ├─ 是 → plan / tdd-plan
  │     └─ 否 ↓
  │
  ├─ 是否需要多视角分析？
  │     ├─ 是 → multi-cli-plan
  │     └─ 否 ↓
  │
  ├─ 是否需要规划？
  │     ├─ 是 → lite-plan
  │     └─ 否 → lite-lite-lite
  │
  └─ 不知道用什么命令？
        └─ ccw-coordinator

8.4. 下一步学习

本笔记覆盖了 CCW 的主干工作流和日常开发场景。

进阶内容（第二篇笔记）：

• Issue 工作流完整实战
• Level 5 智能编排深度解析
• 多 CLI 协同原理
• 生产环境最佳实践

推荐阅读顺序：

1. ✅ 本笔记：主干工作流 + 日常场景
2. 📖 第二篇：Issue 工作流 + 高级特性
3. 📖 第三篇：命令速查 + 最佳实践