| name | planning-mode |
| description | Planning Mode skill for guided execution of large tasks. Provides structured task decomposition, user confirmation, per-task verification, retry logic, and quality summary. |
| stage | planning |
| type | delivery-skill |
| version | 1.0 |
| tools | ["plan_create","plan_update_task","plan_ask_user","plan_complete","update_workspace_memory"] |
Planning Mode — 大任务引导执行 Skill
概述
Planning Mode 是 SuperAgent 处理大型、多步骤任务的结构化工作模式。它通过"先想后做"强制 AI 在执行前澄清意图、拆解任务、获得用户确认，执行过程中验证每步结果，失败时执行重试决策树，完成后提供质量总结。
需求澄清框架（5W1H）
在意图不明确时，使用 plan_ask_user 提问，覆盖以下维度：
| 维度 | 问题示例 | 类型 |
|---|
| What | 哪些文件/模块需要修改？整个模块还是特定功能？ | choice/text |
| Why | 这个改动的业务目标是什么？ | text |
| Who | 影响哪些角色/用户？ | choice |
| When | 是否有截止日期或优先级约束？ | choice |
| Where | 修改范围：前端/后端/全栈/基础设施？ | choice |
| How | 技术方案偏好（如有）：新建 vs 改造，框架选型等？ | choice/text |
澄清原则：
- 每次
plan_ask_user 最多提 3 个问题，避免信息过载
- 选择题（choice）提供 3-4 个选项，覆盖最常见场景
- 问答题（text）用于开放性背景信息收集
- 回答收到后，结合上下文推断其余细节，不再反复询问
任务分解原则（MECE）
MECE = Mutually Exclusive, Collectively Exhaustive（相互独立、完整覆盖）
分解规则
-
独立性：每个任务可以单独执行，不依赖其他任务的中间状态
- 好：
创建 UserService、创建 UserController
- 差：
创建 UserService 并修复它在 UserController 里的调用
-
显式依赖：若任务有先后关系，在任务描述中明确标注
-
完整覆盖：所有子任务的并集 = 完整需求，没有遗漏也没有重叠
-
粒度控制：单个任务预计耗时 1-4 小时（对应改动行数 50-200 行）
- 改动 >200 行的任务必须继续拆分
- 改动 <20 行的任务可以合并（避免过细）
-
文件绑定：每个任务必须列出主要涉及文件（≥1 个），让用户能评估影响范围
任务结构模板
{
"id": "task-001",
"title": "创建 UserService（≤20字）",
"files": ["src/service/UserService.kt", "src/model/User.kt"],
"successCriteria": "workspace_compile 返回零错误；UserServiceTest 所有用例通过",
"estimatedLines": 120,
"dependsOn": []
}
成功标准写法（可验证）
成功标准必须是可以通过工具调用客观验证的，而非主观描述。
| 类型 | 可验证写法 | 不可验证写法 |
|---|
| 编译 | workspace_compile 返回零错误 | "代码写正确" |
| 测试 | workspace_test 全部通过 | "功能正常" |
| API | GET /api/users 返回 200 + JSON 数组 | "接口可用" |
| 文件 | workspace_read_file 返回非空内容 | "文件已创建" |
| 构建 | npm run build 无 TypeScript 错误 | "前端完成" |
每个任务至少有 1 个编译/测试类的可验证标准，不能只依赖代码生成即视为完成。
失败决策树
任务执行后验证失败时，按以下决策树处理：
验证失败
│
├─ 第 1 次失败
│ ├─ 诊断根因（读错误信息、定位问题文件）
│ ├─ 制定修正方案（明确与第 1 次的区别）
│ └─ 自动重试 → plan_update_task(taskId, "in_progress", detail="重试1")
│
├─ 第 2 次失败
│ ├─ 换替代方案（不同实现路径）
│ └─ 自动重试 → plan_update_task(taskId, "in_progress", detail="重试2:替代方案")
│
└─ 第 3 次仍失败
├─ plan_update_task(taskId, "blocked")
├─ plan_ask_user 说明：
│ - 已尝试的 3 种方案
│ - 当前错误信息（关键部分）
│ - 可选方向（跳过/换方案/提供更多信息）
└─ 等待用户决策后继续
诊断原则：
- 每次重试前，先用
workspace_read_file 读取报错文件的相关代码
- 不要在同一错误上重复执行相同操作超过 2 次
- 编译错误优先看具体行号；测试错误优先看断言失败的值
总结质量标准（三段式）
plan_complete 的 summary 必须包含以下三段：
做了什么（What）
- 完成任务列表（打勾格式）
- 失败/跳过任务说明
- 关键技术决策：选择了什么方案，为什么
遇到什么（Issues）
- 遇到的技术障碍及解决方式
- 未解决的已知问题（标注影响范围）
- 与原计划的偏差（如有）
建议什么（Next Steps）
- 至少 2 条具体的后续工作建议
- 按优先级排序（P1/P2/P3）
- 每条建议有明确的行动描述
总结示例：
## 做了什么
- ✅ 创建 UserService（120行）- 选用 Spring Cache 而非手动 Redis 以减少依赖
- ✅ 创建 UserController（80行）
- ❌ 用户头像上传（已跳过）- S3 配置信息缺失，需运维提供
## 遇到什么
- Kotlin 枚举序列化问题：添加了 @JsonValue 注解，全局排查完毕
- 测试数据库连接超时：改用 @DataJpaTest 内存模式解决
## 建议什么
- P1: 补充 S3 配置后完成头像上传功能（约 2 小时）
- P2: 为 UserService 添加缓存单元测试（缓存击穿场景）
- P3: 考虑将 User 领域拆为独立模块（当前 UserService 已超 300 行）
Context 管理建议
当预计任务集总 context 超过 300k tokens 时：
- 分 Session 规划：在
plan_create 的任务列表中，将任务划分为 Session A / Session B
- 记忆持久化：完成 Session A 后，用
update_workspace_memory 记录：
- 已完成的任务和关键决策
- 未完成任务的当前状态
- 下一 Session 的起点
- Session B 启动：新 Session 开始时先读 workspace memory，从记录的起点继续
