blueprint

blueprint skill 概览

blueprint 的作用是什么

blueprint skill 可以把一句话目标拆解成适合复杂工程工作的分步建设方案。它专为跨多个会话、多个 PR 的任务设计，让新接手的 agent 在没有额外猜测的情况下也能获得足够上下文继续推进。如果你需要一份用于 Project Setup 的 blueprint、迁移路线图，或带依赖关系的重构计划，这个 skill 会非常合适。

谁适合安装它

如果你经常需要在不同会话之间交接工作、协调并行子任务，或希望计划在上下文丢失后依然可执行，就值得安装 blueprint。它尤其适合在现有 repo 中工作的 agent：这类场景真正的难点往往不是“想出方案”，而是“按正确顺序安全落地”。

它和普通方案有什么不同

和通用 prompt 不同，blueprint 内置了触发规则、依赖排序、并行步骤识别、对抗式审查关卡，以及计划变更协议。当主要风险不在于写代码本身，而在于顺序选错、步骤范围划分失衡，或遗漏回滚路径时，这些机制就很关键。

如何使用 blueprint skill

正确安装并触发它

先用目录中常规的 skill 安装方式安装 blueprint skill，然后只在任务确实属于多阶段时再调用。这个仓库对触发条件的定义本来就刻意收得很窄：当你需要的是一份 plan、blueprint 或 roadmap，而且工作大概率要跨多个会话或多个 PR 时再用它；如果只是一次就能完成的小改动，就不要为了规划而额外引入它。

给它足够好的输入信息

Blueprint 在输入中明确包含目标、目标 repo、约束条件和完成标准时效果最好。较弱的提示是“plan the refactor”。更强的写法是：“Create a blueprint for Project Setup: move config loading into a shared module, keep backward compatibility for two releases, and separate UI changes from backend migration.” 范围定义越具体，产出的依赖图和步骤粒度通常就越靠谱。

先读这些文件

先看 SKILL.md，然后检查 repo 中任何说明工作流、约定或现有计划的文档。在这个仓库里，skill 的主体内容是自包含的，所以你最需要提取的是它的处理流程：research、design、review，以及 mutation rules。如果目标代码库里还有 memory files、架构文档或以往迁移记录，这些都会显著提升 blueprint 的输出质量。

能产出更好结果的使用流程

使用 blueprint 最好分三轮：第一轮生成计划，第二轮检查每个步骤是否真的能独立执行，第三轮补齐遗漏的依赖关系或不安全的并行安排。要特别留意那些会改动同一批文件、共享状态或依赖发布顺序的步骤；这类地方最容易出现“看起来整齐、执行时翻车”的计划。用好 blueprint 的关键不在“写得更细”，而在“顺序正确，并且给出足够的冷启动执行上下文”。

blueprint skill 常见问题

blueprint 只适合大型项目吗？

大多数情况下是的。这个 skill 是为单个 PR 装不下、或者不先做规划就有明显风险的工作而设计的。如果任务很小、路径很直接，或者只要少量工具调用就能完成，普通 prompt 通常会更快。

blueprint 和普通 prompt 的区别是什么？

普通 prompt 也可以要求生成计划，但 blueprint 多了一层结构化能力：步骤依赖、并行识别、回滚思路，以及用于发现薄弱假设的审查层。因此，当你需要一份用于 Project Setup 的 blueprint，或处理其他对顺序和交接质量要求很高的任务时，它通常更可靠。

blueprint 适合初学者吗？

适合，前提是你的目标是学习如何把项目拆成可管理的阶段。如果你还在决定“这个任务到底是什么”，那它的帮助就没那么大，因为这个 skill 默认前提是：已经存在一个明确的工程目标、约束条件，以及可走通的完成路径。

什么情况下不该用 blueprint？

如果工作小到可以直接做完、用户明确表示“just do it”，或者任务本身没有有意义的依赖结构，就不要使用 blueprint。在这些情况下，规划带来的额外开销只会拖慢速度，不一定会改善结果。

如何改进 blueprint skill 的使用效果

明确边界条件

最好的 blueprint 输出，几乎都来自清晰的范围边界：哪些必须改，哪些必须保持稳定，哪些不在范围内，以及什么才算成功。如果你要的是一份用于 Project Setup 的 blueprint，就要说清楚你改的是 repo bootstrapping、environment config、CI setup，还是三者都改。范围模糊，是最容易让计划变得过大或过浅的原因。

一开始就提供依赖线索

当 blueprint 知道哪些部分会阻塞其他部分时，它的表现会明显更强。请提前说明 migrations、shared modules、feature flags、API contracts、release order，以及任何必须先落地、后续步骤才能启动的事项。这样它更容易产出可用的依赖图，而不是一串彼此割裂的任务清单。

直接要求可执行的步骤

如果你想让 blueprint skill 给出更好的结果，就明确要求它输出“新接手的 agent 也能直接执行”的步骤。这意味着每一步都应包含足够的上下文、预期结果和风险说明，避免执行者为了推进单个步骤又把整个 repo 重读一遍。对于多 agent 协作，这一点尤其重要，因为模糊的步骤标题通常只会带来返工。

把第一版计划当成草稿继续迭代

把第一版 blueprint 当作草稿，在检查完遗漏约束、会互相冲突的并行工作，以及大到无法放进一个 PR 的步骤后，再继续收紧和修正。如果计划过宽，就拆分；如果过细，就合并那些重复性的准备工作。目标不是做出一份更好看的大纲，而是得到一份真正能降低执行风险的 blueprint。