hplan：为AI编程助手构建持久化工作记忆，解决长任务目标漂移

1. 项目概述：为Claude Code构建持久化的工作记忆

如果你和我一样，经常让Claude Code处理一些复杂的重构或开发任务，比如把一个单体应用拆成微服务，或者把整个认证系统从Session迁移到JWT，那你肯定遇到过这样的场景：任务进行到一半，Claude突然开始“跑偏”了。它可能忘了某个关键接口的改动，或者重复修改一个已经改好的文件，甚至把整个任务目标都搞混了。这背后的核心问题，是AI助手和我们人类一样，也有“工作记忆”的限制。Claude Code的上下文窗口虽然大，但在处理涉及几十个文件、跨越多个阶段的复杂任务时，那些关键的细节——比如每个阶段要改哪些文件、接口的调用链如何变化、整体的进度卡在哪里——很容易在一次次工具调用中被“挤”出上下文，导致目标漂移和细节丢失。

hplan（Hierarchical Persistent Planning）这个项目，就是为了解决这个问题而生的。它的核心思想非常巧妙：把文件系统当作AI的持久化工作记忆。简单来说，就是让Claude Code把复杂的多阶段任务计划，写成一个结构化的目录树，放在项目的.plan/文件夹里。然后，通过一系列自动化的“钩子”（hooks），在关键时刻（比如每次工具调用前、用户发送消息后）把计划的关键部分重新注入到Claude的上下文中，确保它永远不会忘记核心目标和当前进度。

这就像给Claude配了一个永远不会丢的“任务清单”和“进度看板”。它不是简单地记录待办事项，而是采用了一种分层递进的披露方式：一个极度精简的全局概览（overview.md）负责维持目标感；而每个阶段详细的规格说明（spec.md）、检查清单（checklist.md）和调用链图（call_chain.md）则被分门别类地存放，只在需要时才被激活和注入。这种设计，让Claude既能“看见森林”（整体目标），又能“看清树木”（当前阶段的细节），从而在长达数十甚至上百次工具调用的复杂任务中，始终保持航向。

2. 核心设计思路与架构解析

2.1 问题根源：AI在长任务中的“记忆失焦”

要理解hplan的价值，得先看清它要解决的两个核心痛点，这也是我在长期使用AI编程助手时最深切的体会。

目标漂移（Goal Drift）：你可以把Claude想象成一个注意力非常集中，但短期记忆有限的天才程序员。当你给它一个简单指令，比如“修复这个函数的bug”，它能完美执行。但如果你说“请将我们的用户系统从使用Session改为JWT，并实现Refresh Token机制，同时更新前后端所有相关代码，最后完成端到端测试”，这个任务就包含了分析、后端重构、前端适配、测试等多个阶段，涉及数十个文件。Claude在埋头修改authMiddleware.js时，可能还记得要加JWT验证；但在修改了十几个文件后，当它开始处理前端的axios拦截器时，很可能已经忘了整个迁移的最终目标是要完全取代Session，而不仅仅是新增一个选项。这种逐渐偏离原始目标的现象，就是目标漂移。

详细规格丢失（Detailed Spec Loss）：复杂任务之所以复杂，是因为有大量细节需要追踪。还是以JWT迁移为例：第一阶段要分析哪些现有文件？第二阶段具体要创建JwtService类和TokenBlacklist模块吗？它们的接口是什么？login接口的返回值要从{user}改成{accessToken, refreshToken, user}吗？第三阶段前端的请求头如何设置？这些细节如果全部堆在Claude的上下文中，会迅速耗尽宝贵的token空间。但如果不放进去，Claude就可能基于不完整或过时的信息做出错误决策。传统的做法是用户不断在聊天中提醒和纠正，效率很低。

hplan的解决方案，不是去扩大Claude的“脑容量”（上下文窗口），而是给它一个“外部大脑”——文件系统。通过将计划结构化、持久化，并智能地按需加载，它从根本上改变了AI处理长任务的方式。

2.2 分层规划：概览与详情的分离艺术

hplan最精妙的设计在于其“分层”和“持久化”规划。它没有把整个庞大的计划塞进一个文件，而是拆解成一个清晰的目录树结构：

.plan/ ├── overview.md # 全局概览（≤25行） ├── decisions.md # 关键决策日志 ├── errors.md # 错误追踪日志 └── phases/ # 阶段目录 ├── phase1_analyze/ │ ├── spec.md # 该阶段详细规格（≤60行） │ ├── call_chain.md # 调用链变更图（可选） │ └── checklist.md # 逐项检查清单 ├── phase2_backend/ └── ...

这种结构带来了几个关键优势：

1. 关注点分离：overview.md只关心最高层级的战略问题：目标是什么？现在在哪个阶段？整体进度如何？有什么阻塞？它被限制在25行以内，确保每次注入时都简洁、聚焦。而具体的战术细节，比如“UserController.login方法第47行需要添加refreshToken参数”，则放在对应阶段的spec.md里。这样，Claude在思考“接下来该做什么”时，看概览；在执行“具体怎么做”时，才去看详细规格。

2. 渐进式披露：这是避免上下文污染的关键。在整个任务过程中，Claude的上下文里始终有overview.md（通过PreToolUse钩子每次工具调用前注入）。但phases/phase2_backend/spec.md这样的详细文件，只有在phase2_backend被标记为“进行中”时，才会在用户发送消息后被自动注入（通过UserPromptSubmit钩子）。这意味着，当Claude在专注地编写后端JWT模块时，它不会被前端适配或测试阶段的细节干扰。每个阶段，它只获得完成当前工作所必需的信息。

3. 状态持久化与恢复：所有计划文件都保存在磁盘上。即使Claude Code的会话意外中断，或者你隔了一天再打开项目，只要运行hplan的恢复逻辑，它就能立刻从.plan/目录中读取到上次的任务进度、当前的阶段、以及所有已完成的检查项，实现“断点续传”。这解决了AI助手缺乏长期记忆的根本问题。

2.3 自动化钩子：让计划“活”起来的引擎

计划写得再好，如果不能让Claude自动地、在正确的时间去查看和更新它，那就只是一堆静态文档。hplan通过四个核心的钩子脚本，将整个计划体系与Claude Code的工作流深度集成：

这四个钩子形成了一个完整的监督和提醒闭环，使得计划不再是需要Claude（或用户）主动回忆的负担，而是变成了一个自动化的、与环境交互的“工作流伙伴”。

注意：钩子的执行依赖于Claude Code的技能（Skills）系统。这意味着hplan的生效是无感的。一旦安装并触发，Claude会在后台自动运行这些脚本，用户通常不需要手动干预钩子的执行过程。

3. 从安装到实战：手把手搭建你的AI“第二大脑”

3.1 环境准备与技能安装

hplan的安装过程极其简单，因为它本质上是一个Claude Code技能（Skill）。Claude Code允许用户通过~/.claude/skills/目录来扩展其能力。以下是具体步骤：

1. 克隆仓库：打开你的终端，执行以下命令获取hplan的最新代码。

   git clone https://github.com/Noirewinter/hplan.git

   这会在当前目录创建一个名为hplan的文件夹。

2. 复制技能：将技能目录复制到Claude Code的技能文件夹中。通常这个文件夹位于你的用户目录下。

   cp -r hplan/skills/hplan ~/.claude/skills/

   这个命令将hplan技能包（包含所有钩子脚本和模板）放置到Claude Code能够扫描并加载的位置。

3. 重启Claude Code：这是关键且必须的一步。Claude Code只在启动时加载技能目录。安装完成后，请完全关闭并重新启动你的Claude Code桌面应用程序或编辑器插件。

4. 验证安装：重启后，在Claude Code的聊天窗口中，你可以尝试输入/，如果能看到hplan相关的命令提示（或者直接输入/hplan），则说明技能加载成功。更常见的触发方式是直接描述一个复杂任务，Claude会智能判断是否需要启用hplan。

实操心得：有时技能没有立即生效，可能是因为Claude Code有缓存。如果重启后仍不工作，可以检查~/.claude/skills/hplan/目录是否存在且结构完整，或者尝试在Claude Code的设置中寻找“重新加载技能”的选项。

3.2 初始化你的第一个分层计划

安装完成后，让我们通过一个真实的复杂任务来启动hplan。假设你有一个Express.js后端项目，目前使用Session进行用户认证，现在需要迁移到JWT（JSON Web Token）并实现Refresh Token（刷新令牌）机制。

你不需要手动创建任何.plan/目录或文件。只需像平常一样，向Claude Code清晰地描述这个复杂任务：

我需要将当前项目的用户认证系统从基于Session的模式，迁移到JWT + Refresh Token模式。 具体任务包括： 1. 分析现有的认证流程和所有相关文件（控制器、中间件、路由）。 2. 后端重构：创建JWT签发与验证服务，修改登录/注册接口返回tokens，改造认证中间件，考虑Token黑名单或Redis存储方案。 3. 前端适配：修改所有API请求的拦截器，在请求头中携带Access Token，实现Token过期自动刷新逻辑。 4. 进行端到端测试，确保登录、权限验证、Token刷新全流程通畅。 这是一个多阶段的重构任务，请使用hplan来帮助我们规划和追踪进度。

当你发送这样一段描述后，Claude Code（在hplan技能的作用下）会识别出这是一个多阶段复杂任务。它会首先在项目根目录下自动创建.plan/目录结构，并利用模板初始化所有必要的文件。

初始化后的.plan/目录预览：

• overview.md: 会根据你的任务描述，生成一个初始的概览，包含目标、拟定的阶段（如phase1_analyze,phase2_backend等）。
• decisions.md和errors.md: 初始为空，用于后续记录。
• phases/目录下：会为每个识别出的阶段创建子目录（如phase1_analyze/），并在其中生成spec.md（等待填充细节）、checklist.md（初始任务项）和可选的call_chain.md模板。

至此，你的AI“第二大脑”已经就绪。所有后续的规划、执行和追踪都将围绕这个目录展开。

3.3 解读核心文件：以JWT迁移为例

让我们深入看看，在JWT迁移任务中，hplan生成的核心文件具体长什么样，以及它们如何协作。

overview.md- 战略指挥中心这个文件是灵魂，必须保持精简（≤25行）。它由Claude维护，并通过钩子反复注入。

# JWT Auth Migration current_phase: phase2_backend ## Goal Migrate user auth from Session-based to JWT + Refresh Token, ensuring statelessness and improved security. ## Phases - [x] phase1_analyze: Audit existing auth flow and identify all touchpoints → complete - [ ] phase2_backend: Implement JWT service, refactor endpoints and middleware → in_progress (3/6) - [ ] phase3_frontend: Adapt frontend interceptors and token refresh logic → pending - [ ] phase4_test: Conduct end-to-end testing of the new auth flow → pending ## Blockers - Need to decide on storage solution for refresh tokens (Database vs Redis). ## Last Decision Proceed with Redis for refresh token storage due to faster invalidation and 7-day expiry requirement. ## Last Error None

为什么这样设计？这25行信息是Claude的“罗盘”。current_phase告诉它现在的主战场在哪里。Phases用复选框直观展示全局进度，in_progress (3/6)这样的标记提供了微观进度。Blockers和Last Decision则聚焦了当前需要关注的关键决策点。所有这些信息，让Claude在每次行动前都能用几秒钟快速回顾全局，避免迷失。

phases/phase2_backend/spec.md- 战术执行手册当current_phase是phase2_backend时，这个文件会被自动注入。它包含该阶段的所有具体指令。

# Phase 2: Backend Refactor - Detailed Specifications ## Objective Replace session-based authentication in all backend endpoints with JWT. ## Files to Modify/Create 1. **Create**: `src/services/JwtService.js` - Functions: `signAccessToken(payload)`, `signRefreshToken(payload)`, `verifyToken(token, isAccessToken=true)` - Use `jsonwebtoken` library, secrets from environment variables. 2. **Modify**: `src/controllers/AuthController.js` - `login`: Return `{ accessToken, refreshToken, user }` instead of just setting session. - `register`: Similarly return tokens. - Add `refresh` endpoint to exchange a valid refresh token for a new access token. 3. **Modify**: `src/middleware/auth.js` - New function `authenticateJWT`: Extract token from `Authorization: Bearer <token>` header. - Verify token using `JwtService.verifyToken`. - Attach decoded user to `req.user`. - Remove session parsing logic. 4. **Create** (Optional): `src/services/TokenBlacklist.js` or integrate with Redis for immediate refresh token revocation. ## Interface Changes - **Login/Register Response**: BEFORE: `{ user: {id, name, email} }` AFTER: `{ accessToken: string, refreshToken: string, user: {id, name, email} }` - **Protected Routes**: BEFORE: Relied on `req.session.userId`. AFTER: Rely on `req.user.id` set by `authenticateJWT` middleware. ## Dependencies - Install: `jsonwebtoken`, `redis` (if chosen) - Update `.env.example` with `JWT_ACCESS_SECRET`, `JWT_REFRESH_SECRET`, `REDIS_URL`.

这个文件就是Claude在本阶段的“工作说明书”。它明确列出了要动哪些文件、怎么改、输入输出是什么。有了它，Claude就不需要从模糊的聊天记录里去回忆“我到底要不要改AuthController？”这样的细节。

phases/phase2_backend/checklist.md- 进度追踪器这是一个动态更新的任务清单，通常由Claude在完成每个子任务后勾选。

- [x] Analyze and decide on JWT library (`jsonwebtoken`) - [x] Create `src/services/JwtService.js` skeleton - [ ] Implement `signAccessToken` and `signRefreshToken` functions - [ ] Implement `verifyToken` function - [ ] Refactor `AuthController.login` method - [ ] Refactor `AuthController.register` method - [ ] Create `AuthController.refresh` endpoint - [ ] Implement `authenticateJWT` middleware - [ ] Update all route definitions to use new middleware - [ ] Test backend token flow in isolation

这个清单将spec.md中的目标分解为可执行、可验证的步骤。PostToolUse钩子会不断提醒Claude去更新它，而Stop钩子则会检查所有阶段的清单是否全部完成，从而防止任务被意外标记为“完成”。

call_chain.md(可选) - 影响面分析图对于涉及多个模块调用的重构，这个文件非常有用。它帮助Claude（和未来的你）理解变更的影响范围。

# Call Chain Changes for JWT Migration ## BEFORE (Session-based)

[图示或文字描述] User Request ->authMiddleware(checksreq.session) ->routeHandler-> Response

## AFTER (JWT-based)

[图示或文字描述] User Request ->authenticateJWT(checksAuthorizationheader, verifies JWT) ->routeHandler-> Response Refresh Request ->validateRefreshToken->JwtService.signAccessToken-> New Access Token Response

## Modified Components - **Removed**: `express-session` middleware, session store logic. - **Added**: `authenticateJWT` middleware, `JwtService`, token refresh endpoint. - **Updated**: All route handlers that previously read `req.session`.

通过对比“前后”调用链，Claude能更系统地进行重构，避免遗漏某些隐蔽的依赖点。

4. 工作流深度剖析：钩子如何驱动智能协作

理解了核心文件后，我们再回到那四个钩子，看看在一个完整的任务周期中，它们是如何像齿轮一样精密咬合，驱动Claude与hplan协同工作的。

4.1 场景推演：一次完整的用户交互循环

假设我们正处于JWT迁移任务的phase2_backend阶段，并且已经完成了一部分工作。

1. 用户发送消息：你检查进度后，对Claude说：“JwtService的verifyToken函数好像没处理过期错误，完善一下。”

2. UserPromptSubmit钩子触发：这个钩子脚本首先检查.plan/目录。它发现overview.md中current_phase: phase2_backend，且该阶段状态为in_progress。于是，它执行以下操作：

   • 读取overview.md（全局状态）。
   • 读取phases/phase2_backend/spec.md（当前阶段详细规格）。
   • 读取phases/phase2_backend/checklist.md（当前待办事项）。
   • 将这三部分内容，自动附加在你刚刚发送的用户消息之前，一并提交给Claude模型。结果：Claude收到的提示变成了：“[以下是来自hplan的上下文]+[你的原始消息]”。它立刻知道自己正在处理后端重构，JwtService是当前重点，并且verifyToken函数在检查清单上还未完成。它完全理解了上下文，无需你重复说明。

3. Claude思考与准备行动：Claude分析后，决定调用“编辑文件”工具来修改src/services/JwtService.js。

4. PreToolUse钩子触发：在Claude执行编辑操作之前，这个钩子被调用。它做了一件非常简单但至关重要的事：再次将overview.md（仅25行）注入到Claude的上下文中。结果：尽管Claude刚刚才从UserPromptSubmit获得了详细规格，但在它动手敲代码的前一秒，overview.md再次强化了它的目标记忆：“我们是在做JWT迁移，目标是替换Session，当前在第二阶段，进度是3/6”。这有效防止了在具体编码时陷入细节而忘了大方向。

5. Claude执行工具调用：Claude成功编辑了文件，添加了完善的错误处理。

6. PostToolUse钩子触发：在编辑操作之后，这个钩子被调用。它不会自动修改文件，而是会向Claude发送一个提醒：“记得更新phase2_backend的检查清单和概览中的进度哦。”结果：Claude收到提醒，很可能会在接下来的回复中，主动说：“已完成verifyToken的错误处理。现在我来更新一下进度。”然后它会调用工具去修改checklist.md，将对应项标记为[x]，并可能将overview.md中的进度更新为(4/6)。这培养了Claude“即做即记”的良好习惯，保证了计划文件的实时性。

7. 任务接近尾声：当所有阶段的checklist.md都勾选完毕，Claude认为任务完成，准备发送总结消息。

8. Stop钩子触发：在Claude发出最终回复之前，这个钩子被调用。它会运行一个检查脚本，遍历phases/下所有checklist.md文件。

   • 如果所有项均为[x]：钩子放行，Claude可以正常发送“任务完成”的消息。
   • 如果发现任何[ ]未完成项：钩子会阻止Claude结束，并向其注入一条警告信息，例如：“检测到phase3_frontend的检查清单中还有2项未完成。请确认所有阶段工作均已完结。”结果：这提供了一个最终的质量关卡，避免了因为Claude的误判或疏忽而导致任务被提前关闭，确保交付物的完整性。

4.2 决策与错误日志：项目管理的延伸

decisions.md和errors.md是两个辅助但极其有价值的文件。它们的作用超越了单次任务执行，更像是项目日志。

• decisions.md：记录所有关键的技术决策和理由。例如：

  ## 2023-10-27: Refresh Token Storage **问题**：Refresh Token需要持久化以便于吊销和验证，选择数据库还是Redis？ **选项**： 1. 数据库（User表新增字段）：简单，但频繁读写可能成为瓶颈，吊销需要更新数据库。 2. Redis：内存存储，读写极快，天然支持TTL（自动过期），吊销直接删除Key即可。 **决策**：选择Redis。 **理由**： - 性能更优，适合高频的Token验证操作。 - TTL特性完美匹配Refresh Token的过期需求。 - 简化吊销逻辑。 **影响**：需要引入`redis`依赖，并配置相关环境变量。

  当未来你或其他人回顾项目，或者任务中断后需要接续时，这份决策日志能快速让人理解当时的架构思考，避免重复讨论或做出矛盾的修改。

• errors.md：记录任务执行过程中遇到的错误和解决方案。例如：

  ## 2023-10-27: JWT Verification Failing in Middleware **错误**：在`authenticateJWT`中间件中，`JwtService.verifyToken`抛出`TokenExpiredError`，导致所有带过期Token的请求返回500错误。 **根本原因**：`verifyToken`函数内部没有区分`JsonWebTokenError`和`TokenExpiredError`，统一抛出导致中间件崩溃。 **解决方案**：修改`verifyToken`函数，对`TokenExpiredError`返回一个特定的标识（如`{ expired: true }`），并在中间件中据此返回401状态码和清晰的`Token expired`信息，而非500。 **修复提交**：修改了`src/services/JwtService.js`和`src/middleware/auth.js`。

  这不仅帮助Claude在后续遇到类似问题时能参考解决，也为项目积累了宝贵的故障排查知识库。

5. 高级技巧与实战避坑指南

经过多个项目的实践，我总结出一些让hplan发挥最大效能的技巧，以及一些常见的“坑”和解决方法。

5.1 编写高质量规格的黄金法则

hplan的效果很大程度上取决于spec.md和overview.md的质量。以下是几条黄金法则：

1. 目标SMART化：在overview.md的Goal部分，尽量使用SMART原则（具体、可衡量、可实现、相关、有时限）来描述。例如，“优化性能”是模糊的，而“将首页API响应时间从200ms降低至100ms以下”则是清晰的。这能帮助Claude更好地判断任务是否完成。
2. 阶段划分要正交：划分阶段时，尽量让每个阶段的任务相对独立，输出明确。例如，“分析”、“后端重构”、“前端适配”、“测试”就是很好的正交划分。避免出现“阶段A：开发用户模块和部分UI”这种耦合度过高的阶段，这会导致上下文切换混乱。
3. spec.md要具体到文件行：好的规格说明书应该像给初级开发者的工单。不要写“修改认证逻辑”，而要写“修改src/middleware/auth.js第15-30行的authenticate函数，将Session检查替换为JWT验证，使用JwtService.verifyToken方法”。越具体，Claude的执行准确率越高。
4. 善用checklist.md进行任务分解：将spec.md中的每个要点分解成checklist.md中可独立勾选的小任务。例如，“创建JWT服务”可以分解为“创建文件”、“实现signAccessToken”、“实现signRefreshToken”、“实现verifyToken”、“编写单元测试”。小任务更容易管理和产生成就感。

5.2 常见问题与排查技巧实录

即使设计得再好，在实际使用中也可能遇到问题。下面是一个常见问题速查表：

5.3 超越代码重构：hplan的多样化应用场景

虽然hplan的示例多集中于代码重构，但其“分层持久化规划”的思想适用于任何复杂的、多步骤的Claude Code任务。

• 数据迁移脚本编写：阶段1：分析源数据和目标模式。阶段2：编写数据提取脚本。阶段3：编写数据转换与清洗脚本。阶段4：编写数据加载脚本与验证。每个阶段的spec.md可以详细定义字段映射规则、转换函数和异常处理逻辑。
• 技术文档撰写：阶段1：确定文档大纲和受众。阶段2：撰写核心概念章节。阶段3：撰写API参考章节。阶段4：添加示例代码和图表。阶段5：进行审阅和润色。overview.md跟踪整体进度，每个阶段的spec.md可以列出该章节的要点和风格要求。
• 基础设施即代码（IaC）部署：阶段1：设计云资源架构图。阶段2：编写Terraform/CloudFormation模板。阶段3：配置CI/CD流水线。阶段4：部署与冒烟测试。call_chain.md在这里可以很好地描述资源之间的依赖关系。

关键在于，将任何宏大任务分解为有明确输入输出的阶段，并为每个阶段创建清晰的规格说明和检查清单。hplan提供的框架，能将这些离散的计划点串联成一个可管理、可追踪、可恢复的智能工作流。

最后，我个人最深的体会是，hplan不仅仅是一个工具，它更是一种与AI协作的范式转变。它迫使我们将模糊的需求转化为结构化的计划，这本身就是一个极佳的澄清和设计过程。而一旦有了这个“外部大脑”，Claude Code就从一名有时会健忘的天才临时工，转变为了一个可靠、持久、目标明确的资深项目伙伴。它可能不会让你完全放手，但绝对能让你从重复的提醒和上下文管理中解放出来，将精力真正集中在更高层次的架构和决策上。