23 · 规格即架构:约束怎么写给 AI

一句话点题:17 章 说「把判断喂给 AI」。但判断如果只活在你脑子里、或聊天框里说过一句,AI 下次就忘了、就替你乱填默认值。把判断写成 AI 每次都读、且机器能强制的「规格」,才是真护栏——在 AI 时代,写清楚约束本身,就是架构工作。

---

🤝 AI 协同设计篇第 1 章 · 本篇讲什么

前置:实战篇(18–22)。 你已经会设计、演进、拆迁 AI 系统了。AI 协同这一篇换个视角:不是「你怎么造」,而是「你怎么和 AI 一起造,且不失控」。 它不讲 vibe coding 的工具技巧,只讲两件事——怎么把约束写给 AI(本章 + 25)、怎么审查 AI 的产出(24),最后(26)收成一套决策树。和 architecture-copilot skill 同一条产品线。

---

一、问题:判断不写下来,等于没有

17 章 的结论是:代码 AI 来产,但规格、约束、验收标准是你的。问题是——怎么「给」?

新手以为「给」就是聊天时说一句「记得加幂等啊」。但这行不通:

   你以为的「喂判断」                 实际发生的
   ─────────────────                ──────────────────────────
   聊天里说「退款要幂等」      →      这轮记得;下一轮上下文压缩后忘了;
                                     换个会话从零开始;换个同事完全不知道

更要命的是 17 章 那条:AI 默认给你「乐观路径」——你不明确说「退款要幂等、要防重复扣款」,它就不写,然后给你一段 demo 能跑、生产会炸的代码。

所以核心命题:架构约束必须落成持久的、AI 每次都自动读到的、最好机器能强制的形式。口头的、一次性的、靠人记的约束,在 AI 协作里等于不存在。这件事,本质就是 08 章「最先丢失的永远是为什么」在 AI 时代的升级版——只不过现在「读者」从三个月后的同事,变成了每次对话都从头开始的 AI。

---

二、规格金字塔:从「人读」到「机器强制」

把约束按「可执行程度」分三层,越往下越硬、越绕不过:

                    ▲ 越往上:管「为什么」,靠人理解
        ┌───────────────────────┐
        │   ADR(架构决策记录)     │  人读 ——「为什么这么定、放弃了什么」
        │   08 章                 │     AI 读它 → 知道边界与历史,不乱改
        ├───────────────────────┤
        │  AGENTS.md / CLAUDE.md  │  AI 常驻读 ——「该做什么 / 禁做什么」
        │  (项目级规则书)          │     每次对话自动加载,是 AI 的「长期记忆」
        ├───────────────────────┤
        │  适应度函数 / lint / CI  │  机器强制 ——「违反就 fail,绕不过」
        │  14 章                  │     不靠自觉,靠红灯
        └───────────────────────┘
                    ▼ 越往下:管「强制」,机器自动验证

三层各管一段,缺一不可:

层	形式	管什么	读者
ADR	一页纸文档(08)	为什么这么决定、取舍	人 + AI(理解意图)
AGENTS.md / CLAUDE.md	项目根的规则文件	做什么 / 不做什么(常驻规则)	AI(每次对话)
适应度函数 / CI	自动化测试(14)	红线(违反即拦)	机器

为什么要三层而不是一层? 因为约束分三种:有的只能靠人理解(「为什么当年选了双写」——写进 ADR);有的能用自然语言让 AI 持续遵守(「退款必须幂等」——写进 AGENTS.md);有的能被机器精确验证(「领域层不准 import web 层」——写成 CI 检查)。能往下沉一层,就别停在上一层——文档靠自觉,CI 靠强制。

---

三、怎么写好 AGENTS.md(AI 的常驻规则书)

AGENTS.md(或 CLAUDE.md)是这一层的主角——它是放在项目根、AI 每次对话都自动读的文件(Claude Code / Codex 的记忆文件正是干这个)。但 90% 的人写得像废话。

坏例(等于没写):

- 写高质量、可维护、可扩展的代码
- 遵循最佳实践
- 注意性能和安全

AI 看到这些什么也做不了——「高质量」是多高?「最佳实践」是谁的?这些是正确的废话。

好例(具体 + 可执行 + 带「为什么」+ 有反例):

## 数据与一致性
- 所有「碰钱」的操作(扣款/退款)必须带幂等键;重复请求返回上次结果,
  绝不重复执行。理由见 ADR-003。
- ❌ 禁止让模型直接调用支付 API;模型只能产出「退款提议」,
  由确定性的退款服务执行(见 19 章设计)。

## 韧性
- 所有外部调用(模型 API / 第三方)必须设超时 + 重试(指数退避)。
  理由:依赖一定会抽风(见 12 章)。

## 边界
- 领域层禁止 import web 层 / 框架。违者 CI 会 fail(见 fitness test)。

写 AGENTS.md 的五条纪律:

1. 具体到可执行:不说「注意安全」,说「所有外部输入在入库前必须校验;用户内容当不可信(含提示注入)」。
2. 带上「为什么」:像 ADR 一样给理由——AI(和人)知道理由才不会在「显得多余」时把它删掉(呼应 08 章 那个「删双写炸三周」的开场)。
3. 给反例(❌):明确「禁止做什么」比「应该做什么」更管用——这正是堵住 AI 乐观路径默认值的地方。
4. 短而狠:AI 的上下文窗口有限且按 token 计费(17 章 的上下文工程)。规则书是常驻成本,别写成小说;写最高频、最容易被违反的那几条。
5. 随代码演进:过时的规则比没有更糟(它会主动误导 AI)。规则变了就改,和 08 章 的 ADR 一样追加/更新。

AGENTS.md 就是「写给 AI 的架构边界」。你在 19 章 设计时做的每个「选了 A 放弃 B」、20 章 写的每条 ADR,凡是希望 AI 持续遵守的,都该提炼成 AGENTS.md 里的一条。

---

四、能机器强制的,就别只写文档

金字塔最底层最硬:能写成测试/lint 的约束,就别只写在文档里——文档靠 AI 和人的自觉,CI 是绕不过的红灯。这正是 14 章 的适应度函数在 AI 协作里的核心价值:

   约束的归宿,按「能不能被机器验证」分流:

   能被机器精确验证  ──▶  适应度函数 / lint / 契约测试 / CI 门禁(强制)
   能用语言约束 AI   ──▶  AGENTS.md(常驻规则)
   只能靠人判断      ──▶  ADR + 人工 review checklist(下一章 24)

约束	落成什么(尽量往「强制」沉)
领域层不准依赖框架	依赖检查(CI fail)
退款必须幂等	AGENTS.md 规则 + 「缺幂等键」的契约测试
模型调用必须经过抽象层	依赖检查(扫到直连 provider 就 fail,见 21 章)
p99 < 200ms	性能测试(超了 fail)
「为什么用 RAG 不用微调」	ADR(只能人读,无法机器验证)

架构智慧:AI 会忠实地执行你写下的约束,也会忠实地无视你没写下的约束。把「靠提醒」的约束,尽量变成「靠红灯」的约束——你少提醒一次,系统就少烂一块。CI 门禁不在乎是人还是 AI 提交的代码,它一视同仁地拦。

---

五、对接 architecture-copilot:让规格「长出来」

写 ADR、AGENTS.md、适应度函数,听起来是额外负担。但它其实就是把你本来就该想清楚的判断(07 步骤⑧、08 的 ADR)落到纸上——而这件事,本身也能让 AI 帮你做。

architecture-copilot skill 正是干这个:把这套教程的知识,变成在 Claude Code / Cursor / Codex 里引导你一步步产出架构判断与规格的交互式 skill——帮你问对问题、写出 ADR、生成 AGENTS.md 的初稿。你负责判断,它负责把判断结构化成 AI 能遵守的规格。

强观点:规格即架构(spec is architecture)。 在 AI 时代,「把约束写清楚、写到 AI 读得到的地方」不是写文档的杂活,而是核心架构工作本身。因为:你写下的约束 = AI 产出的边界。约束写得含糊,AI 就在含糊处替你做主(且总是挑最省事的乐观路径)。 架构师的判断力,通过「规格」这个接口,变成了 AI 的行为约束。

---

🎯 随堂检验

🤔想让 AI 在每次写代码时都遵守「碰钱的操作必须幂等」,最有效的做法是?

• A每次开始对话时,在聊天框里口头提醒一句
• B把它写进项目根的 AGENTS.md / CLAUDE.md(AI 常驻读),并尽量补一个「缺幂等键就 fail」的 CI 检查强制兜底
• C相信模型足够聪明,会自己想到加幂等

🤔下面哪条 AGENTS.md 规则写得最有用?

• A编写高质量、可维护、遵循最佳实践的代码
• B所有外部调用必须设超时 + 指数退避重试(理由:依赖一定会抽风,见 12 章);❌ 禁止无超时的裸调用
• C尽量注意性能和安全

---

本章小结

• 判断不写下来等于没有:聊天里的口头约束会丢;AI 默认只给乐观路径,你没明说的约束它就不写。这是 08 章「为什么会丢失」在 AI 时代的升级版。
• 规格金字塔:ADR(人读的为什么,08)→ AGENTS.md / CLAUDE.md(AI 常驻读的规则)→ 适应度函数 / CI(14,机器强制)。能往下沉一层就别停在上层。
• 写好 AGENTS.md:具体可执行、带「为什么」、给反例(❌)、短而狠、随代码演进。它就是「写给 AI 的架构边界」。
• 能机器强制的别只写文档:文档靠自觉,CI 靠红灯;CI 不在乎代码是人还是 AI 写的。
• 规格即架构:把约束写清楚、写到 AI 读得到的地方,本身就是核心架构工作——这正是 architecture-copilot 要帮你做的事。

承上启下:规格管的是「事前把约束给到 AI」。但 AI 仍会产出不符合约束、或你没想到要约束的东西——所以还需要「事后逐条审」。下一章 24 · 审查清单:AI 产出默认缺什么,给你一张按进阶篇组织的生产级 review checklist:AI 的「乐观路径」默认漏掉哪些,你照着逐条补问。

---

相关链接

• 理论本体:17 · 大模型时代的架构判断(把判断喂给 AI)、08 · ADR 与演进(记录为什么)、14 · 演进与拆分(适应度函数)
• 案例来源:19 · 完整设计 / 20 · 演进剧本 里的取舍与 ADR,正是该写进 AGENTS.md 的素材
• 配套 skill:architecture-copilot · 记忆文件实例 Claude Code / Codex