Jim4546 文档驱动开发工作流（devflow）
把「需求 → 文档 → 代码」三者强制对齐的成套开发工作流，封装成可跨项目复用的 Skill。 源出自 cvabase 项目的固定工作流，已去项目化，任何代码项目都能直接用，无需为每个项目重写 CLAUDE.md。
核心原则（永远成立）
要做什么（需求文档）→ 文档写了什么（设计/接口/原型）→ 代码实现了什么，三者必须永远对齐。 任何一步发现不一致，先更新文档，再改代码，绝不允许"代码先行、文档补写"。
调用方式
用户输入 /devflow <阶段> <内容>，第一个词是阶段名，其余是任务描述。例如：
/devflow plan 给知识库加个批量导出按钮/devflow RU 新增 CINNO 数据源/devflow verify（验收，内容可空，从 git diff 推断）
若用户没写阶段名、只给了一个任务描述，先判断任务类型再选起点（见下「步骤裁剪」），不要默认从头跑全套。
第 0 步：进场先做两件事（每次必做）
- 识别本项目的文档体系。不要假设叫 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 层文档"，并询问是否要新建一份最小文档，而不是默默跳过对齐。
- 判断任务类型，裁剪步骤（见下表），把结论一句话告诉用户再动手。
步骤裁剪（解决"短平快小任务也要走全套吗"）
| 任务类型 | 跑哪些步骤 | 说明 |
|---|---|---|
| 纯文档更新（只动 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 — 想法记录（想法不丢失）
- 找到本项目的需求/Backlog 文档（PRD.md 的"暂缓功能/Backlog"章节，或等价位置）。
- 追加一行：
| **[想法标题]** | [一句话：为什么暂缓 / 待评估] | [触发条件或评估时间] |；描述较详时在下方补一段。 - 若文档有版本变更记录表，追加一行小版本（+0.1）。
- 只动需求文档，不写代码、不改其他文件。
- 回复：
✅ 已记录到 Backlog：[想法标题]
/plan — 规划模式（⛔ 全程禁止改文件、禁止写代码）
按顺序做四件事：
- 挑战前提（先问"该不该做"再想"怎么做"）：真实问题是什么？不做会怎样？有没有更简单、范围更小、能解决 80% 的做法？与现有功能/文档体系有无冲突？前提站不住或有明显更优解就直说，别硬着头皮做。
- 理解目标：1-3 句复述规划目标，确认范围。
- 多轮澄清（最多 3 轮，不是一次问完）：每轮只问当前最关键的几个问题，分类 🎯功能边界 / 🎨UI交互 / ⚠️边界情况 / 🔗依赖影响。答案暴露新疑点就继续追问。收敛信号：已无 🔴 关键未知，剩下都是实现细节。3 轮仍有关键未知则明说"还有 X 没定，建议先定再规划"。
- 输出完整技术方案：新增/修改哪些文件（具体路径）、每个文件改什么（一句话）、是否需要数据库变更、是否新增接口、预估工作量、潜在风险。
末尾问用户："方案确认后，输入
/devflow RU开始执行。"
/RU — Requirements Update（文档先行 → 写代码 → 三方对齐）
严格按 9 步，不可跳步，每步完成等用户确认再进入下一步：
理解需求 — 1-3 句复述目标和范围，让用户确认无偏差。
集中提问 — 一次性列出所有不确定点，分类（🎯功能边界 / 🎨交互展示 / ⚠️异常处理 / 🔗依赖影响）。
确认优先级 — 紧急（本次迭代）/ V1 / V2 / Backlog。
技术方案确认 — 动手前先说清：改哪些文件（具体路径）、新增还是改现有、有无数据库变更、预估工作量；等用户确认方向。
判断受影响文档 — 逐一判断哪些主文档需更新（参照下表，按本项目实际文档名替换）：
变动类型 必须更新 可能需要更新 新增/修改功能 需求文档(PRD) 路线图(ROADMAP) 新增/修改页面或 UI 交互 原型/UI 文档 — 新增/修改 API 接口 设计文档(SPEC) + API 文档 架构文档(ARCH) 新增数据库表/字段 设计文档(SPEC) 架构文档(ARCH) 架构或技术栈变动 SPEC + ARCH — 部署/环境变动 部署文档(DEPLOY) — 版本发布 CHANGELOG + ROADMAP — 列出本次要更新的文档清单，让用户确认。
先改文档 — 按清单逐一改主文档，每改完一份说明改了什么。文档与需求对齐后才进入下一步。
再改代码 — 按方案实现，每改完一个文件说明改了什么。
三方对齐验证 — 逐项检查需求↔文档↔代码一致：功能与需求文档一致、页面标题/导航与原型文档一致、API/数据库字段与设计文档一致、类型检查/编译无报错、边界情况覆盖、未影响现有功能。有数据库变更则提示用户跑迁移命令。
询问是否提交 — 验证通过后给出建议 commit message，询问是否提交。
防文档漂移：改任何"数量型数据"（数据源数、接口数、表数、实体数…）前，先全局 grep 查全所有引用位置再统一改——只改主文件、漏掉其他引用是漂移的头号根因。约定一份文档为"数字唯一权威"，其余引用统一写"见 X §N"，不要到处硬编码同一个数字。
/verify — 功能验收（🔴 硬门槛：未通过禁止 commit）
这是人工验收流程，不是自动化测试。按 5 步输出验收报告（清晰到能直接给非技术同事看）：
- 理解改动 —
git diff HEAD --stat+git log --oneline -8；$ARGUMENTS 非空以其为主，为空则从 diff 推断。 - 验收报告：
- ✅ 功能说明（非技术语言 1-3 句，说清用户能感受到什么变化，禁止写技术术语）
- 🧪 验收步骤（≥3 步，每步写「操作 + 预期结果」，覆盖正常流程和边界情况；涉及后台/定时任务给出手动触发方式）
- 📋 文档同步核查（逐一读取相关文档判断是否已正确更新；该更新而未更新的立即补上，不要只报告问题）
- ⚠️ 已知限制（诚实说明本次实现的约束/不完整之处）
- 🚀 后续操作建议（是否需要 commit / 重启服务 / 数据库迁移）
- 确认文档全部同步 — 读取所有"应更新"的文档，末尾输出同步状态清单。
- 一句话结论：通过 / 部分通过 / 待补充 + 核心功能一句话 + 需用户确认的点。
- 只在结论为「通过」时才放行后续 commit。"部分通过 / 待补充"一律不放行，倒逼修复。
若项目用 marker/hook 机制把 verify 设成 commit 硬门槛，遵循项目约定写 marker；不要绕过 hook（删 marker、
--no-verify等），有问题跟用户说。
/simplify — 代码质量检查
对本次改动做质量复查：重复代码、冗余逻辑、低效写法、可合并/可删除的部分。只做质量清理，不找功能 bug（找 bug 是 verify 的事）。本仓若有内置的 /simplify 或 code-review 能力，优先复用。
commit & push
- 验收通过后才 commit，给出规范 commit message。
- commit 完成后主动问："改动已 commit，是否 push 到 origin/
<branch>？" 等用户明确同意再 push。 - 绝不在用户没要求时擅自 push，也不要把 commit + push 合并成一句默认执行。
落地到新项目的两种用法
- 轻量用（推荐给短平快小任务）：进任意项目直接
/devflow <阶段>，按"步骤裁剪"只取需要的步骤，零搭建。 - 重度用（长期项目）：让我把上面各阶段落成本项目的
.claude/commands/idea|plan|RU|verify.md，并在项目 CLAUDE.md 里写明文档体系与硬门槛——之后该项目内用原生/idea /plan /RU /verify即可。需要时直接说"把这个工作流装进当前项目"。