使用 AI 工具开发时，规模太大的任务往往难以控制。在同一个 session 里，会话一长，上下文就会被不断压缩，AI 也会逐渐「遗忘」。
如果直接使用常见的计划模式，AI 瞬间输出一大段计划，谁又能认真看完？说是给人看的，到头来往往还是给 AI 自己看。紧接着，它又一口气生成大量代码，审阅起来十分困难，最后很容易陷入 Bug 泥沼：不断修复，又不断引入新的 Bug。
所以，我逐渐摸索出了一套适合自己的计划流程。卓！
下面是我的提示词 start-plan.md：
---
description: 进入计划模式前的约束规则（先写计划书、禁止擅自写代码、计划书保存在 ./.planning 等）
---
写在前面，重点注意事项：
1. 我们先写计划书，按照计划书逐步讨论好计划，逐步实施。
2. 禁止AI擅自写代码，只有我给出明确指令后才能开始写。
3. 每次讨论结束或编写代码后都要完善计划书，注意需要遍览整个计划书，如果前面步骤的调整、代码编写、需求更改、讨论结果对后续步骤有影响，也同样要调整后续步骤。
4. 计划书按开发步骤来写，因为需要逐步讨论和实施。
5. 将每个步骤关联的需求部分，如5.1.1,5.1.2这种写在计划书里，方便开发人员对照审阅。
6. 每次完成计划后，需要在计划书中列出涉及到的接口，增加或删除了哪些接口，影响了哪些接口的入参或出参，方便开发人员维护接口文档
7. 计划书保存在./.planning目录下(如果没有该目录，就新建一个)。
8. 计划文件需要在头部有一个描述性的文本，记录该计划文件的基本信息，当多个计划并行时，方便AI进行区分、选择，每次讨论或开发完成后需要回顾，斟酌是否需要调整该头部描述。
9. 每个开发步骤必须自包含：步骤执行所需的表结构、枚举值、字段定义、接口契约等内容，必须直接列在该步骤下，禁止用「见第X章」「见X.Y节」「参见上文」等跨章节引用让审查者跳来跳去。设计章节可作为索引/附录保留，但步骤本身必须能独立审阅，无需跳转他处拼凑信息。
10. 一切讨论基于计划文件：对计划提出的疑问、反馈、需求核实结论、设计选项权衡等，必须作为对应步骤下的「待讨论」项或设计决策点更新到计划文件中，禁止只在对话里回答而不落计划。对话中的结论若未写回计划文件，视为未达成共识。审查者只认计划文件，不认对话记录。
在 pi 中，可以将提示词自定义为一个斜杠命令。我会把它作为开发时的第一条指令，然后在同一个会话中持续推进。
通过逐步讨论，我们可以不断更新和完善计划，及时查缺补漏。每个步骤都能在实施前反复打磨，让 AI 和开发者真正吃透需求、对齐理解，从而减少因需求偏差而产生的 Bug。按照步骤逐项编写代码，也能控制每个 commit 的代码量，降低审阅时的心智负担。有时，完成一两个步骤后，后续所有步骤都需要随之调整——这很正常，也很健康，鼓隆。
代码编写完成后，我会继续在当前会话中修复 Bug，并把发现的问题一并记录下来。等项目上线后，还可以让 AI 根据这些记录做一次 Bug 分析，再用分析结果补充全局 AGENTS.md。这样在处理下一个新任务时，AI 就能表现得更加准确、严谨。
start-plan.md V2
description: 进入严格计划模式：先写完整计划，逐步讨论，获得明确授权后再实施 argument-hint: "[需求描述或需求文件路径]"
进入严格计划模式
本次需求补充信息（可为空）：$ARGUMENTS
一、核心约束
- 先完整阅读需求文档、原型、附件、项目约束及相关代码，再编写计划；不得改写需求文档。
- 当前阶段只能阅读、检索、只读数据侦察和修改计划文件，禁止修改业务代码、数据库数据或执行破坏性命令。
- 只有用户明确表示“按计划实施”“开始开发”“可以修改”等，才能编码；默认只实施明确授权且标记为“可实施”的步骤。
- 计划必须从初版开始列出全部开发步骤，供用户掌控全局和跨步骤查看；按业务闭环拆分，不按 Controller/Service/Mapper 机械分层。
- 每次讨论或开发结束后都要重新通读整个计划。当前结论、代码实现或需求变化影响其他步骤时，必须同步更新相关前后步骤、数据库设计、接口影响和依赖。
- 所有疑问、反馈、口径确认和方案取舍都必须写入对应步骤的“待讨论点”；未写回计划文件的对话结论不视为共识。
二、计划文件
- 计划保存在
./.planning/<需求短名>-plan.md；目录不存在时创建。需求资料即使位于.planning子目录，也不得被计划覆盖。 - 新建前先检索
./.planning/*-plan.md：同需求已有计划则更新；有多个候选时先让用户选择；没有才新建。 - 文件名取稳定的需求标题，空白替换为短横线，去除非法字符，不随意添加日期或随机串。
三、计划结构
计划默认采用以下结构：
# 计划文件说明
# 需求分析
# 需求范围与职责划分
# 数据库设计
# 开发步骤（重点）
## 步骤一：🟦 描述性名称
### 关联需求
### 现状
### 内容
### 待讨论点
### 产出
### 接口影响
## 步骤二：🟦 描述性名称
......
## 步骤N：🟦 描述性名称
......
# Bug 记录
- 计划文件说明：用紧凑表格或短列表记录计划名称、需求来源、范围、负责人、作者、计划状态、当前重点步骤、有效需求版本、关键依赖和最后更新时间；同时列出全部步骤及状态。计划状态使用：
规划中、实施中、阻塞、待验收、已完成、已取消。 - 需求分析：简单说明业务目标、核心流程、主要变化、关键约束和已发现的冲突，不大段复述需求。
- 需求范围与职责划分：仅在多人、多仓库、前后端或跨团队协作时保留，简要说明各方范围、交付物、依赖和联调边界；不涉及则省略。
- 数据库设计：仅在涉及表、字段、索引、数据迁移或 SQL 语义变化时保留。核对真实 schema 后，精简说明相关表、关键字段、关联键、约束/索引、新库与升级库兼容；多表关系确有必要时增加只含关键字段的 Mermaid ER 图。
- 开发步骤：初版必须完整列出步骤一至步骤 N。后续步骤可以暂时简洁，但每一步都必须具备六个固定栏目，不能只写一句标题。
- Bug 记录：仅记录功能上线后用于复盘的 Bug，按
Bug-001递增；初版写“暂无上线后 Bug”。每项至少记录版本、现象、影响、根因、修复、同模式排查、验证、预防措施、关联步骤/接口和状态。
四、每个开发步骤的写法
- 步骤状态使用：
待讨论、讨论中、阻塞、可实施、实施中、已完成。每个步骤应能独立讨论、实施、验证和提交。状态必须以图标形式直接标注在步骤标题开头，方便在目录中一眼看清各步骤状态；状态变化时同步替换标题图标。图标映射如下：🟦 待讨论、💬 讨论中、⛔ 阻塞、🟢 可实施、🚧 实施中、✅ 已完成。标题格式为## 步骤一：🟢 描述性名称。 - 关联需求：列出需求章节、编号、原型或附件位置，例如 5.1.1、5.1.2，并说明本步骤负责其中哪部分。
- 现状：只记录本步骤直接相关的现有流程、代码、表、状态、接口、权限和已知问题，不写“代码现状大全”，不把猜测写成事实。
- 内容：写清要开发的业务流程、状态变化、权限、关键字段、主要模块、兼容策略、边界和验证要求。
- 步骤必须自包含：执行和审阅本步骤所需的表结构、关键字段、枚举值、状态含义、接口契约和决策规则必须直接写在本步骤下；禁止只写“见第 X 章”“参见上文”。全局数据库设计可作概览，但不能替代步骤中的必要信息。
- 待讨论点：使用表格维护，至少包含编号、事项、状态、结论/影响。状态使用：
待讨论、讨论中、已确定、搁置、已废止。结论确定后必须同步改写本步骤正文及受影响的其他步骤，不能让旧口径继续并列生效。 - 产出：保持精简，列出可验收的代码、迁移、配置、测试、文档或联调结果。实施后补充实际产出、验证结果、未验证项、已知限制和提交版本；未提交时写“未提交”。
- 接口影响：仅记录以下四类接口：新增的接口、删除的接口，请求参数、响应字段或枚举取值发生变化的接口，以及接口参数（含入参和出参）含义发生变化的接口；逐项列出方法/路径及对应的变化点，供开发人员维护接口文档。内部逻辑、权限、错误码、幂等或兼容性等不涉及上述四类变化的接口不在此处记录；无符合要求的接口变化时明确写“无”。
- 一个步骤的关键口径、范围、产出、接口和验收方式均已明确，所有阻塞实施的讨论项都已“已确定”或明确“搁置”后，才能标记为“可实施”。
五、讨论与实施循环
- 初版计划完成后，只汇报计划路径、完整步骤顺序、主要待讨论点和建议先讨论的步骤，然后等待用户，不得直接编码。
- 用户可以按顺序讨论，也可以跨步骤讨论；每轮结束都必须更新计划文件说明、对应步骤及所有受影响步骤。
- 获得实施授权后，只开发本轮明确授权的步骤，并遵守项目已有的权限、数据库、验证、Java 编译和 Git 约束。
- 步骤实施完成后，将实际修改、接口变化、验证结果和未验证项写回计划，重新整理后续步骤，将本步骤标记为“已完成”或“阻塞”，然后停止，等待下一步讨论或授权。
- 最后一步完成后，汇总未验证项、人工/CI 待办、提交版本、迁移版本、已知限制和部署回归要求；完整业务闭环验收后，计划才能标记为“已完成”。
