Domain Docs

工程技能在探索代码库时应如何消费此仓库的领域文档。

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

工程技能在探索代码库时应如何消费此仓库的领域文档。

Before exploring, read these

探索前请阅读以下内容

CONTEXT.md at the repo root, or
CONTEXT-MAP.md at the repo root if it exists — it points at one CONTEXT.md per context. Read each one relevant to the topic.
docs/adr/ — read ADRs that touch the area you're about to work in. In multi-context repos, also check src/<context>/docs/adr/ for context-scoped decisions.

仓库根目录的 CONTEXT.md，或者
如果存在，仓库根目录的 CONTEXT-MAP.md——它指向每个上下文的一个 CONTEXT.md。阅读与话题相关的每一个。
docs/adr/——阅读与你即将工作的区域相关的 ADR。在多上下文仓库中，还要检查 src/<context>/docs/adr/ 中上下文范围内的决策。

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.

如果其中任何文件不存在，请静默继续。不要标记缺失，也不要在前期建议创建它们。/domain-modeling 技能（通过 /grill-with-docs 和 /improve-codebase-architecture 访问）会在术语或决策实际得到解决时惰性创建它们。

File structure

文件结构

Single-context repo (most repos):

单上下文仓库（大多数仓库）：

/
├── CONTEXT.md
├── docs/adr/
│   ├── 0001-event-sourced-orders.md
│   └── 0002-postgres-for-write-model.md
└── src/

/
├── CONTEXT.md
├── docs/adr/
│   ├── 0001-event-sourced-orders.md
│   └── 0002-postgres-for-write-model.md
└── src/

Multi-context repo (presence of CONTEXT-MAP.md at the root):

多上下文仓库（根目录存在 CONTEXT-MAP.md）：

/
├── CONTEXT-MAP.md
├── docs/adr/                          ← system-wide decisions
└── src/
    ├── ordering/
    │   ├── CONTEXT.md
    │   └── docs/adr/                  ← context-specific decisions
    └── billing/
        ├── CONTEXT.md
        └── docs/adr/

/
├── CONTEXT-MAP.md
├── docs/adr/                          ← 系统级决策
└── src/
    ├── ordering/
    │   ├── CONTEXT.md
    │   └── docs/adr/                  ← 上下文专用决策
    └── billing/
        ├── CONTEXT.md
        └── docs/adr/

Use the glossary's vocabulary

使用词汇表的术语

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 CONTEXT.md. Don't drift to synonyms the glossary explicitly avoids.

当你的输出命名一个领域概念时（在 Issue 标题、重构提案、假设或测试名称中），请使用 CONTEXT.md 中定义的术语。不要偏离到词汇表明确回避的同义词。

If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for /domain-modeling).

如果你需要的概念尚不在词汇表中，这是一个信号——要么你正在发明项目不使用的语言（重新考虑），要么存在真正的缺口（记录给 /domain-modeling）。

Flag ADR conflicts

标记 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（事件溯源订单）矛盾——但值得重新讨论，因为……