共享语言

定义

共享语言是指在一个项目中，专门整理并文档化的一套术语体系，用来让开发者、领域专家与 AI 代理围绕同一套领域模型说话和写代码。

在本文语境里，它被明确提出为解决“代理过于冗长”这一问题的修复方式：代理刚进入项目时，往往需要一边做事一边猜项目黑话和业务术语，于是经常“20 个词才能说清 1 个概念”。共享语言的作用，就是把这些术语提前定义成可复用的短语，让代理能直接 decode 项目里的 jargon，而不是每次都用长句临时解释。

在本文档中的语境

原文把共享语言放在“#2: The Agent Is Way Too Verbose”这一问题下讨论。这里的核心判断是：项目一开始时，开发者与他们服务的领域专家通常并不说同一种语言；作者在与 agents 协作时感受到了同样的张力，因为 agents 也是被直接丢进项目里，再被要求边做边理解术语。

因此，作者给出的修复方式不是单纯要求代理“简洁一点”，而是建立一份文档，让代理能读懂项目内部的术语系统。原文直接将其描述为“a document that helps agents decode the jargon used in the project”。

这一定义说明，共享语言首先不是某个模型参数、提示词技巧或编码规范，而是一种面向项目语义层的文档资产。它解决的是术语压缩、语义对齐和表达复用问题。

关键机制或组成

1. 以领域模型为中心压缩表达

原文引用了 Eric Evans 在 领域驱动设计 中的表述：开发者之间的对话，以及代码中的表达，都应当来自同一套领域模型。共享语言的关键机制正是把“业务概念”压缩成可反复调用的术语。

文中的示例非常具体：

• Before："There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"
• After："There's a problem with the materialization cascade"

这不是单纯把句子写短，而是把一整串上下文、约束和对象关系，折叠进一个项目内已经定义好的术语 materialization cascade。一旦这个术语被文档化，后续每次提到它，代理就不需要重新铺陈“course / section / lesson / file system spot”这一长串解释。

2. 通过文档帮助代理解码项目黑话

共享语言在本文中被明确描述为一份文档。原文提到的例子是一份 CONTEXT.md，说明这种语言通常不是口头约定，而是项目中的可读文档。

它的作用包括：

• 解释项目内已经形成的 jargon
• 为复杂概念提供统一叫法
• 让代理在后续对话、修改建议和代码实现中反复复用这些叫法
• 减少每个会话都重复定义概念的成本

作者特别强调这种简洁性会“session after session”持续产生收益，也就是收益不是一次性的，而是在多轮协作中不断累积。

3. 反向影响代码命名

共享语言不仅用于对话，还会进入代码表达层。原文明确列出其额外收益之一：

• 变量、函数和文件会使用共享语言进行一致命名

这意味着共享语言不是只影响 issue 描述、讨论记录或 prompt，而是会沉淀到代码符号中。一个术语一旦被项目确认，它就更可能同时出现在：

• 需求讨论中
• 代理与人的对话中
• 变量名中
• 函数名中
• 文件名中

这种一致性会进一步降低代理在代码库中搜索、定位和迁移语义时的成本。

4. 降低代理的 token 开销

原文还指出，共享语言会让代理“spend fewer tokens on thinking”。其原因不是模型被修改了，而是语言被压缩了：同一个概念如果有一个简洁、稳定、被文档定义过的名字，代理在理解、计划和表达时就不必反复展开长描述。

因此，共享语言对 token 的节约至少体现在两层：

• 输入侧节约：人类不必每次都用长句解释旧概念
• 推理与输出侧节约：代理内部思考和最终表达都可以借助更短、更稳的术语

这也是它被视为不仅减少冗长，而且能提升协作效率的重要原因。

细节与边界

它主要解决的是“术语对齐”，不是一切工程问题

在原文结构中，共享语言对应的是“代理太啰嗦”这一类问题；而“代码根本跑不起来”则被放到下一节，通过 tdd、静态类型、浏览器访问和自动化测试等反馈回路来解决。

这说明共享语言的边界很明确：

• 它擅长解决表达过长、术语不统一、语义难以压缩的问题
• 它不能替代测试、调试、类型系统和运行反馈
• 即使你和代理已经靠共享语言对齐了要做什么，代码仍然可能写得很差，这时需要别的机制介入

换言之，共享语言改善的是“理解与表述层”的质量，不直接保证“执行与验证层”的正确性。

它不是单纯的简写表，而是项目语义基础设施

如果只是随手发明一些缩写，但没有让代理真正理解这些词背后的领域含义，那么这种做法并不能构成本文所说的共享语言。原文强调它来自同一套 domain model，因此共享语言的前提是：术语必须能稳定映射到项目中的对象、关系、流程或决策。

因此，好的共享语言通常具有几个特征：

• 术语背后有清晰定义，而不是含糊口号
• 相同概念在不同会话里应尽量使用相同说法
• 术语不仅能说得短，还能指导代码中的命名与结构
• 复杂且难解释的决策可以被额外文档化，而不是只留在临时对话里

在本文中，它与文档化工作流绑定出现

原文明确说明，这一做法已经被内建进 grill-with-docs：它不仅是一轮 grilling session，还会帮助你与 AI 建立共享语言，并把难以解释的决策记录进 ADR。

这说明共享语言并不是一次性写完的词汇表，而更像一种伴随式文档实践：

• 在开始改动之前先对齐
• 通过追问把概念打磨清楚
• 把稳定术语写入文档
• 把难讲清的设计决定沉淀为 ADR

作者甚至把它称为整个仓库里“可能最酷的技术之一”，并明确建议实际去试。这一评价侧面说明，在其方法体系里，共享语言不是边角优化，而是高杠杆实践。

与其他条目的关系

• grill-with-docs：共享语言在原文中被直接说成内建于这个 skill 中；它通过 grilling session 帮助人与 AI 建立术语共识，并把难说明的决定写入 ADR。
• grill-me：/grill-with-docs 被描述为与其相同但“加了更多好东西”的版本，因此共享语言可以理解为比基础 grilling 更进一步的文档化对齐能力。
• User-invoked skills：共享语言并非纯理论，而是通过显式调用的 skill 落地到项目协作流程中。
• Productivity：共享语言直接提升会话效率、命名一致性和导航效率，属于典型的高收益生产力实践。