| name | plan |
| description | 当用户要为多步骤开发任务写计划、制定实现计划、规划或拆解任务，要求先规划再动手，或询问
“怎么实现这个功能”“给我个方案”且任务不止一步时使用。
|
| metadata | {"openclaw":{"emoji":"📋"}} |
plan — 实现计划编写技能
执行前置
遵循当前目录 AGENTS.md「技能执行公共契约」；仅按需读取技能正文与 reference。
为多步骤任务编写可执行、无占位符、可独立验证的实现计划。
假设执行者对代码库零上下文：计划中写清每个任务的文件、接口、代码与测试步骤。
核心原则
- 先有规格，再写计划：从需求/规格/设计文档出发，规格缺席时先澄清需求
（参考 brainstorming/make Step 1），不凭空规划。
- 假设执行者零上下文：计划自包含——文件路径、接口签名、代码示例、验证命令
全部给出；读者可能跳序阅读，任务间依赖通过"Consumes/Produces"显式声明。
- 任务粒度 = 最小的独立测试单元：每个任务自带测试周期（写失败测试 → 运行确认失败
→ 最小实现 → 运行确认通过 → 交付检查），一步一动作（2-5 分钟粒度）；
配置/脚手架/文档步骤并入其交付物所属任务，不单列空任务。
- 无占位符：禁止 TBD/TODO/"实现细节后补"/"类似任务 N"/"写测试"（无测试代码）/
"添加适当错误处理"（无具体内容）；每步必须给出执行者实际需要的内容。
- DRY / YAGNI / TDD：不重复造轮子、不做超前设计、测试先行。
- 文件结构先于任务分解：先锁定文件清单与职责边界（每个文件一个清晰职责，
一起变化的放一起），再据此分解任务。
- 自审：计划完成后对照规格做覆盖检查、占位符扫描、类型/命名一致性检查。
- 诚实边界：计划与规格矛盾、或有需求无法落实时如实说明，不硬编。
触发时机
- 用户要求计划："写计划"、"制定计划"、"实现计划"、"规划"、"拆解任务"、"任务分解"
- 用户要求先规划："先规划再动手"、"怎么实现这个功能"、"给个方案"、"做个计划"
- 规格已存在：用户给出 spec/设计文档要求转化为实现计划
- 与其他技能配合：计划执行（按计划实现）用 make 技能；计划实现报错用 debug；
性能不足用 optim；计划涉及的需求澄清可用 make Step 1 方法论
工作流程
Step 1. 明确规格与范围
- 确认规格来源：需求文档/设计文档/用户描述；无规格时先澄清
（做什么、不做什么、验收标准——所有问题一次性全部提出，用户一次回答），输出一句任务定义；
- 范围检查：规格覆盖多个独立子系统时，建议按子系统拆分计划，
每个计划独立可交付、可测试；拆分方式与用户一次确认。
Step 2. 设计文件结构（分解决策锁定点）
- 先确定将新建/修改哪些文件、各自职责（一个文件一个清晰职责；
一起变化的文件放一起；按职责而非技术层拆分）；
- 既有代码库遵循既有模式；不擅自重构大文件，但计划中可合理包含拆分；
- 文件结构在终端摘要中说明，它是任务分解的依据。
Step 3. 任务分解与编写
按依赖顺序分解任务，每个任务：
### Task N: <组件名>
**文件:**
- 新建: `exact/path/to/file.py`
- 修改: `exact/path/to/existing.py:123-145`
- 测试: `tests/exact/path/to/test.py`
**接口:**
- 消费: <来自前面任务的内容——确切签名>
- 产出: <后续任务依赖的内容——确切函数名、参数与返回类型>
- [ ] **Step 1: 写失败测试**
<测试代码>
- [ ] **Step 2: 运行确认失败**
运行: `pytest tests/path/test.py::test_name -v` 预期: FAIL
- [ ] **Step 3: 最小实现**
<实现代码>
- [ ] **Step 4: 运行确认通过**
运行: `pytest ...` 预期: PASS
- [ ] **Step 5: 交付检查**
`git diff --check`；有 Git 且有本次改动时不自动暂存、提交或推送；用户明确要求时按指定范围执行。
计划文档头部：
# <功能名> 实现计划
**目标:** <一句话描述构建什么>
**架构:** <2-3 句方案>
**技术栈:** <关键技术/库>
**规格:** <规格/设计文档路径>
**全局约束:** <版本下限、依赖限制、命名与平台要求——逐行精确复制自规格>
Step 4. 自审（覆盖/占位符/一致性）
写完计划后以全新视角对照规格检查：
- 规格覆盖：逐条核对规格要求 → 每个都能指向一个任务；缺口补任务；
- 占位符扫描：全文搜索 TBD/TODO/“实现细节后补”/"类似任务 N"/
"添加适当错误处理"等模式并补全；
- 类型与命名一致性：后置任务中的函数名/签名/属性名与前置任务定义一致
（Task 3 用
clearLayers()、Task 7 用 clearFullLayers() 即计划 bug）；
- 发现的问题就地修复，不另开评审。
Step 5. 保存与交接
- 保存计划到
docs/plans/YYYY-MM-DD-<feature-name>.md，同时在终端摘要中说明；
- 向用户提供执行方式选择：
- 本会话内联执行：按计划逐步执行（建议转 make 技能编排）；
- 子任务代理执行：每任务派发独立子代理执行+审查；
- 用户手动执行：计划交付给用户自行实施。
Step 6. 总结（结构化输出）
✓ 计划完成
对象: <任务定义>
任务: <N 个任务，每个独立可验证>
规格: <规格来源路径>
计划: docs/plans/YYYY-MM-DD-<feature>.md
自审: <覆盖检查 N 条需求全覆盖; 占位符扫描 0; 一致性检查通过>
遗留: <未覆盖项/待用户确认项，无则省略>
错误处理
| 场景 | 处理 |
|---|
| 无规格/需求含糊 | 先澄清需求（做什么/验收标准），不凭空规划 |
| 规格覆盖多个子系统 | 建议拆分为多个独立计划，与用户确认 |
| 计划过长 | 拆 references/ 或按子系统拆分计划，保持可读 |
| 任务依赖不明 | 通过 Consumes/Produces 显式声明接口，缺则补写 |
| 发现占位符 | 补全具体内容（路径/签名/代码/验证命令）后重审 |
| 命名/签名不一致 | 修正为一致后重审 |
| 需求无法落实 | 如实说明并建议修改需求或方案，不硬编 |
注意事项
- 计划必须自包含、可执行：执行者不应需要猜测或跳转查证；
- 计划文档属于本次交付物；交付前执行
git diff --check，不自动暂存、提交或推送。
