writing-plans

writing-plans skill 概览

writing-plans skill 是做什么的

writing-plans skill 用于在真正开始写代码之前，把功能 spec 或需求文档整理成一份详细的实施计划。它的核心职责不是帮你发散想法，而是产出一份“可落地、可评审”的计划：即使执行者对代码库背景了解不多，也能拿到明确的文件级指引、测试步骤和任务顺序。

谁适合使用 writing-plans

writing-plans 特别适合已经明确了需求范围、现在需要为 Requirements Planning 制定执行方案的工程师、技术负责人，以及 agent 驱动的工作流。尤其在以下场景下更有价值：改动跨多个文件、会涉及测试与文档，或者后续执行人并不是最初撰写 spec 的那个人。

它真正解决的是什么问题

使用 writing-plans 的人，通常是想减少实现阶段的“靠猜推进”。它带来的价值不只是“生成一份计划”，而是“生成一份没有隐含前提、让合格工程师也能照着执行的计划”。这包括：需要改哪些文件、如何把工作拆成可执行的小任务、应该测什么，以及在正式实现前哪里应该先拆 scope。

它和通用提示词有什么不同

writing-plans skill 的方法有明确倾向，而且这些倾向都很关键：

• 在拆解任务前，先做 scope 检查
• 在写任务前，必须先梳理文件职责
• 更偏好小步、可测试的增量，而不是大而泛的阶段划分
• 默认执行者对业务和代码上下文掌握较弱
• 自带 reviewer prompt，用来检查计划是否真的可实施

如果你在意交接质量，它会比一句“帮我写个 implementation plan”的通用 prompt 更靠谱。

什么情况下 writing-plans 很适合

在以下情况下，writing-plans 是很强的匹配：

• 你已经有书面的 spec、ticket 或需求文档
• 这是一个多步骤、且包含实质实现细节的改动
• 需要同时协调代码、测试和文档
• 所在仓库里文件边界和执行顺序很重要

如果你只想快速列个提纲，或者做个粗略估算，那它可能会显得偏重。

如何使用 writing-plans skill

writing-plans 的安装上下文

这个仓库并没有在 skill 内部单独提供包级安装器，所以实际可行的 writing-plans install 方式，是先安装它所属的上层 skill 集合，再从中调用这个 skill：

npx skills add https://github.com/obra/superpowers --skill writing-plans

如果你的环境使用的是别的 skill loader，那就安装 obra/superpowers 这个集合，并从 skills/writing-plans 里选择 writing-plans。

建议先看这两个文件

如果你只是想快速评估，优先看：

• skills/writing-plans/SKILL.md
• skills/writing-plans/plan-document-reviewer-prompt.md

SKILL.md 里是实际的规划流程；plan-document-reviewer-prompt.md 则体现了这份计划需要达到的质量标准。对于判断这个 skill 是否适合进入生产工作流，这两个文件最有参考价值。

这个 skill 需要什么输入

writing-plans usage 的效果最好时，你应当提供：

• 原始 spec 或需求文档
• 目标仓库，或明确的代码库范围
• 与架构、工具链、截止时间、向后兼容相关的约束
• 如果你不想用默认路径，就说明计划输出的位置
• 是否需要把工作拆成多份彼此独立的计划

如果没有真实 spec，writing-plans 往往还是能产出看起来像样的结构，但在实现指导层面会明显变弱。

一开始先加上规定的声明

上游说明里明确要求 agent 先声明：

I'm using the writing-plans skill to create the implementation plan.

如果你要把它接进 agent 工作流，建议保留这句话。这样可以明确当前调用的是哪套规划标准，也能减少流程上的歧义。

最好在写代码前使用，并放在独立 worktree 里

这个 skill 的设计目标是“实现前规划”，并且默认它会运行在一个由上游 brainstorming 工作流创建的独立 worktree 中。即使你没有完全照搬那套搭配，原则仍然值得保留：先在隔离环境里做规划，再开始改代码。这样产出的计划才是一个经过刻意设计的交付物，而不是编码过程顺手留下的副产品。

如何把模糊目标变成高质量 prompt

较弱的 prompt：

• “Make a plan for adding billing.”

更强的 prompt：

• “Use the writing-plans skill to create an implementation plan for adding team billing to our SaaS app. Spec: docs/specs/team-billing.md. Repo areas likely involved: apps/web, services/billing, db/schema. Constraints: Stripe is already used for individual billing, do not break existing subscriptions, include migration and rollback considerations, and call out tests and docs. If the spec spans independent subsystems, propose separate plans.”

为什么这个版本更有效：

• 它明确指出了 spec
• 它给出了可能涉及的文件或模块
• 它说明了会影响任务拆解的关键约束
• 它允许按 scope 拆分，而不是强行塞进一个过大的计划

按照 skill 的规划顺序来用

一份靠谱的 writing-plans guide，应该遵循仓库隐含的这套顺序：

1. 先检查 spec 是否应该拆成多份独立计划
2. 在拆任务前，先把文件和职责对应起来
3. 再写成小而可执行的实现任务
4. 把测试、文档和验证步骤一起写进去
5. 最后对照 spec 复审整份计划

最常见的问题，就是跳过“文件结构梳理”这一步，结果任务写得很空泛。

好的输出应该包含什么

一份高质量的 writing-plans for Requirements Planning 计划，通常应当包含：

• 计划目标，以及对应的 spec
• 需要新增或修改的文件
• 每个文件为什么存在，或者为什么要改
• 足够小、能独立完成并验证的任务
• 不只是编码步骤，还包括测试指引
• 如果相关，还要包括文档或迁移更新
• 足够详细，让另一位工程师不会轻易卡住

如果输出大多只是类似“backend”“frontend”“QA”这样的主题阶段，那通常说明它还太粗。

默认的计划保存路径，以及何时覆盖

这个 skill 建议把计划保存到：

docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

如果你的仓库已经有既定规划目录，比如 docs/plans/ 或 specs/implementation/，那就应该覆盖这个默认路径。关键不在于非得用哪个目录，而在于保持一致，并且让 reviewer 之后能找得到。

如何使用 reviewer prompt

计划初稿写完后，可以把 plan-document-reviewer-prompt.md 当作第二轮审查模板。它的审查标准都很实用：

• 完整性
• 与 spec 的一致性
• 任务拆解质量
• 是否可构建、可执行

这也是 writing-plans skill 很有辨识度的一点：它不只负责“生成计划”，还顺带给了你一套轻量的验收检查方式。

一套实际可用的工作流

一套比较稳妥的流程通常是这样的：

1. 收集 spec 和仓库上下文
2. 运行 writing-plans
3. 检查计划拆分是否合理
4. 审视文件边界和任务粒度
5. 运行 plan reviewer prompt
6. 在真正开始实现前先修订计划

按这个方式使用，writing-plans 最有价值的角色是“规划闸门”，而不只是一个写作便利工具。

writing-plans skill 常见问题

writing-plans 适合新手吗？

适合，前提是新手手里已经有一份相对具体的 spec。这个 skill 会通过强制要求明确文件和测试指引，来弥补代码库上下文不足的问题。但如果真正的问题是产品方向本身还没想清楚，那它能帮上的就比较有限。

它和直接让 AI 写 implementation plan 有什么区别？

通用 prompt 很容易写出“看起来很完整、实际上比较浅”的计划。writing-plans 更有用，是因为它会强制往文件级拆解、关注可测试性，以及强调交接质量。这样通常能减少正式编码后的返工。

什么情况下不该用 writing-plans？

在下面这些情况下可以跳过：

• 改动非常小，而且影响范围很局部
• 你还在决定产品 scope
• 你当前需要的是架构探索，而不是执行规划
• 这项工作本来就是实验性的，很可能马上又会改

这类场景下，轻量笔记往往比正式计划更合适。

它是否依赖特定技术栈或框架？

不依赖。这个 skill 偏流程方法，而不是框架绑定。它的建议之所以能跨技术栈复用，是因为重点放在任务拆解、文件职责、测试和可评审性上。

writing-plans 能处理大型 spec 吗？

可以，但前提是你认真执行 scope 检查。源码里明确提醒：如果一个需求跨多个彼此独立的子系统，通常应该拆成多份计划。你如果硬要塞成一个超大的总计划，任务质量通常会明显下降。

只靠 writing-plans 就足够做 Requirements Planning 吗？

如果你做的是以实现为中心的 Requirements Planning，很多时候是够用的。但如果你还处在需求探索阶段，就不够。因为它默认前提是：你已经知道要做什么，现在缺的是一条可靠的实现路径。

如何改进 writing-plans skill 的使用效果

提供更强的仓库上下文

想让 writing-plans 结果更好，最简单的方法就是明确指出可能涉及的目录、模块或文件。这个 skill 本来就要求尽早梳理文件职责；如果你提前给出可能的触点，输出就会更具体，也更不容易流于空泛。

先把彼此独立的子系统拆开

如果你的 spec 把几个不相干的问题揉在一起，先拆开，再去要最终计划。比如：

• auth 改动
• billing 改动
• admin UI 改动

它们在产品层面也许会一起发布，但只要实现和测试能独立进行，就通常值得拆成多份计划。

明确要求先做文件职责映射

如果第一版计划写得比较虚，可以直接补一句要求：

• “List each file to add or modify and state its responsibility before writing tasks.”

这和 skill 的结构高度一致，通常能明显改善“任务拆得不清楚”的问题。

强制更小的任务粒度

一个常见失败模式，是任务大到无法安全实现。你可以明确要求：

• 每个任务都能形成可测试的进展
• 每个任务边界清晰
• 每个主要改动后都写明验证方式

这也是 writing-plans usage 最容易被改善的地方：任务越小，越容易评审、分配和执行。

让测试要求更具体

不要只说“include tests”，而要进一步说明：

• 关注哪一层级的测试
• 需要更新哪些现有测试套件
• 是否必须包含 migration、integration 或 regression 检查

这个 skill 本来就重视测试，但如果约束给得更具体，整份计划会更有执行价值。

用 reviewer 驱动迭代，而不只是做最终把关

把 reviewer 模板当成修改工具，而不只是最后一道 gate。第一版计划出来后，可以继续追问：

• spec 里还缺哪些要求
• 哪些任务还不够可执行
• 哪些地方执行者可能会卡住
• 是否已经出现 scope creep

相比笼统地说“改进一下计划”，这种方式通常更能打磨出高质量的第二版。

留意这些常见失效模式

在下面这些情况下，writing-plans skill 的效果通常会变差：

• spec 本身不完整
• 文件边界是猜的，而不是基于仓库实际结构
• 任务只描述结果，不描述实现步骤
• 提到了测试，但没有和具体代码改动对应起来
• 一份过大的计划掩盖了多个本该独立交付的部分

如果你发现这些问题，先修输入，再去怀疑 skill 本身。

补充那些会改变实现方案的约束

比较有用的约束包括：

• 向后兼容要求
• 性能预期
• migration 安全性
• 部署顺序
• 文档更新义务
• 禁止新增依赖的规则

这些信息能帮助 writing-plans for Requirements Planning 生成更贴合你实际环境的计划，而不是停留在通用理想解。

用真实交接需求来检验计划

判断计划质量的方法其实很简单：如果让另一位对上下文不熟的工程师来接手，他能不能基本不反复追问、直接照着做？如果不能，就继续改，直到文件选择、任务边界和验证步骤都足够明确。

保持计划 DRY，并聚焦实现

源说明里强调了 DRY、YAGNI、TDD 和 frequent commits。落实到计划中，意思就是：去掉重复任务、避免过度预设未来工作、优先选择能快速编码并快速验证的小增量。相比一味增加文字量，这些原则对输出质量的影响更大。