planning-with-files：让 AI 编码代理“过目不忘“的三文件持久化规划指南

planning-with-files让 AI 编码代理过目不忘的三文件持久化规划指南【免费下载链接】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-filesplanning-with-files是一个面向 AI 编码代理的技能包它要求代理把任务拆成task_plan.md、findings.md、progress.md三个 Markdown 文件写在磁盘上再靠钩子在每一轮对话前把计划重新读回上下文。这样一来哪怕你执行/clear、会话被压缩compaction甚至进程崩溃代理也能从磁盘恢复目标、阶段和已完成的工作。它适合所有跑多步骤长任务、被代理失忆折磨过的 Claude Code、Codex、Cursor 等 60 多个代理的用户核心关键词是planning-with-files、AI 代理持久化规划、上下文丢失恢复。一、代理为什么会越做越偏用过 AI 编码代理做长任务的人大概都撞过这几堵墙易失记忆代理内部的待办清单如 TodoWrite只活在上下文窗口里窗口一清清单就没了目标漂移工具调用超过 50 次后最初的目标被后面的细节挤出了模型的注意力错误反复出现失败没有被记录同一个坑会再摔一次上下文塞满所有信息都堆在窗口里而不是存下来项目作者给这个现象起了个形象的类比上下文窗口是 RAM文件系统是硬盘。RAM 快但断电即失硬盘慢但永存。大多数代理的问题在于它们把所有重要状态都放在 RAM 里而 RAM 随时会被清空。这个项目的思路很直接重要的东西一律落盘。二、三文件模式把笔记本和档案柜分开三个文件各管一摊方案的核心不是某个脚本而是一种纪律。每个复杂任务开始时先创建三个文件task_plan.md → 阶段划分 勾选进度 决策记录是 /clear 后的续跑点 findings.md → 调研结论、踩坑记录随时追加 progress.md → 会话日志 测试结果用记忆系统来打比方task_plan.md是行动清单findings.md是笔记本progress.md是档案柜。三份文件都是纯 Markdown直接放在项目根目录默认被 gitignore不会污染仓库。什么时候触发、什么时候写入项目把这套纪律写成了代理必须遵守的规则场景动作任务需要 3 步以上或 5 次以上工具调用先建三文件再动手学到新东西立刻追加进findings.md做完一个动作在progress.md记一笔一个阶段完成在task_plan.md勾选并刷新Next Step上下文被清掉用 session catchup 重读三文件恢复现场其中还有一条很实用的2-Action 规则每做 2 次查看/浏览/搜索操作就把关键发现写进文本文件——因为图片和网页内容在多模态窗口里最容易丢。三、钩子机制让落盘成为反射而不是自觉光靠规则代理在长对话里照样会偷懒。真正让这套模式立住的是一组生命周期钩子。五条生命周期钩子以 Claude Code 为例技能注册了 5 个钩子Codex 是 7 个Pi 是 8 个UserPromptSubmit每轮对话开始时把磁盘上的task_plan.md以BEGIN PLAN DATA数据块的形式重新注入上下文PreToolUse工具调用前再次确认计划状态PostToolUse写文件后提醒更新 progress.mdPreCompact上下文压缩前提醒把进度冲刷到磁盘Stop会话想结束时检查计划是否真的完成门控模式下这套机制的本质是注意力刷新不指望模型记住 50 轮前的目标而是每轮都把目标重新摆到它面前。官方 FAQ 里管这叫对抗context rot上下文腐化——目标随窗口变满而被挤出注意力窗口的漂移现象。/clear 之后如何续跑最典型的恢复流程是 session catchup查当前 IDE 的会话存储Claude Code 在~/.claude/projects/Codex 在~/.codex/sessions/找到计划文件最后一次被更新的时间点提取那之后发生的对话也就是可能丢失的上下文输出一份补位报告让新会话先同步再干活效果上有项目自己的基准数据会话在半程被强制掐断后带计划文件的新会话平均5.0 轮重新找到状态裸代理要13.3 轮且所有测试运行最终都全绿——差别在重新定向的成本不在正确性。详见 docs/evals.md。四、10 分钟上手三种安装路线挑一条路线装路线命令附带内容Claude Code 插件/plugin marketplace add OthmanAdi/planning-with-files然后/plugin install planning-with-filesplanning-with-files技能 斜杠命令 全部钩子其他 60 代理npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g技能 脚本 模板npmnpm install planning-with-files同上但不自动注册钩子插件路线最完整。走技能路线安装的用户要注意钩子可能静默缺席项目信任未接受、frontmatter 钩子未注册而钩子恰恰是这个技能的灵魂。装完后跑一次/plan-doctor做自检能逐项检查解析、注入、认证和延迟是否正常。日常怎么用装好后触发方式很简单——输入/plan插件路线或者直接对代理说planning with files this task。几个高频命令/plan创建三个计划文件并开启会话/status一眼看清当前阶段和总进度/plan-attest给task_plan.md上锁详见下节/plan-doctor安装健康自检sh scripts/init-session.sh --autonomous 任务名以自主模式初始化更多命令和各平台差异见 docs/installation.md 与 docs/quickstart.md。五、权衡与坑为结构付出什么会踩什么结构化是有价格的官方评估Anthropic skill-creator 框架10 个并行子代理、30 条客观断言、3 组盲测 A/B的结果指标带技能不带技能30 条断言通过率96.7%29/306.7%2/30三文件模式遵守率5/50/5盲测 A/B 胜率3/30/3平均评分10.0/106.8/10但同一份数据也记录了代价平均 token 消耗多约 68%耗时多约 17%。这不是缺陷而是设计——多出来的开销换的是文件结构、阶段纪律和错误记录。想要省掉这部分开销v3 提供了自主模式--autonomous砍掉每次工具调用前的计划复述只保留每轮开头的注入适合注意力保持能力强的模型。两个容易踩的静默坑并行任务共用一个根目录两个会话同时读写同一份task_plan.md后写的会覆盖先写的。v2.36.0 的解法是 slug 模式——每个任务独立一个目录.planning/2026-01-10-backend-refactor/task_plan.md .planning/2026-01-10-incident-investigation/task_plan.md再用PLAN_ID环境变量把终端绑定到具体计划。v3.10.0 还加了并行写守卫正常工作时勾选数只增不减一旦检测到减少就会打印告警行。一次性会话被劫持CI 里的一次性任务如果和别人的未完成计划共享工作目录钩子会照单全读。设PLANNING_DISABLED1即可让本次调用完全跳过计划读取。完整的长任务调参门控上限、PWF_INJECTsmart智能注入等见 docs/long-running-agent-tasks.md。六、安全设计计划文件如何防外部干扰这个技能有个天然的攻击面PreToolUse 钩子会把task_plan.md反复注入上下文如果外部内容能混进这个文件就会被每轮调用放大。2026 年 3 月的主动安全审计确认了这条提示注入放大路径v2.21.0 的加固动作是从allowed-tools中移除WebFetch和WebSearch切断外部内容进入计划文件的通道规定外部内容只能写进findings.md不碰task_plan.md的自动注入循环对来源为外部的指令性内容要求用户确认SHA-256 认证防篡改的最后一道闸/plan-attest会对task_plan.md计算 SHA-256 并写入认证文件。之后每次钩子要注入计划前都会先比对哈希——文件被人或另一个代理动过就拒绝注入。写入路径采用临时文件 原子改名保证读者永远不会看到写了一半的认证文件在 Linux/WSL 上还有flock协作锁辅助。细节见 docs/attestation-locking.md。七、适合谁、怎么选模式这个技能面向的是执行中的状态管理不是跨会话的事实记忆。向量库、知识图谱那类 memory 工具解决的是回忆过去planning-with-files 解决的是现在这件事进行到哪一步了两者互补而非替代。两种运行模式的取舍门控模式--gatedStop 钩子在五个条件同时成立时才拦截会话结束处于门控模式、存在进行中的阶段、钩子激活、阻止次数未超PWF_GATE_CAP默认 20、自上次阻止后账本有新进展。适合需要确定性完成保证的无人值守长任务。自主模式--autonomous降低重注入频率、默认开启认证适合强模型的长时间运行。不选任何模式钩子输出与 v2.43 逐字节一致老用户零迁移成本。一句话小结如果你的代理总在做长任务时忘了初心/clear之后从头再来那 planning-with-files 的思路值得直接抄——把计划当硬盘上的 RAM 镜像用钩子做每轮刷新用三文件做读写分工。它是 MIT 协议的安装一条命令的事多语言版本阿拉伯语、德语、西班牙语、简中、繁中也已齐备详见 docs/languages.md。【免费下载链接】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），仅供参考