Skip to content

Noirewinter/hplan / skills/hplan-zh

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

---
name: hplan
version: "1.0.0"
description: >
  分层持久化计划管理,适用于复杂的多阶段开发任务。当用户要求进行涉及多文件修改、
  架构重构、系统设计等需要详细规划的任务时使用(超过5次工具调用的任务)。
  创建分层的计划目录结构:overview.md(全局摘要)+ 每个阶段独立目录(详细规格、
  调用链、检查清单)。触发词包括:开始规划、制定计划、任务分解。
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
hooks:
  UserPromptSubmit:
    - hooks:
        - type: command
          command: "sh \"${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/hplan}/scripts/recover-context.sh\""
  PreToolUse:
    - matcher: "Write|Edit|Bash|Read|Grep|Glob"
      hooks:
        - type: command
          command: "sh \"${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/hplan}/scripts/inject-overview.sh\""
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "sh \"${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/hplan}/scripts/post-edit-remind.sh\""
  Stop:
    - hooks:
        - type: command
          command: "sh \"${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/hplan}/scripts/check-complete.sh\""
---

# 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 校验 |
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall