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 来产,但规格、约束、验收标准是你的。问题是——该怎么给到 AI?
新手以为把约束给到 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 的五条纪律:
- 具体到可执行:不说注意安全,说清楚所有外部输入在入库前必须校验;用户内容当不可信(含提示注入)。
- 带上为什么:像 ADR 一样给理由——AI(和人)知道理由才不会在显得多余时把它删掉(呼应 08 章 那个删双写炸三周的开场)。
- 给反例(❌):明确禁止做什么比写应该做什么更管用——这正是堵住 AI 乐观路径默认值的地方。
- 短而狠:AI 的上下文窗口有限且按 token 计费(17 章 的上下文工程)。规则书是常驻成本,别写成小说;写最高频、最容易被违反的那几条。
- 随代码演进:过时的规则比没有更糟(它会主动误导 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 默认只给乐观路径,你没明说的约束它就不写。这是 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
💬 评论