用 planning-with-files 让编码智能体在 /clear 之后仍不偏离计划

长任务总以同一种方式翻车：/clear、崩溃或上下文压缩清空了窗口——计划跟着一起死掉。planning-with-files 是一个 27k 星的技能，它把计划放在磁盘上并每轮重新注入，让新会话从当前阶段继续，而不是反过来问你刚才在干什么。

为什么这个 Skill 重要

核心是一个三文件模式：task_plan.md 追踪阶段和勾选项，findings.md 沉淀调研笔记和决策，progress.md 记录会话和测试结果。背后的原则很直白——把上下文窗口当内存、把文件系统当磁盘，重要的东西一律写盘。生命周期钩子（Claude Code 插件路线上的 SessionStart、UserPromptSubmit、PreCompact）在每轮开始时把当前阶段带回窗口。

README 报告了带技能时 96.7% 的断言通过率（29/30）和 3 比 3 的盲测 A/B 胜绩——这是项目自己的评测，当作厂商数字来看。3.x 版本为长程运行加了一套机制：SHA-256 证明机制会在注入时拒绝被篡改的计划，gated 模式的 Stop 钩子在仍有 in_progress 阶段时会拦住停止（带阻塞上限和停滞检测，未完成的计划本身不会困死会话），并行写入防护则在已完成阶段数下降时于下一轮告警。

安装

在 Claude Code 上，插件路线把技能、钩子和斜杠命令一起装好：

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

其他代理走 Agent Skills 标准的一行命令，README 称覆盖 60+ 个代理：

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

把 --skill 换成 planning-with-files-zh 可以装简体中文版。一个有记载的注意点：技能路线的安装可能悄悄丢掉钩子——如果你依赖钩子，请走插件路线并用 /plan-doctor 验证。

实战流程：规划多阶段重构，然后挺过 /clear

1. 装好插件后，对智能体说 plan this task（或输入 /plan）。它会为当前任务创建三个规划文件。
2. 正常干活。发现写进 findings.md，完成的阶段在 task_plan.md 里打勾。
3. 现在执行 /clear 并让智能体继续。UserPromptSubmit 钩子把磁盘上的计划数据块注入上下文，智能体从当前阶段接着干——不用重新解释，也不会重做已完成的工作。

技能自己的触发规则很克制：任务需要 3 步以上或 5 次以上工具调用，才值得创建这三个文件。

实战流程：两个任务并行跑

并行任务用隔离目录，不共享根计划。用命名的 slug 启动每个任务，会得到 .planning/YYYY-MM-DD-<slug>/ 目录和独立的三件套；PLAN_ID 把一个宿主钉在其中一个上，set-active-plan.sh --list 列出已保存的计划和各自阶段数。并行写入防护覆盖两个会话互相覆盖的失败模式：已完成项或已完成阶段数一旦下降，下一轮就会告警。

技巧

• 装完先跑 /plan-doctor。它自检计划解析、注入、证明、安装面和每次触发的延迟——是发现「悄悄没钩子」安装的最快办法。
• 计划文件默认进 gitignore，是工作记忆而不是交付物。下一个任务会覆盖根计划，值得保留的内容要晋升进代码、提交或文档。
• 按 README 的说法，v3.6.0 优化后单次钩子触发约 289 毫秒——日常开着没问题。
• npm install planning-with-files 路线适合把文件钉进项目依赖，但它本身不注册钩子。

什么时候不该用它

这个技能管理的是执行状态，不是知识检索——README 把它与代理记忆工具对比，后者负责召回过去会话的事实，两者互补。单步任务不需要三个文件。自动化全靠钩子：如果你的宿主跑不了插件的生命周期钩子，你得到的只是文件模式，撑不过一次重置。

查看排行榜了解更多 skill。