hplan — 分层持久化计划管理

用文件系统作为持久化工作记忆。overview.md 保持精简（≤25行），详细规格按阶段拆分到独立目录中。

核心原则

上下文窗口 = RAM（易失、有限）
文件系统   = 磁盘（持久、无限）
→ 重要信息必须写入磁盘
→ 被 hook 注入的内容必须精简
→ 被深度参考的内容必须详尽
→ 二者分离，互不冲突

如果感觉上下文缺失，主动读取

.plan/

下的相关文件即可。所有计划信息都持久化在磁盘文件中，不会因上下文变化而丢失。

目录结构

所有计划文件存放在项目根目录的

.plan/

目录下：

.plan/
├── overview.md              ← 全局摘要（精简，被 hook 反复注入）
├── decisions.md             ← 所有决策记录
├── errors.md                ← 所有错误记录
└── phases/
    ├── phase1_xxx/
    │   ├── spec.md          ← 该阶段详细规格（修改文件、代码变更）
    │   ├── call_chain.md    ← 调用链 / 架构图（可选）
    │   └── checklist.md     ← 逐项完成状态
    ├── phase2_xxx/
    │   ├── spec.md
    │   ├── call_chain.md
    │   └── checklist.md
    └── ...

关键约束

overview.md 必须保持精简

overview.md 是被 PreToolUse hook 每次注入到上下文的文件。严格控制在 25 行以内。格式如下：

# [项目名称]
current_phase: phase2_xxx

## Goal
[一句话描述最终目标]

## Phases
- [x] phase1_xxx: [阶段描述] → complete
- [ ] phase2_xxx: [阶段描述] → in_progress (2/4)
- [ ] phase3_xxx: [阶段描述] → pending

## Blockers
[当前阻塞项，没有则写 None]

## Last Decision
[最近一条重要决策的一句话摘要]

## Last Error
[最近一条错误的一句话摘要，没有则写 None]

绝对不要在 overview.md 里放详细的文件清单、代码片段、调用链。那些内容属于 phase 目录。

详细内容放在 phase 目录中

每个

phases/phaseN_xxx/

目录包含该阶段的完整信息：

spec.md — 该阶段的详细规格：

• 需要修改哪些文件、每个文件的具体变更内容
• 新增文件的接口设计、数据结构定义
• 依赖关系和前置条件

spec.md 控制在 60 行以内。 当用户发送新消息时，如果有进行中的阶段，当前阶段的 spec.md 会被自动注入到上下文。如果一个阶段的 spec 写出来超过 60 行，说明这个阶段的粒度太粗，应该拆分成两个或更多阶段。拆分时保持每个阶段的 spec 聚焦于一组相关的修改，而非堆砌所有细节。

call_chain.md（可选）— 调用链 / 架构变更图：

• 修改前后的调用关系对比
• 用文本或 Mermaid 语法绘制

checklist.md — 该阶段的逐项检查清单：

# Phase 2: 后端接口改造 — 检查清单
- [x] 新建 src/auth/token.py
- [x] 修改 src/auth/routes.py
- [ ] 修改 src/middleware/auth.py
- [ ] 修改 config/auth.yaml
- [ ] 运行单元测试确认无回归

工作流

1. 创建计划（必须在开始执行前完成）

收到复杂任务后：

1. 创建

   .plan/

   目录结构（可运行

   sh scripts/init-plan.sh

   快速初始化）
2. 用模板创建 overview.md（参考 templates/overview.md）
3. 为每个阶段创建 phase 目录和 spec.md / checklist.md
4. 如果涉及架构变更，创建 call_chain.md
5. 创建 decisions.md 和 errors.md

参考模板文件：

• templates/overview.md
• templates/spec.md
• templates/checklist.md
• templates/call_chain.md
• templates/decisions.md
• templates/errors.md

2. 用户确认（不可跳过）

计划创建完成后，必须停下来等待用户确认，严禁自行开始执行。

向用户展示以下内容并请求确认：

• overview.md 的完整内容（目标和阶段划分）
• 每个阶段的 spec.md 摘要（修改哪些文件、核心变更）
• 总阶段数和预估工作量

明确询问用户：

• 阶段划分是否合理？是否需要增减或拆分阶段？
• 每个阶段的修改范围是否正确？是否遗漏了文件或变更点？
• 是否可以开始执行？

只有在用户明确表示同意后，才能进入执行阶段。 如果用户提出调整意见，修改计划文件后再次展示并请求确认。

修改计划时必须保持 overview.md 与 phases/ 目录同步

在确认阶段与用户反复调整计划时，任何对阶段的增删改都必须同时更新两个地方：

• 新增阶段：在 overview.md 中添加条目，同时创建

  phases/phaseN_xxx/

  目录及 spec.md、checklist.md
• 删除阶段：从 overview.md 中移除条目，同时删除对应的

  phases/phaseN_xxx/

  目录
• 重命名阶段：更新 overview.md 中的 phase ID，同时重命名

  phases/

  下的目录（不要保留旧目录）
• 拆分阶段：删除原阶段目录，创建拆分后的多个新目录，更新 overview.md

每次修改计划后，运行

sh scripts/validate-plan.sh

校验一致性。该脚本会检查：

• overview.md 中的每个阶段是否有对应目录
• 每个目录中是否包含 spec.md 和 checklist.md
• phases/ 下是否有 overview.md 未引用的残留目录

3. 执行阶段

用户确认计划后，进入工作循环：

1. 开始新阶段前：必须先读取该阶段的 spec.md 全文（和 call_chain.md，如有），完整理解要做什么。这一步不可跳过。
2. 执行工作：按 checklist.md 逐项推进
3. 完成子任务后：更新 checklist.md（

   [ ]

   →

   [x]

   ）
4. 阶段全部完成后：
   • 更新 overview.md：标记该阶段 complete，更新

     current_phase

     指向下一阶段
   • 可运行

     sh scripts/advance-phase.sh

     辅助切换
   • 将该阶段的重要发现记录到 decisions.md

4. 切换阶段

当 overview.md 中

current_phase

变更后：

• PreToolUse hook 会继续注入 overview.md，确保目标感知
• 必须主动读取新阶段的 spec.md 和 checklist.md，确认工作范围

5. 错误处理

第1次失败：诊断并修复 → 记录到 errors.md
第2次失败：换一种方法 → 记录到 errors.md
第3次失败：重新审视假设 → 更新 spec.md
第3次后仍失败：向用户说明情况，请求指导

6. 完成验证

Stop hook 会自动检查 overview.md 中所有阶段的完成状态。如果存在未完成的阶段，会提示你检查剩余任务。用户可以随时通过删除

.plan/

目录来退出计划。

7. 自主完成原则

应尽量亲自执行 checklist 中的每一项，而非将工作交给用户手动执行。

如果某个子任务你无法完成（例如需要外部服务的密钥、需要物理设备操作），应当：

1. 在 errors.md 中记录具体原因
2. 在 overview.md 的 Blockers 中标注
3. 向用户明确说明你被什么阻塞了，请求用户提供必要的信息或操作
4. 等待用户回应后继续完成，而不是跳过

以下行为应避免：

• 将 checklist 中的子任务描述为"建议用户手动执行"
• 列出剩余步骤的说明后结束，而非实际执行这些步骤
• 将可以通过代码完成的操作（创建文件、修改配置、运行测试等）推给用户

8. 完成后的修改

计划全部完成后，用户可能提出修改意见。根据修改的复杂度选择不同的处理方式：

直接修复（修改涉及 ≤2 个文件，不改变架构）：

• 不启动新计划，直接修改代码
• 在 decisions.md 中记录修改内容

追加阶段（修改涉及 3+ 个文件，或需要调整调用链）：

• 在现有

  .plan/

  上追加新的 phase 目录（如 phase10_fix_xxx）
• 更新 overview.md：添加新阶段条目，设置

  current_phase

  指向新阶段
• 向用户展示新增阶段的 spec 并请求确认，确认后执行
• 运行

  sh scripts/validate-plan.sh

  校验一致性

全新计划（修改的性质是推翻原设计）：

• 将现有

  .plan/

  重命名为

  .plan.archived/

  （保留记录）
• 启动全新的 hplan 流程：创建计划 → 用户确认 → 执行

判断标准：如果用户的修改意见可以表述为"在现有架构上修 N 个问题"，追加阶段；如果必须表述为"重新设计 XXX 模块"，全新计划。

何时使用

使用：

• 多阶段开发任务（3+ 阶段）
• 涉及多文件修改的重构
• 需要记录调用链/架构变更的任务
• 跨会话的长期项目

不使用：

• 简单问答
• 单文件修改
• 快速查询

读写决策矩阵

场景	操作	原因
刚写完文件	不读	内容还在上下文中
开始新阶段	读 spec.md + checklist.md	完整理解工作范围
做重要决策前	读 overview.md + 相关 spec	确保目标对齐
遇到错误	读 errors.md	避免重复失败

反模式

不要	应该
在 overview.md 里放详细信息	放在 phase 目录的 spec.md 里
overview.md 超过 25 行	精简到只有摘要
spec.md 超过 60 行	拆分为多个阶段，每个阶段的 spec 保持聚焦
跳过创建计划直接执行	先创建完整的 .plan/ 目录
忘记更新 checklist.md	每完成一项立即更新
在 spec.md 里更新状态	状态在 checklist.md，规格在 spec.md
重复同样的失败操作	记录错误，变换方法
把未完成的子任务交给用户手动执行	尽量自己执行，遇到阻塞时请求用户提供必要信息
列出剩余步骤的说明后结束	尽量实际执行这些步骤，完成后再结束
创建计划后直接开始执行	展示计划并等待用户确认后才执行
修改 overview.md 后不同步 phases/ 目录	增删改阶段时同时更新两处，用 validate-plan.sh 校验