# Grill With Docs

> brainstorming 完成后使用——依次完成全部 Stage 的领域对质和最终状态设计，再统一交给 writing-plans

- Skill: `dawnmoon1542/grill-with-docs` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add dawnmoon1542/grill-with-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dawnmoon1542/grill-with-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: DawnMoon1542 (https://skillmd.com/u/dawnmoon1542)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/dawnmoon1542/grill-with-docs

---


# 领域对质与最终状态设计

读取 brainstorming 确认的完整需求和全部 Stage，按顺序完成每个 Stage 的设计。设计目标是全部 Stage 执行后的最终系统，不为开发期间保持服务运行而增加过渡兼容机制。中间 Stage 可以处于不可启动、不可部署或不可用状态，这不构成设计缺口。

**开始时声明：** “我正在使用 grill-with-docs 技能依次完成全部 Stage 的设计。”

<HARD-GATE>
在全部 Stage 的设计分支完成对质、术语和方案细节达成共识前，不得调用 writing-plans 或任何实现技能。
</HARD-GATE>

## 阶段性保存

每当一个 Stage 的术语、职责、接口、数据流、错误处理或测试策略形成可审查结果时，立即写入对应设计文件。

文件中区分已确认内容、待决定内容和未完成部分。后续讨论产生变化时，更新已有文件，不等待整个 Stage 完成后才首次写入。术语和 ADR 在相关决定形成后立即更新。


## 输入

读取 brainstorming 产出的索引文件：

```text
docs/brainstorming/YYYY-MM-DD-<slug>.md
```

必须获得：

- 完整需求边界
- 最终成功标准
- 方向选型
- 明确排除的内容
- 全部 Stage 的范围、依赖和顺序

不得只读取第一个 Stage 后提前交给 writing-plans。

## 输出

每个 Stage 生成独立设计文件：

```text
docs/grill/YYYY-MM-DD-<slug>-stage-1.md
docs/grill/YYYY-MM-DD-<slug>-stage-2.md
docs/grill/YYYY-MM-DD-<slug>-stage-N.md
```

同时按需更新：

- `docs/CONTEXT.md` 或对应 context 文件
- `docs/CONTEXT-MAP.md`
- `docs/adr/NNNN-<decision-slug>.md`
- brainstorming 索引中的设计状态和设计文件

无显式 Stage 时使用统一的 Stage 1 文件名。

## 流程

```dot
digraph grill {
    "读取完整 brainstorming 索引" [shape=box];
    "探索代码、术语表和 ADR" [shape=box];
    "定位下一个 Stage" [shape=box];
    "对质最终状态设计" [shape=box];
    "更新术语与 ADR" [shape=box];
    "生成 Stage 设计文件" [shape=box];
    "设计自审" [shape=box];
    "用户确认 Stage 设计？" [shape=diamond];
    "更新 Stage 设计状态" [shape=box];
    "还有 Stage？" [shape=diamond];
    "调用 writing-plans" [shape=doublecircle];

    "读取完整 brainstorming 索引" -> "探索代码、术语表和 ADR";
    "探索代码、术语表和 ADR" -> "定位下一个 Stage";
    "定位下一个 Stage" -> "对质最终状态设计";
    "对质最终状态设计" -> "更新术语与 ADR";
    "更新术语与 ADR" -> "生成 Stage 设计文件";
    "生成 Stage 设计文件" -> "设计自审";
    "设计自审" -> "用户确认 Stage 设计？";
    "用户确认 Stage 设计？" -> "对质最终状态设计" [label="需要修改"];
    "用户确认 Stage 设计？" -> "更新 Stage 设计状态" [label="已确认"];
    "更新 Stage 设计状态" -> "还有 Stage？";
    "还有 Stage？" -> "定位下一个 Stage" [label="是"];
    "还有 Stage？" -> "调用 writing-plans" [label="否"];
}
```

## 探索既有实现

开始设计前读取当前 Stage 相关的上下文、ADR、领域模型、接口、调用方、测试和构建约束。只有跨 Stage 契约或整体架构需要时，才扩大到全部相关文件。

检查：

- 相关上下文文档
- 与当前 Stage 相关的 ADR
- 领域模型、接口、数据结构和错误类型
- 当前 Stage 会修改的直接调用方
- 现有测试和构建约束

代码是现状事实来源。设计文档描述目标状态，两者冲突时明确记录需要替换的现有行为。

## 最终状态优先

设计每个 Stage 时，只描述它在完整需求完成后承担的职责。除非最终需求明确要求长期兼容，否则不得为了开发期间保持服务运行而加入：

- 新旧接口并存
- compatibility adapter
- deprecated alias
- 双读或双写
- 新旧 Schema 并存
- 临时数据格式转换层
- feature flag 分批切换
- 为旧调用方保留的临时入口
- 为中间 Stage 准备的独立部署方案

Stage 无须独立部署，也无须保证完成该 Stage 后服务可启动或可用。中间 Stage 的不可用状态不需要通过兼容接口、临时数据结构或独立部署方案处理。

以下内容仍须设计：

- 最终架构和组件边界
- 最终接口和数据模型
- 最终错误处理
- 全部 Stage 完成后的外部契约
- 数据完整性和不可逆操作保护
- 用户明确要求长期保留的兼容行为
- 最终测试策略

数据安全不等同于开发期间兼容。允许一次性替换旧结构，但不得丢失或错误转换已有数据。

## 逐一对质

对每个 Stage 沿设计树逐项确认：

- **术语精确性**：领域术语是否与 CONTEXT 一致
- **最终职责**：该 Stage 最终负责什么，不负责什么
- **接口边界**：组件完成全部 Stage 后如何交互
- **数据流**：最终数据从哪里产生、流向哪里
- **错误处理**：最终异常如何传播和呈现
- **数据安全**：迁移、删除和不可逆操作是否保护数据
- **测试策略**：当前 Stage 的行为测试及最终集成测试
- **跨 Stage 依赖**：后续 Stage 依赖哪些明确产物

每次只提出一个需要用户决定的问题。能从代码确认的事实不询问用户。

## 术语和 ADR

术语确认后立即更新 CONTEXT。格式参见 [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md)。

方案决策同时满足以下条件时创建 ADR：

1. 难以逆转。
2. 缺少背景会令人困惑。
3. 存在真实权衡。

格式参见 [ADR-FORMAT.md](./ADR-FORMAT.md)。

不得为纯开发过渡机制创建 ADR，因为这类机制默认不应存在。

## 重要变更与发布操作

检查数据库结构、已有数据迁移或删除、外部契约不兼容、必需环境配置、部署与外部依赖、服务或运行任务中断、专项公告、旧版本恢复限制。数据库表、字段、约束和索引的实际变化即使自动迁移也须标识；可选配置且默认行为不变、常规构建重启、仅内部调用调整不单独标识。公告独立判断，不能只按技术破坏性判断。不得将未知事项记为“无”。

每个 Stage 设计文件在一级标题之后、需求索引之前放置“重要变更与发布操作”引用块，记录当前 Stage 涉及的类别、影响、更新代码之外的操作、执行时机、公告、恢复限制、详细说明链接和评估状态。跨 Stage 操作指向负责该操作的设计章节，不重复定义执行顺序。无相关事项时写“已评估，无需额外操作，无不兼容变更，无专项公告”；未知事项写“待确认”并列出具体问题。

正文按实际需要明确迁移机制与命令入口、配置项及默认行为、执行前提与顺序、已有数据验证、失败处理、恢复条件，以及公告对象、内容和时机。不得写入真实 secret。自动迁移同样需要说明已有数据影响；测试环境执行成功不代表生产环境已执行。

设计自审必须检查这些要求与头部一致，新增、取消或改变事项时同步需求索引。必要迁移方法、验证方式或操作顺序尚不明确时，不将相关设计标记为完成。最终系统的发布迁移不属于禁止的开发期兼容机制。

## Stage 设计文件结构

每个设计文件至少包含：

```markdown
# <功能名称> Stage N 设计

> **重要变更与发布操作：** <填写本节规定的引用块；未完成评估时注明待确认事项>

**需求索引：** `docs/brainstorming/YYYY-MM-DD-<slug>.md`
**Stage：** N / 总 Stage 数
**依赖：** 无或前置 Stage

## Stage 职责

## 最终架构位置

## 接口定义

## 数据流与数据安全

## 错误处理

## 与其他 Stage 的契约

## 测试策略

## 明确排除
```

“明确排除”应记录未采用的开发期兼容机制，防止 writing-plans 再次引入。

## 自审

使用 [spec-document-reviewer-prompt.md](./spec-document-reviewer-prompt.md) 审查：

- 当前 Stage 是否符合完整需求
- 最终状态是否清晰
- 与已确认 Stage 是否一致
- 跨 Stage 契约是否明确
- 是否包含纯过渡兼容设计
- 数据安全是否完整
- 测试策略是否覆盖最终行为

审查通过并获得用户确认后：

1. 更新 brainstorming 索引中的设计状态为已完成。
2. 写入对应设计文件。
3. 继续下一个 Stage。

## 终止条件

仅在以下条件全部满足后调用 writing-plans：

1. 全部 Stage 已完成设计。
2. 全部 Stage 设计已通过自审。
3. 全部 Stage 设计已获得用户确认。
4. CONTEXT 已更新。
5. 符合条件的 ADR 已创建。
6. brainstorming 索引记录了全部设计文件。

交接内容包括 brainstorming 索引和按顺序排列的全部 Stage 设计文件。