plan-writing

计划编写

来源：obra/superpowers

概述

此技能提供一个框架，用于将工作拆分为清晰、可执行且带有验证标准的任务。

任务拆分原则

1. 任务小而专注

• 每项任务应耗时 2-5 分钟
• 每项任务只有一个明确结果
• 可独立验证

2. 验证标准明确

• 如何判断任务已完成？
• 可以检查或测试什么？
• 预期输出是什么？

3. 顺序合理

• 明确依赖关系
• 尽可能并行开展工作
• 突出关键路径
• 阶段 X：验证始终放在最后

4. 在项目根目录动态命名

• 计划文件以 {task-slug}.md 的形式保存在 PROJECT ROOT
• 根据任务命名（例如，“add auth” → auth-feature.md）
• 绝不放在 .agents/、docs/ 或临时文件夹中

计划原则（不是模板！）

🔴 不要使用固定模板。每份计划都应根据任务量身定制。

原则 1：保持简短

❌ 错误	✅ 正确
50 项任务，还包含多层子任务	最多 5-10 项清晰的任务
列出每个微小步骤	只列出可执行事项
冗长的描述	每项任务一句话

规则： 如果计划超过 1 页，就太长了。请精简。

---

原则 2：具体，不要泛泛而谈

❌ 错误	✅ 正确
“搭建项目”	“运行 npx create-next-app”
“添加身份验证”	“安装 next-auth，并创建 /api/auth/[...nextauth].ts”
“设置 UI 样式”	“为 Header.tsx 添加 Tailwind 类”

规则： 每项任务都应有明确且可验证的结果。

---

原则 3：根据项目类型调整内容

对于新项目：

• 使用什么技术栈？（先决定）
• MVP 是什么？（最少功能）
• 文件结构是什么？

对于功能添加：

• 哪些文件会受影响？
• 需要哪些依赖项？
• 如何验证其是否有效？

对于 Bug 修复：

• 根本原因是什么？
• 要修改哪个文件或哪一行？
• 如何测试修复结果？

---

原则 4：脚本因项目而异

🔴 不要复制粘贴脚本命令。应根据项目类型选择。

项目类型	相关脚本
前端/React	ux_audit.py、accessibility_checker.py
后端/API	api_validator.py、security_scan.py
移动端	mobile_audit.py
数据库	schema_validator.py
全栈	根据所涉及的内容，混合使用上述脚本

错误： 在每份计划中都添加所有脚本 正确： 只添加与当前任务相关的脚本

---

原则 5：验证应简单明了

❌ 错误	✅ 正确
“验证组件是否正常工作”	“运行 npm run dev，点击按钮，确认出现提示消息”
“测试 API”	“运行 curl localhost:3000/api/users，确认返回 200”
“检查样式”	“打开浏览器，确认深色模式切换正常”

---

计划结构（灵活，而非固定！）

# [Task Name]

## Goal
One sentence: What are we building/fixing?

## Tasks
- [ ] Task 1: [Specific action] → Verify: [How to check]
- [ ] Task 2: [Specific action] → Verify: [How to check]
- [ ] Task 3: [Specific action] → Verify: [How to check]

## Done When
- [ ] [Main success criteria]

## Notes
[Any important considerations]

就是这样。 除非确有必要，否则不需要阶段或子章节。 保持精简。仅在需要时增加复杂度。

---

最佳实践（速查）

1. 从目标开始 - 我们要构建或修复什么？
2. 最多 10 项任务 - 如果更多，就拆分成多份计划
3. 每项任务均可验证 - 明确的“完成”标准
4. 针对具体项目 - 不使用复制粘贴的模板
5. 随做随更新 - 完成后标记 [x]

---

适用场景

• 从零开始创建新项目
• 添加功能
• 修复 Bug（如果较复杂）
• 重构多个文件