# Devflow

> 文档驱动开发工作流：idea→plan→RU→verify→simplify→commit 六步法，强制「要做什么(PRD)↔文档写了什么(SPEC/原型)↔代码实现了什么」三方永远对齐。当用户要做新功能/重构/bugfix，或说 /idea /plan /RU /verify /simplify、规划方案、文档先行、功能验收、三方对齐、防文档漂移时使用。任何项目通用，不绑定特定目录结构；支持短平快小任务的轻量模式（可跳过部分步骤）。

- Skill: `jim4546/devflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jim4546/devflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jim4546/devflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: Jim4546 (https://skillmd.com/u/jim4546)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jim4546/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` 即可。需要时直接说"把这个工作流装进当前项目"。