社区孵化

人工智能软件开发

Hi 各位佬，

最近我高强度的在使用 Claude Code 和 Codex CLI 做开发。不得不说，AI 确实能极大提高效率，但用久了大家可能也有类似的感觉：信任成本很高。

主要体现在几个方面：

1. 既当裁判又当运动员：让 AI 既写代码又写测试，它倾向于写一些容易通过的测试，甚至直接修改测试逻辑来适配有问题的代码。
2. “西西弗斯” 式的完成：有时候它会在文档里信誓旦旦地写上 [x] Completed，但当去检查代码，发现只是一堆 TODO 或者只是个空壳。
3. 上下文漂移：聊得多了，它就忘了最初 Design 文档里的约束，开始自由发挥。
4. 缺乏长期思维：AI 输出的设计和代码有时候会不考虑长期演进，而只为了完成短期任务或者跑通测试。

为了解决这些问题，我开发了一个叫 Dev-PlayBooks 的项目（项目地址：github.com/ozbombor/dev-playbooks-cn）

本质上是一套结构化的 Prompt 策略配合 Shell 脚本工具链。目的是把软件工程里那些能够对抗 AI 缺陷的最佳实践，应用到 AI 的工作流里，约束 AI 的开发行为。

主要有这么几个特性：

1. 角色隔离

这是 Dev-PlayBooks 最核心的原则 —— 不再在一个对话框里完成所有任务。

设计阶段

• Proposal Author：负责提出提案。它的目标是把变更的 Why（为什么做）、What（做什么）和 Impact（影响范围）说清楚，并给出初步的设计方案。
• Proposal Challenger：专门负责 “挑刺” 和查漏补缺。它会质疑 Author 的假设，指出风险、不一致和设计缺陷，并寻找缺失的验收标准。
• Proposal Judge：负责最终裁决。它会综合 Author 的提案和 Challenger 的质疑，做出 Approved、Revise 或 Rejected（实际上不会发生，AI 还是很保守的） 并将理由记录在 Decision Log 中。

只有通过裁决，变更流程才会进入 Design 阶段。当然，如果觉得流程过重，也可以跳过 Challenger 和 Judge，直接进入设计。

编码阶段 分为 Test 组（包含 Test Owner 和 Test Reviewer）和 Coding 组（包含 Coder 和 Code Reviewer）：

• Test Owner：在一个独立的 Session 里工作。它的任务是根据设计文档写测试（Verification）。最重要的是，它被禁止读取实现代码（src/）。这就逼着它必须基于契约（Contract）来写测试。
• Coder：在另一个 Session 里工作。它的任务是让测试变绿。最重要的是，它被禁止修改测试代码（tests/）。Coder 就没法通过改测试来作弊，必须老老实实地通过红绿循环。
• Reviewer：审计生成的生产代码和测试代码的质量、完成度，并且提出修改建议或者通过提议。

2. 编码计划的颗粒度控制与无偏见思考

颗粒度控制

我发现 AI 在生成编码计划的时候，倾向于把所有东西一股脑放在计划里面，甚至会囊括所有的实现代码。这会导致 AI 在编码阶段直接陷入实现细节，丧失了计划阶段应该有的全局视野。

为此在 Dev-PlayBooks 里面，AI 被要求关注规划优势与抽象优势。Planner 的职责是把注意力分配到全局的模块划分、接口契约和验收锚点上，而不是去写具体的函数实现。那些不需要全局视野的实现细节，刻意留白给 Coder 去发挥。这样既保证了整体架构不走样，又给了编码阶段足够的灵活性。

无偏见

在现实项目中，tests/ 目录下通常已经成千上万行代码。如果允许 Planner 读取 tests/，AI 看到现有的 UserTest.java，它会下意识地把新功能的计划写成 “修改 UserTest.java”，而不是根据新设计思考 “我们需要一个新的 OAuth2Verification 模块”。

后果是，编码计划会不自觉地被旧架构引导，试图把新功能塞进旧的测试结构里，而不是按照新 Design 的意图去规划。所以 Planner 被要求禁止访问 tests/，隔离旧测试的干扰，强制它基于设计文档进行零基准思考，而不是基于现有代码做增量修补。

3. 归档阶段通过脚本验证作为硬闸门

Dev-PlayBooks 认为归档对质量控制也相当重要。Archiver Skill 是整个工作流的唯一出口，它不是简单的文件移动，而是一次严格的全量审计：

• 强制脚本验证：归档前必须运行 change-check.sh --mode strict。如果脚本返回非零（比如 AC 覆盖率未达 100%、Evidence 目录为空、Task 未全部打勾），归档流程立即终止。
• 自动回写设计：如果开发过程中发现了 Design Gap（记录在 deviation-log.md），Archiver 会自动将其回写到 design.md，确保文档永远反映项目的真实状态。
• 规格合并：将本次变更产生的 Specs 和 Contracts 合并到项目的 “真理源”（Truth Root），为下一次变更积累上下文。

只有通过了这一系列严苛检查的变更，才有资格进入 archive 目录，否则它就只能继续停留在 changes 目录里等待修复。

4. 代码质量监控

Dev-PlayBooks 引入了系统熵的概念。其实就是定期跑脚本统计圈复杂度、代码流失率、依赖深度等指标，生成一个 history.json。 这主要是为了防止 AI 为了实现功能堆砌代码。当熵值曲线异常升高时，就能知道：该停下来维护代码质量了。

更多特性，可以进入仓库页面查看。

目前这个项目支持 Claude Code、Codex CLI、Qoder 等主流 AI 编程工具。

安装方法

1. npm install -g dev-playbooks-cn
2. dev-playbooks-cn init：进入初始化页面，选择需要配置的 AI 编程工具，确认后会自动把 Spec 文档结构和 Skills 初始化进入项目。

更新方法

项目根目录下运行：dev-playbooks-cn update

迁移

如果你已经在使用 OpenSpec 或者 SpecKit，可以通过 dev-playbooks-cn --help 获取迁移指令，一键迁移到 Dev-PlayBooks，并自动适配 CLAUDE.md 和 AGENTS.md。

本项目的规范使用起来比较重，适合那些大型项目、复杂任务、对代码质量要求高的佬友。

项目地址：github.com/ozbombor/dev-playbooks-cn

欢迎大家试用、提 Issue、提 PR。