跳到主要内容

常见问题（FAQ）

关于 CCW、工作流、命令与排错的常见问题汇总。

通用问题​

CCW 是什么？​

CCW（Claude Code Workflows）是一套面向工程实践的工作流自动化平台：将 AI 能力与结构化开发流程结合，提供 40+ 命令与 15 个集成工作流，帮助你更快、更稳地完成开发，同时保持质量标准。

核心特性：

  • AI 驱动的代码分析 / 生成 / Review
  • 15 个工作流级别：从快速执行到智能编排
  • Session 管理：完整状态持久化，可暂停/恢复
  • 多 Agent 并行协作：支持并行任务与依赖分析
  • 内置测试、验证与代码审查

系统要求是什么？​

最低要求：

  • Node.js 16.x 或更高
  • Git 2.x 或更高
  • 可用内存 4GB
  • 磁盘空间 500MB

推荐配置：

  • Node.js 18.x LTS
  • 可用内存 8GB
  • 磁盘空间 2GB（用于 artifacts 与 sessions）

如何安装 CCW？​

# npm 全局安装
npm install -g @ccw/cli

# 或使用 npx（无需安装）
npx @ccw/cli init

# 在项目中初始化
ccw init

CCW 是否免费？​

是的，CCW 开源且免费使用。但 CCW 会集成第三方 AI 服务（Gemini、Codex、Claude、Qwen 等），这些服务可能有各自的计费方式。你需要为所使用的 AI 服务配置对应的 API Key。

支持哪些编程语言？​

CCW 支持所有编程语言。AI 模型可以分析与生成任意语言代码，例如：

  • Web：JavaScript、TypeScript、Python、PHP、Ruby
  • Mobile：Swift、Kotlin、React Native、Flutter
  • Systems：Rust、Go、C、C++
  • Data：Python、R、SQL
  • Enterprise：Java、C#、.NET

工作流选择​

如何选择合适的工作流？​

Details
决策框架

可以用下面这棵“快速决策树”：

  1. 是开发后期维护（合并后修复/增强）？ → 使用 Issue Workflow
  2. 不确定该用哪些命令？ → 用 ccw-coordinator（Level 5）
  3. 需求不清晰/要探索方案？ → 用 brainstorm:auto-parallel（Level 4）
  4. 需要可恢复的持久 session？
    • 标准开发 → plan → execute（Level 3）
    • TDD → tdd-plan → execute（Level 3）
    • 修复测试 → test-fix-gen → test-cycle-execute（Level 3）
  5. 需要多视角对比分析？ → 用 multi-cli-plan（Level 2）
  6. 要修 Bug？ → 用 lite-fix（Level 2）
  7. 需要简单规划？ → 用 lite-plan → lite-execute（Level 2）
  8. 只是很快的小任务？ → 用 lite-lite-lite（Level 1）

Main Workflow 与 Issue Workflow 有什么区别？​

Details
对比说明

Main Workflow 用于主开发流程：

  • 功能开发（Levels 1-5）
  • 处于活跃开发阶段
  • 基于依赖的并行
  • 在当前分支工作

Issue Workflow 用于开发后期维护：

  • 合并后的 bug 修复与增强
  • 主工作流完成之后
  • 可选 worktree 隔离
  • 保持主分支稳定
维度Main WorkflowIssue Workflow
目的功能开发开发后修复
时机开发阶段主工作流完成之后
范围完整功能实现定点修复/增强
并行策略依赖分析worktree 隔离（可选）
分支模型当前分支开发可使用隔离 worktree

什么是“最小执行单元”（Minimum Execution Units）？​

Details
解释

最小执行单元 指的是必须作为一个原子组一起执行的一组命令，用来达成“有意义的里程碑”。如果把这些命令拆开执行，逻辑链条会被打断，容易产生不完整状态。

常见最小执行单元：

单元命令目的
快速实现lite-plan → lite-execute轻量规划 + 执行
多 CLI 规划multi-cli-plan → lite-execute多视角分析 + 执行
Bug 修复lite-fix → lite-execute诊断 + 修复执行
可验证规划plan → plan-verify → execute规划 + 验证 + 执行
TDD 规划tdd-plan → execute测试驱动的规划与执行
测试修复循环test-fix-gen → test-cycle-execute生成测试任务 + 执行修复循环

示例：lite-plan → lite-execute 必须配套完成。如果只做到 lite-plan 就停下，会得到一个计划但没有实现。

各个工作流级别分别适用于什么场景？​

Details
级别选择指南

Level 1（lite-lite-lite）：

  • 快速修补（拼写、轻微调整）
  • 简单功能（单函数、小工具）
  • 配置修改（环境变量、超时）
  • 文档更新

Level 2（lite-plan、lite-fix、multi-cli-plan）：

  • 单模块功能
  • Bug 诊断与修复
  • 技术选型决策
  • 方案对比

Level 3（plan、tdd-plan、test-fix-gen）：

  • 多模块变更
  • 重构
  • TDD
  • 测试失败修复

Level 4（brainstorm:auto-parallel）：

  • 新功能设计
  • 系统架构重构
  • 探索性需求
  • 多维权衡

Level 5（ccw-coordinator）：

  • 复杂多步工作流
  • 不确定使用哪些命令
  • 端到端自动化
  • 团队协作

Issue Workflow：

  • 开发后期的 Issue 修复
  • 维护主分支稳定性

命令使用​

工作流命令怎么用？​

Details
常见命令模式

基本格式：

ccw <command> <arguments>

示例：

# Level 1 - 直接执行
ccw lite-lite-lite "Fix login button"

# Level 2 - 轻量规划
ccw lite-plan "Add user profile page"
ccw lite-execute --in-memory

# Level 3 - 完整工作流
ccw workflow:plan "Implement OAuth2"
ccw workflow:execute --session WFS-oauth-auth

# Level 4 - 头脑风暴
ccw brainstorm:auto-parallel "Design notification system"

# Level 5 - 智能编排
ccw ccw-coordinator "Refactor API layer"

lite-execute 与 execute 有什么区别？​

Details
对比

lite-execute（Level 2）：

ccw lite-execute --in-memory
  • 面向 Level 2 工作流
  • 内存规划（不生成 session 文件）
  • 可对独立任务并行执行
  • 可选代码审查

execute（Level 3）：

ccw workflow:execute --session WFS-{session-id}
  • 面向 Level 3 工作流
  • 基于 session 的执行
  • 依赖分析
  • 完整状态跟踪，可暂停/恢复
  • 任务完成总结

如何使用 hotfix 模式？​

Details
Hotfix 用法

Hotfix 模式 用于生产环境紧急修复：

ccw lite-fix --hotfix "Production database connection failing"

它会做什么：

  • 跳过大多数诊断阶段
  • 最小化规划（更偏向直接执行）
  • 自动生成后续任务，用于完整修复与复盘（post-mortem）

何时使用：

  • 生产事故
  • 需要立刻修复的严重 bug
  • 宕机与服务中断

修复之后： CCW 会自动生成后续任务，包括：

  • 完整根因分析
  • 全面修复
  • 复盘文档

如何恢复（resume）一个暂停的 session？​

Details
Session 恢复
# 恢复最近的 session
ccw workflow:session:resume

# 恢复指定 session
ccw workflow:session:resume WFS-user-auth-v2

# 列出全部 session
ccw workflow:session:list

Session 状态：

  • active：正在运行
  • paused：暂停，可恢复
  • completed：已完成并归档

AI 模型​

CCW 支持哪些 AI 模型？​

Details
支持的模型

CCW 通过 CLI 端点支持多个模型：

模型能力最适合
GeminiAnalysis + WriteCode review、调试、重构
CodexAnalysis + Write + ReviewGit-aware review、实现
ClaudeAnalysis + Write复杂推理、文档
QwenAnalysis + Write代码生成、模式匹配

可在 ~/.claude/cli-tools.json 中配置模型端点。

如何配置 API Key？​

Details
API Key 配置

使用环境变量：

# Gemini
export GEMINI_API_KEY="your-key-here"

# OpenAI (Codex)
export OPENAI_API_KEY="your-key-here"

# Anthropic (Claude)
export ANTHROPIC_API_KEY="your-key-here"

# Qwen
export DASHSCOPE_API_KEY="your-key-here"

或在 .env 文件中配置：

GEMINI_API_KEY=your-key-here
OPENAI_API_KEY=your-key-here
ANTHROPIC_API_KEY=your-key-here
DASHSCOPE_API_KEY=your-key-here

什么是 multi-CLI 协作？​

Details
multi-CLI 说明

multi-CLI 协作 会让多个 AI 模型从不同视角并行分析同一个问题：

ccw multi-cli-plan "Compare Redis vs RabbitMQ for message queuing"

工作方式：

  1. 多个模型独立分析
  2. 各自给出洞察与建议
  3. 汇总为更完整的分析结论
  4. 在决策前获得更多视角

适用场景：

  • 技术选型
  • 架构决策
  • 方案对比
  • 权衡分析

测试​

如何为存量代码补充测试？​

Details
生成测试

Session 模式（基于已有 session）：

ccw test-fix-gen WFS-user-auth-v2

Prompt 模式（直接描述需求）：

ccw test-fix-gen "Add unit tests for the auth API"

CCW 会：

  1. 分析代码结构
  2. 生成合适的测试用例
  3. 按项目模式创建测试文件
  4. 编写断言并实现测试

如何修复失败的测试？​

Details
测试修复流程
# 生成测试修复任务
ccw test-fix-gen "Tests failing for user registration"

# 执行 test-fix 循环
ccw test-cycle-execute

流程：

  1. 分析测试失败原因
  2. 定位根因
  3. 迭代修复
  4. 验证通过率 >= 95%
  5. 通过则停止，否则在达到最大迭代次数后停止

什么是 TDD（测试驱动开发）？​

Details
TDD 说明

TDD 遵循“Red-Green-Refactor”循环：

  1. Red：先写一个失败的测试
  2. Green：写最少的代码让测试通过
  3. Refactor：在保持测试通过的前提下改进代码

铁律：

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

为什么要先写测试？

维度Test-FirstTest-After
证据先失败再实现（能证明实现有效）立即通过（证明不了什么）
发现编码前发现边界条件编码后才发现边界条件
验证验证需求验证实现

故障排查​

我的工作流失败了，该怎么办？​

Details
排查步骤
  1. 查看报错信息 - 识别根因线索
  2. 检查 session 状态 - 查看 .workflow/.ccw-coordinator/{session}/state.json
  3. 恢复 session - 使用 ccw workflow:session:resume 继续
  4. 调整后重试 - 根据错误调整方案

常见修复：

  • API key 错误：确认环境变量已设置
  • Module not found：运行 npm install 或 pip install
  • Git 错误：确保 git 状态干净（git status）
  • 超时错误：在任务 JSON 中增加超时时间

如何跳过一个失败的任务？​

Details
跳过任务

编辑任务 JSON，把 status 设置为 "completed"：

jq '.status = "completed"' .workflow/active/WFS-{session}/.task/IMPL-001.json

谨慎使用：跳过任务可能导致工作流处于不完整状态。

如何清理旧的 sessions？​

Details
清理命令
# 列出 sessions
ccw workflow:session:list

# 删除指定 session
rm -rf .workflow/active/WFS-{session-id}

# 清理所有已完成 sessions
ccw workflow:clean

自动清理：

  • 已完成 sessions 会归档到 .workflow/completed/
  • 旧 sessions（> 30 天）通常可安全删除

为什么我的工作流很慢？​

Details
性能建议

可能原因：

  1. 代码库很大：CCW 会分析整个项目

    • 建议：使用 --focus-paths 限制分析范围

  2. 依赖很多：AI 响应慢

    • 建议：用更快的模型（如 Gemini Flash）先做初步分析

  3. 任务串行：在等依赖任务完成

    • 建议：在 plan-verify 中检查依赖关系

  4. 网络问题：访问 AI 服务的 API 慢

    • 建议：检查网络与服务状态

优化示例：

# 限制分析范围
ccw plan "Add login" --focus-paths src/auth

# 先用更快的模型
ccw cli -p "Quick analysis" --model gemini-2.0-flash --mode analysis

# 尽量并行
ccw workflow:execute --parallel 4

如何调试工作流问题？​

Details
调试工作流

开启 debug 日志：

DEBUG=ccw:* ccw workflow:plan "My feature"

查看 session 日志：

# 查看 session 状态
cat .workflow/active/WFS-{session}/workflow-session.json

# 查看任务进度
cat .workflow/active/WFS-{session}/TODO_LIST.md

使用 debug 工作流：

ccw workflow:debug-with-file "Debug memory leak in connection handler"

该工作流会以“假设驱动”的方式调试，并把探索过程文档化。

集成​

CCW 能否集成到现有的 CI/CD？​

Details
CI/CD 集成

可以。CCW 可用于 CI/CD 流程，例如：

GitHub Actions 示例：

- name: Run CCW Workflow
  run: |
    ccw workflow:plan "Implement feature"
    ccw workflow:execute --session WFS-feature
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

最佳实践：

  • 在 CI 中用 --mode analysis 做代码审查
  • API key 存放在 secrets 管理中
  • 在隔离环境中运行工作流
  • 归档 sessions 便于审计追踪

CCW 支持 monorepo 吗？​

Details
Monorepo 支持

支持。

面向 workspace 的执行：

# 在指定 package 中执行
ccw plan "Add auth to frontend" --cd packages/frontend

# 跨多个 package 执行
ccw plan "Update API contracts" --include-dir packages/api,packages/shared

好处：

  • 依赖感知的任务分发
  • 跨包并行执行
  • 共享 session 状态
  • 跨 workspace 协同变更

如何从其他工具迁移？​

Details
迁移指南

从基础 Git 工作流迁移：

# 之前：手工规划
git checkout -b feature
# ... manual planning ...

# 之后：用 CCW 做规划
ccw plan "Add feature"
ccw execute --session WFS-feature

从其他 AI 工具迁移：

  • CCW 提供结构化工作流（而非零散提示）
  • Session 管理（而非依赖聊天记录）
  • 多 Agent 协作（而非单一 AI）
  • 持久化产物（而非一次性输出）

迁移步骤：

  1. 安装 CCW：npm install -g @ccw/cli
  2. 初始化：ccw init
  3. 从 Level 2 工作流开始熟悉
  4. 逐步在更复杂任务中采用更高等级

最佳实践​

工作流最佳实践有哪些？​

Details
最佳实践

1. 先从简单开始

  • 使用能满足需求的最低工作流级别
  • 不要为简单任务过度工程化
  • 随着复杂度增加再升级工作流

2. 先规划再执行

  • 有验证步骤就尽量使用
  • 执行前先 review 生成的计划
  • 根据项目上下文调整任务

3. 持续测试

  • 将测试融入工作流
  • 关键功能使用 TDD
  • 每次迭代后运行测试

4. Review 代码

  • 使用内置 review 工作流
  • 利用 multi-CLI 获得多视角反馈
  • 迭代式合并 review 建议

5. 记录关键决策

  • 复杂决策用 brainstorm 工作流
  • 保留 session artifacts 便于复盘
  • 归档已完成 sessions

6. 维护 session 卫生

  • 结束后及时 complete session
  • 定期清理旧 sessions
  • 归档重要 sessions

如何最大化 AI 辅助收益？​

Details
AI 最佳实践

1. 提示要具体

Bad: "Fix the bug"
Good: "Fix the 500 error when users update their profile picture"

2. 提供上下文

ccw plan "Add OAuth2" \
  --context "Using Express.js, MongoDB, Passport.js" \
  --reference "Similar to existing Google OAuth implementation"

3. 使用 multi-CLI 协作

# 获取多个视角
ccw multi-cli-plan "Architecture decision"

4. 利用 memory

# 基于已有工作继续推进
ccw plan "Continue auth refactor" --memory WFS-auth-v1

5. 选择合适模型

  • Gemini Flash：快，适合初步分析
  • Gemini Pro：深度推理，适合复杂任务
  • Codex：代码 review 与实现（git-aware）
  • Claude：文档与复杂推理

相关文档​

仍有疑问？ 欢迎在 GitHub 提交 Issue 或查看 讨论区。