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

Strapi 的 AI Agent 领域文档体系CONTEXT 文件、ADR 决策与术语表的工程实践【免费下载链接】strapi Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapi在 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 repos domain documentation when exploring the codebase.也就是说这份文档不是给人读的架构说明书而是规范 Agent 行为的操作手册——规定工程类技能在探索代码库时应该按什么顺序、以什么态度消费领域文档。2. 探索前必读清单三层领域文档文档给出的第一组规则是探索代码前先读这三样东西仓库根目录的CONTEXT-MAP.md——它是指向各上下文CONTEXT.md的索引。读与当前主题相关的每一个上下文文档。目标包内的CONTEXT.md——例如在数据库包工作时读packages/core/database/CONTEXT.md。这是该上下文的术语表glossary。仓库根目录的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 dont exist,proceed silently. Dont flag their absence; dont suggest creating them upfront. The/domain-modelingskill (reached via/grill-with-docsand/improve-codebase-architecture) creates them lazily when terms or decisions actually get resolved.其背后的设计意图是惰性生成lazy creationCONTEXT-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 relevantCONTEXT.md. Dont drift to synonyms the glossary explicitly avoids.Agent 在输出中凡是涉及领域概念——无论是 issue 标题、重构提案、假设还是测试名——都必须使用对应CONTEXT.md中定义的术语禁止漂移到术语表明确回避的同义词上。这与 Strapi 仓库本身的治理风格一致AGENTS.md 中明确要求Entity Service 已废弃内容操作一律使用 Document Servicestrapi.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/lineardocs/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 领域文档协议写一份消费规范相当于本文主角文档放在docs/agents/之类的固定位置明确 Agent 探索代码前先读哪些文件、缺失时静默前进、输出必须使用术语表词汇、矛盾 ADR 必须显式声明预留三层文件结构根级CONTEXT-MAP.md做索引每个包一个CONTEXT.md做术语表docs/adr/全局packages/context/docs/adr/上下文级存决策采用惰性生成策略不要预创建空文件让文档只在实际敲定术语或决策时由领域建模流程落盘——Strapi 当前主仓正是协议先行、内容为空的实例可作为该策略可行性的真实佐证与 Agent 引导文档协同把这份协议与 monorepo 结构说明如 Strapi 的 AGENTS.md、issue 跟踪规范、分诊标签映射放在一起形成完整的 Agent 协作面。这套机制的本质是把人脑中的领域知识转化为 Agent 可检索、可验证、可追责的文本资产导航CONTEXT-MAP、词汇CONTEXT.md、决策ADR各司其职并配套了静默前进、显式冲突、术语表纪律三条防止 Agent 噪音与漂移的行为约束。【免费下载链接】strapi Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考