Devflow

文档驱动开发工作流（devflow）

把「需求 → 文档 → 代码」三者强制对齐的成套开发工作流，封装成可跨项目复用的 Skill。 源出自 cvabase 项目的固定工作流，已去项目化，任何代码项目都能直接用，无需为每个项目重写 CLAUDE.md。

核心原则（永远成立）

要做什么（需求文档）→ 文档写了什么（设计/接口/原型）→ 代码实现了什么，三者必须永远对齐。 任何一步发现不一致，先更新文档，再改代码，绝不允许"代码先行、文档补写"。

调用方式

用户输入 /devflow <阶段> <内容>，第一个词是阶段名，其余是任务描述。例如：

• /devflow plan 给知识库加个批量导出按钮
• /devflow RU 新增 CINNO 数据源
• /devflow verify（验收，内容可空，从 git diff 推断）

若用户没写阶段名、只给了一个任务描述，先判断任务类型再选起点（见下「步骤裁剪」），不要默认从头跑全套。

第 0 步：进场先做两件事（每次必做）

1. 识别本项目的文档体系。不要假设叫 PRD.md / SPEC.md。先扫一遍仓库，找到对应三类文档的真实文件：
   • 需求层（要做什么）：PRD.md / REQUIREMENTS.md / docs/需求.md …
   • 设计层（怎么实现 / 长什么样）：SPEC.md / DESIGN.md / ARCH.md / prototype.md / UI.md / API.md …
   • 协作约定层：README.md / CHANGELOG.md / CLAUDE.md … 找不到就明确告诉用户"本项目没有 X 层文档"，并询问是否要新建一份最小文档，而不是默默跳过对齐。
2. 判断任务类型，裁剪步骤（见下表），把结论一句话告诉用户再动手。

步骤裁剪（解决"短平快小任务也要走全套吗"）

任务类型	跑哪些步骤	说明
纯文档更新（只动 docs / README / CHANGELOG / CLAUDE.md）	RU 的"改文档"部分 → commit	跳过 verify / simplify
配置改动（.env.example、*.config.*、.claude/**）	直接改 → commit	跳过 verify
单行 hotfix（改错字、调常量，diff ≤ 2 行且不动函数签名/控制流/schema）	改 → verify → commit	可跳 plan / RU，但仍要验收
新功能 / 重构 / bugfix	idea?→plan→RU→verify→simplify→commit	一步都不能跳
只是先记个想法，暂不做	只跑 idea	落到 backlog 就结束

轻量小任务的正确姿势：不用新建目录、不用重写 CLAUDE.md，进任意项目直接 /devflow，按上表只取需要的几步。

---

阶段定义

/idea — 想法记录（想法不丢失）

1. 找到本项目的需求/Backlog 文档（PRD.md 的"暂缓功能/Backlog"章节，或等价位置）。
2. 追加一行：| **[想法标题]** | [一句话：为什么暂缓 / 待评估] | [触发条件或评估时间] |；描述较详时在下方补一段。
3. 若文档有版本变更记录表，追加一行小版本（+0.1）。
4. 只动需求文档，不写代码、不改其他文件。
5. 回复：✅ 已记录到 Backlog：[想法标题]

/plan — 规划模式（⛔ 全程禁止改文件、禁止写代码）

按顺序做四件事：

0. 挑战前提（先问"该不该做"再想"怎么做"）：真实问题是什么？不做会怎样？有没有更简单、范围更小、能解决 80% 的做法？与现有功能/文档体系有无冲突？前提站不住或有明显更优解就直说，别硬着头皮做。
1. 理解目标：1-3 句复述规划目标，确认范围。
2. 多轮澄清（最多 3 轮，不是一次问完）：每轮只问当前最关键的几个问题，分类 🎯功能边界 / 🎨UI交互 / ⚠️边界情况 / 🔗依赖影响。答案暴露新疑点就继续追问。收敛信号：已无 🔴 关键未知，剩下都是实现细节。3 轮仍有关键未知则明说"还有 X 没定，建议先定再规划"。
3. 输出完整技术方案：新增/修改哪些文件（具体路径）、每个文件改什么（一句话）、是否需要数据库变更、是否新增接口、预估工作量、潜在风险。 末尾问用户："方案确认后，输入 /devflow RU 开始执行。"

/RU — Requirements Update（文档先行 → 写代码 → 三方对齐）

严格按 9 步，不可跳步，每步完成等用户确认再进入下一步：

1. 理解需求 — 1-3 句复述目标和范围，让用户确认无偏差。

2. 集中提问 — 一次性列出所有不确定点，分类（🎯功能边界 / 🎨交互展示 / ⚠️异常处理 / 🔗依赖影响）。

3. 确认优先级 — 紧急（本次迭代）/ V1 / V2 / Backlog。

4. 技术方案确认 — 动手前先说清：改哪些文件（具体路径）、新增还是改现有、有无数据库变更、预估工作量；等用户确认方向。

5. 判断受影响文档 — 逐一判断哪些主文档需更新（参照下表，按本项目实际文档名替换）：

   变动类型	必须更新	可能需要更新
   新增/修改功能	需求文档(PRD)	路线图(ROADMAP)
   新增/修改页面或 UI 交互	原型/UI 文档	—
   新增/修改 API 接口	设计文档(SPEC) + API 文档	架构文档(ARCH)
   新增数据库表/字段	设计文档(SPEC)	架构文档(ARCH)
   架构或技术栈变动	SPEC + ARCH	—
   部署/环境变动	部署文档(DEPLOY)	—
   版本发布	CHANGELOG + ROADMAP	—

   列出本次要更新的文档清单，让用户确认。

6. 先改文档 — 按清单逐一改主文档，每改完一份说明改了什么。文档与需求对齐后才进入下一步。

7. 再改代码 — 按方案实现，每改完一个文件说明改了什么。

8. 三方对齐验证 — 逐项检查需求↔文档↔代码一致：功能与需求文档一致、页面标题/导航与原型文档一致、API/数据库字段与设计文档一致、类型检查/编译无报错、边界情况覆盖、未影响现有功能。有数据库变更则提示用户跑迁移命令。

9. 询问是否提交 — 验证通过后给出建议 commit message，询问是否提交。

防文档漂移：改任何"数量型数据"（数据源数、接口数、表数、实体数…）前，先全局 grep 查全所有引用位置再统一改——只改主文件、漏掉其他引用是漂移的头号根因。约定一份文档为"数字唯一权威"，其余引用统一写"见 X §N"，不要到处硬编码同一个数字。

/verify — 功能验收（🔴 硬门槛：未通过禁止 commit）

这是人工验收流程，不是自动化测试。按 5 步输出验收报告（清晰到能直接给非技术同事看）：

1. 理解改动 — git diff HEAD --stat + git log --oneline -8；$ARGUMENTS 非空以其为主，为空则从 diff 推断。
2. 验收报告：
   • ✅ 功能说明（非技术语言 1-3 句，说清用户能感受到什么变化，禁止写技术术语）
   • 🧪 验收步骤（≥3 步，每步写「操作 + 预期结果」，覆盖正常流程和边界情况；涉及后台/定时任务给出手动触发方式）
   • 📋 文档同步核查（逐一读取相关文档判断是否已正确更新；该更新而未更新的立即补上，不要只报告问题）
   • ⚠️ 已知限制（诚实说明本次实现的约束/不完整之处）
   • 🚀 后续操作建议（是否需要 commit / 重启服务 / 数据库迁移）
3. 确认文档全部同步 — 读取所有"应更新"的文档，末尾输出同步状态清单。
4. 一句话结论：通过 / 部分通过 / 待补充 + 核心功能一句话 + 需用户确认的点。
5. 只在结论为「通过」时才放行后续 commit。"部分通过 / 待补充"一律不放行，倒逼修复。

若项目用 marker/hook 机制把 verify 设成 commit 硬门槛，遵循项目约定写 marker；不要绕过 hook（删 marker、--no-verify 等），有问题跟用户说。

/simplify — 代码质量检查

对本次改动做质量复查：重复代码、冗余逻辑、低效写法、可合并/可删除的部分。只做质量清理，不找功能 bug（找 bug 是 verify 的事）。本仓若有内置的 /simplify 或 code-review 能力，优先复用。

commit & push

1. 验收通过后才 commit，给出规范 commit message。
2. commit 完成后主动问："改动已 commit，是否 push 到 origin/<branch>？" 等用户明确同意再 push。
3. 绝不在用户没要求时擅自 push，也不要把 commit + push 合并成一句默认执行。

---

落地到新项目的两种用法

• 轻量用（推荐给短平快小任务）：进任意项目直接 /devflow <阶段>，按"步骤裁剪"只取需要的步骤，零搭建。
• 重度用（长期项目）：让我把上面各阶段落成本项目的 .claude/commands/idea|plan|RU|verify.md，并在项目 CLAUDE.md 里写明文档体系与硬门槛——之后该项目内用原生 /idea /plan /RU /verify 即可。需要时直接说"把这个工作流装进当前项目"。