要解决的问题

编码智能体的工作记忆活在上下文窗口里：一旦压缩、/clear 或进程崩溃，之前谈定的方案、已经验证过的结论、踩过的坑就一起没了。结果是同一个坑反复踩，或者恢复后按错误的旧假设继续改。

planning-with-files 的做法很直接：把计划写到磁盘上，并让它在每一轮重新进入上下文。

三个文件分别放什么

  • task_plan.md：目标、拆解后的步骤、当前进度、每步的判据
  • findings.md：已经验证的事实与来源（读了哪个文件、跑了哪条命令得到的结论）
  • progress.md：时间线与状态变更，便于恢复时判断「上次停在哪」

技能通过生命周期钩子在每一轮注入选定的计划上下文，因此计划能在上下文丢失、压缩、崩溃之后继续存在；自动恢复只读取项目内的文件。如果要做跨会话的聚合统计或有界回放，必须显式打开 catchup 模式，否则不会去读同项目的本地会话记录——这一点对关心数据边界的团队很重要。

怎么装

它按 Agent Skills 标准分发，可装到 60 多个智能体上；对 Claude Code、Codex CLI、Pi 与 Hermes Agent 提供原生插件（仓库内可见 .claude-plugin、.codex-plugin、.codebuddy、.kiro、.factory、.pi 等目录）。安装按各智能体的插件或技能目录放置即可，钩子由插件机制注册。

落地注意三点

  • 更新时机：一个步骤完成、或得到新的验证结论时立刻写回文件，不要攒到最后——崩溃恰恰发生在你没写的时候
  • 多人协作：计划文件进版本控制后会出现并发修改，建议按人分节或按分支隔离，避免互相覆盖
  • 效果验证：作者给出 3 次盲测 A/B 全胜，这属于自测口径；接入前用你自己的长任务做一次对照（同样任务、同一模型，一次开技能一次不开），比较返工次数与恢复成功率