CONTEXT.md 格式规范与领域建模实战：为 Agent 项目建立统一领域语言

CONTEXT.md 格式规范与领域建模实战为 Agent 项目建立统一领域语言【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills导读本文以 skills13/skills 仓库中domain-modeling技能配套的 CONTEXT 格式规范为核心系统讲解如何在代码库根目录编写和维护CONTEXT.md上下文词汇表与CONTEXT-MAP.md多上下文地图从而为 AI Agent 与开发者建立一份统一领域语言Ubiquitous Language。读完本文你将掌握 CONTEXT 文档的完整结构模板、四条编写铁律、单上下文与多上下文的判别规则以及这份格式在本仓库中如何被domain-modeling、grill-with-docs等技能实际消费与推断。背景为什么 Agent 项目需要一份领域词汇表在本仓库的 README.md 中作者 Matt Pocock 引用了 Eric Evans《领域驱动设计》中的观点当开发者与领域专家说着不同的语言沟通就会冗长低效。在 AI 编码时代这个问题被放大了——Agent 被丢进一个项目后只能边摸索边猜测术语于是用 20 个词才能说清楚 1 个词就能表达的意思。解决之道就是一份共享语言文档即CONTEXT.md。它帮助 Agent 解码项目中的行话带来三个直接收益变量、函数和文件使用共享语言命名保持一致性Agent 导航代码库更轻松Agent 用更精炼的语言思考节省 token。而CONTEXT-FORMAT.md这份文档正是规定这份词汇表应该长成什么样的规范文件。它是domain-modeling技能见 SKILL.md在解析术语、更新词汇表时强制遵循的书写格式。CONTEXT.md 的标准结构根据 CONTEXT-FORMAT.md 的Structure一节一份标准的CONTEXT.md结构如下# {Context Name} {One or two sentence description of what this context is and why it exists.} ## Language **Order**: {One or two sentence description of the term} _Avoid_: Purchase, transaction **Invoice**: A request for payment sent to a customer after delivery. _Avoid_: Bill, payment request **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account逐段拆解这个模板# {Context Name}上下文名称。在单上下文仓库中它就是项目名在多上下文仓库中它是某个限界上下文如 Ordering、Billing的名字。标题下方的描述用一到两句话说明这个上下文是什么、为什么存在让读者在阅读术语前先建立整体心智模型。## Language小节词汇表的正文逐条列出领域术语。每个术语的书写格式固定为三段加粗的术语名、一到两句话的定义、_Avoid_后列出需要避免的同义词。_Avoid_列表这是格式的灵魂——不仅告诉读者该用什么词还明确不该用什么词把容易引发歧义的近义词如 Order 对应的 Purchase、transaction直接钉死。编写 CONTEXT.md 的四条核心规则规则一要有主见Be opinionated当同一个概念存在多个候选词时必须挑出最好的一个写入术语定义把其余候选词全部放进_Avoid_列表。格式规范明确要求When multiple words exist for the same concept, pick the best one and list the others under_Avoid_.这份格式拒绝模棱两可——领域语言的目的是消除歧义而不是记录所有可能的说法。本仓库自己的 CONTEXT.md 就是一个示范它把 Issue tracker 定为规范术语_Avoid_列中明确排除了backlog manager、backlog backend、issue host三个候选词。规则二定义要精炼Keep definitions tight每个术语的定义最多一两句话并且要定义它是什么what it IS而不是它做什么what it does。示例中Invoice的定义是A request for payment sent to a customer after delivery.这是一个典型的是什么定义描述 Invoice 的本质身份一份付款请求而非罗列行为。反例则是用动作链描述术语例如当客户下单后系统向客户发送一份账单文件并更新应收账款状态——这种定义把行为细节塞进了词汇表违背了精炼原则。规则三只收录本项目特有的概念通用编程概念timeout、error types、utility patterns无论项目里用得多么频繁都不应该出现在CONTEXT.md中。在决定是否收录一个术语前先自问这是这个上下文独有的概念还是一个通用编程概念只有前者才属于词汇表。这条规则把CONTEXT.md和普通技术文档严格区分开它是领域词汇表不是编程字典。规则四出现自然聚类时使用小标题分组当术语之间自然形成聚类时用子标题subheadings分组如果所有术语属于单一连贯领域扁平列表也完全可以。例如一个订单系统可以把术语分为 Ordering、Fulfillment、Payments 三组每组下放各自的术语条目。单上下文与多上下文CONTEXT-MAP.md 的判别单上下文绝大多数仓库对于大多数仓库整个项目共享一套领域词汇此时只需在仓库根目录放一个CONTEXT.md即可/ ├── CONTEXT.md ├── docs/adr/ └── src/多上下文monorepo 或大型系统当项目拆分为多个限界上下文时根目录应放置一个CONTEXT-MAP.md列出所有上下文、它们的位置以及彼此的关系。格式规范给出了完整模板# Context Map ## Contexts - [Ordering](https://link.gitcode.com/i/9e8414c86c7dee8523f8b1f59258bc4d): receives and tracks customer orders - [Billing](https://link.gitcode.com/i/9e8414c86c7dee8523f8b1f59258bc4d): generates invoices and processes payments - [Fulfillment](https://link.gitcode.com/i/9e8414c86c7dee8523f8b1f59258bc4d): manages warehouse picking and shipping ## Relationships - **Ordering → Fulfillment**: Ordering emits OrderPlaced events; Fulfillment consumes them to start picking - **Fulfillment → Billing**: Fulfillment emits ShipmentDispatched events; Billing consumes them to generate invoices - **Ordering ↔ Billing**: Shared types for CustomerId and Money这份地图包含两个部分Contexts 列表每个条目链接到对应上下文自己的CONTEXT.md并附一句话职责描述方便快速导航。Relationships 关系图描述上下文之间的依赖与数据流。示例中用事件OrderPlaced、ShipmentDispatched表达异步协作用↔双向箭头表达共享类型CustomerId、Money。这份关系描述为后续 ADR 中的集成模式决策如通过领域事件而非同步 HTTP 通信提供了上下文基础。与文件布局的对应关系在 domain-modeling/SKILL.md 的 File structure 一节中多上下文仓库的典型布局是/ ├── CONTEXT-MAP.md ├── docs/ │ └── adr/ ← system-wide decisions ├── src/ │ ├── ordering/ │ │ ├── CONTEXT.md │ │ └── docs/adr/ ← context-specific decisions │ └── billing/ │ ├── CONTEXT.md │ └── docs/adr/注意其中的分工根目录的docs/adr/存放全局性架构决策而每个上下文目录下的docs/adr/存放上下文内决策。CONTEXT-MAP.md 负责把这两层决策的位置与领域词汇的位置统一组织起来。Skill 如何推断应用哪种结构domain-modeling技能在读取领域文档时会按如下顺序自动推断见 CONTEXT-FORMAT.md 的 Single vs multi-context repos 一节如果存在CONTEXT-MAP.md读取它以定位各上下文如果只有根目录的CONTEXT.md按单上下文处理如果两者都不存在则在第一个术语被解析时惰性创建根目录的CONTEXT.md当存在多个上下文时推断当前讨论主题属于哪个上下文若无法确定直接询问用户。从源码结构看这套推断逻辑与 setup-matt-pocock-skills/domain.md 中定义的消费规则完全一致该文件规定其他工程技能在探索代码库前应先读CONTEXT.md或CONTEXT-MAP.md及docs/adr/若文件不存在则静默跳过不主动创建——创建动作统一由domain-modeling在真正解析出术语时惰性完成。实战剖析本仓库自带的 CONTEXT.md 范例本仓库根目录的 CONTEXT.md 本身就是一个严格遵循上述格式的真实成品可以逐项对照规范验证结构合规包含# Matt Pocock Skills标题、两句话的项目描述以及## Language小节。术语条目完整如Issue tracker词条给出定义 The tool that hosts a repos issues: GitHub Issues, Linear, a local.scratch/markdown convention, or similar.并附_Avoid_: backlog manager, backlog backend, issue host。规则三的体现该词汇表只收录Issue tracker、Issue、Decision ticket、Triage role等本项目技能体系特有的概念没有收录任何通用编程术语。规则一的体现词条下方还设有 Flagged ambiguities 小节记录历史上被解决的歧义例如 backlog 曾被混用为工具与工作本体现已解决为统一术语Issue tracker。这个范例证明CONTEXT.md不是一份静态模板而是一份随项目演进持续修订的活文档。domain-modeling技能要求术语一被敲定就立刻更新 CONTEXT.md不要批量积压见 SKILL.md 的 Update CONTEXT.md inline而本仓库的 Flagged ambiguities 小节正是这种持续修订留下的轨迹。CONTEXT.md 的边界它只是词汇表不是规格书domain-modeling/SKILL.md 特别强调了一条铁律CONTEXT.mdshould be totally devoid of implementation details. Do not treatCONTEXT.mdas a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.CONTEXT.md中完全不得包含实现细节。它既不是规格书、不是草稿纸、也不是实现决策的仓库——它只是一份词汇表。需要记录实现决策时应当使用独立的 ADR架构决策记录其格式见 ADR-FORMAT.mdADR 存放于docs/adr/采用0001-slug.md顺序编号只有满足难以回退、脱离上下文令人费解、源于真实权衡三个条件时才值得创建。这条边界与 README 中引用的 Evans 观点一脉相承统一语言服务于对话与代码都源自同一个领域模型这一目标而把词汇与决策分开存放正是为了让词汇表保持纯粹、让 Agent 可以低成本地引用。总结CONTEXT-FORMAT.md是一份小而精的规范它把一个工程实践中最容易被忽视的问题——我们到底用什么词说话——变成了可复制、可检验的文档格式。要点回顾结构标题 上下文描述 ## Language术语小节每个术语含定义与_Avoid_列表四规则有主见地选词、精炼定义是什么而非做什么、只收领域特有概念、按自然聚类分组组织单上下文放根目录CONTEXT.md多上下文放CONTEXT-MAP.md 各上下文自己的CONTEXT.md推断domain-modeling技能按CONTEXT-MAP.md→ 根CONTEXT.md→ 惰性创建的顺序自动适配边界词汇表不承载实现细节决策归 ADR。遵循这份格式你的仓库就能像本仓库一样让每个进入的 Agent 和开发者用同一套语言思考——这正是降低 AI 协作成本、提升代码库可导航性的第一块基石。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考