使用 Claude Code 创建实现计划的 writing-plans 技能
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
原文链接：使用 Claude Code 创建实现计划的 writing-plans 技能（cccskills）
技能页面：writing-plans
本文结论
安装 writing-plans 后，只需提供规格或需求即可生成实现计划。
该机制会在编写代码之前，先生成一份记录了变更文件、函数类型、测试和验证命令的计划。
本文将介绍计划书的内容与自检项目，以及如何在 Claude Code 或 Codex 中安装该技能。
后半部分还会介绍如何将计划交给其他智能体进行实现。
提供规格书后，在动任何代码之前，系统会先生成一份完整的计划书，其中包含每个任务的变更文件和测试步骤。
例如可以这样请求：
请根据附件中的规格书制定实现计划。
暂时不要编写代码。
智能体首先声明将使用 writing-plans，然后将计划保存至 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md。
计划开头列出目的、结构方针、所用技术以及原始规格书的位置。
其下方紧接着是涉及整个规格的约束条件，以及"Review Focus"栏目。
Review Focus 中列出的是所有任务的测试均未覆盖的输入项或失败条件。
每个任务由以下三个要素构成：
| 要素 | 内容说明 |
|---|---|
| Files | 需创建、变更或测试的文件路径。变更文件精确到行号 |
| Interfaces | 从前置任务接收的内容，以及传递给后续任务的函数名、参数和返回值类型 |
| 步骤 | 带复选框的步骤：编写失败测试、确认失败、编写最小实现、确认通过、提交 |
计划完成后，智能体会要求用户阅读计划，询问实现方式后停止等待。
在未经确认的情况下，实现过程不会自动启动。
writing-plans 是一项将规格书转化为"实现者无法自行决定的事项"清单的技能。
通过以下四项功能，在实现前消除导致返工的歧义。
计划的预设读者是一位既不了解该代码库也未读过规格书的实现者。
因此，计划中会列出涉及的文件、函数名称与类型、规格中的具体数值，以及支撑每个任务的测试。
计划不包含函数的具体实现。
但若某算法仅凭类型和测试无法确定，则作为例外予以记录。
每个任务都是一个拥有独立测试周期、可在评审中单独被退回的最小单位。
配置、准备工作和文档工作，须包含在需要这些工作的任务中。
若规格涉及多个独立的子系统，智能体会建议按子系统分别制定计划。
计划完成后，智能体会与规格书对照，逐一核查以下五项内容：
发现问题时当场修正，并为缺少对应任务的需求补充任务。
此阶段还会发现命名不一致的问题，例如 Task 3 中写的是 clearLayers()，Task 7 中却写成了 clearFullLayers()。
每个任务的 Interfaces 栏记录接收和传递内容的精确类型。
实现者只需阅读自己负责的任务，即可与相邻任务保持名称和类型的一致性。
计划开头还记录了原始规格书的位置，接收方可以对照计划与规格书一同阅读。
writing-plans 是 obra/superpowers 中的一项技能，附带文件仅为 SKILL.md。
若通过命令安装，请执行以下命令。
可选择安装到 Claude Code 或 Codex 等智能体中。
npx skills add https://github.com/obra/superpowers --skill writing-plans
若希望由智能体代为安装，请直接发送以下文本。
该内容要求智能体在确认内容后再进行部署。
请安装以下 Agent Skill：
https://github.com/obra/superpowers/tree/main/skills/writing-plans
请先确认 SKILL.md 及附带文件的内容，确认没有可疑操作（如向外部发送数据、读取认证信息等），然后将其部署至：Claude Code 请放至 ~/.claude/skills/writing-plans/，Codex 请放至 ~/.agents/skills/writing-plans/。
安装位置可根据是在所有项目中使用还是仅在特定项目中使用来选择。
| 智能体 | 所有项目中使用 | 仅特定项目中使用 |
|---|---|---|
| Claude Code | ~/.claude/skills/ | 项目的 .claude/skills/ |
| Codex | ~/.agents/skills/ | 项目的 .agents/skills/ |
在请求中附上规格书的位置以及计划保存路径或执行方式的偏好，可以让对话更高效。
以下是三种典型的请求方式：
根据这项功能新增的需求，制定一份包含变更文件和测试步骤的实现计划。
请保存至 docs/plans/。
计划将保存至指定的 docs/plans/，因为用户指定的保存路径优先于默认路径。
每个任务都附有文件列表以及从编写测试开始的带复选框步骤。
请告诉我计划中 Task 2 需要执行哪些测试、用什么命令执行，以及什么输出代表成功。
计划的确认步骤中记录了执行命令和成功时的输出。
因此返回的内容是：在确认失败阶段和确认成功阶段，分别按计划中记录的命令和预期结果作答。
计划完成后，我想按任务将实现工作分配给不同的智能体。
若提前告知执行方式，智能体不会再次询问，仅要求确认计划。
若未告知，智能体会询问选择以下两种方式中的哪一种，并附上各自的推荐理由。
| 方式 | 进行方式 | 特点 |
|---|---|---|
| Subagent-driven | 每个任务由新的子智能体实现，由新的审查者确认后再进入下一步。最后对整个分支进行审查 | 最为严谨。每个任务和审查均使用新的上下文 |
| Native | 在同一会话中依次实现所有任务，最后由能力最强的模型审查者对整个分支进行确认 | 最省成本且速度最快。中途没有独立审查 |
writing-plans 是一项需要在手头已有规格或需求的情况下使用的技能。
前提规格由人工准备并确认内容。
若规格仍有歧义就直接提交，计划也会继承这些歧义。
在实现阶段，该技能会调用其他技能。
Subagent-driven 方式需要 subagent-driven-development，Native 方式需要 executing-plans。
两者均包含在 obra/superpowers 中，请一并安装。
请勿直接接受计划，务必自行阅读并判断。
尤其要关注 Review Focus 栏，其中列出了测试未覆盖的输入项和失败条件。
建议按照对实际用户影响程度的高低依次审阅。
许可证为 MIT。
安装前请阅读 SKILL.md 的内容，确认指令内容。
以下介绍同属 obra/superpowers 的三项技能，用于连接计划的前后环节。
brainstorming 在制定计划的前期阶段，通过对话梳理目的和约束条件，整理出与工作规模相匹配的设计方案。
当规格尚未确定时，可以从这里出发。
subagent-driven-development 将计划按任务交给不同的智能体处理，在确认规格符合性和代码质量的同时推进工作。
executing-plans 在同一会话中按顺序执行各任务，最后对整个分支进行审查。
使用前提是手头有规格或需求。
若尚未确定，请先通过 brainstorming 梳理目的和约束条件，再从中制定计划。
默认保存路径为 docs/superpowers/plans/ 目录下，以带有日期和功能名称的 Markdown 文件格式保存。
请求时若指定了保存路径，则以指定路径为准。
不能。
计划保存并完成自检后，智能体会停下来等待用户审阅。
负责实现的是 subagent-driven-development 或 executing-plans。
计划书的格式示例基于 Python 和 pytest，但前提是实现者会使用项目所用的语言进行编写。
计划中记录的是文件、类型、测试和验证命令，因此内容会根据语言进行相应调整。
writing-plans 是一项适合那些让 AI 智能体直接写代码却频繁返工的开发者使用的技能。
它会在编写代码之前，先根据规格书生成一份包含变更文件、函数类型、测试和验证命令的计划。
在此基础上，还会对命名不一致和规格遗漏进行自检。
生成的计划可以按任务单位交给其他智能体或负责人处理。
不妨先从一个小型功能新增的规格书开始尝试。
cccskills 页面
本文转载自 cccskills 的文章「使用 Claude Code 创建实现计划的 writing-plans 技能」。
技能详情和安装方法请参阅 cccskills 的 writing-plans 页面。