项目共同语言

定义

项目共同语言 是团队与 AI Agent 围绕代码库、业务对象、实现流程、常见故障和决策语境共同建立的一套统一术语系统。

它不是普通的术语表，也不是单纯为了统一命名风格而写的一页词汇说明，而是一层工程化的共享语言层：团队成员和 Agent 在描述同一类对象、状态、问题和动作时，使用同一套可复用、可压缩、可指代的表达。

这层语言的核心作用，是把项目里原本只存在于少数人脑中的黑话、隐喻、上下文和经验判断显式化，让 Agent 不必在每次对话里重新猜意思，也让人类不必反复把长句翻译成背景说明。

在本文语境中的含义

在 Matt Pocock 公开的 skills 方法论语境里，项目共同语言 被视为治理 Agent 两类典型问题的关键手段之一：话太多 与 自作主张。

原因很直接：如果项目内已经存在一套团队默认理解、但没有被明确写出来的黑话和压缩表达，那么 Agent 每次接到任务时都要重新推断这些词背后的真实含义。模型一旦没有把握，就会倾向于说得更长、更保守，或者擅自脑补一个意思继续往下做。

因此，共同语言并不是修辞层面的优化，而是减少推断空间、降低歧义、提升执行精度的一种工程治理手段。

为什么需要建立共同语言

项目在长期演化中，几乎一定会形成内部黑话。

这些黑话可能指向某类业务实体，某个特定的数据流转过程，某种重复出现的故障模式，或者某种大家都懂但很难一句话讲清楚的实现状态。团队成员彼此熟悉时，这种表达能极大压缩沟通成本；但对 Agent 来说，如果这些词没有被显式定义，它每次都只能从上下文临时猜。

临时猜测会带来三个直接后果：

• 表达变长：因为模型不敢假设自己懂，只能用冗长描述覆盖多种可能含义。
• 表达不精确：它可能抓住了表面词义，却没有抓住项目里的特定义项。
• 产生误解：需求澄清、问题复现、工单指派和修复方案都可能建立在错误理解上。

这也是为什么共同语言会被放在“先审清楚要什么、建立共同语言、用测试闭环约束实现、定期防止代码库腐化”这一组方法里：它解决的是 Agent 进入项目上下文时最基础的语言对齐问题。

具体示例

文中的例子非常具体：原本团队需要描述的是“某节课在某个章节里被落到文件系统上生成实体文件时会出问题”。

这句话牵涉多个层次的信息：某节课、某个章节、落到文件系统、生成实体文件、并且在这个过程中出现问题。若每次都用完整自然语言重述，不仅长，而且不同人或不同 Agent 可能抓重点不同。

在建立了共同语言后，这类问题被统一压缩成一句话：物化级联出问题了。

这不是偷懒的简写，而是把一段项目内部已经稳定出现的结构、路径和错误模式，压成一个所有参与者都能解码的术语。

它带来的收益至少有三层：

• 长描述被压缩成短指令，表达明显变短。
• 团队与 Agent 说的是同一个词，不需要来回翻译自然语言版本和实现语义版本。
• 一旦这个术语在项目中稳定下来，后续需求、工单、诊断记录和代码讨论都能复用它。

关键机制

1. 把隐含语义显式化

共同语言首先要求把“大家平时都这么说，但没人正式定义过”的词，写成可共享的定义。

重点不是收集所有词，而是优先定义那些会反复出现、会影响判断、会决定下一步动作的词。

例如某类级联关系、某种物化过程、某种失败状态、某类工单类型、某个阶段性产物，这些都比泛泛的风格词更值得优先定义。

2. 让术语对应稳定对象或问题模式

一个有效的共同语言术语，不应只是好记的缩写，而应当稳定对应某个项目内对象、流程切片、故障模式或决策状态。

只有这样，Agent 才能把词映射到具体上下文，而不是把它当作模糊标签。

3. 允许高压缩表达

共同语言的价值之一就是压缩率。

原本需要几十个字才能交代清楚的问题，如果能被一个术语准确代替，那么需求传递、工单标题、对话上下文和调试记录都会显著变短，同时保留精度。

这也是它被用来治理 Agent“话太多”的原因之一：不是简单要求模型少说，而是给它更高密度、低歧义的表达单元。

4. 在多个环节复用

项目共同语言 不只服务于写文档。

它与前期需求澄清有关，因为需求里的核心对象和关键动作需要先被说准；它与工单拆分有关，因为拆出来的票如果没有统一术语，边界和依赖关系会很难描述；它与故障诊断有关，因为问题定位往往依赖对故障模式的快速命名；它也与任务交接有关，因为交接的本质就是把语义最小损耗地传给下一个执行者。

换句话说，它贯穿从想法形成到实现落地再到问题修复的多个阶段，而不是孤立的命名规范。

效果

建立 项目共同语言 后，最直接的效果包括：

• 缩短表达：长句可以压缩成稳定术语。
• 减少来回翻译：团队语言与 Agent 语言不再分裂。
• 提高任务交接效率：同一个词可以跨人、跨轮次、跨工单复用。
• 提高问题定位效率：常见故障模式有固定叫法后，排查入口更明确。
• 降低误解概率：Agent 不必每次重新猜项目黑话的意思。
• 改善需求澄清质量：讨论更容易从模糊描述收敛到明确对象和边界。

这些效果叠加后，能直接改善 Agent 协作中的两种常见体验问题：一是回复过长但信息密度不高，二是看似积极执行却在错误理解上越走越远。

细节与边界

它不是为了制造 jargon

共同语言的目标不是故意制造圈内黑话，更不是为了显得专业。

恰恰相反，它强调的是：术语要比原始说法更准确、更稳定、更可复用。如果一个词只是听起来酷，但不能稳定指向同一类对象或问题，那它就不是合格的共同语言。

它不是越多越好

不是把项目里所有口头习惯都收编进来，就叫建立了共同语言。

真正值得固化的，是那些高频、关键、容易歧义、会影响判断和执行结果的表达。过量术语反而会增加记忆负担，让 Agent 和人都更难掌握。

它必须能被 Agent 复用

如果某个词只有老成员能懂、没有定义、没有示例、没有适用边界，那么它仍然只是人类内部默契，还不算工程化的共同语言。

要让 Agent 真正受益，术语至少需要能被明确解释，最好还能和典型场景、常见错误、上下游关系一起出现。

它服务于协作，不替代分析

共同语言能压缩表达，但不能代替需求分析、技术判断和问题复现。