Strapi 的 AI Agent 领域文档体系：CONTEXT 文件、ADR 决策与术语表的工程实践

在 Strapi 这个 Yarn workspaces + Nx 单仓（monorepo）中，docs/agents/ 目录为参与仓库工作的 AI Agent 与工程技能（skills）定义了一套"领域文档消费规范"。本文以 docs/agents/domain.md 为核心，讲解这套由 CONTEXT-MAP.md、各包级 CONTEXT.md 与 docs/adr/ 三层构成的领域文档体系：Agent 在探索代码库前该读什么、文件缺失时该如何处理、为什么必须使用术语表词汇，以及如何正确暴露 ADR 决策冲突。读完本文，你可以在自己的大型代码库中复刻同一套"Agent 可读的领域知识架构"。

1. 为什么需要这套文档体系

Strapi 主仓是一个典型的多上下文（multi-context）仓库：框架核心、官方插件、Provider 实现、CLI 工具全部放在同一个仓库的 packages/* 下。从根目录的 AGENTS.md 可以看到其上下文划分：

packages/core/       # 框架：strapi、admin、database、content-manager、types、utils…
packages/plugins/    # 官方插件：users-permissions、i18n、graphql、documentation…
packages/providers/  # 邮件 + 上传 Provider 实现
packages/utils/      # 共享工具：logger、eslint-config、tsconfig、vitest-config
packages/cli/        # CLI 工具：create-strapi-app、cloud-cli

当 Agent 需要修改某个具体领域（例如数据库抽象层 @strapi/database 或内容管理 @strapi/content-manager）时，靠通读整个 monorepo 定位"这个领域里概念到底叫什么、历史上做过哪些设计决策"成本极高。docs/agents/domain.md 开宗明义地说明了它的定位：

How the engineering skills should consume this repo's domain documentation when exploring the codebase.

也就是说，这份文档不是给人读的架构说明书，而是规范 Agent 行为的操作手册——规定工程类技能在探索代码库时，应该按什么顺序、以什么态度消费领域文档。

2. 探索前必读清单：三层领域文档

文档给出的第一组规则是"探索代码前，先读这三样东西"：

1. 仓库根目录的 CONTEXT-MAP.md——它是指向各上下文 CONTEXT.md 的索引。读与当前主题相关的每一个上下文文档。
2. 目标包内的 CONTEXT.md——例如在数据库包工作时读 packages/core/database/CONTEXT.md。这是该上下文的术语表（glossary）。
3. 仓库根目录的 docs/adr/——系统级架构决策记录（Architecture Decision Records）。同时检查上下文级决策目录 packages/<context>/docs/adr/。

三者构成清晰的三级结构：CONTEXT-MAP.md 负责"导航"，CONTEXT.md 负责"词汇"，docs/adr/ 负责"决策"。

3. 多上下文仓库的文件结构

原文档给出了标准的目录布局（存在根级 CONTEXT-MAP.md 即代表这是一个多上下文仓库）：

/
├── CONTEXT-MAP.md
├── docs/adr/                          ← 系统级决策
└── packages/
    ├── core/
    │   ├── database/
    │   │   ├── CONTEXT.md
    │   │   └── docs/adr/              ← 该上下文的专属决策
    │   └── content-manager/
    │       ├── CONTEXT.md
    │       └── docs/adr/
    └── plugins/
        └── users-permissions/
            ├── CONTEXT.md
            └── docs/adr/

对照 Strapi 实际的包布局，这里的 database/、content-manager/、users-permissions/ 恰好对应 AGENTS.md 中列出的核心包（@strapi/database 负责 MySQL/PostgreSQL/MariaDB/SQLite 数据库抽象，@strapi/content-manager 负责内容管理 UI），说明该结构示例是直接按本仓库真实包路径撰写的。

4. 关键设计：文件不存在时"静默前进"

这份文档中最值得注意的一条规则是：

If any of these files don't exist, proceed silently. Don't flag their absence; don't suggest creating them upfront. The /domain-modeling skill (reached via /grill-with-docs and /improve-codebase-architecture) creates them lazily when terms or decisions actually get resolved.

其背后的设计意图是惰性生成（lazy creation）：

• CONTEXT-MAP.md、CONTEXT.md、docs/adr/ 不是随仓库初始化的必需文件，而由 /domain-modeling 技能（经由 /grill-with-docs、/improve-codebase-architecture 两个入口技能触发）在实际讨论中真正敲定了某个术语或某条决策时才落盘；
• Agent 发现文件缺失时，既不应把它当错误报告，也不应主动建议"先创建这些文件"——那会产生大量噪音和空文件；
• 这避免了"为了文档而文档"，让领域文档只沉淀被实际使用过的概念与决策。

从当前仓库的实际状态可以印证这一设计的真实执行：

• 仓库根目录不存在 CONTEXT-MAP.md；
• 全部 packages/* 下没有任何 CONTEXT.md；
• 不存在 docs/adr/ 目录。

这说明当前 Strapi 主仓正处于该体系所预期的"尚未开始惰性沉淀"阶段——文档先定义好消费协议，内容则等真实需求出现时再逐步生成。

5. 术语表纪律：只用 CONTEXT.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 in the relevant CONTEXT.md. Don't drift to synonyms the glossary explicitly avoids.

Agent 在输出中凡是涉及领域概念——无论是 issue 标题、重构提案、假设还是测试名——都必须使用对应 CONTEXT.md 中定义的术语，禁止漂移到术语表明确回避的同义词上。这与 Strapi 仓库本身的治理风格一致：AGENTS.md 中明确要求"Entity Service 已废弃，内容操作一律使用 Document Service（strapi.documents）"、"@strapi/types 是共享 TypeScript 类型的唯一事实来源"，本质都是同一类"统一词汇"约束，只是前者面向人写的贡献指南，而 CONTEXT.md 机制面向 Agent 的输出行为。

文档还给出了一个自我诊断的启发式判断：如果你需要的概念不在术语表里，这是一个信号——要么你在发明项目并不使用的语言（应重新考虑），要么存在真实的术语缺口（记录下来交给 /domain-modeling 补齐）。

6. ADR 冲突检测：显式暴露，而非静默覆盖

第三条规则针对架构决策记录：如果你的输出与既有 ADR 相矛盾，必须显式指出，而不是悄悄绕过去。文档给出的标准表述方式是：

Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…

这条规则的实际价值在于把"决策推翻"变成一个可审计的显式事件：Agent 不能自行改写历史决策，只能提出"值得重开讨论的理由"，最终是否重开由人决定。对大型多人（多 Agent）协作的 monorepo 而言，这能有效防止不同 Agent 会话各自为政地推翻既有架构约束。

7. 在 docs/agents/ 文档集中的位置

docs/agents/domain.md 并非孤立存在，它是 docs/agents/ 目录下"Agent 协作协议"的一部分，同目录还有两份配套文档：

• docs/agents/issue-tracker.md：规定 issue 先以 Obsidian Markdown 笔记（notes/work/strapi/issues/）形式存在，仅在用户明确要求时通过 Linear MCP 提升为公司级 Linear issue，并定义了 frontmatter 结构（title / type / status / labels / created / linear）；
• docs/agents/triage-labels.md：把五个规范的 triage 角色（needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix）映射到本仓库 tracker 实际使用的标签字符串。

三者合起来覆盖了 Agent 工作的三条线：领域知识（domain.md，本文主题）、问题跟踪（issue-tracker.md）、分诊标签（triage-labels.md）。

与这套文档配套的还有仓库的技能（skills）机制：AGENTS.md 说明 .ai/skills/ 是提交到仓库的技能规范源，每个包含 SKILL.md 的子目录即一个技能；yarn ai:sync 会把它们符号链接到 .agents/skills/、.claude/skills/、.cursor/skills/ 三个 AI 工具目录。当前仓库中已提交的技能见 .ai/skills/git-conventions/SKILL.md，而 domain.md 所引用的 /domain-modeling、/grill-with-docs 等技能属于外部技能集（triage-labels.md 中提及的 mattpocock/skills 风格），由用户环境按需加载。

8. 工程实践总结：如何复刻这套体系

从 docs/agents/domain.md 抽象出来，任何多包 monorepo 都可以按以下四步落地同样的"Agent 领域文档协议"：

1. 写一份消费规范（相当于本文主角文档）：放在 docs/agents/ 之类的固定位置，明确 Agent 探索代码前先读哪些文件、缺失时静默前进、输出必须使用术语表词汇、矛盾 ADR 必须显式声明；
2. 预留三层文件结构：根级 CONTEXT-MAP.md 做索引，每个包一个 CONTEXT.md 做术语表，docs/adr/（全局）+ packages/<context>/docs/adr/（上下文级）存决策；
3. 采用惰性生成策略：不要预创建空文件，让文档只在实际敲定术语或决策时由领域建模流程落盘——Strapi 当前主仓正是"协议先行、内容为空"的实例，可作为该策略可行性的真实佐证；
4. 与 Agent 引导文档协同：把这份协议与 monorepo 结构说明（如 Strapi 的 AGENTS.md）、issue 跟踪规范、分诊标签映射放在一起，形成完整的 Agent 协作面。

这套机制的本质，是把"人脑中的领域知识"转化为 Agent 可检索、可验证、可追责的文本资产：导航（CONTEXT-MAP）、词汇（CONTEXT.md）、决策（ADR）各司其职，并配套了"静默前进、显式冲突、术语表纪律"三条防止 Agent 噪音与漂移的行为约束。