一个帮你把开发任务做稳做牢的工作流工具。
专门治「需求没想清楚就写代码」这个毛病。
你平时开发功能的时候，是不是经常这样：
- 「先写代码再说」→ 写到一半发现方向错了，白干
- 「需求大概清楚」→ 做到一半发现漏了关键场景
- 「先上线再补测试」→ 结果永远没补
- 「验收就是点两下」→ 上线后出 bug 才发现没测到位
这个工作流就是专门治这些毛病的 👊
它是一个 6 步走的标准流程，每一步都规定了「先看什么资料、再做什么事」，保证：
- ✅ 需求想清楚了再动手
- ✅ 方案比较过了再选
- ✅ 测试写好了再写代码
- ✅ 验收做完了再交付
把你的开发任务想象成 「盖房子」：
干啥：把「我要盖个房子」变成「要盖多大的、几层、几个卧室、什么风格」。
具体来说：
- 先看项目背景和已有资料，搞明白现状
- 然后逐条追问关键问题：
- 这个功能给谁用？
- 解决了什么问题？
- 什么算「做完了」？
- 什么情况绝对不算做完了？
- 有没有现成的方案可以用？
- 如果涉及不了解的外部信息（比如竞争对手怎么做、有没有现成的库），去网上查清楚
- 最后写一份需求文档，至少包括：
- 背景和问题
- 谁用、怎么用
- 做什么 + 明确不做什么
- 验收标准（怎么才算做好）
- 风险点
产出：一份需求文档 📄
🛑 到这里要停下来给你看 → 确认没问题了再走下一步。
干啥：想 2~3 个不同的实现方案，比较它们的优缺点，选一个。
具体来说：
- 基于第 1 步确认的需求，想几套方案
- 每套方案要说明：
- 要改哪些文件
- 难度有多大
- 会不会影响现有功能
- 好不好测试
- 万一做错了能不能回退
- 如果涉及不熟悉的技术，先去查资料搞明白再设计方案
- 关键术语一旦定下来，就写成文档，后面统一用
- 只有重要决策才写正式记录，不需要每个小选择都写
产出：一份设计方案 📄
🛑 到这里要停下来给你看 → 你选一个方案，再走下一步。
干啥：把方案拆成一个个可以动手干的小任务。
具体来说：
- 每个任务必须满足「先写一个会失败的测试 → 写最少代码让测试通过 → 检查有没有问题」
- 写明每个任务要改哪些文件、怎么验证
- 任务排好先后顺序（依赖关系）
- 默认一个任务干完再干下一个，不会同时开多个
产出：一份实施计划清单 ✅
🛑 到这里要停下来给你看 → 你确认计划没问题，再开始写代码。
干啥：按计划一个个任务干，每个任务都走「红 → 绿 → 重构」三步：
每个任务的循环：
- 🔴 红：先写一个测试，这个测试现在肯定会失败（因为代码还没写）
- 🟢 绿：只写让测试通过的最少代码，不写多余的
- 🔧 整理：在测试的保护下，改掉刚才写的临时代码里的问题
- ✅ 验证：跑一下全部测试，确认没搞坏别的东西
重复上述步骤，直到所有任务干完。
原则：
- 先写测试再写代码，不是先写代码再补测试
- 只写最少量的代码让测试通过，不提前写「未来可能会用到」的代码
- 测试至少要覆盖：正常情况、边界情况、出错情况
产出：可以运行的代码 + 配套的自动化测试 ✅
干啥：把前面所有的产出从头到尾检查一遍，看看有没有遗漏或做错。
具体来说：
- 对照需求文档：该做的都做了吗？
- 对照设计方案：结构跟设计的一致吗？
- 对照实施计划：每个任务都完成了吗？
- 检查代码有没有安全问题、性能问题
- 检查测试是不是真的有用（不是只走个过场）
- 把发现的问题按严重程度修掉
如果发现需求或设计有问题，退回去重做，不能只改表面。
产出：一份审查报告 + 修复后的代码 ✅
干啥：最后一次全部检查，确认没问题了，问你「接下来怎么处理」。
具体来说：
- 重新跑一遍全部测试，确认都是绿的
- 检查工作区状态，列出所有改动的文件
- 然后问你：
- 要不要提交到本地仓库？
- 要不要推送到远程仓库？
- 要不要创建合并请求？
- 要不要清理临时工作区？
🛑 必须等你说「干」，才会执行上面的操作。
| 场景 | 建议 |
|---|---|
| 做一个全新功能 | ✅ 必须用 |
| 修改一个已有功能 | ✅ 建议用 |
| 修一个 bug | ✅ 建议用（除非只是改个错别字） |
| 只是改个文案 | ❌ 不用走 6 步，直接改 |
注意：这个工作流有一个硬规矩——不管任务看起来多小，都不能自己判断「这个太小了，跳过几步」。必须完整走完 6 步。如果你觉得某个任务确实很简单，在第 1 步停下来跟确认就好。
| 禁止行为 | 错误例子 |
|---|---|
| 自己判断任务小就跳步骤 | 「只是改个错别字，直接处理，不走 6 步。」 |
| 用自己编的问题替代内置追问 | 「大概问两句就行，不用那么细。」 |
| 缺了参考资料就凭经验做 | 「少一个参考文件不影响，按经验来。」 |
| 没有等你确认就进入下一步 | 「方案大致清楚了，先写代码再说。」 |
| 没有你授权就开多个任务并行 | 「这两个任务没关联，同时做快一点。」 |
| 没有你授权就提交、推送、合并 | 「直接帮你提交并推送。」 |
| 没有刚刚跑过的验证证据就说做完了 | 「代码看起来没问题，应该算完成了。」 |
| 出什么问题 | 怎么处理 |
|---|---|
| 本地文件缺失或损坏 | 停止工作流，告诉你「技能包不完整」，不凭经验代替 |
| 查资料的网络连不上 | 记录查不到的项，等你决定是等联网还是标记为「猜测」 |
| 测试一直通不过 | 找到根本原因，缩小改动范围再试；如果还不行，停下来报告 |
| 审查发现需求不成立 | 退回第 1 步修改需求，不修表面症状 |
| 不是 git 仓库 | 跳过 git 相关的交付选项，只做文件级验证 |
本项目包含两部分，各自有独立的许可证：
SKILL.md— 核心工作流流程scripts/目录 — 检查更新和验证完整性的工具agents/目录 — 智能助手配置test-prompts.json— 测试用例
协议：GNU AGPL-3.0
简单说：你可以自由使用和修改，但如果把你的修改版发布出去（包括放在网上给别人用），必须同样公开源代码。
references/ 目录下所有文件，来自以下项目，各自保留原始许可证（全部是 MIT 协议）：
- agent-reach（网上搜索调研工具）
- code-reviewer（代码审查指南）
- ponytail（写最简代码的方法论）
- 以及更多（详见 NOTICE 文件）
MIT 协议简单说：你可以随便用，只要保留原作者的版权声明就行。
本工具是一个 纯本地的 AI 技能包：
- ❌ 不上传你的代码或数据到任何服务器
- ❌ 不需要联网（查资料除外）
- ❌ 不安装任何隐藏文件
⚠️ 你自己的代码请自行做好备份
requirement-workflow/
├── SKILL.md ← 核心工作流流程（就是上面那 6 步）
├── scripts/ ← 维护工具
│ ├── check_upstream.py ← 检查参考资料有没有更新
│ └── validate_bundle.py← 检查技能包有没有缺失文件
├── agents/ ← 智能助手的配置文件
├── references/ ← 参考资料（来自多个第三方项目）
│ ├── brainstorming.md ← 需求头脑风暴方法
│ ├── grill-me.md ← 严苛追问方法
│ ├── grilling.md ← 深入追问方法
│ ├── writing-plans.md ← 怎么做实施计划
│ └── ...更多
├── NOTICE ← 第三方项目版权声明
├── LICENSE ← AGPL-3.0 协议全文
└── README.md ← 就是这个文件