brainstorm-beagle

Brainstorm：将想法转化为规格说明

通过协作对话，将模糊的想法转化为全面且不涉及实现的项目规格说明。

输出是一份独立的规格说明文档——结构足够清晰，任何智能体系统都能使用；也足够明了，人类可以据此采取行动。它记录 WHAT 和 WHY，绝不涉及 HOW。

<hard_gate> 切勿编写任何代码、创建实现计划、搭建项目框架或采取任何实现行动。此技能只生成一份规格说明文档。无论项目看起来多么简单，都必须经过此流程——“简单”项目中未经审视的假设最容易造成大量无谓工作。 </hard_gate>

工作流

按顺序完成以下步骤：

1. 检查是否有概念简报——如果此想法对应的 .beagle/concepts/<slug>/brief.md 存在，则读取该文件，并跳过步骤 2-4 中的大部分内容（参见下文的 概念简报导入）
2. 探索上下文——阅读项目文件、文档、git 历史记录和现有规格说明（如果已有简报，则进行精简检查）
   • 先例检查（仅限现有项目）：在现有代码库中为功能编写规格说明之前，先进行中立的能力检查，确认该功能尚不存在（参见下文的 先例检查）。无论是否有简报，都必须执行。
3. 评估范围——这是一个规格说明，还是需要拆分？
4. 提出澄清问题——一次只问一个问题，并顺着线索深入（如果已有简报，则少问或不问）
5. 提出 2-3 种方向——概述产品方案及其权衡
6. 起草规格说明——编写结构化的规格说明文档
7. 自我审查——检查完整性、矛盾之处和实现细节渗入情况（参见 references/spec-reviewer.md）
8. 用户审查——提交用户审批，并根据需要迭代
9. 写入磁盘——保存到 .beagle/concepts/<slug>/spec.md

Brief present? ──→ Yes → Ingest brief (skip most discovery) ──┐
                ──→ No  → Explore context → Assess scope       │
                                            ├─ Too large? → Decompose → Brainstorm first sub-project
                                            └─ Right size? → Clarifying questions ─┘
                                                                                   │
Brownfield? ──→ Yes → Prior art check (neutral capability sweep) ─→ Already exists? ─→ surface, reshape/kill spec
            ──→ No  → skip ─────────────────────────────────────────────────────────────────────┐
                                                                                                  │
Both paths converge → Propose directions → Draft spec → Self-review (fix inline) → User review
                                                                                        ├─ Changes? → Revise
                                                                                        └─ Approved? → Write to concept folder

最终状态是一份已写好的规格说明。 此技能不会转入实现、规划或任何其他技能。由用户决定如何处理这份规格说明。

概念简报导入

如果用户对一个已有 .beagle/concepts/<slug>/brief.md 的概念调用 brainstorm-beagle（该文件由 PRFAQ 流程生成），则在步骤 1 导入简报，并跳过大部分探索工作：

1. 阅读简报。 客户、问题、解决方案概念、重要性、已确定的决策和研究线索都已记录在案。不要就这些内容再次采访用户。
2. 浏览 PRFAQ 参考文档。 打开 .beagle/concepts/<slug>/prfaq.md，查看其中的 Reasoning 区块——它们解释了哪些内容受到质疑，以及早先为何做出相关决策。这些是背景信息，不是需要重新讨论的内容。
3. 从待解决问题开始。 简报的 Open Questions 部分列出了 PRFAQ 提出但尚未解决的问题。你要询问用户的是这些问题，而不是已经确定的客户、问题或动机。
4. 继续探索方向。 跳过澄清问题和范围评估，除非简报对范围本身的说明含糊不清。

简报是上下文交接，不是门槛。对产出的规格说明仍须自行审查——无论上游已经完成多少探索，brainstorm-beagle 仍负责检测实现细节渗入、检查需求是否可测试，以及确保范围得当。

没有简报时： 正常执行步骤 2-9。并非每个想法都来自 PRFAQ。

简报不能免除先例检查。 简报（或其背后的 issue）会将功能描述成有待构建的内容——这正是 先例检查 要消除的偏见。即使导入了简报，也必须执行检查。

既有实现检查

这一步是为避免一种具体且代价高昂的失败：编写规格，重新实现代码库中已有的能力。只要构想是在现有代码库（棕地项目）中添加功能，就适用此步骤。对于没有现有代码的绿地项目构想，请跳过。

**要防止的失败模式：**问题或简报将某项功能描述为新功能（“我们移除了旧的截断功能，请重新设计”），或者干脆没有提及已有实现。你——或你委派其进行探索的子 Agent——会接受这种说法，只查找它所指向的位置，确认这种说法，然后编写一份重复已有且经过测试的代码的功能规格。这样一来，下游规划者和执行者就会根据这份规格重新构建已有功能。

应遵循的准则：中立搜索，不受既有说法影响。

1. 对整个工作区进行能力关键词扫描——检查每个 crate/package/module，而不只是问题所指向的目录。根据能力可能使用的名称、同义词和缩写进行搜索，而不是只搜问题中的用词。对于截断功能，在所有源代码根目录中搜索 grep -riE 'truncat|spill|cap|max_bytes|head_bytes|limit|trim|elide'。尽量扩大范围；只要有一个文件匹配，就足以推翻原有假设。
2. 不要相信“此功能不存在”的说法。 问题和简报可能会过时，因为代码可能在问题提交后就已经有人编写。问题中的“我们移除了 X／X 尚不存在”应视为需要通过 grep 证伪的假设，而不是可以直接接受的事实。
3. 如果委派子 Agent 进行探索，应让它执行中立扫描，而不是按既有说法限定范围。 应要求它“在整个工作区中 grep 这些能力关键词，并报告所有匹配结果”，而不是“去 module/foo 里找 X 的实现”。范围受限的任务会让子 Agent 重复受到既有说法的偏见影响。提供关键词列表；不要提供问题中对代码位置的推测。
4. 明确说明发现。 如果扫描发现该能力（或其大部分）已经存在：
   • 明确指出，并引用相关文件——“agent/src/spill.rs 已实现带旁路文件的头尾截取，并且有相应测试。”
   • 围绕缺口重新调整规格，而不是重新描述整个功能：扩展、修复或接入现有实现，而不是从头重建。这样通常会大幅缩小规格，甚至不再需要编写规格。
   • 将此发现记录为关键决策（Key Decision），例如“基于现有的 spill.rs 实现，而不是新建截断模块”，以免下游规划者再次讨论这个问题。
5. 组合检查。 对扫描发现的每种现有机制，都要确认：它是否位于同一数据流水线中的该功能上游或下游？它是否会转换该功能依赖的数据（截断、筛选、缓冲、重排、去重）？如果答案是肯定的，那么“该机制已经存在”并不代表调查结束——它与新功能的组合方式才是关键问题。将这种交互记录为关键决策（Key Decision），例如“bash 已在上游将输出限制为 50 KiB；spill 必须在该限制生效前捕获数据，否则无法提供完整输出”，并为该决策添加标签 needs-spike-before-planning，同时在其 Rationale 中补充：**Spike required:** 在锁定计划前，依据此仓库验证上游／下游的数据形态（会截断、筛选、缓冲、重排、去重什么内容，以及此功能是在其前还是之后捕获数据），并在结果与假设不符时修订此决策。 在同一流水线中，新机制若与现有机制组合不当，即使两者都不是重复实现，也会导致交付的功能无法正常工作。

这与第 2 步“探索上下文”（Explore context）不同；后者通过阅读来了解项目。既有实现检查是对抗性的：它的作用是在“功能是新的”这一假设固化为规格之前，设法证伪该假设。

提问

你是思考伙伴，不是采访者。用户有一个模糊的想法——你的工作是帮助他们把想法打磨得更清晰。

如何提问：

• 从开放式问题开始。 让他们畅所欲言地讲述自己的想法。不要用结构化问题打断他们。
• 顺着他们的热情深入。 追问他们着重强调的内容。什么让他们兴奋？是什么问题引发了这个想法？
• 挑战模糊之处。 绝不接受含糊的回答。“好”是什么意思？“用户”指谁？“简单”又是怎样的？
• 让抽象的想法具体化。 “带我走一遍使用过程。”“具体来说，它是什么样的？”
• 澄清歧义。 “你说的 Z，是指 A 还是 B？”
• 知道何时停止。 当你了解要做什么、为什么做、为谁做，以及完成的标准时，就提出继续推进。

提问方式：

• 每条消息只问一个问题。如果一个话题需要追问，就分多条消息进行。
• 尽可能采用选择题——相比开放式问题，人们更容易对具体选项作出回应。
• 用户选择“其他”或想自由解释时，就改用纯文本。不要强迫他们回到结构化选项。
• 2-4 个选项最合适。绝不要使用宽泛的类别（“技术”“业务”“其他”）。

可以询问的内容：

询问内容	示例
动机	“是什么促使你提出这个想法？”“你现在在做什么，而这个项目可以取代它？”
具体情况	“带我走一遍使用过程。”“举个例子。”
澄清	“你说的 X，是指 A 还是 B？”
成功标准	“你怎么知道它正在发挥作用？”“怎样才算完成？”
边界	“这个项目明确不包含什么？”

不要询问的内容：

• 技术实现细节（留到规划阶段）
• 架构模式（留到规划阶段）
• 用户的技术水平（无关紧要——系统会负责构建）
• 成功指标（可从工作内容中推断）
• 不考虑上下文而照搬的固定问题（“你的核心价值是什么？”“有哪些利益相关方？”）

背景检查清单（在心里检查，不要说出来）：

• 用户要构建什么（具体到能向陌生人解释清楚）
• 为什么需要它（驱动项目的难题或需求）
• 面向谁（即便只有用户自己）
• “完成”是什么样的（可观察到的结果）

以上四项都明确后，就提出继续推进。如果用户想继续探索，就继续。

范围评估

深入提问之前，先评估这个想法是一个项目还是多个项目。

需要拆分的迹象：

• 包含多个彼此独立的子系统（“构建一个包含聊天、文件存储、计费和分析的平台”）
• 各部分之间没有明确的先后依赖关系
• 需要数月才能完成

需要拆分时：

1. 帮助用户找出彼此独立的部分及其关系
2. 确定这些部分的构建顺序
3. 按照常规流程集思广益，讨论第一个子项目
4. 每个子项目都单独编写规格说明

对于规模合适的项目，直接开始澄清问题。

探索方向

了解想法后，提出 2-3 个高层次方向。这些是产品方向，而非技术架构。

好的方向：

• “针对单个文件操作的 CLI 工具，还是监视目录的守护进程”
• “只包含核心循环的聚焦版 MVP，还是包含配套功能的更全面首版”
• “优先优化使用速度（面向高级用户），还是优先优化易发现性（面向新用户）”

不好的方向（涉及具体实现）：

• “使用 React 和 REST API，还是使用 HTMX 和服务器端渲染”
• “存储使用 PostgreSQL，还是 SQLite”
• “使用单体仓库，还是多仓库”

先给出你的建议并解释原因。以自然对话的方式说明利弊。

范围纪律

头脑风暴自然会产生超出当前范围的想法。请妥善处理：

当用户在头脑风暴过程中扩大范围时：

“这是个很棒的想法，但它本身就是一个独立的项目／阶段。我会把它记录在‘未来考虑事项’中，以免遗漏。现在，我们先聚焦于[当前范围]。”

**判断方法：**这能否让我们更明确要构建什么，还是增加了一项可以独立存在的新能力？

将暂缓处理的想法记录在规范的“未来考虑事项”部分。不要遗漏，也不要着手实现。

实现细节泄漏

规范绝不能规定实现方式。这是最难遵守的纪律。

允许（WHAT）	不允许（HOW）
“用户可以按日期和类别筛选结果”	“添加一个接受查询参数的 /api/filter 端点”
“必须支持 10k 个并发用户”	“使用 Redis 缓存会话”
“数据必须在不同会话之间持久保留”	“使用 PostgreSQL 和 users 表存储数据”
“必须支持离线使用”	“使用带有 IndexedDB 的 service worker”
“搜索必须让人感觉即时完成”	“使用带防抖查询的 Elasticsearch”

**例外——约束：**当用户确实存在约束（“必须使用 PostgreSQL，因为我们的基础设施就是这样运行的”）时，应将其连同理由写入“约束”部分。约束是边界条件，而不是头脑风暴期间作出的设计选择。

依赖工具行为的关键决策

规范中的某些关键决策会采用“我们将使用工具 Y 的功能 X 来实现 Z”这样的形式（例如“通过 sqlx 的离线缓存，在两个后端上实现编译时 SQL 检查”“通过框架的单二进制目标构建双平台版本”）。这些决策看似已经确定，却包含一个未经验证的假设：在应用到当前代码库时，工具的实际行为是否与文档所暗示的一致。

记录这类关键决策时，必须二选一，不得两者皆无：

1. **引用已验证的示例。**指出代码库中的文件（或磁盘上的可比代码库），证明该工具已经实现了决策所依赖的功能。core/.sqlx/ 中现有的 N 个查询文件就是引用；凭记忆说“sqlx 支持编译时检查”则不算。
2. **为决策添加 needs-spike-before-planning 标签。**在理由中添加明确标记：**需要进行 Spike：** 在 plan-lock 之前，针对本仓库验证 <具体命令／行为>；如果结果与假设不符，则修订此决策。

缺少上述任一项的决策，会被下游规划者当作事实写入计划，执行者也会据此尝试构建——而“文档说它能用”正是一个 5 行计划任务膨胀成 400 行 bash 变通方案的原因。Spike 标签会提示规划者添加一个 Task 0 Spike；引用则会告诉规划者，现有代码中已经隐含完成了 Spike。

这条规则的范围比实现细节泄漏更窄。决策仍然可以处于 WHAT 层面（例如“数据必须在编译时进行类型检查”就是 WHAT）。此规则仅适用于决策的理由依赖用户在没有证据的情况下断言的特定工具行为。

规格说明格式

使用 references/spec-template.md 中的模板。规格说明包含以下部分：

1. 核心价值 — 用一句话说明最重要的内容
2. 问题陈述 — 问题是什么、谁遇到了这个问题，以及为什么是现在
3. 需求 — 必须具备、应该具备、不在范围内（并说明原因）
4. 约束 — 附带理由的硬性限制
5. 关键决策 — 头脑风暴期间做出的决策，以及考虑过的替代方案
6. 参考依据 — “我希望它像 X 一样”的示例、外部文档、灵感来源
7. 开放问题 — 尚未解决、需要后续研究的事项
8. 未来考虑事项 — 已出现但应归入后续阶段的想法

需求必须具体且可测试：

好的需求	不好的需求
“用户可以撤销最近 10 次操作”	“提供良好的撤销支持”
“页面在 3G 网络下的加载时间不到 2 秒”	“性能快”
“可与屏幕阅读器配合使用”	“无障碍”
“导出为 CSV 和 JSON”	“支持多种导出格式”

自我审查

起草规格说明后，请检查以下事项：

1. 占位内容 — 是否有任何 TBD、TODO 或含糊的需求？请修正。
2. 矛盾 — 是否有任何章节相互冲突？请解决。
3. 实现泄漏 — 是否有需求规定了 HOW？请改写为 WHAT。
4. 不可测试的需求 — 是否有人能验证这些需求已满足？请使其具体明确。
5. 缺少理由 — 约束和范围外事项是否说明了原因？请补充理由。
6. 范围 — 是否足够聚焦，适合在单个规划周期内完成？
7. 重复造轮子（现有项目） — 是否有任何必须具备的功能会重建代码库中已有的能力？如果尚未检查先前方案，请现在检查。请围绕实际差距重新表述重复的需求。
8. 使用方（现有项目） — 是否有任何必须具备的需求引入了新的对外能力（API 表面、命令、端点、导出契约），但规格说明中没有任何内容会使用它？如果没有指出谁或什么会使用它，请明确使用方，或将该项移至 未来考虑事项。无人使用的对外接口属于推测性内容——请在提交前修正。

请直接修正问题，然后提交给用户审核。

详细审核清单请参阅 references/spec-reviewer.md。

提交草稿前的检查（用户审核步骤）： 只有每一项都能如实回答是（而非“感觉没问题”）时，才继续。

1. 模板： 草稿遵循 references/spec-template.md 中的章节结构（或说明有意省略的部分及原因）。
2. 不依赖诚信假设来确保完整性： 已满足上述第 1–7 项；未解决的占位内容/TODO 仅限于 开放问题，不得夹带在必须具备的需求中。
3. 泄漏检查： 除明确列在 约束 中且附有理由的项目外，每项必须具备/应该具备的需求都通过了 references/spec-reviewer.md 中 实现泄漏 部分的双方案测试。
4. 产物： 草稿文本已出现在对话中（或单个附加缓冲区中），确保用户审核的是具体文案，而非摘要。

编写规范

创建或覆盖 spec.md 前必须通过： 只有以下两项都满足后才能写入。

1. 用户确认门槛： 用户明确批准了草稿，或指示你保存/写入文件（仅表达模糊的热情不算批准——如有疑问，请先确认）。
2. 路径确认门槛： 目标路径已确定——默认为 .beagle/concepts/<slug>/spec.md，且 slug 已确定（取自 brief frontmatter 或双方同意的标题）。

• 默认路径： .beagle/concepts/<slug>/spec.md
• Slug 来源： 如果已导入 brief，则沿用其 frontmatter 中的 slug；否则根据概念标题生成 kebab-case slug（≤40 个字符，不含日期）。用户偏好优先于默认路径。
• 会话内的配套输出： 如果 brainstorm-beagle 在会话中调用 web-research 或 artifact-analysis，请传入 output_dir: /abs/path/.beagle/concepts/<slug>/research/ 或 output_dir: /abs/path/.beagle/concepts/<slug>/analysis/，以便研究结果与上游 PRFAQ 生成的内容保存在同一个概念文件夹中。这样，整个概念构思过程的审计记录都能集中存放。
• 使用提交信息提交到 git：docs: add <slug> project spec
• 写入后，告知用户：

  "规范已写入 <path>。请检查；如果需要修改，请告诉我。"

• 等待用户批准后，再视为头脑风暴完成。

核心原则

• 一次只问一个问题——不要让用户应接不暇
• 顺着话题深入——不要机械地逐项核对清单
• 严格遵循 YAGNI——删除所有明显不必要的内容
• 只做具体决策——写“卡片式布局”，而不是“现代且简洁”
• 不涉及实现——只说明是什么和为什么，绝不说明如何实现
• 完整记录所有内容——范围之外的想法放入 Future Considerations，不要遗漏
• 渐进式验证——继续之前先确认理解一致
• 每项能力都必须有使用者——新增面向外部的接口名称时，必须说明谁/什么会使用这项必备能力；否则将其移入 Future Considerations。没有使用者的接口只是推测
• 规范应独立完整——任何人都应能单独阅读并理解项目