Reactive Resume 多上下文领域文档体系：Agent Skills 如何消费 CONTEXT-MAP.md、CONTEXT.md 与 ADR

Reactive Resume 在 docs/agents/domain.md 中定义了一套「多上下文领域文档（domain docs）」体系，规定工程类 Agent 技能（engineering skills）在动手改代码之前应如何读取、如何使用本仓库的领域文档与架构决策记录（ADR）。本文完整继承该文档的读取顺序、文件结构、术语规范与 ADR 冲突处理规则，并结合仓库中已落地的 ADR-0001、ADR-0002 以及 AGENTS.md 中的边界约束，说明这套体系在当前代码库中的真实落地状态与使用方式。

一、这份文档的定位：Agent 技能与领域文档之间的消费协议

docs/agents/domain.md 的开头只有一句话，但它是整份文档的纲：

How engineering skills consume this repository's domain documentation. （工程技能如何消费本仓库的领域文档。）

它不描述某个业务功能，而是描述协作基础设施：当 AI Agent 技能进入这个仓库执行任务时，应该先读什么、以什么为权威、遇到术语缺失或决策冲突时该怎么办。这一点可以从 AGENTS.md 的 Agent skills 部分得到印证——它有两个并列条目，分别指向：

• Issue tracker：问题与规格单（specs）追踪在 GitHub Issues，操作规范见 docs/agents/issue-tracker.md；
• Domain docs：仓库使用多上下文领域文档布局，见 docs/agents/domain.md。

也就是说，docs/agents/ 目录是整个 Agent 工作流的「入口说明书」，而 domain.md 负责其中「领域知识从哪里来、怎么用」这一半。

二、探索代码之前，按顺序先读三类文件

原文明确给出「Before exploring, read these」清单，共三类，顺序不可颠倒：

1. 仓库根目录的 CONTEXT-MAP.md：它是指向各上下文（context）专属 CONTEXT.md 文件的索引。Agent 必须先读它，再读与当前任务相关的每一个 context 对应的 CONTEXT.md。
2. docs/adr/：存放触及当前工作区域的系统级（system-wide）决策记录。
3. CONTEXT-MAP.md 中引用的、属于具体上下文范围的 ADR 目录（context-scoped ADR directories）：这些是某个 app 或 package 局部的决策，不在系统级目录里。

原文紧接着给出了一条重要的缺失处理策略：

If any file does not exist, proceed silently. Do not flag absence or suggest creating it upfront. /domain-modeling creates domain documents lazily when terminology or decisions become settled. （如果某个文件不存在，静默继续。不要标记缺失，也不要主动建议创建。/domain-modeling 会在术语或决策沉淀下来时才惰性创建领域文档。）

这条「静默跳过 + 惰性创建」规则值得注意：它意味着领域文档体系不是预置齐套的，而是随术语和决策逐步固化而生长的。从当前仓库的实际状态可以印证这一点——在仓库根目录执行查找，CONTEXT-MAP.md 与任何 CONTEXT.md 文件目前都不存在（find . -name "CONTEXT*.md" 结果为空）。按 domain.md 自身的规则，这属于「文件尚不存在」的正常状态：Agent 不应当作问题上报，更不应在术语尚未沉淀前凭空创建。换言之，当前仓库处于该体系的冷启动期，而已经存在的 docs/adr/0001-workspace-boundaries.md 和 docs/adr/0002-agent-ai-sdk-adoption.md 正是「决策已沉淀、但领域术语文档尚未生成」的典型中间态。

三、文件结构：多上下文布局（multi-context layout）

原文给出的目录树必须完整理解，它是整个体系的骨架：

/
├── CONTEXT-MAP.md
├── docs/adr/                    ← 系统级决策
├── apps/
│   └── <context>/
│       └── CONTEXT.md
└── packages/
    └── <context>/
        ├── CONTEXT.md
        └── docs/adr/            ← 上下文专属决策

各条目的语义：

路径	作用
CONTEXT-MAP.md	上下文边界的唯一权威（authoritative）索引。原文强调："CONTEXT-MAP.md is authoritative for context boundaries"——上下文怎么划分，以它说了算。
docs/adr/	跨上下文、影响整个系统的决策（如包边界策略、技术选型）。
apps/<context>/CONTEXT.md	该 app 作为独立领域上下文时的术语表与概念说明。
packages/<context>/CONTEXT.md	该 package 作为独立领域上下文时的术语表与概念说明。
packages/<context>/docs/adr/	该上下文私有的、不需要上升为系统级的决策。

原文还有一条重要的「负向」规则：不是每个 app 或 package 都需要 CONTEXT.md——只有当它代表一个有意义的领域上下文（meaningful domain context）时才创建。对照当前仓库结构（apps/web、apps/server 与 packages/api、packages/schema、packages/pdf 等十几个内部包），这条规则实际上是在防止「一个包一份文档」的形式主义泛滥。

这里的 <context> 与 AGENTS.md 中「Package and feature boundaries」一节描述的包角色体系（role:domain、role:infra、role:adapter、role:api、role:rendering、role:tooling）是互补关系：后者是可执行的边界标签（由 turbo boundaries 检查），前者是可阅读的领域语言载体。ADR-0001 恰好把两者粘在一起——它既规定了 turbo boundaries 这样的执行检查，也解释了「新代码必须先有 owner 再谈放哪个目录」的归属问题，这正是未来 CONTEXT-MAP.md 划分上下文边界的直接依据。

四、术语表词汇（glossary vocabulary）：输出必须用 CONTEXT.md 里的词

原文「Use glossary vocabulary」一节规定：当 Agent 的输出命名某个领域概念时——无论是 issue 标题、重构提案、假设（hypotheses）还是测试名——都必须使用相关 CONTEXT.md 中定义的术语，不得漂移到已被明确回避的同义词（Do not drift to explicitly avoided synonyms）。

对「找不到词」的情况，原文给了一个诊断性的二分判断：

Missing terminology signals either language foreign to project or genuine domain-model gap. Reconsider first; otherwise note gap for /domain-modeling. （找不到术语，要么说明你用的是项目外的外语，要么是真实的领域模型缺口。先自我反思；若确属缺口，记录下来留给 /domain-modeling 处理。）

这条规则的价值在 ADR-0002 中可以看得很直观。ADR-0002 全文围绕一套高度自洽的内部术语运转：run（一次执行）、thread（会话线程）、draft row（草稿行）、reaper（回收器）、approval-requested / approval-responded（审批部件状态）等。如果 Agent 在 issue 标题里写「session 死了用 cleaner 清理」，虽然意思相近，但已经脱离该文档定义的词汇表，读者（包括后续消费该 issue 的 Agent）无法再把它与 messages-persistence.ts、STALE_AGENT_RUN_TTL_MS 等实现精确对应。术语统一本质上是在维护「文档语言 ↔ 源码标识符」之间的可追溯性。

五、标记 ADR 冲突：不得静默推翻已接受的决策

原文「Flag ADR conflicts」一节给出了一条硬规则与一个示范句式：

If output contradicts existing ADR, surface conflict explicitly instead of silently overriding: （如果输出与既有 ADR 矛盾，必须显式暴露冲突，而不是静默覆盖。）

Contradicts ADR-0007 (event-sourced orders), but worth reopening because… （与 ADR-0007（事件溯源订单）矛盾，但值得重开，因为……）

在 Reactive Resume 当前只有两份 ADR 的体量下，这条规则的实操含义是：任何提案若与 ADR-0001 Workspace Boundaries（状态 Accepted）冲突，必须引用 ADR 编号并说明「为什么值得重开」，而不能默默改走。

从两份 ADR 的实际写法看，该仓库的 ADR 遵循统一的四段结构——Status / Context / Decision / Consequences / Rejected Alternatives——最后一段尤其值得 Agent 消费：被否决的替代方案（Rejected Alternatives）记录了「为什么不这么做」，避免后续工作重复踩已被否决的路径。例如：

• ADR-0001 明确否决了「纯文档式边界（documentation-only boundaries）」，理由是「之前的问题不是缺乏意图，而是缺乏可执行的强制（executable enforcement）」——这一条反过来解释了为什么 domain docs 体系必须与 turbo boundaries、GritQL 规则（如 tooling/grit/workspace-boundaries.grit）和 Biome noRestrictedImports 配套存在；
• ADR-0002（状态 Proposed）在约束一节中直接引用了「per ADR 0001」——它把 packages/ai 定位为 runtime-universal 包、zod-only 运行时依赖，正是对 ADR-0001 包方向规则的遵循。

这就是「ADR 冲突检查」在真实仓库中的样子：新决策（0002）显式引用旧决策（0001）作为约束前提，而非绕过它。Agent 在提案时若与既有 ADR 相抵触，正确动作就是在文本中显式写出「Contradicts ADR-00XX …, but worth reopening because…」，把裁决交回给人。

六、落地核对清单

结合原文与仓库现状，可以整理出 Agent 进入本仓库时的领域文档工作流：

1. 读根目录 CONTEXT-MAP.md（当前尚不存在 → 按规则静默跳过，不报错、不催建）；
2. 读 docs/adr/ 下与当前任务相关的系统级 ADR，以及上下文私有 ADR 目录（如有）；
3. 输出中所有领域概念使用对应 CONTEXT.md 的既定术语，找不到词时先自我纠正，确属模型缺口则记给 /domain-modeling；
4. 输出若与既有 ADR 矛盾，显式引用 ADR 编号并说明重开理由，禁止静默覆盖；
5. 上下文划分以 CONTEXT-MAP.md 为唯一权威；CONTEXT.md 只在上下文真正有意义时才存在，不追求「一包一文档」。

这套体系的设计取舍在 ADR-0001 的 Consequences 里有一句精准的总结：「New code needs an owner before it gets a folder」（新代码要先有 owner 才谈得上目录归属）。领域文档体系做的正是同一件事的语言版本——先让概念有归属（context），再谈文档与代码的组织。对 Agent 而言，遵循 docs/agents/domain.md 的读取顺序与词汇纪律，是产出可被人类评审、可被后续 Agent 无歧义消费的结果的前提。