planning-with-files 和 Claude Code 计划模式怎么配合，长任务把计划写到磁盘

让 Claude Code 做一个要几十步的任务，做到一半执行了 /clear，或者上下文被自动压缩，它就像换了个人：之前定的阶段、查到的结论、试过的错误方向，全都得重新交代。计划模式能在开工前把方案定下来，却解决不了“执行过程中记忆丢了”的问题。

planning-with-files 是一个开源的 Skill（作者 OthmanAdi，MIT 协议），做法很朴素：把计划、发现和进度写成三个 Markdown 文件放在项目里，再用钩子在每一轮对话开始时把关键内容重新注入。官方 README 的一句话是：Agent 的上下文窗口会消失，但计划不会。

这篇按官方仓库当前的 README 和常见问题整理：三个文件各放什么、钩子怎么保证它真的生效、在 Claude Code 里怎么装、和计划模式怎么分工，以及官方数据的适用范围。

三个文件各放什么

这个 Skill 在项目里维护三个纯 Markdown 文件：

下图左边是没有这个 Skill 时的样子：Agent 反复重复、遗忘、重做；右边是有三个文件后，每个阶段都有明确的记录和状态。

官方用一个类比解释：上下文窗口像内存，容易丢、容量有限；文件系统像硬盘，持久；重要的东西要写到硬盘上。

并行任务不会互相覆盖：每个任务可以放在 .planning/日期-名称/ 这样的独立目录里，同样是这三个文件，通过 .active_plan 指定当前使用哪一个（v2.36.0 起支持）。这些文件默认会被 gitignore，只是“工作记忆”，不是要提交的交付物。

为什么不是一条提示词，而是一套钩子

“把计划写进文件”这件事，靠提示词让模型自觉去做并不可靠。官方的思路是用生命周期钩子把它变成机械流程。Claude Code 插件路线会注册 6 个钩子：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact 和 Stop。

上图是一轮工作的循环：调用工具之前读一遍 task_plan.md 刷新目标（PreToolUse），然后工作，工具执行后更新 progress.md 并标记状态（PostToolUse），最后检查所有阶段是否完成（Stop）。需要说明的是，Stop 检查只在可选的“门控模式”下才会拦截提前收尾。

对应到几类具体的丢失场景，官方给出的处理方式是：

官方还给出了单次钩子的耗时：自 v3.6.0 优化后，一次钩子触发约 289 毫秒。

在 Claude Code 里安装

Claude Code 推荐走插件路线，它会同时带上 Skill、钩子和斜杠命令：

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

其他 Agent，或者想一行命令装好，可以用 Agent Skills 通用安装器：

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

这里有一个官方明确提醒过的坑：通过 npx skills add 装的 Skill，有可能悄悄变成“没有钩子”的状态（比如项目信任没被接受，或者项目级安装时前置钩子没有注册）。而钩子正是它区别于普通提示词的核心。所以如果你依赖钩子，请走插件路线，装完用 /plan-doctor 自检，它会逐项给出通过、警告或失败，检查路径解析、注入、校验、安装方式和单次触发耗时。

装好后，输入 /plan 开始，或者直接让 Agent“规划一下这个任务”，Skill 也会在多步骤任务里自行触发。

常用命令

下面是 Claude Code 插件路线提供的主要命令：

它和计划模式、记忆工具是什么关系

官方 FAQ 对这两个问题讲得很清楚。

和 Claude Code 计划模式：两者是前后两个阶段，不是二选一。计划模式负责在动手前设计并批准方案；planning-with-files 负责在执行期间把阶段状态、发现、错误和进度持久化到磁盘，并每轮重新注入。衔接只需要一步：接受计划模式的方案后，让 Agent 把它写进 task_plan.md 并拆成阶段（或者直接输入 /plan 让 Skill 据此建文件），然后切回普通模式去执行。

和记忆工具：记忆类工具（向量库、知识图谱）帮 Agent 回忆过去会话里的事实；planning-with-files 管理的是当前任务的执行状态：阶段、状态、依赖和完成检查。解决的是计划的连续性，不是检索，两者可以互补。如果你想给 Claude Code 加跨会话的记忆，可以看claude-mem 安装与使用教程。

进阶：自主模式和门控模式

任务时间很长、不想一直盯着时，官方 v3 版本提供了两种可选模式（不加模式标记时，行为与旧版一致）：

• 自主模式（/pwf --autonomous）：去掉每次工具调用前的计划复述，保留每轮开头的注入，并默认打开计划校验；
• 门控模式（--gated）：增加 Stop 完成门，只有当“还有进行中的阶段”等条件同时满足时才拦截；默认最多连续拦截 20 次（可用 PWF_GATE_CAP 调整），所以未完成的计划本身不会把会话困死。

对多 Agent 并行，官方的约定是：一个编排者负责 task_plan.md，每个执行者追加到自己的日志文件，并用 PLAN_ID 把各自终端固定到某个计划上。

官方数据怎么读

README 给了两组数据，都需要带着范围看：

• 文件结构遵循度：在 Claude Sonnet 4.6 上的评测里，有这个 Skill 时 30 条断言通过 29 条（96.7%），没有时通过 2 条（6.7%）。官方说明这个数字衡量的是“是否创建并维护了三文件结构”，不是长时间自主运行中的目标漂移；
• 清空上下文后的恢复：项目自己的内部基准里，有计划文件时平均 5.0 轮恢复工作，普通 Agent 需要 13.3 轮；官方明确称这是作者自测，不是独立对比。

所以更稳妥的理解是：它能显著降低“清空之后重新摸清状况”的成本，至于对你自己项目的收益，用一个真实的长任务试一次最直接。

使用时的几条规则和注意事项

README 的四条核心规则很适合直接写进团队约定：

1. 开工前先建 task_plan.md；
2. 每看完两次页面或搜索结果，就把发现存一次；
3. 所有错误都要记录，避免重复犯；
4. 不重复失败的做法，记录尝试并改变方案。

另外，计划文件是“工作记忆”，任务完成后不会自动归档，下一个任务会覆盖根目录里的计划。值得长期保留的结论，要自己提升到代码、提交信息或文档里。

和 AIGoCode 一起用

这个 Skill 运行在 Claude Code 和 Codex 等工具内部，不改变你访问模型的方式。如果你通过 AIGoCode 使用 Claude Code，可以先用接入 AIGoCode 前，Claude Code 和 Codex CLI 先检查这四项确认基础配置，再装这个 Skill。

长任务另一个常见问题是会话越来越长。想了解什么时候该压缩、什么时候该分叉或回退，可以参考Claude Code 压缩、分叉与回退怎么选，5 个场景的常用命令对比；多步任务容易跳步骤，则可以看Agent 跑多步任务总跳步骤？用确定性控制流把流程交给代码。

总结

planning-with-files 的核心是把“计划”从会丢的上下文里搬到磁盘，再用钩子保证每轮都读回来。上手的最短路径：走插件路线安装，输入 /plan 建好三个文件，用 /plan-doctor 确认钩子在工作；已经用计划模式定好方案的话，把方案写进 task_plan.md 再开始执行。

参考链接

• planning-with-files 官方仓库：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/evals.md
• 长任务说明：https://github.com/OthmanAdi/planning-with-files/blob/master/docs/long-running-agent-tasks.md