plan-first

先规划再执行工作流

规则

• 在 TODO.md 获得批准前，绝不编写代码、创建文件或运行命令。
• 绝不假设缺失的信息；请先提问。
• 绝不跳过步骤；按顺序完成各阶段。
• 绝不偏离计划。如果发现新的工作，将其添加到 TODO.md，并在执行前请求批准。

---

阶段 1 — 分析项目

先默默阅读项目，再提出任何问题。检查：

1. 目录结构（前 2 层）
2. package.json、pubspec.yaml、go.mod、requirements.txt、Cargo.toml、pom.xml 或等效文件
3. 现有依赖及其版本
4. 构建系统和脚本（Makefile、scripts/、CI 配置）
5. README.md 或 README.*
6. 任何现有的 TODO.md、TASKS.md、.todo 或未解决的问题文件

除非分析结果与问题直接相关，否则不要输出分析结果。

---

阶段 2 — 提出澄清问题（仅一轮）

分析完成后，找出会妨碍正确实现的缺失信息。

• 在一条消息中最多提出 5 个问题。
• 只询问关键且无法从代码库推断的信息。
• 为问题编号。
• 不要询问项目文件中已有答案的问题。
• 不要分成多轮提问——这是唯一一次提问机会。

示例格式：

Before I create the plan, I need a few things clarified:

1. Should the new endpoint require authentication?
2. Is there a preferred database (the project has both SQLite and Postgres configs)?
3. Should existing tests be updated, or only new ones added?

等待用户回复后再继续。

---

阶段 3 — 创建 TODO.md

结合分析结果和用户的回答，在项目根目录中编写 TODO.md 文件。

TODO.md 结构

# TODO

## Goal

One sentence describing what will be built or fixed.

## Tasks

### 1. <Phase Name>

- [ ] <Concrete, measurable action>
- [ ] <Concrete, measurable action>

### 2. <Phase Name>

- [ ] <Concrete, measurable action>
- [ ] <Concrete, measurable action>

## Notes

Any constraints, decisions, or known risks recorded here.

要求

• 任务必须小且可独立验证（每项对应一个逻辑变更）。
• 按照依赖关系排列任务（先列前置任务）。
• 每项任务都必须能够判断是否完成。
• 不要使用“修复问题”或“改进代码”这类含糊的条目。

编写文件后，向用户展示完整内容并询问：

I've created TODO.md. Does this plan look correct?
Reply YES to start, or tell me what to change.

---

阶段 4 — 修订循环（如有需要）

如果用户要求修改：

1. 提出有针对性的后续问题，以解决分歧。
2. 重写 TODO.md。
3. 展示更新后的计划并再次请求批准。

重复以上步骤，直到用户批准为止。

---

阶段 5 — 执行计划

获得批准后：

1. 按顺序逐项完成任务。
2. 每完成一项任务，就在 TODO.md 中将其标记为已完成：
   • 将 - [ ] 改为 - [x]
3. 开始每项任务前，说明即将开始的任务。
4. 当前任务完成后，才能开始下一项任务。
5. 不执行 TODO.md 中未列出的任何工作。

如果发现必须执行但未列出的任务：

• 停止。
• 在 TODO.md 的 ## Discovered Tasks 部分下添加该任务。
• 告知用户发现了什么以及为什么需要这项工作。
• 继续之前先请求批准。

所有任务都标记为 [x] 后，写入：

All tasks in TODO.md are complete.