planning

name	planning
description	任务规划与进度追踪。当任务有 5+ 步骤、多文件改动、或长执行链时使用。 核心机制：用 checkbox 列表追踪进度，每完成一步立即更新，利用"重写列表"将完整任务清单重新注入 context。

Planning — 进度追踪即 Context Recall

为什么需要

长任务中，agent 的注意力会被最近的 debug 循环吸引，早期的任务目标和进度逐渐被推到 context window 远处。

每次更新 checkbox 列表时，你都会重写整个清单 — 这不是格式偏好，而是一个主动召回机制：把完整的任务上下文重新拉回注意力中心。

When to Use

• 任务有 5+ 个步骤（写文件、改代码、跑测试算独立步骤）
• 多文件改动
• 需要跨多轮 tool 调用的长执行链

不需要用于： 单步任务、快速回答、读一个文件。

How — 三条规则

规则 1：开始前列出完整清单

收到任务后，第一件事就是拆解为 checkbox 列表。不是思考中的简短列举，而是正式的 markdown 输出：

## 任务计划
- [ ] 1. 创建项目结构和 __init__.py
- [ ] 2. 实现 models.py（Task 数据模型）
- [ ] 3. 实现 storage.py（持久化和 CRUD）
- [ ] 4. 实现 cli.py（命令行接口）
- [ ] 5. 编写测试（models / storage / cli）
- [ ] 6. 运行 pytest 验证全部通过
- [ ] 7. 编写 README.md

规则 2：每完成一步，立即更新

完成一个步骤后，重写整个列表，将已完成项标记为 - [x]。不要只写"第 3 步完成了"，而是输出完整的更新后的列表：

## 任务进度
- [x] 1. 创建项目结构和 __init__.py
- [x] 2. 实现 models.py（Task 数据模型）
- [x] 3. 实现 storage.py（持久化和 CRUD）
- [ ] 4. 实现 cli.py（命令行接口）  ← 当前
- [ ] 5. 编写测试（models / storage / cli）
- [ ] 6. 运行 pytest 验证全部通过
- [ ] 7. 编写 README.md

关键： 每次更新都重写全部列表，包括未完成的项。目的不是记录历史，而是让完整的任务上下文重新出现在最新的 context 位置。

规则 3：用验证驱动状态变更

只有当你实际验证了某一步的产出（测试通过、编译成功、功能确认）后，才标记为 [x]。不要在"写完了但还没测"时就标记完成。

粒度建议

任务类型	checkbox 粒度
功能开发	每个功能模块 = 1 项
Bug 修复	诊断 → 修复 → 测试 = 3 项
重构	每个目标文件 = 1 项
测试编写	每个测试文件 = 1 项

粒度过细（如每个函数一行）会产生过多噪音，削弱召回效果。 粒度过粗（如"实现后端"一项）则失去了追踪意义。

反模式

❌	问题
只在 thinking 中列出步骤	不算正式输出，下一轮对话中不可见
创建列表后再也不更新	等于没有列表，还浪费了创建时的 context
标记 [x] 但没实际验证	虚假进度，掩盖问题
粒度过细（每行代码一项）	噪音 > 信号