BDD+ADR+PRD：让 Agent 遵守规范的闭环方法

核心结论（一句话）

当 AI Agent 越来越像团队成员，”为什么”必须从模型记忆里搬进 linter / CI / 文档契约——只有”可被静态检查的规范”才能跨 20-50 次 context compaction 存活下来。

分类提炼

知识节点（9 个核心概念）

关联图谱

上游（基于 / 来自）

下游（应用于 / 验证于）

同级（横向 / 并列）

正文要点

1. 5 只猴子隐喻：AI 编码是”无主规则”的复刻

经典心理学实验（Stephenson 1967）：原始猴子被替换光后，规矩依然被执行但没人能解释为什么。AI 写代码迭代 5 轮后，处于完全一样的状态——继承了大量”不能这么写”的反射式约束，但每条约束的”原始理由”已在 context compaction 中蒸发。

2. ADR 的真正革命：写可被静态检查的合同

Cichra 团队 50+ 条 ADR 定义整个产品架构。关键不是写了多少条，而是每条都配一条 linter 规则——违规时 ESLint 直接报”ADR-007 violated, see …“，把治理从”Wiki 软规范”升级为”Compiler 硬约束”。

3. PRD 极简三件事：受众变了，文档形态必须变

受众从人扩展到 Agent 那一刻，背景故事就成了反模式。Agent 不需要 why-you-decide，只需要 what-to-build。10 页 PRD 写得很完整但 6 周后没人会读；3 句话 PRD 才是 Agent 时代的工程交付物。

4. BDD 解决”AI 写的测试读不懂”

比 AI 写代码更难的是读 AI 写的测试——前者起码能跑，后者连”测的是啥”都得猜。Gherkin 把测试代码本身变成产品规范，60 年软件工程最大的浪费（spec 一份、test 一份、对不上没人发现）就此闭合。

5. 闭环执行：让”问题不可能发生”

1
2
3

Git Hook → CI → Linter → Agent 自修 → 重提
   ↑                              ↓
   └────── 收到反馈+文档链接 ←─────┘

不是”发现问题”，是”让问题不可能发生”——把治理从”事后巡检”升级为”提交即拦截”。

6. 20-50 次压缩是知识资产化的核心动机

模型越来越强 ≠ 知识越来越稳。压缩次数只增不减，模型记忆注定不可靠；唯一对冲是把”为什么”放在模型之外（ADR/PRD/BDD），让系统在压缩中保活关键信息。

表格：四件套 + 闭环执行的依赖关系

层 工具 解决的问题 失败代价
目标 PRD 三件事 Agent 不知道”为谁做” 做出技术正确但产品错位的东西
历史 ADR + Linter Agent 推翻历史决策 重新踩已知的坑
验证 BDD + Cucumber 测试代码变黑盒 测试通过 ≠ 产品正确
强制 Git Hook → CI 规范沦为”建议” 47 轮压缩后规范荡然无存

案例：最小可用版本（今晚就能动手）

背景

新接手的 Seetong 三端 + 2 个 C/C++ SDK 团队，想给 AI Agent 写”入职文档”，但不知道从哪开始。

做法（4 步）

  1. 新建 docs/adr/ — 每条决策一个 markdown，固定字段：Context / Decision / Consequences / Date
  2. 新建 docs/prd-mini.md — 只写 3 段：为什么存在 / 解决什么问题 / 用户怎么走
  3. 挑 3 条最重要的 ADR，配 3 条 linter 规则 — 违规时报错并指向 ADR 编号
  4. BDD 暂缓 — 等团队里 Agent 写的测试越来越难读时再引入 Cucumber

结果

一周内能跑通”违规可被静态检查”的最小闭环；ADR 数量会自然增长，但治理负担可控。

我的理解

这套方法论击中了我最焦虑的问题：知识在模型与团队之间不断蒸发。Seetong 三端的”为什么这么写”已经没人记得清，AI Agent 接手后会更糟。

最值得抄的不是 50 条 ADR 的规模，而是 “linter 强制” 这一招——它把”软规范”升级为”硬约束”，从”靠人自觉”变成”靠编译器”。可以立刻用：在 Seetong iOS 项目里给”为什么不用宏”“为什么 QMUI 组件统一前缀”这两条历史决策，配 clang-tidy 静态检查规则，违规直接报”ADR-XYZ violated”。

适合关联的主题