# Context

## Terms

- **Order** — A customer's purchase, containing multiple OrderItems
- **OrderItem** — A single product line item within an Order
- **Cancellation** — Customer-initiated Order termination, can be partial or full
- **Materialization** — Allocating filesystem space for a Lesson

选择性创建ADR（架构决策记录）：

只有当三个条件都满足时才创建：

难以逆转 — 改变主意成本高
没上下文会奇怪 — 未来读者会问"为什么这样？"
真实权衡的结果 — 有明确替代方案，你选了这个有理由

和/grill-me的区别

特性	/grill-me	/grill-with-docs
用途	非代码场景的grilling	工程场景的grilling
领域建模	❌	✅ 使用/domain-modeling
文档更新	❌	✅ 实时更新CONTEXT.md
ADR创建	❌	✅ 选择性创建ADR

简单说： /grill-with-docs = /grill-me + 领域建模 + 文档沉淀

文件结构

单一上下文

/
├── CONTEXT.md              # 词汇表
├── docs/
│   └── adr/               # 架构决策记录
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

多上下文

/
├── CONTEXT-MAP.md          # 指向各上下文
├── docs/
│   └── adr/               # 系统级决策
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md     # ordering上下文的词汇表
│   │   └── docs/adr/      # ordering特定决策
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

惰性创建： 只在有内容时才创建文件。

CONTEXT.md规则

DO（应该）

只存词汇表和概念定义
实时更新，别batch
用CONTEXT-FORMAT.md的格式
完全没有实现细节

DON'T（不应该）

把它当spec
把它当scratch pad
存实现决策
记录技术细节

CONTEXT.md是词汇表，别的什么都不是。

ADR创建原则

只有当三个条件全满足时才创建ADR：

难以逆转 — 改变主意成本有意义
没上下文会奇怪 — 未来读者会疑惑
真实权衡 — 有明确替代方案，你选了这个有理由

任何一个不满足，跳过ADR。

实战案例

场景：订单取消功能

你： "做一个订单取消功能"

AI开始追问：

AI: "取消的是什么？是整个Order还是单个OrderItem？"

你: "都可以，用户想取消啥就取消啥。"

AI: "那Inventory怎么处理？OrderItem取消退对应商品库存，Order取消退全部库存？"

你: "对。"

AI: "如果已经支付了呢？自动退款还是需要审批？"

你: "小于1000自动退，大于1000要财务审批。"

AI: "如果订单已经发货了呢？"

你: "那就不能取消了，要走退货流程。"

AI: "好的，我来更新CONTEXT.md并记录这些决策。"

AI更新CONTEXT.md:

## Terms

- **Order Cancellation** — Customer-initiated termination, can be at Order or OrderItem level
- **Refund Threshold** — Orders under 1000 auto-refund, over 1000 require finance approval
- **Shipping Cutoff** — Orders cannot be cancelled once shipped

AI判断需要ADR:

# ADR 0003: Order Cancellation Rules

## Status

Accepted

## Context

Users need ability to cancel orders, but we need rules for inventory, refunds, and shipping cutoff.

## Decision

- Cancellation available at Order or OrderItem level
- Inventory restored atomically with cancellation
- Refunds under 1000 automatic, over 1000 require finance approval
- Shipping status acts as cancellation cutoff

## Consequences

- Users can partially cancel orders
- Finance team needs workflow for >1000 refunds
- Shipping service must emit status for cancellation check