# Hplan

> 分层持久化计划管理，适用于复杂的多阶段开发任务。当用户要求进行涉及多文件修改、 架构重构、系统设计等需要详细规划的任务时使用（超过5次工具调用的任务）。 创建分层的计划目录结构：overview.md（全局摘要）+ 每个阶段独立目录（详细规格、 调用链、检查清单）。触发词包括：开始规划、制定计划、任务分解。

- Skill: `noirewinter/hplan-2` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add noirewinter/hplan-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/noirewinter/hplan-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Noirewinter (https://skillmd.com/u/noirewinter)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/noirewinter/hplan-2

---


# 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 行以内**。格式如下：

```markdown
# [项目名称]
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** — 该阶段的逐项检查清单：
```markdown
# 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](templates/overview.md)）
3. 为每个阶段创建 phase 目录和 spec.md / checklist.md
4. 如果涉及架构变更，创建 call_chain.md
5. 创建 decisions.md 和 errors.md

**参考模板文件：**
- [templates/overview.md](templates/overview.md)
- [templates/spec.md](templates/spec.md)
- [templates/checklist.md](templates/checklist.md)
- [templates/call_chain.md](templates/call_chain.md)
- [templates/decisions.md](templates/decisions.md)
- [templates/errors.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 校验 |