Grill With Docs

<what-to-do>

围绕这个计划的每个方面持续追问我，直到我们达成共同理解。沿着 design tree 的每个分支往下走，逐一解决决策之间的依赖。对每个问题，都提供你推荐的答案。

一次只问一个问题，并等待我对每个问题的反馈后再继续。

如果某个问题可以通过探索 codebase 来回答，就去探索 codebase，而不是问我。

</what-to-do>

<supporting-info>

Domain awareness

探索 codebase 时，也查找现有文档：

File structure

大多数 repos 只有一个 context：

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

如果根目录存在 CONTEXT-MAP.md，说明 repo 有多个 contexts。这个 map 指向每个 context 的位置：

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

懒创建文件：只有在有内容可写时才创建。如果没有 CONTEXT.md，在第一个 term 被解决时创建。如果没有 docs/adr/，在第一个 ADR 需要时创建。

During the session

Challenge against the glossary

当用户使用的 term 与 CONTEXT.md 中的现有语言冲突时，立即指出。“Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?”

Sharpen fuzzy language

当用户使用含糊或 overloaded terms 时，提出一个精确的 canonical term。“You're saying 'account' — do you mean the Customer or the User? Those are different things.”

Discuss concrete scenarios

讨论 domain relationships 时，用具体场景做 stress-test。发明能探测 edge cases 的场景，迫使用户精确说明概念之间的边界。

Cross-reference with code

当用户说明某件事如何工作时，检查代码是否一致。如果发现矛盾，指出来：“Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?”

Update CONTEXT.md inline

当一个 term 被解决时，立即更新 CONTEXT.md。不要攒到最后；随着发生就捕获。使用 CONTEXT-FORMAT.md 中的格式。

CONTEXT.md 应完全不包含实现细节。不要把 CONTEXT.md 当作 spec、scratch pad 或实现决策仓库。它只是 glossary，除此之外不承担别的职责。

Offer ADRs sparingly

只有以下三点全部为真时，才提议创建 ADR：

1. Hard to reverse — 之后改主意的成本有意义 2. Surprising without context — 未来读者会疑惑“为什么这样做？” 3. The result of a real trade-off — 确实有真实替代方案，并且你基于具体原因选择了一个

如果三者缺一，就跳过 ADR。使用 ADR-FORMAT.md 中的格式。

</supporting-info>

ADR Format

ADRs 放在 docs/adr/ 中，并使用连续编号：0001-slug.md、0002-slug.md，以此类推。

懒创建 docs/adr/ 目录：只有在第一个 ADR 确实需要时才创建。

Template

# {Short title of the decision}

{1-3 sentences: what's the context, what did we decide, and why.}

就这些。一个 ADR 可以只有一段。价值在于记录做出了某个决策以及为什么做，而不是填满各个 section。

Optional sections

只在它们带来真实价值时包含。大多数 ADR 不需要这些。

• Status frontmatter (proposed | accepted | deprecated | superseded by ADR-NNNN) — 决策被重新审视时有用
• Considered Options — 只有被拒绝的替代方案值得记住时才写
• Consequences — 只有需要说明非显而易见的下游影响时才写

Numbering

扫描 docs/adr/，找到现有最大编号并加一。

When to offer an ADR

以下三点必须全部为真：

1. Hard to reverse — 之后改主意的成本有意义 2. Surprising without context — 未来读者看到代码会想“为什么会这样做？” 3. The result of a real trade-off — 确实存在可选方案，并且你基于具体原因选择了其中一个

如果决策很容易撤销，就跳过；你之后直接撤销即可。如果它并不出人意料，没人会追问为什么。如果没有真实替代方案，除了“我们做了显而易见的事”之外就没什么可记录。

What qualifies

• Architectural shape. “我们使用 monorepo。”“write model 是 event-sourced，read model 投影到 Postgres。”
• Integration patterns between contexts. “Ordering 和 Billing 通过 domain events 通信，而不是 synchronous HTTP。”
• Technology choices that carry lock-in. 数据库、message bus、auth provider、deployment target。不是每个 library；只记录那些替换起来会花一个季度的选择。
• Boundary and scope decisions. “Customer data 由 Customer context 拥有；其他 contexts 只通过 ID 引用它。”明确的 no 和 yes 一样有价值。
• Deliberate deviations from the obvious path. “我们不用 ORM 而用 manual SQL，因为 X。”任何合理读者会默认相反做法的地方都值得记录。这能阻止下一位工程师把刻意选择“修掉”。
• Constraints not visible in the code. “由于合规要求，我们不能使用 AWS。”“由于 partner API contract，响应时间必须低于 200ms。”
• Rejected alternatives when the rejection is non-obvious. 如果你考虑过 GraphQL，但因为细微原因选择 REST，就记录下来；否则六个月后还会有人再次建议 GraphQL。

CONTEXT.md Format

Structure

# {Context Name}

{One or two sentence description of what this context is and why it exists.}

## Language

**Order**:
{A concise description of the term}
_Avoid_: Purchase, transaction

**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request

**Customer**:
A person or organization that places orders.
_Avoid_: Client, buyer, account

## Relationships

- An **Order** produces one or more **Invoices**
- An **Invoice** belongs to exactly one **Customer**

## Example dialogue

> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."

## Flagged ambiguities

- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts.

Rules

• Be opinionated. 当多个词表示同一概念时，选择最合适的那个，并把其他词列为应避免的 aliases。
• Flag conflicts explicitly. 如果一个 term 被含糊使用，在 “Flagged ambiguities” 中用清晰 resolution 标出。
• Keep definitions tight. 最多一句话。定义它是什么，而不是它做什么。
• Show relationships. 使用加粗 term 名称，并在显然的地方表达 cardinality。
• Only include terms specific to this project's context. 通用编程概念（timeouts、error types、utility patterns）不属于这里，即使项目大量使用。添加 term 前先问：这是当前 context 独有的概念，还是通用编程概念？只有前者属于这里。
• Group terms under subheadings when natural clusters emerge. 如果所有 terms 属于单个内聚区域，扁平列表就可以。
• Write an example dialogue. 写一段 dev 和 domain expert 的对话，自然展示这些 terms 如何交互，并澄清相关概念之间的边界。

Single vs multi-context repos

Single context（大多数 repos）： repo 根目录一个 CONTEXT.md。

Multiple contexts： repo 根目录一个 CONTEXT-MAP.md，列出 contexts、它们的位置以及彼此关系：

# Context Map

## Contexts

- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping

## Relationships

- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`

Skill 会推断使用哪种结构：

• 如果 CONTEXT-MAP.md 存在，读取它来找到 contexts
• 如果只有根目录 CONTEXT.md，就是 single context
• 如果两者都不存在，等第一个 term 被解决时再懒创建根目录 CONTEXT.md

当存在多个 contexts 时，推断当前话题关联哪一个。如果不清楚，就询问。