为 Agent 工程技能组织领域文档CONTEXT.md、CONTEXT-MAP.md 与 ADR 的消费规范与实战落地【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills导读本文基于setup-matt-pocock-skills技能包中的 domain.md 种子文档系统讲解一套 Agent 工程技能triage、wayfinder、to-spec、to-tickets、grill-with-docs等在探索代码库时应如何消费仓库的领域文档从探索前必读的CONTEXT.md/CONTEXT-MAP.md/docs/adr/到单上下文与多上下文两种仓库布局再到术语表词汇纪律与 ADR 冲突标记规则。读完本文你将掌握为任意仓库搭建领域文档消费约定、让 Agent 在改造代码前先读懂项目通用语言的完整方案并理解这些规则与domain-modeling、grill-with-docs、improve-codebase-architecture等技能之间的协作机制。一、domain.md 在技能包中的定位在 setup-matt-pocock-skills/SKILL.md 定义的初始化流程中setup-matt-pocock-skills会在每个仓库下产出三类配置产物写入docs/agents/issue-tracker.md问题跟踪器在哪里GitHub / GitLab / 本地 Markdown / 其他triage-labels.md五个标准分流角色的实际标签字符串domain.md领域文档的消费规则与布局约定。其中 domain.md 本身是写入docs/agents/domain.md的种子模板它的核心命题是当工程技能需要探索代码库时应该如何读取仓库里的领域文档。它不是教你怎么写领域模型而是规定读之前先看什么、文件缺失时怎么办、输出时用谁的词汇、发现 ADR 冲突如何表态。该技能在 SKILL.md 中被称为prompt-driven skill, not a deterministic script——它先探索、再向用户展示发现并逐节确认、最后写入因此docs/agents/domain.md的内容是可被用户现场编辑的约定而不是写死的脚本。二、探索前必读三类领域文档domain.md规定工程技能在探索代码库时动手前应先读取以下文件优先级文件说明1仓库根目录的CONTEXT.md项目术语表glossary定义领域概念的标准词汇2仓库根目录的CONTEXT-MAP.md若存在上下文地图指向每个上下文各自的CONTEXT.md需逐一读取与当前主题相关的部分3docs/adr/架构决策记录读取即将工作的领域相关的 ADR3多上下文src/context/docs/adr/上下文范围内的决策记录与全局 ADR 并存以本仓库为例根目录的 CONTEXT.md 就展示了这套约定在真实仓库中的样子它包含Language语言/术语表、Relationships关系、Flagged ambiguities已标记的歧义三部分定义了Issue tracker、Issue、Decision ticket、Triage role等术语并为每个术语列出_Avoid_的禁用词如 backlog manager、backlog backend。工程技能在输出 issue 标题、重构提案、假设或测试名时都要复用这套词汇。关于 ADR 的格式细节可参考 ADR-FORMAT.mdADR 存放在docs/adr/采用顺序编号0001-slug.md、0002-slug.md模板极简——一个标题加 13 句话上下文、决定、理由可选Statusfrontmatter、Considered Options与Consequences章节。三、缺失即静默惰性创建原则domain.md有一个容易被忽视但极其重要的规则If any of these files dont exist,proceed silently. Dont flag their absence; dont suggest creating them upfront.也就是说当CONTEXT.md、CONTEXT-MAP.md或docs/adr/不存在时Agent 应静默继续不要抱怨缺失也不要主动建议先创建它们。这背后的机制是惰性创建lazy creation/domain-modeling技能在第一个术语被敲定时才创建CONTEXT.md在第一条 ADR 真正达标时才创建docs/adr/目录这些创建动作通过/grill-with-docs与/improve-codebase-architecture触发。这一点在 domain-modeling/SKILL.md 中被明确为 Create files lazily: only when you have something to write并在 CONTEXT-FORMAT.md 中进一步说明若CONTEXT-MAP.md存在则按多上下文处理若只有根CONTEXT.md则为单上下文若两者都不存在则在首个术语被解决时惰性创建根CONTEXT.md。这一设计刻意避免了脚手架前置没有新术语被敲定之前仓库里就不该有领域文档的空壳。因此工程技能探索仓库时不应把文档缺失当作需要上报或补救的问题。四、单上下文与多上下文两套文件布局domain.md给出了两种仓库布局工程技能应根据是否存在CONTEXT-MAP.md来区分。单上下文仓库绝大多数仓库——一个根CONTEXT.md加一个全局docs/adr// ├── CONTEXT.md ├── docs/adr/ │ ├── 0001-event-sourced-orders.md │ └── 0002-postgres-for-write-model.md └── src/多上下文仓库存在根CONTEXT-MAP.md——根CONTEXT-MAP.md指向各上下文自己的CONTEXT.md全局决策与上下文内决策分置/ ├── CONTEXT-MAP.md ├── docs/adr/ ← system-wide decisions └── src/ ├── ordering/ │ ├── CONTEXT.md │ └── docs/adr/ ← context-specific decisions └── billing/ ├── CONTEXT.md └── docs/adr/两套布局的判别信号在 setup-matt-pocock-skills/SKILL.md 的探索步骤中被明确列出pnpm-workspace.yaml、package.json中的workspaces字段、或带有独立src/的已填充packages/*是 monorepo多上下文信号这些信号缺失即默认单上下文which is almost every repo。多上下文的CONTEXT-MAP.md具体格式见 CONTEXT-FORMAT.md 中的示例Contexts部分用相对链接列出各上下文及其说明Relationships部分用带箭头的行描述上下文之间的交互如 Ordering → Fulfillment: Ordering emitsOrderPlacedevents; Fulfillment consumes them to start picking。五、术语表词汇纪律用 CONTEXT.md 的词不要自己发明domain.md的第三条规则是词汇纪律When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined inCONTEXT.md. Dont drift to synonyms the glossary explicitly avoids.这要求所有技能在输出领域概念时严格使用CONTEXT.md中定义的术语而不要漂移到术语表明确规避的同义词。这条规则与domain-modeling技能的核心主张一脉相承——domain-modeling/SKILL.md 中写道MerelyreadingCONTEXT.mdfor vocabulary is not this skill: thats a one-line habit any skill can do仅仅读取词汇不是 domain-modeling那是一行习惯。也就是说词汇消费是每个技能的基本义务词汇生产才是 domain-modeling 的职责。一个可对照的现实范例是本仓库根目录的 CONTEXT.md它的Language章节定义了Issue tracker并_Avoid_: backlog manager, backlog backend, issue host、Issue_Avoid_: ticket除非引用外部系统或指 Decision ticket、Decision ticket、Triage role等术语Flagged ambiguities章节则记录了 backlog 一词被拆分为工具与工作主体的历史歧义及最终裁定。这正是CONTEXT.mdis a glossary and nothing else 的样板——CONTEXT-FORMAT.md 对格式的硬性要求包括定义要精炼一至两句定义它是什么而非做什么、要敢于取舍同义词放入_Avoid_、只收录项目专属概念通用编程概念不收录。当需要的概念不在术语表中时domain.md给出了判断信号要么你在发明项目不用的语言应重新考虑要么确实存在真实缺口记下来交给/domain-modeling。这避免了 Agent 在输出中擅自创造词汇造成听起来正确其实并非项目语言的污染。六、ADR 冲突标记显式暴露绝不静默覆盖domain.md的最后一条规则处理输出与既有 ADR 冲突的情形If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:Contradicts ADR-0007 (event-sourced orders), but worth reopening because…即当输出与既有 ADR 矛盾时必须显式标记冲突而非静默推翻。推荐的写法是在输出前用引用块说明这与 ADR-0007 冲突但值得重新讨论因为……。这保证了 ADR 作为难以逆转决策记录的权威性——即使要推翻也要以可见的、可讨论的方式提出而不是让 Agent 悄悄产生与已记录决策相悖的代码。这与 ADR 的记录门槛相互呼应ADR-FORMAT.md 规定只有同时满足三条才值得写 ADR——难以逆转、脱离上下文会令人惊讶、真实权衡的结果。正因为每条 ADR 都代表一个高昂的决策成本所以当新输出与之冲突时项目才需要强制显式标记防止下一位工程师顺手修正掉刻意为之的设计。七、与相关技能的协作链路domain.md不是孤立存在的约定它服务于整个工程技能链。其核心协作关系如下/domain-modelingskills/engineering/domain-modeling/领域文档的生产者负责在术语敲定、ADR 达标时惰性创建CONTEXT.md与docs/adr/domain.md中缺失即静默的规则正是为了让出这条生产链路。/grill-with-docsskills/engineering/grill-with-docs/单会话访谈技能驱动domain-modeling在会话中实时把术语写进CONTEXT.md、把达标决策写成 ADR。/improve-codebase-architectureskills/engineering/improve-codebase-architecture/在架构改进过程中沉淀词汇与决策同样触发domain-modeling。/wayfinder、/triage等作为领域文档的消费者探索代码库时遵循domain.md的读取规则与词汇纪律。事实上domain-modeling/docs/engineering/domain-modeling.md 中的文档也印证了这一点domain-modeling是model-invoked reference更多时候运行在grill-with-docs、wayfinder、triage等技能之下同时它记录了domain.md的一个实际使用场景——domain-modeling不检索 issue tracker因此在关闭的 issue 里早已论证并刻意解决的命名冲突会被当作新问题浮出水面现有缓解方案正是把你自己的指令写进docs/agents/domain.md技能们本来就会读它。这恰好说明domain.md这份种子文档写入docs/agents/domain.md后会成为各技能实际消费的运行时约定。八、实践清单接入这套领域文档约定综合 setup-matt-pocock-skills/SKILL.md 与 domain.md在仓库中落地这套领域文档消费约定的步骤是运行/setup-matt-pocock-skills一次性初始化它会探索仓库现状并向你逐节确认 issue tracker、triage 标签与领域文档布局领域文档布局默认选单上下文根CONTEXT.mddocs/adr/仅在存在 monorepo 信号时提供多上下文选项根CONTEXT-MAP.md 各上下文CONTEXT.md确认后将domain.md种子模板写入docs/agents/domain.md连同issue-tracker.md、triage-labels.md一起并在CLAUDE.md/AGENTS.md中登记## Agent skills小节此后各工程技能探索代码库时先读CONTEXT.md及CONTEXT-MAP.md指向的每个相关CONTEXT.md与相关docs/adr/文件缺失则静默继续输出命名一律使用术语表词汇输出与 ADR 冲突时显式标记。这套约定的价值在于它为Agent 在改造代码前先理解项目的通用语言提供了确定性的文件路径与读取顺序同时用惰性创建 缺失静默 冲突显式三条规则避免了文档空壳、虚假词汇和静默决策覆盖三类典型问题——这正是工程技能在真实仓库中可靠运行的领域基础。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 为 Agent 工程技能组织领域文档：CONTEXT.md、CONTEXT-MAP.md 与 ADR 的消费规范与实战落地
为 Agent 工程技能组织领域文档CONTEXT.md、CONTEXT-MAP.md 与 ADR 的消费规范与实战落地【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills导读本文基于setup-matt-pocock-skills技能包中的 domain.md 种子文档系统讲解一套 Agent 工程技能triage、wayfinder、to-spec、to-tickets、grill-with-docs等在探索代码库时应如何消费仓库的领域文档从探索前必读的CONTEXT.md/CONTEXT-MAP.md/docs/adr/到单上下文与多上下文两种仓库布局再到术语表词汇纪律与 ADR 冲突标记规则。读完本文你将掌握为任意仓库搭建领域文档消费约定、让 Agent 在改造代码前先读懂项目通用语言的完整方案并理解这些规则与domain-modeling、grill-with-docs、improve-codebase-architecture等技能之间的协作机制。一、domain.md 在技能包中的定位在 setup-matt-pocock-skills/SKILL.md 定义的初始化流程中setup-matt-pocock-skills会在每个仓库下产出三类配置产物写入docs/agents/issue-tracker.md问题跟踪器在哪里GitHub / GitLab / 本地 Markdown / 其他triage-labels.md五个标准分流角色的实际标签字符串domain.md领域文档的消费规则与布局约定。其中 domain.md 本身是写入docs/agents/domain.md的种子模板它的核心命题是当工程技能需要探索代码库时应该如何读取仓库里的领域文档。它不是教你怎么写领域模型而是规定读之前先看什么、文件缺失时怎么办、输出时用谁的词汇、发现 ADR 冲突如何表态。该技能在 SKILL.md 中被称为prompt-driven skill, not a deterministic script——它先探索、再向用户展示发现并逐节确认、最后写入因此docs/agents/domain.md的内容是可被用户现场编辑的约定而不是写死的脚本。二、探索前必读三类领域文档domain.md规定工程技能在探索代码库时动手前应先读取以下文件优先级文件说明1仓库根目录的CONTEXT.md项目术语表glossary定义领域概念的标准词汇2仓库根目录的CONTEXT-MAP.md若存在上下文地图指向每个上下文各自的CONTEXT.md需逐一读取与当前主题相关的部分3docs/adr/架构决策记录读取即将工作的领域相关的 ADR3多上下文src/context/docs/adr/上下文范围内的决策记录与全局 ADR 并存以本仓库为例根目录的 CONTEXT.md 就展示了这套约定在真实仓库中的样子它包含Language语言/术语表、Relationships关系、Flagged ambiguities已标记的歧义三部分定义了Issue tracker、Issue、Decision ticket、Triage role等术语并为每个术语列出_Avoid_的禁用词如 backlog manager、backlog backend。工程技能在输出 issue 标题、重构提案、假设或测试名时都要复用这套词汇。关于 ADR 的格式细节可参考 ADR-FORMAT.mdADR 存放在docs/adr/采用顺序编号0001-slug.md、0002-slug.md模板极简——一个标题加 13 句话上下文、决定、理由可选Statusfrontmatter、Considered Options与Consequences章节。三、缺失即静默惰性创建原则domain.md有一个容易被忽视但极其重要的规则If any of these files dont exist,proceed silently. Dont flag their absence; dont suggest creating them upfront.也就是说当CONTEXT.md、CONTEXT-MAP.md或docs/adr/不存在时Agent 应静默继续不要抱怨缺失也不要主动建议先创建它们。这背后的机制是惰性创建lazy creation/domain-modeling技能在第一个术语被敲定时才创建CONTEXT.md在第一条 ADR 真正达标时才创建docs/adr/目录这些创建动作通过/grill-with-docs与/improve-codebase-architecture触发。这一点在 domain-modeling/SKILL.md 中被明确为 Create files lazily: only when you have something to write并在 CONTEXT-FORMAT.md 中进一步说明若CONTEXT-MAP.md存在则按多上下文处理若只有根CONTEXT.md则为单上下文若两者都不存在则在首个术语被解决时惰性创建根CONTEXT.md。这一设计刻意避免了脚手架前置没有新术语被敲定之前仓库里就不该有领域文档的空壳。因此工程技能探索仓库时不应把文档缺失当作需要上报或补救的问题。四、单上下文与多上下文两套文件布局domain.md给出了两种仓库布局工程技能应根据是否存在CONTEXT-MAP.md来区分。单上下文仓库绝大多数仓库——一个根CONTEXT.md加一个全局docs/adr// ├── CONTEXT.md ├── docs/adr/ │ ├── 0001-event-sourced-orders.md │ └── 0002-postgres-for-write-model.md └── src/多上下文仓库存在根CONTEXT-MAP.md——根CONTEXT-MAP.md指向各上下文自己的CONTEXT.md全局决策与上下文内决策分置/ ├── CONTEXT-MAP.md ├── docs/adr/ ← system-wide decisions └── src/ ├── ordering/ │ ├── CONTEXT.md │ └── docs/adr/ ← context-specific decisions └── billing/ ├── CONTEXT.md └── docs/adr/两套布局的判别信号在 setup-matt-pocock-skills/SKILL.md 的探索步骤中被明确列出pnpm-workspace.yaml、package.json中的workspaces字段、或带有独立src/的已填充packages/*是 monorepo多上下文信号这些信号缺失即默认单上下文which is almost every repo。多上下文的CONTEXT-MAP.md具体格式见 CONTEXT-FORMAT.md 中的示例Contexts部分用相对链接列出各上下文及其说明Relationships部分用带箭头的行描述上下文之间的交互如 Ordering → Fulfillment: Ordering emitsOrderPlacedevents; Fulfillment consumes them to start picking。五、术语表词汇纪律用 CONTEXT.md 的词不要自己发明domain.md的第三条规则是词汇纪律When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined inCONTEXT.md. Dont drift to synonyms the glossary explicitly avoids.这要求所有技能在输出领域概念时严格使用CONTEXT.md中定义的术语而不要漂移到术语表明确规避的同义词。这条规则与domain-modeling技能的核心主张一脉相承——domain-modeling/SKILL.md 中写道MerelyreadingCONTEXT.mdfor vocabulary is not this skill: thats a one-line habit any skill can do仅仅读取词汇不是 domain-modeling那是一行习惯。也就是说词汇消费是每个技能的基本义务词汇生产才是 domain-modeling 的职责。一个可对照的现实范例是本仓库根目录的 CONTEXT.md它的Language章节定义了Issue tracker并_Avoid_: backlog manager, backlog backend, issue host、Issue_Avoid_: ticket除非引用外部系统或指 Decision ticket、Decision ticket、Triage role等术语Flagged ambiguities章节则记录了 backlog 一词被拆分为工具与工作主体的历史歧义及最终裁定。这正是CONTEXT.mdis a glossary and nothing else 的样板——CONTEXT-FORMAT.md 对格式的硬性要求包括定义要精炼一至两句定义它是什么而非做什么、要敢于取舍同义词放入_Avoid_、只收录项目专属概念通用编程概念不收录。当需要的概念不在术语表中时domain.md给出了判断信号要么你在发明项目不用的语言应重新考虑要么确实存在真实缺口记下来交给/domain-modeling。这避免了 Agent 在输出中擅自创造词汇造成听起来正确其实并非项目语言的污染。六、ADR 冲突标记显式暴露绝不静默覆盖domain.md的最后一条规则处理输出与既有 ADR 冲突的情形If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:Contradicts ADR-0007 (event-sourced orders), but worth reopening because…即当输出与既有 ADR 矛盾时必须显式标记冲突而非静默推翻。推荐的写法是在输出前用引用块说明这与 ADR-0007 冲突但值得重新讨论因为……。这保证了 ADR 作为难以逆转决策记录的权威性——即使要推翻也要以可见的、可讨论的方式提出而不是让 Agent 悄悄产生与已记录决策相悖的代码。这与 ADR 的记录门槛相互呼应ADR-FORMAT.md 规定只有同时满足三条才值得写 ADR——难以逆转、脱离上下文会令人惊讶、真实权衡的结果。正因为每条 ADR 都代表一个高昂的决策成本所以当新输出与之冲突时项目才需要强制显式标记防止下一位工程师顺手修正掉刻意为之的设计。七、与相关技能的协作链路domain.md不是孤立存在的约定它服务于整个工程技能链。其核心协作关系如下/domain-modelingskills/engineering/domain-modeling/领域文档的生产者负责在术语敲定、ADR 达标时惰性创建CONTEXT.md与docs/adr/domain.md中缺失即静默的规则正是为了让出这条生产链路。/grill-with-docsskills/engineering/grill-with-docs/单会话访谈技能驱动domain-modeling在会话中实时把术语写进CONTEXT.md、把达标决策写成 ADR。/improve-codebase-architectureskills/engineering/improve-codebase-architecture/在架构改进过程中沉淀词汇与决策同样触发domain-modeling。/wayfinder、/triage等作为领域文档的消费者探索代码库时遵循domain.md的读取规则与词汇纪律。事实上domain-modeling/docs/engineering/domain-modeling.md 中的文档也印证了这一点domain-modeling是model-invoked reference更多时候运行在grill-with-docs、wayfinder、triage等技能之下同时它记录了domain.md的一个实际使用场景——domain-modeling不检索 issue tracker因此在关闭的 issue 里早已论证并刻意解决的命名冲突会被当作新问题浮出水面现有缓解方案正是把你自己的指令写进docs/agents/domain.md技能们本来就会读它。这恰好说明domain.md这份种子文档写入docs/agents/domain.md后会成为各技能实际消费的运行时约定。八、实践清单接入这套领域文档约定综合 setup-matt-pocock-skills/SKILL.md 与 domain.md在仓库中落地这套领域文档消费约定的步骤是运行/setup-matt-pocock-skills一次性初始化它会探索仓库现状并向你逐节确认 issue tracker、triage 标签与领域文档布局领域文档布局默认选单上下文根CONTEXT.mddocs/adr/仅在存在 monorepo 信号时提供多上下文选项根CONTEXT-MAP.md 各上下文CONTEXT.md确认后将domain.md种子模板写入docs/agents/domain.md连同issue-tracker.md、triage-labels.md一起并在CLAUDE.md/AGENTS.md中登记## Agent skills小节此后各工程技能探索代码库时先读CONTEXT.md及CONTEXT-MAP.md指向的每个相关CONTEXT.md与相关docs/adr/文件缺失则静默继续输出命名一律使用术语表词汇输出与 ADR 冲突时显式标记。这套约定的价值在于它为Agent 在改造代码前先理解项目的通用语言提供了确定性的文件路径与读取顺序同时用惰性创建 缺失静默 冲突显式三条规则避免了文档空壳、虚假词汇和静默决策覆盖三类典型问题——这正是工程技能在真实仓库中可靠运行的领域基础。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考