概览
writing-plans 技能的作用
writing-plans 技能可以帮助你把产品规格（spec）或技术需求文档，在正式开始写代码前转化为完整、可实施的工程计划。它专为这种场景设计：你有一个需要多步交付的特性或变更，希望得到一个清晰拆解的计划，让另外一位工程师在对代码库和业务毫无背景的情况下也能照着执行。
使用 writing-plans，你生成的计划会：
- 假设执行者是有能力的开发者，但对你的代码库和领域完全陌生。
- 明确写出每一部分工作需要创建或修改哪些文件。
- 指出需要补充的测试、文档更新以及人工检查。
- 把整体工作拆解成小而可交付的任务，边界清晰。
这让工作交接、计划评审更容易，也有助于避免 scope creep（需求膨胀）或隐藏的边界情况。它体现了 DRY、YAGNI、TDD 和频繁提交等实践，但重点是项目规划和任务拆解，而不是代码生成。
谁适合使用 writing-plans？
在以下情况下，你可以使用 writing-plans 技能：
- 技术负责人和工程经理：需要为特性开发或重构制定可重复的方法化规划。
- 个人开发者：在实施有风险或跨多个模块的改动前，希望先把自己的思路理清并固化成计划。
- 使用 subagents 或分布式协作的团队：需要依赖清晰的书面计划来协调多个贡献者。
它尤其适用于：
- 你已经有某个特性、迁移或集成的spec 或需求文档。
- 这项工作会涉及多个文件、组件或服务。
- 你希望其他人可以在不需要一直来问你问题的情况下完成这项工作。
以下场景则不太适合：
- 你还在头脑风暴问题或方案阶段（应先使用专门的 ideation/brainstorming 技能）。
- 任务非常小（例如单行修复），不需要正式计划。
- 你主要是在寻求代码评审或代码生成，而不是规划。
它如何融入你的工作流
推荐的使用方式是：在头脑风暴阶段之后，在该项目的一个专用 worktree 中使用 writing-plans。典型流程是：
- 在本技能之外，先完成 spec 的头脑风暴和澄清。
- 为该特性创建或打开一个专用 worktree。
- 运行 writing-plans 技能生成实施计划。
- 将计划（默认）保存到：
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md- 或你自定义的计划存放路径。
- 可选：使用提供的模板调度一个 plan document reviewer subagent，在实施前对计划进行校验。
使用方法
安装与配置
1. 安装 writing-plans 技能
你可以直接从 obra/superpowers 仓库安装该技能：
npx skills add https://github.com/obra/superpowers --skill writing-plans
这会拉取 writing-plans 的技能定义及其配套提示词（prompts），供你在自己的项目中使用。
2. 查看核心文件
安装完成后，建议先查看以下关键文件，以便理解并调整工作流：
skills/writing-plans/SKILL.md– 主要说明技能的行为方式，包括 scope、计划结构以及对工程师的前置假设。skills/writing-plans/plan-document-reviewer-prompt.md– 可复用的 subagent 提示模板，用于审查你已经写好的计划。
本地路径可能会因你 vendor 或 mirror 仓库的方式而不同，但文件名保持一致。
准备运行 writing-plans
3. 确认规格说明和范围
在使用 writing-plans 之前，请确保你已有：
- 针对该特性或变更的清晰 spec 或需求文档。
- 足够的细节来识别主要组件、集成点和约束条件。
该技能包含一个 Scope Check（范围检查） 步骤：如果你的 spec 涉及多个相互独立的子系统，它会假定你已经在头脑风暴阶段把这些工作拆分为多个独立的子项目 spec。如果还没有拆分，建议你：
- 将工作拆解为多个独立计划，每个子系统一个计划。
- 确保每个计划都可以单独产出可运行、可测试的软件。
这样可以避免单个计划过于庞大难以管理，也有助于让工作与可部署单元保持对齐。
4. 准备 worktree 和计划文件
上游指南假定你会：
-
在为该特性准备的专用 worktree 中工作（在头脑风暴阶段已设置）。
-
将生成的实施计划保存为：
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
如果你的团队偏好不同的目录结构，例如 docs/plans/ 或 planning/，可以覆盖这个默认路径。关键是计划需要纳入版本控制，和代码一起演进，并且以后容易找到。
运行技能并撰写计划
5. 明确开启计划会话
在调用技能或开始规划对话时，建议你明确说明：
"I'm using the writing-plans skill to create the implementation plan."
这样可以清楚地设定预期：当前目标是生成一个结构化的实施计划，而不是设计探索或代码输出。
6. 先梳理文件结构
在列出任务之前，writing-plans 强调先做文件层面的拆解：
- 确定将要创建或修改哪些文件。
- 为每个文件分配一个单一且清晰的职责。
- 以边界清晰、接口明确的方式设计各个单元。
在这个阶段，计划应回答：
- 新的逻辑应该放在哪里？
- 会修改哪些现有文件？原因是什么？
- 这些文件在高层次上如何协作？
尽早确定合理的文件结构，有助于后续的任务拆解、代码评审以及未来的重构。
7. 把工作拆成小块任务
在文件映射（file map）确定后，使用 writing-plans 把 spec 转化为一系列小而易懂的任务。上游指南强调：
- 每个任务都应有清晰的目标，且可直接执行。
- 任务要足够小，以便频繁提交。
- 计划要遵循 DRY（不重复）、避免 YAGNI（不做猜测性的工作）。
对于每个任务，计划应包含：
- 它会涉及哪些文件。
- 需要做哪些代码或配置变更（高层级描述）。
- 需要添加或更新哪些测试。
- 需要更新哪些文档。
目标是：一个几乎没有背景的工程师也能拿起任意单个任务，并有信心完成它。
8. 将测试和文档纳入计划
writing-plans 期望你在计划中直接嵌入测试和文档工作：
- 明确需要新增或更新哪些 unit tests、集成测试或端到端测试。
- 在合适的位置注明如何运行测试（例如命令、测试入口）。
- 指出所需的文档更新，如 README 章节、用户指南或 API 文档。
这能确保质量和可维护性从一开始就是计划的核心部分，而不是事后补救。
审查与迭代计划
9. 使用计划审查模板（可选但推荐）
plan-document-reviewer-prompt.md 文件提供了一个结构化的提示模板，用于 plan document reviewer subagent。其主要目的是：
- 检查计划是否完整，并与 spec 匹配。
- 验证任务拆解是否现实、可执行。
- 确认工程师按照计划实施时是否能顺利完成而不被卡住。
该模板列出了审查时需要关注的类别，包括：
- Completeness（完整性） – 对重要需求没有 TODO、占位符或缺失步骤。
- Spec Alignment（规格对齐） – 计划覆盖了 spec，而没有明显的 scope creep。
- Task Decomposition（任务拆解） – 任务边界清晰、可实现。
- Buildability（可实现性） – 有经验的工程师能顺着计划从头走到尾。
审查者被要求重点关注那些会导致实际实施问题的事项，而不是措辞或风格的小修小改。
你可以把这一审查步骤集成到 CI、评审流程或人工审查过程中。
10. 根据反馈迭代
如果审查者（人或 subagent）发现缺失需求、自相矛盾的步骤或描述过于模糊的任务：
- 在计划文件中进行修正。
- 如有必要重新运行或重新调度审查。
- 一旦计划通过审查，就把它视为实施的单一可信来源（source of truth）。
将 writing-plans 适配到你的团队
11. 自定义结构与规范
尽管上游技能定义了明确的默认行为，你仍然可以按需调整：
- 修改计划文件存放位置，以符合你的仓库结构。
- 添加团队自有的检查清单（比如安全审查、性能测试）作为反复出现的任务。
- 将计划与issue tracker 集成，把计划中的任务映射为工单。
由于 writing-plans 主要关注的是结构化工作流和项目管理，它可以很好地跨语言、框架和业务领域迁移使用。
常见问题（FAQ）
我什么时候应该使用 writing-plans 技能？
当你有一个多步骤的特性开发、重构或集成，并已经有相对清晰的 spec，希望写出一份可以由其他工程师在没有背景的情况下执行的实施计划时，就应使用 writing-plans。它在处理涉及多个文件或子系统的复杂变更之前尤其有用。
在哪些情况下 writing-plans 不适合？
以下情况并不适合使用 writing-plans：
- 你还在探索解决方案，spec 尚未稳定。
- 工作体量很小，正式计划反而会造成额外负担。
- 你只是想要代码生成或代码评审，而不是任务拆解和项目规划。
这种情况下，更适合使用以头脑风暴、设计或编码为主的技能。
我必须使用默认的 docs/superpowers/plans/ 路径吗？
不需要。上游指南建议将计划保存到：
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
但同时明确说明：用户对计划存放位置的偏好可以覆盖这个默认值。你可以根据自己的仓库和文档规范，将计划保存在任意目录或使用任意命名规则。
我可以把 writing-plans 用于非代码类项目吗？
该技能是以软件项目和代码库为前提设计的，包括文件映射和测试等概念。不过，它的核心思想——将工作拆分为小任务、明确职责、检查完整性——也可以适配到其他技术类工作流。在存在文件、测试或文档更新等概念的场景中，它的效果会尤其明显。
writing-plans 如何帮助新人上手和工作交接？
因为 writing-plans 假定执行者对你的代码库完全没有背景、品味也可能不可靠（questionable taste），因此它会促使你：
- 解释代码应该放在哪里，以及原因。
- 明确写出测试和文档工作。
- 去除任务描述中的歧义。
这大大简化了把工作交给新成员、外包伙伴或 subagents 的过程。他们可以直接按照计划执行，而不需要从 spec 中反向推断你的意图。
writing-plans 和项目管理工具之间是什么关系？
writing-plans 是对项目管理工具的补充，而不是替代：
- 它提供一份结构化的书面计划，在代码和文件层面说明如何实现一个 spec。
- 之后，你可以将计划中的任务映射到 Jira、GitHub Issues 或 Linear 等工具中。
该技能处在项目管理、工作流模板和技术型报告写作的交汇点，为你提供一套可复用的模式，用来持续产出一致的实施计划。
我能只使用 reviewer prompt，而不使用完整技能吗？
可以。plan-document-reviewer-prompt.md 文件本身就可以作为任何“计划类文档”的审查模板独立使用。你可以将其作为 subagent 的提示词，用于：
- 审查使用 writing-plans 写出的计划。
- 检查由其他流程或工具生成的计划。
不过，当计划本身和审查都遵循 writing-plans 的工作流时，整体效果和一致性通常会更好。