write-blueprint

编写 Blueprint 技能

目的

生成协作式实施计划，并将其作为书面文档，其中每个步骤都遵循构建-评审-验证循环。将模糊的功能请求、架构变更或重构目标转化为具体、按顺序排列的计划，供人类或 Agent 逐步执行。将规划视为对话——探索代码库、了解工具、提出问题、比较方案、评估复杂度，然后生成计划。

工作量级别

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

计划格式

计划应写入一个独立文件（里程碑计划则写入文件夹）。格式决定文件扩展名以及步骤 4 中使用的步骤模板。HTML 是默认格式，因为它支持内嵌 SVG 依赖关系图来表示非线性步骤依赖，支持结构化的 data-status 属性，供 execute-blueprint 精确跟踪进度，并支持步骤之间的锚点交叉引用——这些功能能显著改善多步骤计划，而且无法用 Markdown 表达。

与审计技能不同，Blueprint 格式不是硬性门槛。根据启动消息判断用户的偏好并予以遵循：

• HTML 信号：HTML、html、“as a webpage”、“browser-viewable” → 使用 HTML。
• Markdown 信号：MD、md、Markdown、markdown、“plain text plan”、“as Markdown” → 使用 MD。
• 没有信号：默认静默使用 HTML。磁盘上的文件扩展名（.html 与 .md）是所选格式的权威标识——不要仅为重复说明扩展名已表达的信息，而在计划标题中添加多余的“Format: HTML”行。

如果启动消息确实无法判断格式（例如信号相互冲突，或用户询问“我该使用哪种格式？”），则询问一次并继续。如果通过默认值解决了实际存在的歧义，请在计划标题中简要说明这一处理（例如：“所选格式：HTML——启动消息中的信号相互冲突，因此默认使用 HTML”）。否则，不要因为格式门槛而打断规划对话——规划流程已经有许多硬性门槛（工具链、澄清、方案、计划评审）。

在本次运行的剩余过程中始终使用所选格式：

格式	步骤模板	文件扩展名
HTML	references/step-template-html.md	.html
MD	references/step-template.md	.md

编写 HTML 计划时，应将 references/step-template-html.md 中记录的 HTML 专属功能视为可在能提供信息时使用的工具，而非装饰。若只是将 Markdown 内容包在 HTML 标签中，却不使用这些功能，就失去了选择 HTML 的意义。

反模式：“简单到不必规划”

即使只改一行，也涉及代码放在哪里、会影响什么以及如何验证等假设。“简单”的任务恰恰最容易因未经审视的假设而导致返工——构建-评审-验证结构能在问题累积之前将其发现。计划可以只有一个步骤和一条验收标准；小型计划（≤2 个步骤）的快速路径已经将开销降至最低。反模式是完全跳过规划，而非计划规模太小。

设计原则

重意图，轻代码

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

上下文管理（子 Agent 驱动）

规划刻意采用子 Agent 驱动的方式，让主对话保持精简，只负责协调。两个最消耗令牌的环节——探索阶段（步骤 1）批量读取代码库，以及对抗式计划审查（步骤 5）——都交由子 Agent 处理，子 Agent 返回后即可回收其上下文。主对话只保留提炼后的发现：结构图、已确认的工具链、已解决的需求和审查报告，而不是每个已检查文件的原始内容。execute-blueprint 也采用同样的做法，将每次构建、审查和验证都放在子 Agent 中执行。保持上下文窗口精简，才能让这两种技能在大型代码库和多里程碑计划中扩展，而不会导致效果下降。

工作流

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

生成计划前有两个硬性关卡：

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

未通过这两个关卡就继续，会导致计划建立在猜测之上。

快速通道规则

步骤不超过 2 步且涉及范围明确的变更（配置变更、单文件重构、直接的功能添加）的计划，可以走快速通道：

• 工具发现（步骤 1）： 将发现的工具与生成的计划一起展示，而不是将其作为单独的确认关卡。仍需在计划标题中加入工具链表格。
• 方案提议（步骤 2）： 如果只有一种可信的策略，简要说明后继续——不要凭空捏造其他方案。
• 计划审查（步骤 5）： 跳过子 Agent 派发。快速进行自我审查，检查验收标准是否有遗漏、验证项是否缺失，以及是否存在依赖问题。直接展示计划，并询问用户是否要开始执行。

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

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

先广泛了解代码库。对于规模超过小型项目的代码库，应通过 Claude Code 的 Agent 工具分派探索子 Agent，并行阅读不同区域，再让它们返回提炼后的发现——包括结构图、入口点、数据层、约定和发现的工具链——而不是在主对话中逐个阅读所有文件。协调者综合这些摘要，只保留规划对话所需的信息；这样可以控制上下文窗口的占用。主对话中直接阅读的内容应限于少数必须逐字查看、以便提出精确澄清问题的文件。

检查代码库中的以下内容：

• 项目结构（目录、模块、包）。
• 入口点（主文件、路由定义、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. 澄清需求

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

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

持续确认理解是否准确。总结目前收集到的信息，指出尚待明确之处，并提出后续问题。对于非简单计划，通常需要两到三轮澄清。对于简单、定义明确的任务，一轮可能就足够。

如果规划涉及适合用图表或方案可视化比较的架构决策，superpowers 插件的可视化助手可以在浏览器中呈现这些内容。此功能需要安装 superpowers 插件；如果插件未安装，则没有替代方案。

2. 提出方案

充分理解任务并确认工具链后，在确定计划结构前，先概述 2-3 个可选实施策略。每种策略用一两句话说明，并指出其关键权衡——优化了什么、舍弃了什么，以及存在哪些风险。首先介绍你推荐的策略并解释理由，然后再提出其他方案，帮助用户做出知情选择。等待用户选择方案后，再进行复杂度评估并生成计划。

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

3. 评估复杂度

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

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

步骤划分指导：

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

4. 生成计划

按照上文「计划格式」部分所选格式对应的模板编写计划产物：HTML 输出使用 references/step-template-html.md（默认），Markdown 使用 references/step-template.md。每个步骤都包含三个阶段：构建、对抗性审查和验证。

计划标题：包含标题、日期、目标摘要和已确认的工具链。标题的具体呈现方式见所选模板的「计划文档结构」部分。Markdown 标题如下所示：

# 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]

对于 HTML，标题使用 references/step-template-html.md 中定义的 <header class="plan-header"> 和 <section id="tool-chain"> 框架。HTML 计划中 <article class="step"> 上必需的 ID、类和 data-* 属性不可省略——execute-blueprint 会修改这些确切属性以跟踪进度。

步骤生成规则：

• 从 1 开始按顺序为步骤编号。
• 编写清晰、具体且描述交付成果的标题（「添加用户身份验证端点」），而不是描述活动的标题（「处理身份验证」）。
• 编写具体且可测试的验收标准。避免使用「代码整洁」或「性能良好」等模糊标准。使用可衡量的条件：「第 95 百分位的响应时间低于 200ms」「所有验证错误均返回 422，并包含字段级消息」。
• 在阶段 1（构建）中，按照先写说明的方式描述意图。说明要创建、修改和测试的内容。适用时引用现有代码模式（「遵循 src/repos/product_repo.py 中使用的相同仓库模式」）。
• 在阶段 2（对抗性审查）中，编写针对最可能失败模式的步骤专属审查问题，同时也要包含更广泛的集成问题：此变更是否自然融入现有代码库？是否遵循既定约定和模式？是否可能破坏或降低其直接范围之外的内容？审查应对已完成的工作进行全面、严格的代码审查，而不只是核对验收标准。目标是在继续之前，消除构建阶段引入的所有问题。
• 在阶段 3（验证）中，加入完整的检查清单，并附上已确认工具链中的工具命令。添加标准检查之外的步骤专属验证项目。
• 如果某个步骤确实需要人员在执行继续之前进行检查——例如渲染后的 UI、针对真实数据执行的迁移，或任何工具都无法确认的审批——请在步骤文本中明确说明。execute-blueprint 会自行修复常规问题，只会在计划要求人工参与时暂停，因此未明确说明的检查点不会触发暂停。

依赖跟踪：如果某一步依赖先前步骤的产物，请在目标中明确说明依赖关系。例如：「依赖步骤 2（用户仓库）。使用该步骤中定义的 UserRepository 接口。」

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

• 按照所选格式的扩展名，为每个里程碑创建一个文件：HTML 使用 01_milestone-name.html、02_milestone-name.html 等；Markdown 使用 .md。
• 每个里程碑文件都遵循所选模板中的相同结构（标题、工具链、步骤）。
• 在计划文件夹中添加根目录 README（HTML 计划使用 README.html，Markdown 计划使用 README.md），按顺序列出里程碑，并为每个里程碑附上一句话说明。HTML 版本使用 references/step-template-html.md 中的 <section id="milestones"> 框架。
• 每个里程碑包含 3–5 个步骤。若步骤更多，则拆分里程碑。
• 不要在同一个计划文件夹中混用格式。所有里程碑文件和 README 都使用相同的扩展名。

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 步（评估复杂度），根据步骤数量选择文档布局。有关选择 HTML 还是 Markdown，请参阅本技能前面的“计划格式”。这两项选择彼此独立：任何文档布局都可以采用 HTML 或 Markdown。

单个文档

路径：docs/plans/YYYY-MM-DD-<topic>-plan.<ext>，其中 <ext> 为 html（默认）或 md。

示例（HTML）：docs/plans/2026-03-15-user-auth-plan.html 示例（MD）：docs/plans/2026-03-15-user-auth-plan.md

里程碑文件夹

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

内容（HTML，默认格式）：

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

内容（Markdown）：

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

README（.html 或 .md，与计划格式一致）提供按顺序排列的里程碑列表及其摘要、已确认的工具链，以及适用于所有里程碑的跨领域注意事项。

处理计划执行

当用户要求执行计划时，调用 blueprints:execute-blueprint——它提供完整的子 Agent 编排、Git 处理和进度跟踪，并支持 .md 和 .html 两种计划格式。如果无法调用，则逐步执行，每次完成全部三个阶段后再继续下一步。在计划标题中为已完成的步骤添加勾号，并勾选第 3 阶段的复选框（对于 HTML 计划，则在步骤的 <article> 上设置 data-status="complete"，更新状态徽章文字，在步骤标题前添加 ✅ ，并为验证复选框添加 checked），以便在不同会话间恢复进度。有关计划步骤各阶段应包含的内容，请参阅 references/step-template.md 或 references/step-template-html.md。

处理范围变更

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

其他资源

有关详细指导，请参阅以下参考文件：

• references/step-template.md — Markdown 步骤模板，包含各阶段指导和完整的步骤示例。选择 Markdown 作为计划格式时，请将其用作结构参考。
• references/step-template-html.md — HTML 步骤模板，包含必需的脚手架、结构约定（ID／类／data-* 属性）、HTML 专属功能说明和完整的步骤示例。选择 HTML 作为计划格式（默认格式）时，请将其用作结构参考。
• references/tool-discovery.md — 按语言分类的查找表，用于检测不同生态系统中的项目工具。在第 1 步探索代码库时，请将其用作参考。
• references/plan-review-subagent.md — 第 5 步中分派的对抗性计划审查子 Agent 的提示词模板。生成计划后分派审查子 Agent 时，请原样使用此模板。