sp-grill-with-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<what-to-do>

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time, waiting for feedback on each question before continuing.

If a question can be answered by exploring the codebase, explore the codebase instead.

</what-to-do> <supporting-info>

<what-to-do>

对我进行全面访谈，深入了解该计划的各个方面，直到我们达成共识。梳理设计树的每个分支，逐一解决决策之间的依赖关系。对于每个问题，请给出你的推荐答案。

每次只提出一个问题，等待反馈后再继续。

如果某个问题可以通过探索代码库来解答，请直接探索代码库。

</what-to-do> <supporting-info>

Domain awareness

领域感知

During codebase exploration, also look for existing documentation:

在探索代码库时，同时查找现有文档：

File structure

文件结构

Most repos have a single context:

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

If a

CONTEXT-MAP.md

exists at the root, the repo has multiple contexts. The map points to where each one lives:

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

Create files lazily — only when you have something to write. If no

CONTEXT.md

exists, create one when the first term is resolved. If no

docs/adr/

exists, create it when the first ADR is needed.

大多数代码库只有一个上下文：

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

如果根目录下存在

CONTEXT-MAP.md

，则代码库包含多个上下文。该文件会指明每个上下文的位置：

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

延迟创建文件——仅当有内容可写时再创建。如果不存在

CONTEXT.md

，则在第一个术语被明确后创建它。如果不存在

docs/adr/

目录，则在需要创建第一个ADR时创建该目录。

During the session

会话期间

Ask in the user's terms, not the model's

使用用户的术语提问，而非模型术语

The person answering knows the product, not necessarily the schema. Pose every question in what they can see and do — which screen, what they press, what happens next — and only then give the model-level backing. When two or more paths are in play, a small table beats prose:

	where	what you press	what it writes
A	the screen that exists today	the control already on it	a row owned by its parent
B	the screen we are changing	no such control exists yet - it is what we are adding	a row owned by nobody

The table is the SHAPE, not the scope. The same framing fits a queue, a schema, a CLI flag or a cron job: name the surface the user would actually observe, whatever that surface is.

Then make the stake observable with one concrete walk-through: "you save an item while working inside project X; three months later you delete project X; today the item disappears from your library too." A user who cannot picture the consequence cannot choose between the options.

Two tells that the FRAMING was wrong rather than the explanation: the answer comes back as a question ("what do you mean?", "which step of the app is this?"), or you needed entity names and ADR numbers just to state the options. Re-pose it - do not re-explain it at greater length.

Put trade-off reasoning in the message body where it can actually be read; keep option labels to a few words.

回答问题的人了解产品，但不一定熟悉架构模型。所有问题都要从用户可见和可操作的角度提出——比如哪个页面、点击什么按钮、后续会发生什么——之后再给出模型层面的依据。当存在多个可选方案时，用表格比文字描述更清晰：

	位置	点击控件	写入内容
A	当前已存在的页面	页面上已有的控件	归属于父级的一行数据
B	我们正在修改的页面	尚无此控件——这是我们要新增的内容	无归属的一行数据

表格呈现的是形态，而非范围。这种框架同样适用于队列、数据库 schema、CLI 标志或定时任务：明确用户实际能观察到的界面，无论该界面是什么形式。

然后通过一个具体的流程演示让影响可视化：“你在项目X中保存了一个条目；三个月后你删除了项目X；如今该条目也从你的库中消失了。” 用户如果无法想象后果，就无法在选项中做出选择。

如果出现以下两种情况，说明提问框架有误而非解释不够：回答是一个问题（“你指的是什么？”、“这是应用的哪一步？”），或者你需要使用实体名称和ADR编号才能说明选项。此时应重新提问——不要长篇大论地重新解释。

将权衡推理放在消息正文中，以便用户能实际阅读；选项标签则控制在几个词以内。

Challenge against the glossary

对照术语表校验

When the user uses a term that conflicts with the existing language in

CONTEXT.md

, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

当用户使用的术语与

CONTEXT.md

中的现有术语冲突时，立即指出：“你的术语表将‘cancellation’定义为X，但你似乎指的是Y——到底是哪一个？”

Sharpen fuzzy language

明确模糊表述

When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."

当用户使用模糊或多义术语时，提出一个精确的标准术语。“你提到‘account’——你指的是Customer还是User？这两者是不同的概念。”

Discuss concrete scenarios

讨论具体场景

When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.

当讨论领域关系时，用具体场景进行压力测试。设计能探查边缘情况的场景，迫使用户明确概念之间的边界。

Cross-reference with code

与代码交叉验证

When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

当用户说明某功能的工作方式时，检查代码是否一致。如果发现矛盾，及时指出：“你的代码会取消整个Order，但你刚才说支持部分取消——哪个是正确的？”

Update CONTEXT.md inline

实时更新CONTEXT.md

When a term is resolved, update

CONTEXT.md

right there. Don't batch these up — capture them as they happen. Use the format in CONTEXT-FORMAT.md.

CONTEXT.md

should be totally devoid of implementation details. Do not treat

CONTEXT.md

as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.

当术语被明确后，立即更新

CONTEXT.md

。不要批量处理——在确定时就记录下来。使用CONTEXT-FORMAT.md中的格式。

CONTEXT.md

应完全不含实现细节。不要将

CONTEXT.md

当作规范、草稿本或实现决策的存储库。它只是一个术语表，仅此而已。

Record every decision as an ADR

将每个决策记录为ADR

Always create an ADR for every design decision — one ADR per decision, the moment the decision is made. Do not batch or defer. Create

docs/adr/

lazily on the first ADR. Use the format in ADR-FORMAT.md.

A decision qualifies if one option was chosen over another — architectural shape, technology choice, naming, scope boundary, safety mechanism, a deliberate no. When in doubt, write the ADR. A short ADR is better than a missing one.

Record the options, not just the winner. Every ADR opens with a small Mermaid decision diagram (see

${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md

, Rule 3) carrying one

|rejected|

branch per alternative that was genuinely on the table, each with its one-line reason for losing — that is what stops the same option being re-proposed in six months.

</supporting-info>

始终为每一个设计决策创建ADR——一个决策对应一个ADR，在决策确定的那一刻就创建。不要批量处理或延迟创建。在创建第一个ADR时再延迟创建

docs/adr/

目录。使用ADR-FORMAT.md中的格式。

只要是在多个选项中做出选择的决策都需要记录——包括架构形态、技术选型、命名、范围边界、安全机制，以及明确的否决项。如有疑问，就编写ADR。简短的ADR比缺失的ADR更好。

记录所有选项，而不仅仅是最终选定的方案。每个ADR开头都要有一个小型Mermaid决策图（参见

${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md

第3条规则），每个真正被考虑过的备选方案都要有一个

|rejected|

分支，并附上一行落选原因——这能避免六个月后同一方案被再次提出。

</supporting-info>