Planning-with-Files：让 AI 编码代理 /clear 之后依然记得自己要干什么-平芜编程栈

Planning-with-Files：让 AI 编码代理 /clear 之后依然记得自己要干什么

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files

跑长任务时最崩溃的场景大概是这个：上下文撑爆了，你敲下/clear，代理一脸茫然地问你"我们刚才在干什么"。它重新读仓库、要你复述目标，甚至把做完的事再做一遍。planning-with-files 解决的就是这个问题：把计划写成磁盘上的 markdown 文件，让它在上下文消亡之后依然能捡起来继续干。

本质：把代理的记忆从内存挪到硬盘 🧠

说白了，它把上下文窗口当成 RAM，把文件系统当成磁盘。

RAM 的特点是快但会断电清零，磁盘慢但东西不会丢。代理的 TodoWrite 列表、它"记着"的目标和结论，全都活在 RAM 里，一次压缩或一次/clear就全没了。planning-with-files 做的事只有一件：凡是你觉得重要的状态，必须落到磁盘上。

落盘的只有三个文件：task_plan.md记阶段和进度，findings.md记调研和决策，progress.md记会话日志和测试结果。三个文件加一个约定：上下文随时会死，磁盘不会。

原理：钩子替你"翻笔记"

你可能会问：让代理"记得写文件"这种事，靠提示词提醒不就行了？答案是靠不住。模型调用 50 次工具之后，早就忘了最初的目标。所以这个项目不靠自觉，靠钩子。

Claude Code 上它注册了 5 个生命周期钩子（见 skills/planning-with-files/SKILL.md 的 frontmatter）。最关键的一个是每轮开始时的注入钩子：它从磁盘读task_plan.md，把目标、当前阶段、下一步动作重新塞进上下文。

# 每轮开始，钩子从磁盘读计划并注入上下文，伪代码： read task_plan.md -> 包上 BEGIN/END PLAN DATA 标记 -> 注入当前轮

换个角度看，目标能一直待在模型的注意力窗口里，不是因为它"记得看"，而是因为有机制每轮把目标放到它眼前。这就是 Manus 那套"把文件系统当工作内存"的套路，被打包成了一个可安装的 skill。

核心能力

断线之后接着跑

会话在第三小时死了，新会话进来不用你复述背景：session-catchup 脚本会去读上一个会话的记录（Claude Code 在~/.claude/projects/，Codex 在~/.codex/sessions/），对照计划文件最后修改的时间点，把中间漏掉的事补出来。项目内部的恢复基准测试里，有文件的会话平均 5.0 轮就重新回到正轨，裸代理要 13.3 轮。

长任务里防跑偏

两个可选模式都是为无人值守的长任务准备的。--autonomous砍掉每次工具调用后的计划复读，只在每轮开头注入一次，适合注意力长的模型；--gated在停止钩子上加了完成门禁——只有计划文件里确实还有in_progress阶段、且会话确实在往前推进时，才允许阻止停止。它判断的是磁盘上的计划产物，不是对话记录，代理没法"嘴说做完了"就溜走；卡死也有上限，默认连续拦 20 次就放行，不会把会话永远困住。

多会话互不串台

同一个仓库同时跑两个任务，两个会话各写各的.planning/日期-slug/目录，通过.active_plan指针选中当前计划。好处是并行不互相覆盖，代价是你要自己管哪个 slug 对应哪个任务；后来加的写保护会在"已完成的阶段数变少了"这种反常信号上提醒你，说明另一个会话把活儿冲掉了。

防篡改的计划锁定

/plan-attest用 SHA-256 给task_plan.md上锁，钩子每次触发都重新哈希比对，发现被改过就拒绝注入。这条防线的意义在于：无人的长任务循环里，任何一次注入都会被每个 tick 放大，锁住计划就是掐断放大链。

选型与取舍

适合谁：任务要 3 步以上、要调用 5 次以上工具、或者你打算让代理挂着跑几小时、随时可能/clear和压缩的场景。这类工作里，结构化的开销是值得的。

不适合谁：几分钟就能干完的活。项目自己的说法很诚实——5 次工具调用以内能搞定的任务，别开这个 skill，结构只有在工作长到会丢东西时才回本。

代价是真实存在的，而且测过：正式评测里，带 skill 的运行平均比不带多花约 68% 的 token、多花约 17% 的时间（docs/evals.md）。换来的是 30 条客观断言 96.7% 通过（不带是 6.7%），盲测 A/B 三场全胜。这是拿速度换结构、换可恢复性，你得先想清楚哪个对你更重要。

和别的方案比：代理记忆工具（向量库、知识图谱）解决的是"跨会话回忆事实"，这里解决的是"当前任务执行到第几步"，两者互补不冲突；Claude Code 原生的 plan mode 是动手前定方案，这个是执行期间持续维持状态，衔接方式是让代理把批准的方案写进task_plan.md再开工。

快速上手

Claude Code 用户走插件路线，一次带上 skill、钩子和斜杠命令：

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

其他 60 多种代理走 Agent Skills 标准，一行装完（详见 docs/installation.md）：

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

装完打/plan建三个文件开干。注意 skill 路线的安装有时会因为项目信任没接受等原因"看起来装了、钩子其实没注册"，跑一次/plan-doctor或sh scripts/plan-doctor.sh验证一下，钩子才是这个项目的立身之本。

边界与局限

几个需要自己心里有数的地方：

计划文件默认被 gitignore，也不自动归档。任务做完它们就当工作内存丢掉了，值得留下的东西得你自己提炼进代码或文档，项目没有替你做这步。
安全上，2026 年 3 月的审计发现过注入放大路径：外部内容若混进task_plan.md，会被钩子在每次工具调用时重新注入。v2.21.0 起移除了 WebFetch/WebSearch 权限并划了边界——网页内容只准进findings.md。但如果你用的是老模式且没开 attestation，防注入基本只靠分隔符，别指望它。
触发是概率性的。官方数据里 skill 的自然触发率在 60%-67% 之间，想让它在每个复杂任务上必开，得在项目规则文件里手动加一句强制指令。
评测数字有范围：96.7% 衡量的是"三文件模式的执行保真度"，不是长程自主运行下的目标漂移，v3 新特性也不在那个数里。