blueprint

Blueprint Skill

目的

将协作式实施计划编写为文档，让每个步骤都遵循构建、审查、验证的循环。将含糊的功能请求、架构变更或重构目标转化为具体且有序的计划，使人类或 Agent 能够逐步执行。将规划视为一场对话——探索代码库、发现工具链、提出问题、比较方案、评估复杂度，然后生成计划。

工作量级别

根据任务复杂度调整探索深度，但始终宁可更全面。先广泛阅读，再逐步聚焦——目标是制定一份在执行过程中不会出现意外的计划。

反模式：“简单到无需规划”

即使只改一行，也包含对修改位置、影响范围和验证方式的假设。“简单”任务恰恰最容易因未经审视的假设而造成返工浪费——构建、审查、验证的结构能在问题叠加前将其发现。计划可以只有一个步骤和一项验收标准；小型计划的快速通道（≤2 个步骤）已将开销降至最低。反模式是完全跳过规划，而不是计划规模太小。

设计原则

优先使用文字，而非代码

计划步骤应使用文字描述意图。除接口签名、配置键和架构形状外，不要包含代码块（完整规范见 references/step-template.md）。第 3 阶段检查清单中的工具命令属于操作说明，并非代码——始终允许使用。

工作流

流程： 探索代码库 → 确认工具链（硬性门槛）→ 澄清需求（硬性门槛）→ 提出方案 → 评估复杂度 → 生成计划 → 对抗性审查 → 计划就绪。

生成计划前有两个硬性门槛：

1. 工具确认门槛（第 1 步之后）：只展示工具链并等待确认——不要将其与澄清问题或任何其他输出合并。
2. 就绪门槛（第 1b 步之后）：澄清过程中发现的所有关键歧义都必须解决。如果以不同方式解决某个歧义会改变计划结构、步骤数量或所选方案，那么该歧义就是关键歧义。

未通过这两个门槛就继续，将导致计划建立在臆测之上。

快速通道规则

涵盖范围较窄变更（配置变更、单文件重构、直接新增）的 ≤2 步计划符合快速通道条件：

• 工具发现（第 1 步）： 将发现的工具与生成的计划一并展示，而不是单独设置确认门槛。计划标题中仍须包含工具链表格。
• 方案提议（第 2 步）： 如果只有一种可信方案，简要说明后继续——不要臆造其他方案。
• 计划审查（第 5 步）： 跳过子 Agent 调度。快速自审，检查验收标准是否有遗漏、验证项是否缺失，以及依赖项是否存在问题。直接展示计划，并询问用户是否要开始执行。

对于包含 3 个或更多步骤的计划，或任何涉及架构、多个模块或横切关注点的计划，所有步骤都必须遵循完整工作流——没有例外。

1. 探索代码库并发现工具

首先，广泛阅读代码库。检查：

• 项目结构（目录、模块、软件包）。
• 入口点（主文件、路由定义、CLI 命令）。
• 数据层（模型、架构、迁移、仓库）。
• 配置（设置文件、环境变量、功能标志）。
• 现有测试（测试结构、固定数据、工厂、覆盖率）。
• 文档（架构文档、ADR、含设置说明的 README）。

探索时，发现项目工具链。 工具发现不是一个独立阶段，而是在探索代码库的过程中自然进行的。遇到配置文件、CI 流水线和锁文件时，记录它们所表明的测试运行器、代码检查工具、格式化工具、类型检查器和软件包管理器。完整的各语言查询表和检测方法请参阅 references/tool-discovery.md。当 CI 流水线命令与配置文件中的命令冲突时，以 CI 命令为准——它们反映了实际运行的命令。

**此步骤仅以确认工具链结束，不做其他事项。** 探索后，向用户列出发现的工具链并等待确认。此回复中不要提出澄清问题、建议方案或开展其他工作。工具链确认是一个必须通过的关卡：用户必须先确认、添加、移除或重新排列工具，然后你才能进入需求澄清阶段。

将工具链格式化为带编号的列表，并在括号中注明每项发现的来源。示例：

Discovered tools for this project:

1. Package manager: uv (from uv.lock)
2. Test runner: pytest (from pyproject.toml [tool.pytest])
3. Linter: ruff check . (from pyproject.toml [tool.ruff])
4. Formatter: ruff format --check . (from pyproject.toml [tool.ruff.format])
5. Type checker: mypy . (from pyproject.toml [tool.mypy])

Add, remove, or reorder? (or confirm to proceed)

快速通道： 对于不超过 2 步的计划，将工具与计划一起直接列出，而不是单独设置确认关卡（参见快速通道规则）。

1b. 澄清需求

用户确认工具链后，提出澄清问题。重点关注：

• 用户真正想要什么（不一定是他们说的内容——有时两者并不相同）。
• 代码中不可见的约束条件。
• 这项工作的完成标准是什么。
• 是否有相关变更计划需要兼容。

持续深入了解需求。总结目前已收集的信息，指出缺口并提出后续问题。对于非简单计划，通常需要进行 2 到 3 轮需求澄清。对于简单明了的任务，一轮可能就足够了。

如果规划涉及适合通过图示或方案视觉对比来权衡的架构决策，superpowers 插件的视觉伴侣可以在浏览器中呈现内容。此功能需要安装 superpowers 插件；如果未安装，则不提供替代方案。

2. 提出方案

了解任务需求并确认工具链后，在确定计划结构之前，概述 2 到 3 种候选实现策略。每种策略用一两句话描述，并指出其主要权衡——优化了什么、牺牲了什么，以及存在哪些风险。先介绍你推荐的策略并说明理由，再展示其他方案，以便用户做出知情选择。等待用户选定方案后，再进行复杂度评估并生成计划。

快速通道： 如果只有一种可信的策略，简要说明后继续（参见快速通道规则）。

3. 评估复杂度

选定方案后，确定计划的范围：

• 统计预期的步骤数。每个步骤应代表一个独立的工作单元——比琐碎的配置更改大，比完整功能更小。如果可以用一句话描述，就将其与相邻步骤合并；如果需要单独的子计划，就拆分。
• 评估是否存在自然的里程碑（例如，“先完成数据层，再完成 API，最后完成 UI”）。
• 根据步骤数选择输出格式：
  • 5 个或更少的步骤，且关注点单一：单个计划文档。
  • 6-8 个步骤，且关注点单一：单个文档，使用分组标题。
  • 存在不同阶段或步骤超过 8 个：里程碑文件夹，每个里程碑对应一个文件。
  • 不明确：询问用户。

步骤规模指南：

• 每个步骤都必须可以独立验证——无需等待后续步骤完成，该步骤的所有测试即可通过。
• 步骤应按顺序逐步推进。后续步骤可以依赖前面的步骤，但不能反过来。
• 避免纯结构性的步骤（“创建目录”），除非项目尚无现有结构。结构性工作应并入第一个功能步骤。

4. 生成计划

按照 references/step-template.md 中定义的结构编写计划产物。每个步骤都包含三个阶段：构建、对抗性审查和验证。

计划标题：包含标题、日期、目标摘要和已确认的工具链。

# Plan: [Feature/Change Title]

**Date**: YYYY-MM-DD
**Goal**: [1-2 sentence summary of what this plan achieves]

## Tool Chain

| Category | Tool | Command |
|---|---|---|
| Test runner | [discovered] | `[test command]` |
| Linter | [discovered] | `[lint command]` |
| Type checker | [discovered] | `[type-check command]` |
| Formatter | [discovered] | `[format command]` |

## Steps

[Steps follow here, each using the 3-phase template]

步骤生成规则：

• 从 1 开始，按顺序为步骤编号。
• 编写清晰、具体且描述交付成果的标题（“添加用户身份验证端点”），而非描述活动的标题（“处理身份验证”）。
• 编写具体且可测试的验收标准。避免“代码整洁”或“性能良好”这类模糊标准。使用可衡量的条件：“第 95 百分位响应时间低于 200ms”“所有验证错误均返回 422，并附带字段级消息”。
• 在第 1 阶段（构建）中，按照先写说明性文字的方式描述意图。说明要创建、修改和测试的内容。适用时引用现有代码模式（“遵循 src/repos/product_repo.py 中使用的同一仓库模式”）。
• 在第 2 阶段（对抗性审查）中，编写针对最可能故障模式的具体审查问题，同时加入更广泛的集成问题：此更改是否自然融入现有代码库？是否遵循既定约定和模式？是否可能影响或降低直接范围之外的任何部分？审查应对已完成的工作进行全面、严格的代码审查，而不只是检查验收标准。目标是在继续之前消除构建阶段引入的所有问题。
• 在第 3 阶段（验证）中，加入已确认工具链的完整检查清单和命令。除标准检查外，还要添加针对该步骤的验证项。

依赖跟踪：如果某个步骤依赖前一步骤的产物，应在目标中明确说明依赖关系。例如：“依赖第 2 步（用户仓库）。使用其中定义的 UserRepository 接口。”

编写里程碑文件夹（适用时）：

• 每个里程碑创建一个文件：01_milestone-name.md、02_milestone-name.md 等。
• 每个里程碑文件遵循相同结构（标题、工具链、步骤）。
• 在计划文件夹的根目录添加 README.md，按顺序列出里程碑，并用一句话描述每个里程碑。
• 每个里程碑包含 3-5 个步骤。如果某个里程碑包含更多步骤，应将其拆分。

5. 对抗性计划审查

将计划写入磁盘后，派遣一个子 Agent 对整个计划进行对抗性审查。子 Agent 从磁盘重新读取计划，不受规划上下文影响——它充当挑剔的第二双眼睛，唯一目的就是在开始执行前找出弱点。

为什么使用子 Agent：编写计划的 Agent 会受自身推理影响。没有完整规划对话历史的新子 Agent 会像执行者一样阅读计划——发现作者看不到的歧义、遗漏和逻辑缺陷。子 Agent 只会收到简要的范围摘要（见下文的 {{PLANNING_CONTEXT}}），以确认计划涵盖了用户的全部意图，而不只是整个规划对话。

快速通道： ≤2 个步骤的计划跳过子 Agent——改为快速自我审查（见快速通道规则）。

派遣审查子 Agent： 使用 Claude Code 的 Agent 工具派遣计划审查子 Agent。具体提示词模板请参考 references/plan-review-subagent.md。派遣前替换占位符：

• {{PLAN_PATH}} — 计划文件或里程碑文件夹的绝对路径。
• {{PROJECT_ROOT}} — 项目根目录的绝对路径。
• {{PLANNING_CONTEXT}} — 编写一份简短摘要（5-10 句话），说明：用户最初的请求、澄清过程中确定的关键约束和决策、商定的范围边界，以及任何明确的排除项（“我们同意不处理 X”）。这样子 Agent 就有足够的上下文来确认计划涵盖了用户的全部意图，而不只是目标标题中描述的内容。

references/plan-review-subagent.md 中的子 Agent 提示词包含完整的审查方法，涵盖完整性、依赖关系、规模、标准质量、阶段质量、文案规范、架构和风险。

子 Agent 返回后：

• 如果审查发现没有问题：告知用户计划已通过对抗性审查，并询问他们是否要开始执行。
• 如果审查发现问题：向用户展示所有发现及子 Agent 的完整报告。由用户决定是否需要修改，或计划目前这样是否可以接受。
  • 如果用户希望修改：按要求修改计划，然后提出是否要对更新后的计划重新进行对抗性审查。用户可以接受再审一轮，也可以拒绝并继续执行。重复这一审查—修改循环，直到用户满意。
  • 如果用户表示计划没问题：继续询问他们是否要开始执行。

不要跳过计划审查（上述快速通道除外）。未经用户同意，不要自动解决审查发现的问题。计划审查是一个硬性关卡——通过此步骤后，计划才算完成。

获得批准后： 将计划文件提交到 git，确保其在不同会话间保留，并支持基于复选标记的进度跟踪。不要跳过此步骤——如果不提交，跨会话续做功能就会失效。

输出格式

请参阅第 3 步（评估复杂度），根据步骤数量选择格式。

单个文档

路径：docs/plans/YYYY-MM-DD-<topic>-plan.md

示例：docs/plans/2026-03-15-user-auth-plan.md

里程碑文件夹

路径：docs/plans/YYYY-MM-DD-<topic>/

内容：

docs/plans/2026-03-15-user-auth/
  README.md
  01_data-layer.md
  02_api-endpoints.md
  03_frontend-integration.md

README.md 提供按顺序排列的里程碑列表及其摘要、已确认的工具链，以及适用于所有里程碑的横切关注事项。

处理计划执行

用户要求执行时，调用 blueprint:execute — 它提供完整的子 Agent 编排，包括批处理、git 处理和进度跟踪。如果不可用，则逐步处理，每次完成全部三个阶段后再进入下一步。在计划标题中用勾号标记已完成的步骤，并勾选第 3 阶段的复选框，以支持跨会话续做。关于计划步骤各阶段应包含的内容，请参阅 references/step-template.md。

处理范围变更

• 如果执行期间的范围变更导致剩余计划中超过一半的内容失效，建议重新开始，而不是修补基于过时假设制定的计划。
• 如果执行期间需要新增步骤，请按照相同的 3 阶段结构（构建、对抗性审查、验证）提出这些步骤，并将其插入计划中的适当位置。

其他资源

详细指南请参阅以下参考文件：

• references/step-template.md — 完整的步骤模板，包含各阶段指南和一个完整的示例步骤。所有计划中的每个步骤都应以此作为结构参考。
• references/tool-discovery.md — 用于检测不同生态系统中项目工具的各语言查找表。在第 1 步探索代码库时将其作为参考。
• references/plan-review-subagent.md — 在第 5 步中调度对抗性计划审查子 Agent 的提示词模板。生成计划后调度审查子 Agent 时，请原样使用此模板。