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-filesplanning-with-files 是面向 AI 编码代理的持久化规划工具它把任务的阶段、发现和进展写进磁盘上的三个 Markdown 文件并在每轮对话开始时重新注入解决代理在 /clear、崩溃或上下文压缩后忘掉任务进度、只能从头再来的问题。为什么 /clear 之后AI 代理会忘记任务用过编码代理做复杂任务的人大概都撞过这堵墙记忆易失代理脑子里的待办清单上下文一重置就全没了目标漂移工具调用超过 50 次后原始目标被新信息挤掉错误重复没写下来的失败下次会原样再犯上下文塞满什么信息都往窗口里塞最后一起被遗忘问题的根源是同一个代理把上下文窗口当成了唯一记忆。窗口像内存RAM断电就没磁盘上的文件才是断电不丢的。planning-with-files 的思路很简单——把重要状态写进文件。这个思路源自 Manus。Manus 团队说过一句被广泛引用的话Markdown 是我在磁盘上的工作记忆。这个项目把同样的做法做成了可直接安装的 skill一种标准化的 AI 能力扩展包。如何安装 planning-with-files 并验证钩子生效安装只要一分钟可重复执行。主路线有三条按你用的代理选一条# Claude Code 插件路线技能 钩子 斜杠命令全带 /plugin marketplace add OthmanAdi/planning-with-files /plugin install planning-with-filesplanning-with-files# 其他代理走 Agent Skills 开放标准一行搞定 npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g另有npm install planning-with-files适合把版本锁进仓库和pi install npm:planning-with-filesPi 代理专用。各路线到底带什么、差什么完整对比表见安装指南。⚠️一个要记住的坑插件路线是唯一默认带全套钩子hook即代理在工作的每个节点自动执行的脚本的路。其他路线可能静默失败——装上了技能但钩子没注册。装完跑一次/plan-doctor自检它会逐项输出 PASS/WARN/FAIL。排障入口在故障排查。技能有简体中文版把命令里的 skill 名换成planning-with-files-zh即可另有阿拉伯语、德语、西班牙语、繁体中文详见多语言说明。整个项目覆盖 18 平台Claude Code、Codex CLI、Cursor、GitHub Copilot、Gemini CLI、OpenCode 等支持 60 代理。三文件模式怎么运转上下文窗口当内存文件当磁盘装好后技能的行为很直白判断任务需要 3 个以上步骤或 5 次以上工具调用时先在项目根目录建三个文件task_plan.md → 阶段与状态/clear 后的恢复点 findings.md → 研究笔记和技术决策 progress.md → 会话日志和测试结果什么时候往哪个文件写技能把写下来变成了机械规则而不是靠自觉发生了什么写到哪做了调研findings.md做了技术决策findings.md带上理由完成一个阶段task_plan.md 勾选 progress.md 记录细节出了错task_plan.md 的错误区 progress.md 写清怎么解决的还有一条2 次操作规则每做 2 次查看/浏览操作必须往 findings.md 写一笔。整个设计的关键是钩子。以 Claude Code 为例技能注册了 5 个生命周期钩子UserPromptSubmit、PreToolUse、PostToolUse、Stop、PreCompact。每轮对话开始时钩子从磁盘读出 task_plan.md把目标和当前阶段重新放回上下文——几十个工具调用之后原始目标依然摆在模型眼前。写文件之后PostToolUse 钩子提醒更新计划想停手时Stop 钩子检查阶段是否全部完成。完整流程图见工作流文档。成本方面要心里有数单次钩子触发约 289msv3.6.0 优化后的测量值注入内容每轮约 330 token每次匹配的工具调用再加约 90 token。结构化的代价是少量 token 开销值不值看下一节的数据。长任务怎么跑门控与自主模式怎么选v3 版为长时运行提供了两个可选模式都不设定时行为与 v2 完全一致。# 自主模式只在每轮开始时注入一次计划 ./scripts/init-session.sh --autonomous 任务名自主模式去掉每次工具调用时的计划复述每次约省 90 token只保留轮首注入适合能自己保持注意力的强模型并默认开启计划锁定。门控模式--gated在自主模式之上加了一道停止闸门。只有以下条件同时成立才拦截停止存在进行中的阶段、不在强制续跑中、连续拦截次数未超上限默认 20 次、上次拦截以来账本ledger追加式的进度日志有新进展。任何一条不满足会话就正常放行。换句话说一个没做完的计划永远不会把会话锁死——这既防止代理声称完成但其实没做完也防止未完成任务无限续跑。怎么选单任务长时间运行用自主模式无人值守、需要确定性完成判断的过夜任务用门控模式。机制全文见长任务指南。/clear 或崩溃后如何恢复会话追赶机制把计划放磁盘上最直接的收益是上下文死了计划还在。当会话被 /clear或崩溃打断后技能自动做会话追赶session catchup读取 IDE 的会话存储Claude Code 在~/.claude/projects/找到规划文件最后更新的时间点提取这之后的对话内容生成一份追赶报告给新会话接着干。项目自己的恢复基准测试作者自跑、确定性评分方法见docs/evals.md会话在中途被强杀新会话只收到一句继续这个目录的工作。有规划文件时平均5.0 轮回到工作状态裸代理要13.3 轮。所有组的运行都通过了测试差距纯粹是重新定向的成本。还有一个细节上下文压缩compaction前PreCompact 钩子会提醒代理先把进展刷进磁盘避免压缩把进行中的工作吞掉。多任务并行与计划安全目录隔离与哈希锁多个计划并行怎么互不干扰同一个仓库有多个不相干的任务时根目录的三个文件会打架。v2.36.0 引入了并行计划隔离./scripts/init-session.sh backend-refactor ./scripts/set-active-plan.sh 2026-01-10-backend-refactor每个任务拿到独立的.planning/2026-01-10-backend-refactor/目录里面各有一套三文件由.active_plan指针标记当前活动计划也可以用PLAN_ID环境变量把终端钉在某个计划上。v3.10.0 还加了并行写守卫已勾选项或完成阶段数变少说明另一个会话覆盖了你的工作时钩子会打印一条警告。计划锁定防止计划被恶意或误修改/plan-attest会对 task_plan.md 计算 SHA-256 哈希一段能唯一标识文件内容的指纹存进.attestation文件。之后每次注入时钩子重新校验锁定后计划正文被动过就拒绝注入v3 模式下未锁定的计划干脆不注入。写入路径与并发细节见计划锁定文档。这套设计里还有一层安全考量。2026 年 3 月的安全审计发现钩子的重读计划文件机制会放大外部网页内容——不信任的内容一旦进入 task_plan.md就会被每轮重复注入上下文提示注入放大。v2.21.0 的修复从允许工具列表移除 WebFetch/WebSearch外部内容只许写进 findings.md永远不进 task_plan.md。更多细节见SECURITY.md。还留了逃生通道PLANNING_DISABLED1可让一次性会话跳过所有计划读取适合只是恰好和某个未完成计划共享工作目录的场景。planning-with-files 效果如何基准数字与适用场景正式评估用 Anthropic 的 skill-creator 框架10 个并行子代理5 个用技能、5 个不用、5 类任务、30 条客观断言、3 组盲测 A/B 对比。结果指标用技能不用技能断言通过率96.7%29/306.7%2/30遵循三文件模式5/50/5盲测 A/B 获胜3/30/3平均评分10.0/106.8/10要诚实说明96.7% 衡量的是工作流保真度——代理是否真的创建并维护了这三个文件——而不是长时运行中的目标漂移。成本也是真实的同一评估里结构化运行平均比无结构运行多花 68% 的 token 和 17% 的时间。这个工具本质是用 token 开销换可恢复性和目标一致性。所以适合谁适合3 步以上的多步任务、调研任务、需要扛过 /clear 与压缩的长会话、无人值守运行不适合5 次工具调用以内能做完的小任务——任务不够长结构就回不了本最后一件事要知道计划文件是工作记忆而非交付物。它们默认被 gitignore下一个任务会直接覆盖根计划也没有自动归档。想长期保留的东西请写进代码、提交或文档。写在最后planning-with-files 只做一件事把上下文窗口当内存、把文件当磁盘让钩子机械地替你写状态、读状态。代价是每轮多出的几百个 token换来的是 /clear 不再是事故、目标漂移被压住、无人值守的长任务能被确定性地判断做完了。挑一个你正在做的多步骤任务装一次/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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-filesplanning-with-files 是面向 AI 编码代理的持久化规划工具它把任务的阶段、发现和进展写进磁盘上的三个 Markdown 文件并在每轮对话开始时重新注入解决代理在 /clear、崩溃或上下文压缩后忘掉任务进度、只能从头再来的问题。为什么 /clear 之后AI 代理会忘记任务用过编码代理做复杂任务的人大概都撞过这堵墙记忆易失代理脑子里的待办清单上下文一重置就全没了目标漂移工具调用超过 50 次后原始目标被新信息挤掉错误重复没写下来的失败下次会原样再犯上下文塞满什么信息都往窗口里塞最后一起被遗忘问题的根源是同一个代理把上下文窗口当成了唯一记忆。窗口像内存RAM断电就没磁盘上的文件才是断电不丢的。planning-with-files 的思路很简单——把重要状态写进文件。这个思路源自 Manus。Manus 团队说过一句被广泛引用的话Markdown 是我在磁盘上的工作记忆。这个项目把同样的做法做成了可直接安装的 skill一种标准化的 AI 能力扩展包。如何安装 planning-with-files 并验证钩子生效安装只要一分钟可重复执行。主路线有三条按你用的代理选一条# Claude Code 插件路线技能 钩子 斜杠命令全带 /plugin marketplace add OthmanAdi/planning-with-files /plugin install planning-with-filesplanning-with-files# 其他代理走 Agent Skills 开放标准一行搞定 npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g另有npm install planning-with-files适合把版本锁进仓库和pi install npm:planning-with-filesPi 代理专用。各路线到底带什么、差什么完整对比表见安装指南。⚠️一个要记住的坑插件路线是唯一默认带全套钩子hook即代理在工作的每个节点自动执行的脚本的路。其他路线可能静默失败——装上了技能但钩子没注册。装完跑一次/plan-doctor自检它会逐项输出 PASS/WARN/FAIL。排障入口在故障排查。技能有简体中文版把命令里的 skill 名换成planning-with-files-zh即可另有阿拉伯语、德语、西班牙语、繁体中文详见多语言说明。整个项目覆盖 18 平台Claude Code、Codex CLI、Cursor、GitHub Copilot、Gemini CLI、OpenCode 等支持 60 代理。三文件模式怎么运转上下文窗口当内存文件当磁盘装好后技能的行为很直白判断任务需要 3 个以上步骤或 5 次以上工具调用时先在项目根目录建三个文件task_plan.md → 阶段与状态/clear 后的恢复点 findings.md → 研究笔记和技术决策 progress.md → 会话日志和测试结果什么时候往哪个文件写技能把写下来变成了机械规则而不是靠自觉发生了什么写到哪做了调研findings.md做了技术决策findings.md带上理由完成一个阶段task_plan.md 勾选 progress.md 记录细节出了错task_plan.md 的错误区 progress.md 写清怎么解决的还有一条2 次操作规则每做 2 次查看/浏览操作必须往 findings.md 写一笔。整个设计的关键是钩子。以 Claude Code 为例技能注册了 5 个生命周期钩子UserPromptSubmit、PreToolUse、PostToolUse、Stop、PreCompact。每轮对话开始时钩子从磁盘读出 task_plan.md把目标和当前阶段重新放回上下文——几十个工具调用之后原始目标依然摆在模型眼前。写文件之后PostToolUse 钩子提醒更新计划想停手时Stop 钩子检查阶段是否全部完成。完整流程图见工作流文档。成本方面要心里有数单次钩子触发约 289msv3.6.0 优化后的测量值注入内容每轮约 330 token每次匹配的工具调用再加约 90 token。结构化的代价是少量 token 开销值不值看下一节的数据。长任务怎么跑门控与自主模式怎么选v3 版为长时运行提供了两个可选模式都不设定时行为与 v2 完全一致。# 自主模式只在每轮开始时注入一次计划 ./scripts/init-session.sh --autonomous 任务名自主模式去掉每次工具调用时的计划复述每次约省 90 token只保留轮首注入适合能自己保持注意力的强模型并默认开启计划锁定。门控模式--gated在自主模式之上加了一道停止闸门。只有以下条件同时成立才拦截停止存在进行中的阶段、不在强制续跑中、连续拦截次数未超上限默认 20 次、上次拦截以来账本ledger追加式的进度日志有新进展。任何一条不满足会话就正常放行。换句话说一个没做完的计划永远不会把会话锁死——这既防止代理声称完成但其实没做完也防止未完成任务无限续跑。怎么选单任务长时间运行用自主模式无人值守、需要确定性完成判断的过夜任务用门控模式。机制全文见长任务指南。/clear 或崩溃后如何恢复会话追赶机制把计划放磁盘上最直接的收益是上下文死了计划还在。当会话被 /clear或崩溃打断后技能自动做会话追赶session catchup读取 IDE 的会话存储Claude Code 在~/.claude/projects/找到规划文件最后更新的时间点提取这之后的对话内容生成一份追赶报告给新会话接着干。项目自己的恢复基准测试作者自跑、确定性评分方法见docs/evals.md会话在中途被强杀新会话只收到一句继续这个目录的工作。有规划文件时平均5.0 轮回到工作状态裸代理要13.3 轮。所有组的运行都通过了测试差距纯粹是重新定向的成本。还有一个细节上下文压缩compaction前PreCompact 钩子会提醒代理先把进展刷进磁盘避免压缩把进行中的工作吞掉。多任务并行与计划安全目录隔离与哈希锁多个计划并行怎么互不干扰同一个仓库有多个不相干的任务时根目录的三个文件会打架。v2.36.0 引入了并行计划隔离./scripts/init-session.sh backend-refactor ./scripts/set-active-plan.sh 2026-01-10-backend-refactor每个任务拿到独立的.planning/2026-01-10-backend-refactor/目录里面各有一套三文件由.active_plan指针标记当前活动计划也可以用PLAN_ID环境变量把终端钉在某个计划上。v3.10.0 还加了并行写守卫已勾选项或完成阶段数变少说明另一个会话覆盖了你的工作时钩子会打印一条警告。计划锁定防止计划被恶意或误修改/plan-attest会对 task_plan.md 计算 SHA-256 哈希一段能唯一标识文件内容的指纹存进.attestation文件。之后每次注入时钩子重新校验锁定后计划正文被动过就拒绝注入v3 模式下未锁定的计划干脆不注入。写入路径与并发细节见计划锁定文档。这套设计里还有一层安全考量。2026 年 3 月的安全审计发现钩子的重读计划文件机制会放大外部网页内容——不信任的内容一旦进入 task_plan.md就会被每轮重复注入上下文提示注入放大。v2.21.0 的修复从允许工具列表移除 WebFetch/WebSearch外部内容只许写进 findings.md永远不进 task_plan.md。更多细节见SECURITY.md。还留了逃生通道PLANNING_DISABLED1可让一次性会话跳过所有计划读取适合只是恰好和某个未完成计划共享工作目录的场景。planning-with-files 效果如何基准数字与适用场景正式评估用 Anthropic 的 skill-creator 框架10 个并行子代理5 个用技能、5 个不用、5 类任务、30 条客观断言、3 组盲测 A/B 对比。结果指标用技能不用技能断言通过率96.7%29/306.7%2/30遵循三文件模式5/50/5盲测 A/B 获胜3/30/3平均评分10.0/106.8/10要诚实说明96.7% 衡量的是工作流保真度——代理是否真的创建并维护了这三个文件——而不是长时运行中的目标漂移。成本也是真实的同一评估里结构化运行平均比无结构运行多花 68% 的 token 和 17% 的时间。这个工具本质是用 token 开销换可恢复性和目标一致性。所以适合谁适合3 步以上的多步任务、调研任务、需要扛过 /clear 与压缩的长会话、无人值守运行不适合5 次工具调用以内能做完的小任务——任务不够长结构就回不了本最后一件事要知道计划文件是工作记忆而非交付物。它们默认被 gitignore下一个任务会直接覆盖根计划也没有自动归档。想长期保留的东西请写进代码、提交或文档。写在最后planning-with-files 只做一件事把上下文窗口当内存、把文件当磁盘让钩子机械地替你写状态、读状态。代价是每轮多出的几百个 token换来的是 /clear 不再是事故、目标漂移被压住、无人值守的长任务能被确定性地判断做完了。挑一个你正在做的多步骤任务装一次/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考