spec-brainstorm

规格头脑风暴

通过对话式设计研讨，为重要工作产出重点明确、经过评审的规格。

一次只问一个问题。探索多种方案。分章节审批设计。严格控制范围。设计获批前不得开始实现。

仅在 atelier-orchestrator 选择了由 Spec 支持的 Plan，或人类明确要求编写规格后，才运行此技能。范围有限的工作应直接交给 spec-plan，制定内联 Plan。不要在此处重新判定规划模式。

产物

docs/specs/YYYY-MM-DD-<feature>/
└── design.md  ← This skill's output

需求直接写在文档中——无需单独的 requirements.json。

专属输出约定

此技能只能创建或更新上方所示的 design.md。它可以检查代码仓库并在对话中讨论草稿，但不得修改任何其他文件、创建 plan.json、创建跟踪条目、调用其他工作流技能或编写实现代码。即使人类要求在一个请求中完成头脑风暴、规划和实现，此边界仍然适用。完成 design.md，报告结果，然后停止。

---

经验教训

这些原则适用于每一份规格，始终如此。

规格必须体现其价值

只有当探索、架构、依赖关系或协作需求足以证明持久化产物的必要性时，才应编写持久化规格。不要仅仅因为某项工作涉及多个文件或需要时间，就把范围有限的工作纳入此工作流。这类工作应使用内联 Plan。

设计应便于隔离且清晰明了

将系统拆分为各自目标明确的单元。单元之间应有定义清晰的接口。每个单元都应能独立理解、独立测试。如果无法用一句话说明某个单元的职责，那它承担的内容就太多了。遵循 oracle-codebase-design：使用深模块，在行为发生变化之处设置接缝，并以接口作为测试面。

在现有代码库中工作

先探索当前结构。遵循现有模式。只做有针对性的改进。不要进行无关重构。在提出变更前，先理解现有设计的原因。将已加载的技能视为相关指导，而非必须应用其中所有模式的要求。

拆解

如果请求描述了多个相互独立的子系统，应立即指出。在深入细节前，将其拆分为多个子项目。每个重要子项目都应有自己的规格和计划；范围有限的子项目可以使用内联 Plan。试图涵盖三个子系统的规格毫无帮助。

将迁移与授权、产品行为、基础设施、架构和测试平台项目分开。不要把迁移当作重新设计相邻系统的许可。

严格遵循 YAGNI 原则

从所有设计中移除不必要的功能。如果某项能力不是首个用户故事所需，就不要写入规格。每项功能都有成本——开发、测试、维护，以及日后的理解成本。在探索过程中，及时反对范围蔓延。

未来的使用者不能成为构建共享基础设施的理由。“可复用基础”可以描述一种架构质量，但它不是用户故事，也不是当前需求。

---

步骤 1：了解情况

深入之前，先了解当前所处的环境。

1. 阅读项目背景——AGENTS.md、README、现有架构文档
2. 检查现有规格——浏览 docs/specs/，了解之前的工作。已有怎样的领域模型？确立了哪些模式？此前构建过什么？
3. 阅读近期规格——最近构建的是什么？此功能是在现有工作基础上构建、扩展现有工作，还是从零开始？

此步骤无需说明——不要叙述过程。根据背景信息确定关注重点。

---

步骤 2：需求探索

通过提问了解需要构建什么。如果根据上下文（现有规格、人类提供的详细信息等）已能明确需求，则跳过此步骤。

访谈风格

一次只问一个问题。尽可能优先使用选择题——给出 2-4 个具体选项，而不是开放式问题。保持对话顺畅推进。

好的示例：“这应该是实时处理还是批量处理？（a）通过 WebSocket 实时处理，（b）每 30 秒定期轮询，（c）用户请求时按需处理。”

不好的示例：“数据同步应该如何运作？”

何时跳过需求探索

• 人类提供了清晰、详细的需求
• 功能扩展已有工作，范围定义明确
• 人类说“为 X 编写规格”，且 X 足够具体

拆分检查

在询问任何细节之前，先评估范围。如果请求描述了多个独立的子系统（例如：“构建一个包含电子邮件、短信、推送通知和管理仪表板的通知系统”）：

1. 立即指出：“这看起来包含多个独立项目。我来提议一种拆分方案。”
2. **拆分任务：**确定各个子系统及其依赖关系。
3. 征求同意：“我们应该先为哪一项编写规格？”

不要试图在一份文档中为所有内容编写规格。

YAGNI 检查

在需求探索过程中，对范围提出质疑：

• “第一版就需要这个吗，还是说它只是锦上添花？”
• “我们能否先不做这个，有需要时再添加？”
• “这个功能会显著增加复杂性——这个使用场景是真实存在的，还是假设性的？”

如果人类坚持，就将其纳入——但要在规格中指出相应的权衡。

需求探索问题

根据具体情况调整。不必每次都问完所有问题。

1. 我们要解决什么问题？ — 具体的问题陈述，而非解决方案描述
2. 谁遇到了这个问题？ — 用户角色
3. 他们目前如何解决？ — 当前工作流和痛点
4. 怎样才算成功？ — 可衡量的结果
5. 需要与哪些内容集成？ — 现有系统、API
6. 有哪些限制？ — 技术、业务、法规方面的限制

如果在前期了解中已经知道答案，就进行确认，而不是再次询问。

告诉人类：“根据我的调研，我对我们要构建的内容有了以下理解。这样看起来对吗？”

停止。等待人类确认。

---

第 3 步：调研

深入阅读相关代码库。不要只看函数签名——还要阅读实现、边界情况、错误处理和数据流。追踪调用方和被调用方。阅读测试以了解预期行为。

如果调研涉及多个文件，请按领域将其委派给只读子 Agent（参见 atelier-orchestrator 中的 Delegation），然后根据他们引用的发现整理调研表。

收集调研结果，为规格奠定基础。在第 4c 步组装好获批的设计章节之前，不要编写 design.md。

调研章节必须将每个相关事项对应到负责处理它的现有代码，以及驱动决策的当前需求：

事项	现有解决方案	决策	当前需求
ID	共享解析器和 ID 类型	reuse	解析路由参数

“决策”列中只能使用 reuse、modify、delete 或 new。每个 new 概念都必须对应一项当前需求；未来或假设性的使用方不符合要求。

告诉人类：“我已经写好规格中的调研章节。继续进行设计前，请先审阅。”

停止。等待人类审阅。

---

第 4 步：设计

设计分为三个阶段：探索方案、分章节展示设计，然后编写规格文件。

4a. 探索方案

确定设计前，先提出 2-3 种方案，并说明各自的权衡。

第一种方案必须保留现有架构，并以最小的正确改动实现需求。 只有当前需求确实需要承担额外成本时，才提出更大范围的方案。 如果方案主要区别在于接口形式，请使用 oracle-codebase-design 中的 design-it-twice 参考。

每种方案都需说明：

1. 方案概览 — 简要的架构草图
2. 优点 — 方案的优势
3. 缺点 — 实施中的难点、成本或风险
4. 复杂度估算 — 粗略估计实现工作量

先介绍推荐方案，并解释它胜出的原因。

在请用户批准方案或设计批次之前，删除所有仅以完整性、一致性或假设的复用为理由的内容。

示例：

方案 A：带 JSON 列的单表

• 架构简单，实现快速
• JSON 内部的查询能力有限，后续迁移会比较麻烦
• 复杂度：低

方案 B：规范化关系表

• 查询清晰，便于扩展架构
• 联接更多、迁移文件更多、代码更多
• 复杂度：中

**建议：**方案 B——在此处，查询灵活性比实现速度更重要。

在呈现设计之前，先就选定方案获得明确批准。

告诉用户：“我们应该采用哪种方案？还是要我探索其他方向？”

停止。等待用户选择方案。

4b. 分批呈现设计

分批呈现设计。每批结束后，先获得批准再继续。

前面步骤中已确认的部分（问题、范围、约束、上下文）会根据确认内容写入规格说明——不要重复呈现。

批次 A：用户故事——作为设计依据的契约。编写正式故事，并附上验收标准和优先级。如果被否决：修订。如果否决表明对范围存在误解，则返回探索阶段（步骤 2）。

批次 B：架构——组件设计、领域建模和分层边界。使用 oracle-codebase-design 以及与你的技术栈相关、已安装的语言专属架构或 API 设计技能。然后呈现：组件结构、领域模型、业务逻辑所在位置、IO 所在位置、不可信输入的解析位置（外部接缝），以及每个模块接受测试的接缝。如果被否决：修订。如果否决动摇了所选方案，请提出返回方案探索（4a）。如果发现根本性缺口，则返回研究阶段（步骤 3）。如果细节表明工作复杂度远超估算，请说明情况，并提出重新审视方案。

批次 C：API 设计 + 数据模型——从已批准的架构推导出的契约。不适用的部分可以跳过，但必须明确说明（“没有 API 变更——继续讨论权衡”）。不得默默跳过。如果被否决：修订。如果否决涉及架构，则返回批次 B。

批次 D：权衡 + 未解决问题——考虑过的替代方案、推荐方案胜出的原因、已知限制以及任何尚未解决的问题。通常可以直接在文中修改。

每个批次结束时都要说：

告诉用户：“这样看起来合适吗？”

停止。获得批准后再继续。

如果同一批次循环两次，请停下来询问：

“我们已经对[批次]循环两次了。要重新考虑方案吗？”

**术语规范：**起草各批次时，对照 CONTEXT.md 检查术语，并将已确认的术语记录在 design.md 中。不要通过此技能更新 CONTEXT.md。如果领域概念混淆严重，建议暂停并先使用 oracle-grill-me。

4c. 编写规格说明

所有批次都获批准后，编写完整的规格说明文档。

规格说明应包含的内容

# Feature Name

## Problem
- What problem are we solving
- Who has this problem
- How they solve it today

## Scope
- **In scope:** [specific capabilities]
- **Out of scope:** [explicitly deferred]

## User Stories
- US-1: As a [role], I want [action], so that [benefit]
  - Given X, when Y, then Z
- Priority: must/should/could

## Constraints
- [Technical or business constraints]

## Context
- What exists today, how it works end-to-end
- Existing patterns and conventions
- Dependencies and integration points
- Gotchas, assumptions, technical debt

## Architecture
- Component structure (functional core / effectful edge)
- Domain model: entities, value objects, aggregates
- Where business logic lives, where IO lives

## API Design
- Endpoints, request/response contracts
- Error handling approach
- Event contracts (published/consumed)

## Data Model
- Schema design, access patterns
- Migrations needed

## Trade-offs
- Alternatives considered
- Why this approach wins
- Known limitations

## Open Questions
- Anything unresolved needing human input

根据复杂度调整各部分的篇幅——简单内容写几句话，复杂内容则详细说明。

参考实现

如果人类提供了参考代码——来自开源项目或代码库中的其他位置——就将其作为具体指南。基于参考实现开展工作，能显著改善设计。

自我审查

写完文件后，用全新的视角检查：

1. 占位符扫描 — 是否有 TBD、TODO、FIXME 或未完成的部分？每个部分都应包含实际内容，或直接删除。
2. 内部一致性 — 各部分之间是否存在矛盾？如果“架构”部分称其为“无状态”，但“数据模型”包含会话状态，就解决这一冲突。
3. 范围检查 — 内容是否足够聚焦，适合制定单个实施计划？如果规范涵盖多个独立子系统，就应该在第 2 步中拆分。如果范围仍然太宽泛，现在就指出。
4. 歧义检查 — 是否有任何需求可能有两种解读？如果有，选定一种解读并明确写出，让人类来纠正你。
5. 必要性检查 — 删除那些仅以完整性、一致性或假设性复用为理由的概念。确认每个保留下来的新概念都对应一项当前需求。

**实质性规则：**如果修正会改变已批准部分的实质内容，就重新提交该部分以供批准。措辞和一致性修正可直接修改——在交接时说明这些修改。

---

第 5 步：交接

告诉人类：

“头脑风暴已完成。设计文档已写入 docs/specs/<path>/design.md。你批准本文档后，可单独调用 spec-plan 来创建 plan.json。”

如果人类通过对话或在文件中添加批注提出修改，就处理每条意见、更新规范并重新进行自我审查。如果修改会改变已批准部分的实质内容，就在继续之前重新提交该部分以供批准。交接前，解决所有影响范围、架构、契约、数据、安全性或任务顺序的问题。

报告 design.md 已完成后即停止。不要调用 spec-plan、主动提出自动继续、创建 plan.json 或编写代码。人类必须通过单独请求启动下一阶段。

如果规划过程中发现设计缺陷，就返回研究阶段。迭代模式请参见 atelier-orchestrator。