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-filesplanning-with-files其他 60 多种代理走 Agent Skills 标准一行装完详见 docs/installation.mdnpx 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 新特性也不在那个数里。回到开头那个场景所以回到开头那个问题/clear之后代理失忆。现在它只需要重新读三个文件平均 5 轮就接上上下文而你什么都不用复述。planning-with-files 不是什么复杂系统就是三个 markdown 文件加几个钩子但它把代理记性差从模型问题变成了工程问题——上下文会死计划不会。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考