claude-coding-flow

基于 Claude Code 的 AI 辅助开发工作流，覆盖「需求分析 → 代码生成 → Bug 修复」全链路。

目录

• 简介
• 安装
• 核心概念
• 快速开始
• 三大工作流详解
  • doc-gen：需求分析 → 开发文档
  • code-gen：开发文档 → 代码
  • bug-fix：Bug 溯源与修复
• Dashboard 使用指南
• 目录结构参考
• docs/ 资源配置
• 常见问题

简介

claude-coding-flow 是一套安装到 Claude Code 的 Skill 系统，将开发流程拆解为三个可追溯的工作流：

PRD / UI 设计稿 / API 文档
        ↓  /doc-gen
    开发文档（develop.md）
        ↓  /code-gen
      代码实现
        ↓  /bug-fix
      Bug 修复

每个工作流都会在 .worktree/ 目录下留下完整的任务元数据，并通过 Dashboard 可视化管理全部任务、链路关系和文档差异。

两类 Skill

| 类别 | Skill | 特征 | |------|-------|------| | 核心工作流 | doc-gen / code-gen / bug-fix | 有任务管理（.worktree）、阶段进度、Dashboard 可视化 | | 逆向工具 | code-to-prd / code-to-api | 一次性提取，无任务管理、不进 Dashboard，直接输出到 docs/ |

逆向工具用于从现有代码反推出实现无关的 PRD / API，配合核心工作流形成完整闭环：

                  ┌──────── 正向：从零构建 ────────┐
   docs/prds /    │                                │
   docs/apis  ──→ doc-gen ──→ code-gen ──→ bug-fix │
       ↑          └────────────────────────────────┘
       │
       └─ code-to-prd / code-to-api ←── 现有代码（任意语言）
          逆向提取，可用于跨语言迁移/重写

典型场景：把一个 Java 老项目用 code-to-prd + code-to-api 提取成语言无关的 PRD/API，再走 doc-gen → code-gen 用 Go 重新实现。

安装

前提条件

• Claude Code 已安装
• Node.js ≥ 14
• Python ≥ 3.9（Dashboard 依赖）

步骤

# 1. 在项目根目录安装
npm install claude-coding-flow

# postinstall 会自动执行 flow init，将 skill 文件复制到 .claude/commands/

安装完成后，.claude/commands/ 下会生成三个 skill 文件：

• doc-gen.md
• code-gen.md
• bug-fix.md

安装 Dashboard 依赖

pip install fastapi uvicorn

启动 Dashboard

npx flow dashboard
# 或进入 .dashboard/ 目录手动启动
cd .dashboard && uvicorn main:app --host 0.0.0.0 --port 8000

浏览器访问 http://localhost:8000 查看任务管理界面。

核心概念

Skill 调用方式（两种）

方式一：显式命令

在 Claude Code 对话中输入 /doc-gen、/code-gen、/bug-fix 即可唤起对应工作流，Claude 会全程引导你完成。

方式二：自然语言自动触发（推荐）

直接用日常语言描述意图，Claude 会根据 skill 的描述自动匹配并启动对应工作流，无需记命令：

| 你说 | 自动触发 | |------|---------| | "帮我把这份 PRD 转成开发文档" / "分析一下这个需求" | doc-gen | | "根据这份 develop.md 生成代码" / "实现这个功能" | code-gen | | "这个按钮点了没反应，帮我查一下" / "修一下这个 bug" | bug-fix |

两种方式等价，可混用。命令方式更明确，自然语言方式更顺手。

任务链（Task Chain）

三个工作流之间通过任务 ID 相互关联，形成完整的可溯源链路：

bug-fix 任务
    └── related_task_id → code-gen 任务
            ├── dev_doc_task_id → doc-gen 任务
            │       └── output_doc → develop.md
            └── bug_fix_refs ← [bug-fix 任务 ID 列表]

| 字段 | 所在任务 | 含义 | |------|---------|------| | prev_task_id | 任意 | 同模块上一个迭代任务 | | related_task_id | bug-fix → code-gen | 跨类型关联（溯源用） | | dev_doc_task_id | code-gen → doc-gen | 直接引用生成 develop.md 的 doc-gen 任务 | | output_doc | doc-gen | 产出的 develop.md 文件名 | | bug_fix_refs | code-gen | 关联的 bug-fix 任务 ID 列表（反向引用） |

状态枚举

所有任务和阶段的 status 字段只取以下值：

| 值 | 含义 | |----|------| | pending | 未开始 | | running | 进行中 | | completed | 已完成 | | failed | 失败 |

快速开始

以开发一个「Todo 列表页」为例，走完完整的三段工作流。

第一步：准备资源

在项目根目录创建 docs/ 目录结构：

docs/
  prds/
    todo.md          ← 产品需求文档
  images/
    index.yaml       ← 图片/Figma → 描述（用描述语义匹配需求）
    todo-main.png    ← UI 设计图（或用 Figma URL）
  apis/
    todo-api.md      ← API 接口文档（按标题/描述语义匹配需求）

docs/images/index.yaml 示例（图片/URL → 描述）：

todo-main.png: 待办列表主界面，含输入框、任务列表、筛选标签栏
todo-filter.png: 筛选标签的展开/选中状态
https://www.figma.com/design/xxx: 新增任务弹窗设计稿

API 无需映射文件：doc-gen 直接读取 docs/apis/*.md 的接口标题（如 ## GET /api/todos）和接口描述，与需求章节做语义匹配，自动建立对应关系。

第二步：生成开发文档（doc-gen）

在 Claude Code 中输入 /doc-gen，或直接说「帮我把 todo.md 转成开发文档」让 Claude 自动触发：

/doc-gen

交互压到 1 次提问 + 1 次确认——任务标题自动从 PRD 推导，图片和 API 自动语义匹配到需求（无需选），只需：

1. 一次提问（2 问）：模块（一键选/给 PRD 建议名）+ 需求文档
2. 一次确认：展示「模块 / 自动推导的任务标题 / 全量或增量模式 / 需求文档 + 自动匹配到的图片和 API 清单」，需改可选「需要修改」（可增删匹配到的图片/API）

确认后，Claude 自动分析所有输入，生成 todo-v1-develop.md，内容包括：

• 页面功能概述
• 页面结构分析（组件清单、布局层级）
• 组件交互行为
• 页面状态机
• 数据流分析（接口调用详情）
• 页面事件流
• 开发实现建议
• 缺失交互补全

第三步：生成代码（code-gen）

/code-gen

Claude 会一次性询问（模块名和任务标题自动从文档路径推导，无需手动输入）：

1. 开发文档（未实现的排最前，仅剩一个未实现时直接预选）
2. 代码反思（是否执行深度反思，默认否）
3. 需求补充（可描述额外要求）

Claude 按 6 个阶段推进：需求收集 → 信息加载 → 方案规划 → 代码生成 → 代码反思（可选）→ 交付（含轻量交付自检）。

产出物：

• 实际源码文件
• .worktree/code-gen/.../snapshots/changes.diff（代码快照，用于 bug-fix 溯源）

第四步：修复 Bug（bug-fix）

/bug-fix

交互压到 先描述 + 一键确认起点：

1. 描述 Bug（现象、复现步骤、涉及功能/关键词）
2. Claude 用关键词在所有 code-gen 任务的代码快照/日志里自动预搜，猜出最可能引入该 bug 的任务让你一键确认；命中就省掉手动选模块 + 选任务，未命中则自动转为全局搜索源码
3. 也可选「选其他任务」手动指定，或「直接全局搜索」跳过溯源

完成最小化修复后做轻量自检验证（对照 Bug 现象 + 代码逻辑，不调用编译器；如需编译由用户手动执行）。

三大工作流详解

doc-gen：需求分析 → 开发文档

全量模式

适用于首次生成，或某一需求的全新版本。

输入三类资源：

• 需求文档（必填）：docs/prds/ 下的 .md 文件
• UI 设计（可选）：三种模式——本地 PNG/JPG 图片、HTML UI/UX 文件、Figma 链接，均放在 docs/images/ 下并在 index.yaml 中关联
• API 文档（可选）：docs/apis/ 下的 .md 文件

产出：{需求名}-develop.md（8 章节完整开发文档）

增量模式

适用于需求迭代，只更新变更的部分：

v1 需求 + API → develop-v1.md
               ↓（需求变更 + 图片变更，API 沿用）
v2 需求 + 新图 → develop-v2.md（只重写受影响章节）
               ↓（API 变更，需求/图片沿用）
沿用 v2      + 新API → develop-v3.md（只重写数据流章节）

增量任务的 task.json 中 input_changes 字段记录哪些输入发生了变更：

{"requirement": true, "images": true, "api": false}

Figma 设计稿支持

在 docs/images/index.yaml 中直接填写 Figma URL：

"2. 页面结构分析":
  - https://www.figma.com/design/xxx?node-id=123

doc-gen 会调用 Figma MCP 提取精确的像素值、颜色、字体、布局，100% 还原设计稿到 develop.md。

code-gen：开发文档 → 代码

六阶段流程

| 阶段 | 说明 | |------|------| | 1. 需求收集 | 选择 develop.md（模块名/任务标题自动推导）、是否反思、补充需求 | | 2. 信息加载 | 读取 develop.md、设计图、API 文档、历史代码快照、.claude/skills/ 代码规范 | | 3. 方案规划 | 分析涉及文件、制定实现步骤 | | 4. 代码生成 | 逐文件写入代码 | | 5. 代码反思（可选） | 选「是」时调用 Agent，基于 develop.md + 代码规范 + 当前代码逐项深度反思 | | 6. 交付 | 轻量交付自检（需求覆盖/语法完整/引用一致/无残留）+ 文件清单 + 核心变更 |

代码快照

每次 code-gen 完成后，会生成 snapshots/changes.diff，记录真实的 git diff 输出。这是 bug-fix 溯源的核心依据，通过它可以快速定位 Bug 引入的具体代码位置。

增量迭代

当模块内存在前序任务时，code-gen 会：

1. 加载上一版本的 changes.diff
2. 阅读当前实际源文件
3. 只修改受影响的部分，不重写无关代码

bug-fix：Bug 溯源与修复

三阶段流程

阶段一：定位

按优先级逐步定位：

1. 读取任务链日志和代码快照（最快）
   从 code-gen 任务的 log.md 和 changes.diff 中搜索 Bug 关键词，沿 prev_task_id 链逐任务追查。

2. 全局源码搜索（补充）
   当日志/快照未命中时，执行 grep 全局搜索。

3. 需求溯源（必做）
   定位到代码位置后，继续向上追溯：

   bug 代码位置
       → code-gen 任务（changes.diff + log.md）
       → doc-gen 任务（develop.md + 原始需求）
       → 原始 PRD 章节

阶段二：修复

最小化修改原则：

• 只动引入 Bug 的代码
• 不重写不相关的逻辑
• 修复后生成新的 changes.diff 快照

阶段三：验证

执行编译验证，确认修复有效且未引入新问题。完成后更新 bug_status（resolved / unresolved）。

bug_fix_refs 回写

定位完成后，bug-fix 任务 ID 会自动写回到源头 code-gen 任务的 bug_fix_refs 字段，Dashboard 据此展示反向关联关系。

Dashboard 使用指南

启动

npx flow dashboard
# 浏览器打开 http://localhost:8000

界面结构

侧边栏                    主内容区
┌──────────┐  ┌──────────────────────────────────┐
│ 需求分析  │  │  模块列表                         │
│ 代码生成  │  │  └── 模块名（点击展开任务）        │
│ Bug修复  │  │      └── 任务卡片（状态/阶段进度） │
│──────────│  │                                  │
│ 关闭服务  │  │  [自动刷新: 1分钟，保留UI状态]    │
└──────────┘  └──────────────────────────────────┘

任务卡片

每个任务卡片显示：

• 任务标题 + 状态标签（pending / running / completed / failed）
• 阶段进度条
• 创建/更新时间

右键菜单（doc-gen 任务）

| 菜单项 | 功能 | |--------|------| | 查看需求文档 | 打开该任务的 PRD 原文 | | 查看图片 | 浏览该任务关联的设计图/截图 | | 查看开发文档 | 打开生成的 develop.md | | 查看需求变更 | 纯文本 diff：当前 PRD vs 上一版本 PRD | | 查看开发文档差异 | 纯文本 diff：当前 develop.md vs 上一版本 |

右键菜单（code-gen / bug-fix 任务）

| 菜单项 | 功能 | |--------|------| | 查看详情 | 展示 task.json 的结构化信息（阶段、关联、来源） | | 查看代码快照 | 渲染 changes.diff，带语法高亮 |

文档差异视图

查看需求变更：对两版需求文档做逐行文本对比：

• 绿色高亮：新增行
• 红色高亮：删除行
• 左侧行号（旧版）/ 右侧行号（新版）

查看开发文档差异：对两版 develop.md 做相同的逐行文本对比，直观看出哪些章节/字段被修改。

说明：v3 任务如果需求/图片未变更（input_changes.requirement: false），右键「查看需求文档」会显示友好提示，而非报错。

跨类型关联

点击 code-gen 任务的「查看详情」，可以看到：

• 基于开发文档：链接到对应的 doc-gen 任务
• 相关 Bug 修复：链接到所有关联的 bug-fix 任务

目录结构参考

项目根目录

your-project/
├── docs/                        ← 输入资源（手动维护）
│   ├── prds/                    ← 产品需求文档
│   ├── images/                  ← UI 设计图 / HTML / Figma
│   │   └── index.yaml           ← 图片必需：描述/标题 → 图片映射（图片无法被机器读语义）
│   └── apis/                    ← API 接口文档（.md，无需 index.yaml，直接语义匹配）
├── .worktree/                   ← 工作流输出（自动生成）
│   ├── doc-gen/
│   │   └── {模块名}-{module_id}/
│   │       ├── module.json
│   │       └── {任务标题}-{task_id}/
│   │           ├── task.json
│   │           ├── log.md
│   │           ├── prds/        ← 需求文档副本
│   │           ├── images/      ← 图片副本
│   │           ├── apis/        ← API 文档副本
│   │           └── *-develop.md ← 输出的开发文档
│   ├── code-gen/
│   │   └── {模块名}-{module_id}/
│   │       ├── module.json
│   │       └── {任务标题}-{task_id}/
│   │           ├── task.json
│   │           ├── log.md
│   │           └── snapshots/
│   │               └── changes.diff
│   └── bug-fix/
│       └── {bug标题}-{task_id}/
│           ├── task.json
│           ├── log.md
│           └── snapshots/
│               └── changes.diff
├── .claude/
│   ├── commands/                ← Skill 文件（npm install 自动生成）
│   │   ├── doc-gen.md
│   │   ├── code-gen.md
│   │   ├── bug-fix.md
│   │   └── _flow-conventions.md ← 通用约定文档（被三个主 skill 引用）
│   └── agents/                  ← 工具型 Agent（npm install 自动生成）
│       ├── flow-worktree-scanner.md
│       ├── flow-task-tracer.md
│       ├── figma-extractor.md
│       └── flow-build-runner.md
└── .dashboard/                  ← Dashboard 服务（npm install 自动生成）
    ├── main.py
    ├── db.py
    └── static/

task.json 字段说明

doc-gen task.json

{
  "id": "doc-task-20260526-ab12",
  "module_id": "doc-mod-20260526-cd34",
  "title": "Todo列表页v1",
  "type": "doc-gen",
  "status": "completed",
  "current_phase": 1,
  "prev_task_id": null,
  "phases": [
    {"phase": 1, "name": "信息收集", "status": "completed",
     "started_at": "2026-05-26 10:00:00", "completed_at": "2026-05-26 10:05:00"}
  ],
  "requirement_doc": "todo.md",
  "sketch_folder": "todo-images",
  "api_doc": "todo-api.md",
  "output_doc": "todo-v1-develop.md",
  "input_changes": null,
  "related_task_id": null,
  "created_at": "2026-05-26 10:00:00",
  "updated_at": "2026-05-26 10:05:00"
}

code-gen task.json

{
  "id": "code-task-20260526-ef56",
  "module_id": "code-mod-20260526-gh78",
  "title": "Todo列表页实现",
  "type": "code-gen",
  "status": "completed",
  "current_phase": 7,
  "prev_task_id": null,
  "dev_doc": ".worktree/doc-gen/todo-app-xxx/todo列表页v1-yyy/todo-v1-develop.md",
  "dev_doc_task_id": "doc-task-20260526-ab12",
  "bug_fix_refs": ["bug-task-20260526-ij90"],
  "phases": [ /* 7个阶段 */ ],
  "created_at": "2026-05-26 10:10:00",
  "updated_at": "2026-05-26 11:00:00"
}

bug-fix task.json

{
  "id": "bug-task-20260526-ij90",
  "module_id": null,
  "title": "添加后输入框未清空",
  "type": "bug-fix",
  "status": "completed",
  "current_phase": 3,
  "bug_description": "点击添加按钮后，输入框文字没有清空",
  "bug_status": "resolved",
  "source_info": {
    "requirement": "todo.md (3. 组件交互行为)",
    "locate_method": "task-chain",
    "location": "src/hooks/useTodos.ts: addTodo()",
    "detail": "addTodo 未执行 setInput('') 清空输入框",
    "root_requirement": "todo.md",
    "root_doc_gen_task": "doc-task-20260526-ab12",
    "root_code_gen_task": "code-task-20260526-ef56",
    "introduction_context": "code-gen 阶段遗漏了清空逻辑",
    "full_chain": "todo.md → doc-task-xxx → code-task-xxx → src/hooks/useTodos.ts"
  },
  "related_task_id": "code-task-20260526-ef56",
  "related_module_id": "code-mod-20260526-gh78",
  "phases": [ /* 3个阶段 */ ],
  "created_at": "2026-05-26 11:30:00",
  "updated_at": "2026-05-26 11:45:00"
}

docs/ 资源配置

需求 ↔ 资源的两种匹配方式

| 资源 | 匹配方式 | 是否需要 index.yaml | |------|---------|--------------------| | 图片 / Figma | index.yaml 提供文字描述，doc-gen 用描述语义匹配需求 | ✅ 需要（图片机器不可读语义） | | API 文档 | doc-gen 直接读 .md 的接口标题 + 描述，语义匹配需求 | ❌ 不需要（已废弃） |

docs/images/index.yaml（图片/URL → 描述）

新格式：键是图片文件名或 Figma URL，值是该图的文字描述。doc-gen 用描述与需求章节做语义匹配，无需人工指定章节：

main-screen.png: 主界面，含顶部导航、内容列表、底部操作栏
interaction-detail.png: 列表项展开后的交互细节
https://www.figma.com/design/xxx?node-id=456: 按钮样式设计稿（主/次/禁用三态）

兼容旧格式：旧的「章节标题 → 图片列表」格式仍可用，doc-gen 会自动识别。新项目推荐用「图片 → 描述」格式，减少人工维护章节映射。

API 文档（语义匹配）

直接把 API 文档放进 docs/apis/，doc-gen 读取每个接口的标题和描述，自动与需求章节匹配：

## GET /api/todos
获取待办任务列表（支持 filter 参数筛选）

## POST /api/todos
新增一个待办任务

接口标题 + 描述写得越清晰，语义匹配越准。

多版本 API 管理

API 版本迭代时新建独立文件即可：

docs/apis/
  todo-api.md       ← v1 API 文档
  todo-v2-api.md    ← v2 API 文档（新增 /stats 等接口）

在 doc-gen 增量任务中选择对应版本的 API 文档，doc-gen 自动语义匹配到需求章节。

常见问题

Q: 安装后没有看到 skill 文件？

检查 .claude/commands/ 目录是否存在。若缺失，手动执行：

node node_modules/claude-coding-flow/bin/flow.js init

Q: Dashboard 启动失败？

确认已安装 Python 依赖：

pip install fastapi uvicorn

如果 8000 端口被占用，可指定其他端口：

cd .dashboard && uvicorn main:app --port 8001

Q: doc-gen 增量模式中，v3 任务「查看需求文档」显示友好提示？

这是正常行为。当 input_changes.requirement: false（需求未变更）时，v3 任务的 prds/ 目录为空，Dashboard 会显示「需求文档本次未变更，可查看上一版本的需求文档」提示，而非报错。

Q: 如何查看两个版本之间的需求变化？

在 Dashboard 的 doc-gen 任务上右键，选择：

• 查看需求变更：对比两版 PRD 的逐行文本差异
• 查看开发文档差异：对比两版 develop.md 的逐行文本差异

Q: bug-fix 的「查看详情」没有显示关联的 doc-gen？

确认 code-gen 任务的 task.json 中 dev_doc_task_id 字段已正确填写对应 doc-gen 任务的 ID。旧任务若只有 dev_doc（完整路径），Dashboard 会回退到路径匹配方式。

Q: 能否在同一项目里管理多个功能模块？

可以。每个 /doc-gen 或 /code-gen 任务属于一个模块，不同功能创建不同模块名即可：

doc-gen 模块: todo-app（Todo功能）
             payment（支付功能）
code-gen 模块: todo-web（Todo前端）
              payment-service（支付后端）

Dashboard 按类型（需求分析 / 代码生成 / Bug修复）分栏显示所有模块。

版本历史

| 版本 | 主要变更 | |------|---------| | v1.13.1 | 清理 apis/index.yaml 的遗留描述（文件已不存在）；明确 images/index.yaml 两种写法（图片→描述 / 标题→地址列表）及各自匹配规则（写法二仅键标题参与匹配） | | v1.13.0 | 新增逆向工具 code-to-prd / code-to-api（从代码反推实现无关的 PRD/API，支持跨语言迁移）；flow init 现会把使用手册复制到 docs/flow-manual.md | | v1.12.1 | 三个 skill 的 description 增强，支持自然语言自动触发（不止 /命令）；README 补充「两种启动方式」 | | v1.12.0 | API 语义匹配：API 按文档标题/描述语义匹配需求；images/index.yaml 采用「图片→描述」格式 | | v1.11.0 | 模块化重构：抽出 _flow-conventions.md 共享约定（含 git diff 快照规则）；新增 flow-worktree-scanner / flow-task-tracer / figma-extractor / flow-build-runner 四个 agent；主 skill 移除重复扫描脚本、构建命令矩阵、字段约定 | | v1.10.0 | bug-fix 新增 needs_new_dev 状态；Dashboard 卡片相应优化（虚线 skipped 阶段、靛蓝 100% 进度条、提示条）；回退过度设计的 escalation 链路 | | v1.8.1 | 需求变更和开发文档差异改为纯文本 diff（逐行对比），新增「查看开发文档差异」右键菜单 | | v1.8.0 | doc-gen 增量模式标题不加增量标记，Dashboard 文档 diff 只做文本比较 | | v1.7.1 | 修复 doc-diff 把 H3 子标题错误识别为章节分隔符的问题 | | v1.7.0 | Dashboard 新增关闭服务按钮；自动刷新改为 1 分钟并保留 UI 状态；dev_doc_task_id 健壮关联；需求文档 404 友好提示 | | v1.6.0 | 初始版本：doc-gen / code-gen / bug-fix 三大 Skill + Dashboard |