第 3 章：共享语言
出处
来源：domain-modeling · writing-for-agents · to-questionnaire · 状态：已读
一句话
CONTEXT.md 是词汇表，不是规格；架构决策记录只收「难反悔、不写会让人奇怪、真有过取舍」的决定。 其余已拍的板，只活在这场追问里，要靠下一章的规格接住。
核心概念
主动建模，不是「读一下词汇表」
domain-modeling 自己划界：读 CONTEXT.md 好用词，是任何 skill 都该有的一行习惯；本 skill 是在改模型——顶词、编边界情景、词一结晶就写下来。
一场会话里它做五件事：
- 对照词汇表顶回去。 「词汇表里 cancellation 是 X，你刚才像在说 Y。哪个算？」
- 收模糊词。 「你说的 account，是 Customer 还是 User？」
- 用具体情景压关系。 编边界例子，逼你说清概念之间的线。
- 跟代码对质。 「代码取消的是整张 Order，你刚说可以部分取消。谁对？」
- 立刻改
CONTEXT.md。 不攒。按CONTEXT-FORMAT.md写。
文件懒创建：第一个词拍板才建 CONTEXT.md，第一份决策记录才建 docs/adr/。多数仓库一份根词汇表；根上有 CONTEXT-MAP.md 才是多上下文，每个上下文自己的词汇表和决策记录。
词汇表长什么样
格式本身就是纪律：
**Order**:
{一两句：它是什么}
_Avoid_: Purchase, transaction规则：
- 有立场。 一词多词并存时，选一个，其余进
_Avoid_ - 定义要短。 一两句。写它是什么，不写它做什么
- 只收这个项目自己的词。 timeout、错误类型这类通用编程概念不进表，即使用得很多
Matt 自己这套 skill 仓库的 CONTEXT.md 就是样本：Issue tracker / Issue / Decision ticket / Triage role，每个都写了 _Avoid_。曾经「backlog」同时指工具和里面的活，后来拆开：工具叫 Issue tracker，「backlog」不再当领域词。
CONTEXT.md 必须不含实现细节。不当规格、不当草稿、不当实现决定的仓库。它是词汇表，别的都不是。
决策记录的三道闸，必须同时过
只在三件事都成立时才提议写架构决策记录：
- 难反悔：以后改主意的代价是真的
- 不写会让人奇怪：后人会问「为什么要这样」
- 真有过取舍：有过真正的备选，你为具体理由挑了一个
缺一道就跳过。格式可以是一段话：背景、决定、为什么。编号 docs/adr/0001-slug.md。可选的 Status / Considered Options / Consequences 只在真有信息量时才加。
够格的例子：单体还是多包、上下文之间用领域事件而不是同步 HTTP、换起来要一个季度的技术、谁拥有 Customer 数据、故意不用 ORM、代码里看不见的合规约束。不够格的：此刻不值得做、显而易见的那条路、容易改回去的选择。
一场追问产出零份决策记录，是按设计在工作。副作用：大量已拍的板（顺序保证、反向需求、数字默认值）只活在窗口里。文档把这写成最实质性的公开抱怨——缓解办法是同一场对话接着 /to-spec，并且自己把规格对着答案读一遍，不要假定它写全了。
决定卡在别人脑子里：问卷，不问主题
/to-questionnaire 处理的是追问问不到的那种知识：你缺的那截在另一个人那里。关键句：追问的是「怎么送出」，不是主题本身。 你永远答得了的是：送给谁、你需要带回什么。问卷上的问题瞄准的是对方知道而你不知道的那截。
两问之后写成 to-questionnaire-<slug>.md：目的、从谁到谁、答案怎么用、一段定向上下文、按主题分组、每问一个意思、问下面直接留答、可能被敷衍的才加一行「为什么要问」。异步可能只有一轮，所以最重要的放前面。
给 agent 写文档：两笔预算，一把梯子
writing-for-agents 是写 skill、AGENTS.md / CLAUDE.md、以及任何靠指针够到的文档时的共用参考。包装不同，写法相同：同一套杠杆让每次跑的是同一套过程，而不是同一份输出。
两笔预算：
- 上下文负载：永远在窗口里的东西（
AGENTS.md一行、skill 的 description），每回合都花钱，不论开不开火 - 认知负载：人要记得有哪些文档、何时去拿。人是索引。这不是要最小化的成本，是人保有判断权的代价
上下文指针同时做两件事：材料是什么，以及哪些分支该去拿它。弱指针后面挂必须读的材料，是方差 bug：先改措辞，改不好再内联。
信息梯子：文内步骤 → 文内参考 → 披露出去的参考（另文件，指针触发才加载）。渐进披露主要不是省 token，是保护梯子。分支是最干净的测试：所有分支都要的内联，只有部分分支才走的推到指针后面。
完成标准有两个旋钮：清楚（agent 分得清完没完；含糊的「理解到位」会提前收工）和分量（「每个改过的模型都交代了」逼出来的是真挖，不是「列一份变更」）。最强的标准同时可核对、可穷尽。
两个连带判断：
- 引导词用模型预训练里已有的压缩概念（
tracer bullets、fog of war、tight、red），不要自造再花定义 token。否定是失败模式：「别想大象」把禁止的行为拖进上下文。写正向目标。 - 环境也是真源。 文档复述
package.json脚本，是一份缓存；只有查找很贵时才配得上这段负载。惯例、选择的理由、配置不肯承认的坑，才该写。
关键洞察
- 词汇表压缩的是人与人、人与 agent 的通信，不一定压缩模型的推理。 文档自己记下最锋利的反驳：一个词和它的白话展开，对模型常常是同一结果。即便如此，词汇表仍值——价值在共享它的人。
- 三道闸是在防「什么都写成决策记录」。 记录一多，下一场调查就不敢动真决定；记录太少，窗口一清，精确数字就软成散文。规格接的是中间那截。
- 给 agent 写文档的核心张力：披露太少，顶层膨胀；披露太多，把 agent 真需要的藏起来。 这和 Cookbooks 第 7 章的三级展开是同一判断，用在过程文档而不是 xlsx skill。
个人思考
对照 构建 Claude Code 的经验：我们如何使用 Skills：宝玉那篇说好 skill 是可执行工作包。Matt 补了一层更窄的要求——工作包内部的词必须是项目自己的，而且词的权威位置只有一处。下一章把这场追问收成能活过清空窗口的规格，再切成一张新窗口能做完的工单。