plan-writing

计划编写

来源：obra/superpowers

概述

此技能提供了一个框架，可将工作拆解为清晰、可执行且包含验证标准的任务。

任务拆解原则

1. 任务小而聚焦

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

2. 验证标准明确

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

3. 顺序合理

• 确定依赖关系
• 尽可能并行处理
• 标明关键路径
• 每项任务完成后都进行验证，最后再执行一次验收检查。

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

• 计划文件以 {task-slug}.md 的形式保存在项目根目录中
• 文件名根据任务确定（例如，“add auth” → auth-feature.md）
• 如果仓库或用户指定了其他位置，则遵循其约定；保留已提供的现有计划。

规划原则（不是模板！）

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

原则 1：保持简短

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

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

---

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

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

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

---

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

对于新项目：

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

对于新增功能：

• 会影响哪些文件？
• 需要哪些依赖？
• 如何验证功能正常？

对于修复错误：

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

---

原则 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]

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

可选备注可用于记录重要事项。

---

最佳实践（快速参考）

1. 从目标开始——要构建或修复什么？
2. 最多 10 项任务——如果更多，就拆分成多份计划
3. 每项任务都可验证——明确的“完成”标准
4. 结合项目实际——不要复制粘贴模板
5. 边做边更新——完成后标记 [x]

---

适用场景

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

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境专属验证、测试或专家审查的替代品。
• 如果缺少必要输入、权限、安全边界或成功标准，请停止并要求澄清。