writing-plans

writing-plans 快速入门

superpowers 套件里”写计划”的 Skill,把任何工作切成 2-5 分钟可执行的小任务,带代码与验证命令。

这是什么?解决什么问题?

writing-plans 是 obra/superpowers 仓库的核心子 Skill,与 planning-and-task-breakdown 同源(社区版常作为同一 Skill 的不同表述)。它的唯一目标:把”模糊的开发任务”转成”2-5 分钟粒度、可被 Junior 工程师 follow 的详细计划文档”。
计划文档包含每个任务的:文件路径、完整代码片段、验证命令、验收标准、依赖关系。AI 完成任何一个任务时,只要照着抄就行,不需要”再思考”。
对小白来说,这个 Skill 解决的是”AI 给我一段代码,但我不知道它在干什么、怎么验证、改了之后会不会影响其他地方”的问题。有了 writing-plans,每个任务都自带”怎么测、怎么验、怎么回滚”,AI 完成度与可验证性大幅提升。

准备工作

• 支持 Agent:Claude Code(主推)、支持 Skills 协议的 Agent。
  
• 运行环境:Claude Code 0.2+;Git(用于跟踪每个任务的 commit)。
  
• 目标项目:任意新功能或重构。
  
• 前置流程:建议先 brainstorming(需求对齐)→ writing-plans(出计划)→ executing-plans(执行)。
  

3 步快速上手

第 1 步:确认 Skill 已加载

ls ~/.claude/skills/superpowers/skills/writing-plans/<br>
```<br>
### 第 2 步:在 Claude Code 中提供需求<br>
```bash<br>
claude<br>
```<br>
发起任务:<br>
```<br>
我要做用户认证功能,支持邮箱密码登录、JWT 颁发、刷新令牌、登出。请用 writing-plans Skill 生成详细的开发计划,每个任务 2-5 分钟粒度,带文件路径、代码、验证命令。<br>
```<br>
### 第 3 步:review 与执行<br>
AI 输出 `docs/plans/YYYY-MM-DD-user-auth.md`,人工 review 后:<br>
- 用 executing-plans Skill 批量执行<br>
- 每个任务独立 commit<br>
- 每个任务独立 verify<br>
## 常见踩坑<br>
1. **任务粒度太大**:"实现 JWT 中间件" 这种 30 分钟的大任务,Skill 强制要求拆成 2-5 分钟。<br>
2. **验证命令缺失**:每条任务必须带 `pytest tests/test_jwt.py` 这种具体命令。<br>
3. **代码片段不完整**:不能写"添加一个函数叫 verify_token",必须给完整代码。<br>
4. **依赖关系漏标**:任务 3 用了任务 2 的导出函数,必须显式标 "depends on: 2.1"。<br>
5. **跳过 writing-plans**:很多人嫌麻烦直接让 AI 写代码,Skill 反复要求"先有计划再写代码"。<br>
6. **计划文档没存档**:写完的计划要 commit 到 git,后续 code-review 有据可查。<br>
## 初级用法<br>
- **新功能必走 writing-plans**:在 CLAUDE.md 写明,所有超过 30 分钟的工作必须先出计划。<br>
- **PR 描述自动生成**:把计划文档作为 PR 描述,reviewer 看得明白。<br>
- **学习用模板**:Skill 文档里有大量真实案例,适合学习如何拆任务。<br>
## 高级玩法<br>
- **团队统一模板**:Skill 输出格式做成团队模板,所有项目复用。<br>
- **CI 集成**:每个任务一个 commit,CI 自动跑全量测试,卡粒度更细。<br>
- **进度跟踪**:把任务列表当 Kanban 用,完成一个勾一个。<br>
## 小技巧<br>
- 任务标题用动词("实现 login 接口"),不用名词("login 接口")。<br>
- 验证命令尽量是单行命令,CI 友好。<br>
- 验收标准用 Given-When-Then 格式写,无歧义。<br>
- 复杂任务先拆"调研任务"和"实现任务",不要混在一起。<br>
- 关注作者 blog.obra.dev 分享的真实计划案例。<br>
## 常见问题 FAQ<br>
**Q1: 这个 Skill 跟 writing-plans 有什么关系?必须装吗?**<br>
A: Skill 是给 AI Agent 用的"技能包",能告诉 Agent 怎么按特定规范工作。**不是必须装**——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。<br>

**Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?**<br>
A: writing-plans 来自 Obra,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。<br>

**Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?**<br>
A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。<br>

**Q4: 怎么验证 Skill 装对了?**<br>
A: 在 Agent 中输入"列出已加载的 Skill"或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。<br>

**Q5: 这个 Skill 有许可证吗?能商用吗?**<br>
A: 取决于 writing-plans 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。<br>

## 参考链接<br>
- [superpowers 仓库](https://github.com/obra/superpowers)<br>
- [该 Skill 目录](https://github.com/obra/superpowers/tree/main/skills/writing-plans)<br>
- [配套 brainstorming](https://github.com/obra/superpowers/tree/main/skills/brainstorming)<br>
- [配套 executing-plans](https://github.com/obra/superpowers/tree/main/skills/executing-plans)<br>
- [配套 planning-and-task-breakdown](https://github.com/addyosmani/agent-skills)<br>
- [作者博客](https://blog.obra.dev/)<br>
- [示例计划](https://github.com/obra/superpowers/tree/main/docs/plans)<br>