planning-with-files：3 个文件 + 4 个钩子，让 Claude Code 从"重启即忘"到"永久记忆"

🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划 第 37 篇，AI 编程最佳实战「2026」系列第 4 篇 大家好，欢迎来到 术哥无界 | ShugeX ｜ 运维有术。 我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、Milvus 向量数据库的技术实践者与开源布道者！ Talk is cheap, let's explore。无界探索，有术而行。

封面图

图 1：planning-with-files 核心价值概览

你在用 Claude Code 时，可能遇到过这些情况：

• 聊着聊着，它就忘了最开始说的东西
• 运行 /clear 清空上下文，它又得重新理解项目背景
• 退出会话，第二天打开新会话，它什么都不记得了

这些问题的根源是同一个：AI 的记忆是临时的，没有持久化。

planning-with-files 用三个 Markdown 文件解决了这个问题——把任务计划、研究发现、操作进度全部写成文件存下来。新会话开始时，它会自动读取这些文件，瞬间"回忆"起之前的所有内容。

1. 这玩意儿到底是什么？

一句话：planning-with-files 是给 Claude Code 装上"硬盘记忆"的插件。

它的核心思路特别简单：

上下文窗口 = 内存（RAM）：快，但容量有限，重启就丢
文件系统 = 硬盘（Disk）：慢一点，但容量无限，永久保存

Claude Code 原生有个 TodoWrite 工具可以记任务，但问题是——它存在内存里。一旦上下文满了，你运行 /clear，或者开始新对话，之前的任务全没了。

planning-with-files 的做法是：把任务、进度、发现全部写成 Markdown 文件存在项目里。下次对话开始时，Claude 重新读一遍这些文件，瞬间就能"回忆"起之前的所有上下文。

这玩意儿还有个很厉害的背景——它的工作流借鉴了 Manus AI 的核心模式。Manus AI 是谁？就是那个被 Meta 以 20 亿美元收购的 AI 代理公司。他们的核心技术之一，就是这套"文件系统即记忆"的玩法。

2. 它到底解决了什么问题？

用了这么久，我总结了 AI 编程助手的四大痛点：

痛点一：健忘症

Claude 的上下文窗口是有限的。复杂任务动辄需要几十甚至上百次工具调用，很快就会把上下文撑爆。一旦满了，早期讨论过的方案、做过的决策，全都会被"挤出去"。

痛点二：目标漂移

这是个很隐蔽的问题。你让 Claude 做任务 A，做着做着它觉得需要先做 B，B 没做完又发现 C 更紧急。50 次工具调用之后，它可能已经完全忘记最初的目标是什么了。

痛点三：错误重复

第一次遇到报错，Claude 尝试修复。失败了，换个方法再试。又失败了，它可能会再试一次第一个方法——因为它不记得之前已经试过了。

痛点四：上下文膨胀

有些人（包括以前的我）喜欢把所有信息都塞进提示词里，以为这样 Claude 就能记住。结果呢？上下文爆炸，Token 烧得飞快，效果还不一定好。

planning-with-files 的解决方案就是：把重要的东西写成文件，别塞进上下文里。

3. 怎么安装？

安装特别简单，两行命令搞定。

方法一：从插件市场安装（推荐）

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

方法二：手动安装

mkdir -p .claude/plugins
git clone https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files

安装完成后，你可以用以下命令启动：

我个人习惯用 /plan，简洁好记。

4. 三文件模式：核心概念

这是整个插件的核心设计，也是它区别于其他工具的地方。

对于每个复杂任务，planning-with-files 会创建三个文件：

文件一：task_plan.md（任务计划）

这是指挥中心。里面包含：

• 任务目标
• 分阶段计划（用复选框跟踪进度）
• 当前状态
• 遇到的错误和解决方案

# task_plan.md

## 目标
重构用户认证模块，支持 OAuth2.0。

## 阶段
- [x] 阶段 1: 调研现有认证代码 ✓
- [x] 阶段 2: 设计新的认证架构 ✓
- [ ] 阶段 3: 实现 OAuth2.0 流程（当前）
- [ ] 阶段 4: 迁移现有用户
- [ ] 阶段 5: 测试和上线

## 状态
**当前在阶段 3** - 正在实现授权码流程

## 遇到的错误
- Error: redirect_uri_mismatch
  → 原因：配置文件里的回调地址和注册的不一致
  → 解决：更新 OAuth 配置

文件二：findings.md（研究发现）

这是知识库。研究过程中发现的任何有价值的信息都记在这里：

• 代码库的结构分析
• API 的使用方式
• 踩过的坑和解决方案
• 技术决策的理由

# findings.md

## 代码库结构
- `/auth` - 认证相关代码
- `/middleware` - 认证中间件
- `/models/user.js` - 用户模型

## 关键发现
1. 现有系统使用 session 认证，不支持 token
2. 用户密码用 bcrypt 加密，可以直接迁移
3. 数据库有 unique 约束在 email 字段

## 技术决策
| 决策 | 理由 |
|------|------|
| 使用 passport.js | 社区成熟，OAuth 支持完善 |
| 保留 session 兼容 | 老用户平滑迁移 |

文件三：progress.md（进度日志）

这是工作日志。记录每一步操作和结果：

• 执行了什么命令
• 改了哪些文件
• 测试结果如何

# progress.md

## 2024-02-24 会话记录

### 10:30 - 开始实现 OAuth 流程
- 创建了 `/auth/oauth.js`
- 添加了 passport-google-oauth20 依赖
- 测试：/auth/google 跳转正常

### 11:15 - 遇到 redirect_uri 错误
- 错误：redirect_uri_mismatch
- 排查：发现配置文件写的是 localhost:3000
- 修复：改成 localhost:8080
- 测试：问题解决

### 14:00 - 完成授权码流程
- 实现了完整的 OAuth2.0 授权码流程
- 测试用例通过

为什么是三个文件，不是一个？

一开始我也觉得三个文件有点啰嗦。但用了一段时间后发现，这个设计很聪明：

• task_plan 管进度，findings 管知识，progress 管日志
• 各司其职，不会乱
• 下次接手任务时，先看 task_plan 知道进度，再看 findings 知道背景

三文件模式核心概念图

图 2：三文件模式的职责与关系

5. 工作流程：它是怎么跑起来的？

整个工作流程是这样的：

第一步：创建计划（不能跳过！）

当你给 Claude 一个复杂任务时，它做的第一件事就是创建 task_plan.md。这一步是强制的，插件会检查——如果没有计划文件，它会拒绝继续。

第二步：进入工作循环

然后 Claude 就开始干活了。但和普通模式不同的是，每一步操作前，插件都会自动做一件事：

重新读取 task_plan.md

这个设计太巧妙了。它通过钩子（Hook）机制，在每次执行写文件、编辑、运行命令之前，强制 Claude 重新看一遍计划。这样就算上下文爆了，目标也永远不会丢。

第三步：2-操作规则

插件有个硬性规定：每完成 2 次查看、浏览、搜索操作，必须更新 findings.md。

操作 1: WebSearch 搜索资料 → 记录结果
操作 2: WebFetch 获取文档 → 必须更新 findings.md！
操作 3: 读取代码文件 → 记录发现
操作 4: Grep 搜索关键字 → 必须更新 findings.md！

这个规则听起来有点死板，但实际用下来发现——它强迫你（和 Claude）及时整理信息，而不是堆到最后一次性处理。

第四步：错误持久化

遇到错误时，插件会要求 Claude 把错误信息和解决方案写进 task_plan.md 的"遇到的错误"部分。

这样做的好处是：下次遇到类似问题，翻翻计划文件就知道之前是怎么解决的。

第五步：完成验证

当 Claude 觉得任务完成了想停下来时，插件会拦截这个操作，检查：

• 所有阶段都打勾了吗？
• 真的都做完了吗？

如果还有未完成的阶段，插件会提醒 Claude 继续工作。

工作流程图

图 3：5 步工作流程详解

6. 钩子机制：幕后功臣

前面提到了钩子，这里展开说一下。

planning-with-files 利用了 Claude Code 的钩子系统，在关键节点自动触发特定行为：

其中 PreToolUse 是核心。它确保了：

每次动手之前，先看计划。

这就像开车时的导航——每到一个路口，导航都会提醒你该往哪走。没有这个提醒，你很可能开着开着就跑偏了。

钩子机制架构图

图 4：钩子触发机制与作用

7. 实战场景：看看它是怎么用的

说这么多理论，来看几个实际案例。

场景一：研究任务

假设你要研究"微服务架构的优缺点"：

# task_plan.md

## 目标
整理微服务架构的优缺点分析报告。

## 阶段
- [x] 阶段 1: 创建计划 ✓
- [x] 阶段 2: 搜索和收集资源 ✓
- [ ] 阶段 3: 整理发现（当前）
- [ ] 阶段 4: 输出报告

## 状态
**当前在阶段 3** - 正在整理发现

## 收集的要点
### 优点
- 独立部署、独立扩展
- 技术栈灵活
- 故障隔离

### 缺点
- 运维复杂度高
- 分布式事务难处理
- 服务间通信开销

场景二：Bug 修复

# task_plan.md

## 目标
修复用户登录时的 TypeError。

## 阶段
- [x] 阶段 1: 复现问题 ✓
- [x] 阶段 2: 定位代码位置 ✓
- [ ] 阶段 3: 分析根本原因（当前）
- [ ] 阶段 4: 修复并测试

## 遇到的错误
- TypeError: Cannot read property 'token' of undefined
  → 定位：auth.js 第 47 行
  → 可能原因：user 对象未正确 await

## 状态
**当前在阶段 3** - 正在分析 async/await 调用链

场景三：功能开发

# task_plan.md

## 目标
给网站添加暗黑模式支持。

## 阶段
- [x] 阶段 1: 研究现有主题系统 ✓
- [x] 阶段 2: 设计实现方案 ✓
- [ ] 阶段 3: 实现切换组件（当前）

## 技术决策
| 决策 | 理由 |
|------|------|
| 使用 CSS 变量 | 轻量，浏览器支持好 |
| 存储在 localStorage | 无需后端，刷新保持 |

## 状态
**当前在阶段 3** - 切换组件开发中

可以看到，不管是哪种任务，结构都是一样的：目标、阶段、状态、决策/错误。这个一致性让它很好用——不需要为不同任务类型学不同的模板。

8. 跟其他工具的对比

市面上类似的东西还有几个，我简单对比一下。

对比一：planning-with-files vs TodoWrite

简单说：TodoWrite 是便签纸，planning-with-files 是活页本。

对比二：planning-with-files vs Manus AI

Manus AI 是被 Meta 收购的那家公司，他们的核心工作流就是这套"文件系统即记忆"的模式。

planning-with-files 可以理解为：把 Manus 的核心思路，在 Claude Code 生态里实现了一遍。

区别在于：

• Manus AI 是完整的产品（SaaS）
• planning-with-files 是开源插件，免费使用

对比三：planning-with-files vs oh-my-claudecode

oh-my-claudecode 是另一个 Claude Code 插件，主打多代理协作。

两者的定位不同：

• oh-my-claudecode 关注的是"多人协作"
• planning-with-files 关注的是"单人的持久记忆"

如果你是一个人用 Claude Code 干复杂活，planning-with-files 更合适。如果是团队协作场景，可以考虑 oh-my-claudecode。

工具对比图

图 5：与 TodoWrite、Manus AI、oh-my-claudecode 的对比

9. 最佳实践：我总结的几条经验

用了一个月，我总结了这些经验：

经验一：预估任务复杂度

不是所有任务都需要用这个插件。我的判断标准是：

预计工具调用 > 5 次 → 用
预计工具调用 < 5 次 → 不用

简单问题（比如"这个正则怎么写"）直接问就行，别过度工程化。

经验二：阶段粒度要适中

task_plan 里的阶段别切得太细，也别太粗。我一般按"一个阶段 10-30 分钟工作量"来划分。

太细的阶段会导致计划文件很长，太粗又失去了追踪意义。

经验三：及时更新 findings

2-操作规则是强制的，但实际上我建议更激进一点：

每有重要发现就更新。

不要等操作两次再整理，临时记忆不可靠。

经验四：把 task_plan 当文档用

task_plan.md 不只是给 Claude 看的，它本身就是一个很好的项目文档。

项目做完之后，这个文件可以：

• 给同事看，说明你做了什么
• 给未来的自己看，回忆当时的决策
• 作为团队知识库的一部分

经验五：定期清理旧文件

每个任务都会创建三个文件，时间长了项目根目录会变得很乱。

我的做法是：

• 任务完成后，把三个文件移到 .archive/ 目录
• 或者干脆删掉（反正 Git 里有历史）

10. 注意事项和常见坑

说几个我踩过的坑：

坑一：忘记运行 /plan

安装完插件后，它不会自动启用。每次处理复杂任务前，记得先运行 /plan 命令。

我有好几次干到一半才发现没用插件，只能重新开始。

坑二：简单任务也用它

杀鸡焉用牛刀。对于一个"改个变量名"这种 2 分钟就能搞定的事，没必要搞三个文件出来。

坑三：阶段划分太理想化

计划赶不上变化是常态。task_plan 不是死的，随时可以调整。发现某个阶段比预期复杂？拆分它。发现某个阶段不需要了？删掉它。

坑四：忽略错误记录

遇到错误随手解决了就完事，不往 task_plan 里记。结果下次遇到同样问题，又要重新排查。

坑五：钩子版本要求

完整的钩子功能需要 Claude Code v2.1.0+。如果你用的是老版本，有些自动提醒可能不工作。

11. 优缺点总结

客观评价一下：

优点：

• ✅ 持久化存储：跨会话保留，再也不怕 /clear
• ✅ 防止目标漂移：钩子机制强制重读计划
• ✅ 错误追踪：记录失败，避免重复踩坑
• ✅ 多平台支持：不只 Claude Code，还支持 Cursor、Copilot 等 15+ 平台
• ✅ 自动恢复：上下文清空后能自动恢复会话（v2.2.0+）
• ✅ 文档即代码：计划文件本身是好文档

缺点：

• ⚠️ 学习成本：三文件模式需要适应
• ⚠️ 文件膨胀：每个任务创建三个文件，多了会乱
• ⚠️ 版本依赖：完整功能需要新版 Claude Code
• ⚠️ 过度工程风险：简单任务用它纯属浪费时间

12. 谁适合用这个？

适用人群图

图 6：适用人群推荐等级

强烈推荐（5 星）：

• 复杂项目开发者：经常处理多步骤任务
• 研究人员：需要收集整理大量信息
• 重构爱好者：大型重构任务需要追踪进度

推荐（4 星）：

• 团队协作：计划文件可以作为沟通文档
• 个人知识管理爱好者：喜欢把一切文档化

可选（3 星）：

• 新手开发者：有一定学习成本，但值得投入
• 偶尔使用者：只是偶尔用 Claude Code 干点小事

不推荐（2 星）：

• 简单任务用户：杀鸡用牛刀
• 追求极速的人：创建和更新文件需要时间

13. 总结

说到底，planning-with-files 解决的是一个很本质的问题：

AI 的记忆是短暂的，但我们的项目是长期的。

它用最朴素的方式——写文件——把 AI 的"工作记忆"从内存搬到了硬盘。这个思路简单，但有效。

如果你经常用 Claude Code 处理复杂任务，经常遇到 Claude 健忘、目标跑偏的问题，那这个插件值得一试。

安装只需要两行命令，试用成本很低。但一旦用习惯了，你会发现：

再也不想回到那个 AI 动不动就失忆的年代了。

相关资源

GitHub 仓库：https://github.com/OthmanAdi/planning-with-files

安装指南：https://github.com/OthmanAdi/planning-with-files/blob/master/docs/installation.md

快速开始：https://github.com/OthmanAdi/planning-with-files/blob/master/docs/quickstart.md

工作流程：https://github.com/OthmanAdi/planning-with-files/blob/master/docs/workflow.md

故障排除：https://github.com/OthmanAdi/planning-with-files/blob/master/docs/troubleshooting.md

Manus 收购新闻：https://techcrunch.com/2025/12/29/meta-just-bought-manus-an-ai-startup-everyone-has-been-talking-about/

Manus 上下文工程博客：https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus

好啦，谢谢你观看我的文章，如果喜欢可以点赞转发给需要的朋友，我们下一期再见！敬请期待！