hplan

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