规约驱动 AI 开发

这个 pack 装了什么

这个包收齐了五个让 AI 编码可审计的规约驱动工具。每个攻克 spec → agent → review 循环的不同环节，在同一个项目里组合得很顺。

OpenSpec 和 Planning with Files 是承重对。OpenDeepWiki 给 agent 写出靠谱 spec 所需的代码库上下文，Rivet 是给偏爱节点图而非 markdown 的团队的可视化层。

为什么要规约驱动

"vibe coding" —— 告诉 agent 你想要什么，祈祷它自己做对 —— 在小任务上能凑合，跨日任何东西就崩。三个问题复利：

• 漂移：agent 在多回合中丢失意图。每新一回合从聊天记录重新推断目标，有损耗
• 审计：PR 落地时看不出 agent 当时以为自己在造什么。审查者要从代码 diff 反推意图
• 分支：同一功能三个并发尝试没有共享信息源

Spec 修复这三件事。意图存在 agent 每回合都读的 markdown 文件里（无漂移）。Spec 版本间的 diff 就是审计轨迹（无反推）。并发尝试 fork spec 的方式跟 fork 代码一样（干净分支）。

一条命令装齐

# 装整个 pack
tokrepo install pack/spec-driven-ai-dev

# 或者只装核心对
tokrepo install openspec
tokrepo install planning-with-files

OpenSpec 落地为 specs/ 目录加一个读写它的 Claude Code subagent。Planning with Files 装一个 hook，让 agent 改代码前先输出 PLAN.md。OpenDeepWiki 作为独立进程跑，爬你的仓库并提供可查询 wiki。Rivet 是桌面应用，通过 npm install -g @ironclad/rivet 装。

常见坑

• spec 写得太粗：「做个结账流程」是目标，不是 spec。能用的 spec 列出验收标准、边界情况、out-of-scope 项目。OpenSpec 模板强制这个结构；别把你觉得别扭的章节删掉
• spec 写得太细：给 20 行补丁写 500 行 spec 是过度工程。spec 深度匹配任务风险：小补丁一段就够，跨周功能用完整模板
• spec 腐烂：实现跟 spec 偏离时，spec 就是谎言。Agent 会跟随谎言。让 spec 保持活：每个 PR 要么更新它，要么显式标注偏差
• 混淆 planning 文件和 spec：PLAN.md 是 agent 对下一批工作的推理痕迹；spec 是持久产物。别混；planning 文件是用完即扔
• Rivet 用太多：Rivet 在分支 prompt 流上发光，单次编码任务用它过度。当图能增加清晰度时再用，不要默认

跟其他 pack 的关系

• Anthropic 开发栈给 agent 运行时，这个 pack 在上面加规约层
• Prompt 工程工具箱磨砺 spec 和 plan 内部用的语言
• LLM 评测 & 护栏让你能断言 agent 输出符合 spec 的验收标准

这个 pack 单独不够用的场景

规约驱动开发假设你已经知道想要什么。对探索性工作 —— 「这个产品到底应该是什么？」—— 先走发现流程（访谈 / 原型 / 草图），再把发现翻成 spec。跳过这一步的话，会得到错产品的精美 spec。这个 pack 是清晰度的力倍器，不是清晰度的替代品。