你一定遇到过这个场景
你让 Claude Code 帮你重构一个模块。它列了个计划，开始改代码，改到一半——上下文窗口满了。你跑了个 /clear，或者它自己 compact 了。然后你再问它："刚才改到哪了？"它一脸茫然。
或者更常见的：你让它做一个 5 步以上的任务，它做到第 3 步就开始跑偏，把第 1 步的目标忘了。你得不断提醒它："别忘了，我们的目标是……"
这不是模型笨。这是所有 Coding Agent 的结构性缺陷：上下文窗口就是 RAM，断电就没了。
planning-with-files 就是来解决这个问题的。它不是又一个 AI 编程工具，而是一个让 Agent 把计划写到磁盘上的技能。概念简单到你会觉得"这也值得 24K Star？"——但用过之后你会发现，这确实是 Agent 长任务执行的基础设施级缺失。
它到底在解决什么问题
先搞清楚一个区别。市面上有一类工具叫"Agent 记忆"——比如 Mem0、Zep，它们解决的是"Agent 怎么记住上次跟你聊了什么"。这类工具的本质是跨会话的知识检索。
planning-with-files 解决的不是记忆问题，而是执行状态管理问题。具体来说：
- 目标漂移 — Agent 做了 50 次工具调用后，原始目标被挤出了注意力窗口
- 上下文丢失 — /clear、compact、崩溃后，之前的计划和进度全没了
- 重复犯错 — 上次试过的方法不行，但 Agent 不记得，又试了一遍
- 完成度不可知 — 你不知道 Agent 做到哪了、还差什么
Claude Code 自带的 TodoWrite 工具也试图解决这个问题，但它有个致命缺陷：存在上下文里，不清就满，清了就没了。本质上还是 RAM。
三文件模式：把 RAM 搬到磁盘
planning-with-files 的核心是一个极其简单的模式：每个复杂任务创建三个文件。
task_plan.md → 任务分阶段计划 + 每个阶段的状态
findings.md → 调研发现、技术选型、踩坑记录
progress.md → 会话日志、测试结果、操作记录就这三个文件，放在你的项目根目录。Agent 每次做决策前，先读 task_plan.md；每次有新发现，写进 findings.md；每次做完一步，更新 progress.md。
关键在于自动化。它不是靠你提醒 Agent "记得更新计划"，而是通过 Claude Code 的 Hook 机制自动注入：
- UserPromptSubmit — 你每次发消息，自动把 task_plan.md 的内容注入上下文
- PreToolUse — Agent 每次要调用工具前，重新读一遍计划
- PostToolUse — Agent 写完文件后，提醒它更新进度
- Stop — Agent 要停下的时候，检查计划是否全部完成
- PreCompact — compact 之前，先把计划持久化
这五个 Hook 形成一个闭环：计划始终在磁盘上，每次交互自动从磁盘读回上下文。不管你怎么 /clear、怎么 compact、甚至重启会话，计划都不会丢。
跟竞品到底有什么不同
这个赛道上有几类方案，但解决的问题层次不同：
Claude Code 的 TodoWrite 是最直接的竞品。它也在做任务跟踪，但 TodoWrite 存在上下文里——你 /clear 了就没了，长任务做到一半 compact 了也会丢。planning-with-files 把同样的功能搬到了磁盘上，代价是多了三个文件。
Agent 记忆工具（Mem0、Zep） 解决的是"跨会话记住用户偏好和历史知识"。比如你上次说过"用 TypeScript strict mode"，下次它还记得。但记忆工具不管"当前任务做到哪了"。planning-with-files 管的是当下正在执行的任务的状态，两者互补。
Superpowers 框架（本工坊写过）给 Agent 加了一套工程纪律——TDD、代码审查、提交规范。它解决的是"Agent 怎么写代码"，planning-with-files 解决的是"Agent 怎么记住自己要做什么"。一个管方法论，一个管执行状态。
Claude Code 自带的 session 机制 能在会话间保持一些上下文，但它不提供结构化的计划管理。你没法让 Agent "检查一下之前的计划还差几步没完成"。
所以 planning-with-files 的定位很清晰：它不是替代任何工具，而是给所有工具补上"计划持久化"这一层。你可以同时用 Superpowers 管工程纪律、用 Mem0 管长期记忆、用 planning-with-files 管当前任务的执行状态。
一个真实场景：我拿它重构了一个 API 模块
我有一个 Node.js + Express 的项目，需要把一个 500 行的路由文件拆成独立的 controller/service/route 模块。这个任务大概涉及 15 个文件的创建和修改。
先不用 planning-with-files 跑了一遍。Claude Code 开始拆文件，拆到第 8 个文件的时候，上下文差不多满了。它开始出现明显的目标漂移——把一个 service 的方法名写错了，把另一个 controller 的依赖关系搞反了。我不得不手动纠正两次，然后 /clear 重新开始，告诉它"你刚才做到哪了"。
装上 planning-with-files 之后再跑同样的任务。安装就一行：
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g这次 Agent 自动创建了三个文件。task_plan.md 里列了 5 个阶段：分析现有结构 → 创建 service 层 → 创建 controller 层 → 更新路由 → 验证和清理。每个阶段有 checkbox。
做到第 3 阶段的时候，上下文又满了。我 /clear 了一下。这次不一样了——Agent 自动读回 task_plan.md，看到前两个阶段已经打勾，第 3 阶段进行中，然后继续干活。它甚至还读了 progress.md，知道之前有个 service 的方法名改过了。
最后的结果？一次 /clear 之后，任务无缝继续，没有重复工作，没有目标漂移。整个重构花了大概 25 分钟，比我之前手动盯 + 纠错的方式快了一倍。
但也有不爽的地方。progress.md 的更新有时候太啰嗦——Agent 每写一个文件都要往 progress.md 追加一段日志，搞得文件越来越长。而且它更新 task_plan.md 的时候，有时候会把整个文件重写一遍而不是只改 checkbox，这就触发了额外的 token 消耗。
v3 的自治模式：给长任务加个"闸门"
v3.0.0 加了一个重要的新功能：completion gate（完成闸门）。
之前的问题是：Agent 觉得自己做完了就停了，不管计划是不是真的全部完成。Stop Hook 虽然会检查，但只是提醒，Agent 可以忽略。
gated mode 下，Stop Hook 会阻止 Agent 停下，除非满足 5 个条件：处于 gated 模式、有进行中的阶段、stop hook 没被激活、阻断次数没超限、自上次阻断后有新进展。
autonomous mode 更激进——它把每次工具调用都重新注入计划的开销去掉了，只在会话开始和阶段切换时注入。对强模型（Sonnet 4、Opus 4）来说，这是个合理的取舍：省 token，靠模型自身的能力保持目标。
还有个 hash attestation 机制：你可以用 SHA-256 锁定 task_plan.md，之后如果 Agent 试图篡改计划内容，Hook 会拒绝注入。这对需要严格计划执行的场景（比如 CI/CD 流水线里的 Agent）很有用。
适配 60+ 个 Agent 的野心
planning-with-files 最让我意外的一点是它的适配范围。它不只是 Claude Code 的插件——通过 SKILL.md 开放标准，它能跑在 Cursor、Codex、Gemini CLI、OpenCode、Kiro、Hermes Agent、GitHub Copilot、Continue 等 60+ 个平台上。
每个平台的集成深度不一样：
- Claude Code — 最完整，5 个 Hook 全支持，有 plugin 和 skill 两种安装方式
- Cursor — 支持 hooks.json，Skills 体系
- Codex — 支持 hooks.json，有 PreCompact 适配
- Gemini CLI — 支持 hooks，5 个生命周期事件
- 其他 — 基本是 skill-only 模式，没有 Hook 自动注入，需要 Agent 自己遵守规则
说实话，没有 Hook 的平台体验差很多。skill-only 模式下，Agent 得"自觉"去读计划文件、更新进度，但实际用下来，很多模型做不到——它会直接忽略 SKILL.md 里的指令，按照自己的节奏干活。所以如果你用的是不支持 Hook 的平台，这个工具的价值会打折扣。
我的真实体验：好用，但有学习曲线
用了两周，总结一下：
好的部分：
- 长任务的目标保持确实大幅改善。之前 50+ 工具调用就开始跑偏，现在基本能坚持到最后
- session recovery 真的能用。/clear 之后 Agent 自动恢复上下文，不是"假装记得"，是真的从文件里读回来的
- 三个文件都在项目目录里，git 可追踪，review 的时候能看到 Agent 的"思考过程"
不好的部分：
- 简单任务反而变慢 — 三步以内的任务，创建三个文件 + Hook 注入的开销比直接做还慢。它自己文档里也说了"简单问题、单文件编辑、快速查询"不需要用
- progress.md 会膨胀 — 长任务跑下来，progress.md 可能变成几百行的日志。Agent 每次都读一遍，反而浪费 token
- Hook 注入有延迟 — 每次工具调用前都要跑一遍 inject-plan.sh，体感上比不用的时候慢一点
- 不支持 Hook 的平台上体验打折 — 在 Continue、Pi Agent 这些平台上，基本靠 Agent 自觉，效果不稳定
- v3 的 gated mode 有时候太"执着" — 有一次 Agent 其实已经做完了，但因为 progress.md 里有个阶段的 checkbox 没更新，它被 Stop Hook 反复拦住，多跑了 3 轮才"正式"完成
什么场景值得用，什么场景别用
值得用：
- 需要 5 步以上的复杂任务（重构、多文件迁移、大型 feature 开发）
- 需要中途暂停/恢复的长时间任务
- 多个 Agent 协作的场景（v2.36.0 支持并行计划隔离，每个 Agent 有自己的 .planning/ 目录）
- CI/CD 里跑 Agent 的场景（gated mode + hash attestation 保证计划不被篡改）
别用：
- 改个 bug、加个参数、改个配置——这些任务不需要计划
- 你用的 Agent 不支持 Hook 机制——skill-only 模式效果不稳定
- 你对项目目录整洁度有洁癖——它会在根目录创建 task_plan.md、findings.md、progress.md
跟 Manus 的关系
README 第一句话就写"Work like Manus"。2025 年底 Meta 20 亿美元收购了 Manus，Manus 的核心技术就是"把 Markdown 文件当磁盘上的工作记忆"。planning-with-files 把这个模式提炼成了一个通用的 Agent 技能，让任何 Coding Agent 都能用上这套方法论。
这不完全是营销。Manus 的技术博客确实说过类似的话："Markdown 是我磁盘上的工作记忆。因为我是迭代处理信息的，活跃上下文有上限，所以 Markdown 文件就是我的草稿纸、进度检查点、最终交付物的构建块。"
planning-with-files 做的事情就是把 Manus 内部的这个机制，变成了一个可以安装到任何 Agent 上的标准化技能。
总结
planning-with-files 不是那种会让你"哇"的工具。它做的事情极其简单——让 Agent 把计划写到文件里。但正是这种简单，解决了 Coding Agent 长任务执行中最根本的问题：上下文是易失的，文件是持久的。
24K Star 不是白来的。它的社区生态做得很好——60+ 平台适配、5 种语言版本、活跃的 fork 和扩展。这说明"Agent 需要持久化计划"这件事是真实的刚需。
如果你主要用 Claude Code 或 Cursor，经常做需要 30 分钟以上的复杂任务，装上试试。一行命令的事。
如果你只是偶尔让 Agent 改改 bug，不用折腾。