Skill Planning-With-Files 让智能体计划落盘不丢的文件规划技能

让智能体干一个持续几小时的大任务，最怕的不是它写错代码，而是中途断档：上下文窗口被压缩、会话崩溃、手一滑敲了个 /clear，智能体瞬间失忆，重新 orient 一次就要花十几轮对话。大多数外壳内置的待办清单只活在上下文里，窗口一重置就跟着陪葬。

Planning with Files 的解法朴素得近乎反直觉：把计划写到磁盘上。这个技能维护 task_plan.md、findings.md、progress.md 三个文件，通过每轮触发的生命周期钩子把计划重新注入上下文，清空、压缩、崩溃都动不了它。项目自测数据称，磁盘计划把 13.3 轮的重新定向压缩到 5.0 轮，三次盲测 A/B 对比全胜，基准断言通过率 96.7%。

项目基本信息

一、项目介绍

Planning with Files 是面向 AI 编码智能体和长时任务的持久化文件规划技能。它的核心原则用一句话概括：上下文窗口是内存，易失且有限；文件系统是磁盘，持久且无限——所有重要的东西都写进磁盘。

三个文件各司其职：task_plan.md 存阶段拆解和复选框，是 /clear 之后的恢复点；findings.md 边干边追加调研笔记和决策记录；progress.md 记会话日志和测试结果。并行任务用 .planning/日期-标识/ 目录隔离，通过 .active_plan 切换。全部是纯 Markdown，默认进 gitignore，没有任何别的运行时状态。

技能通过 Agent Skills 标准可以装进 60 多个智能体，并为 Claude Code、Codex CLI、Qoder CLI、Pi、Hermes Agent、OpenCode、DeepSeek Harness 提供原生插件。钩子每轮注入计划上下文，还带哈希证明和完成门控：计划没报告完成，智能体被拦着不许提前收工。

二、核心优势

第一，计划不受上下文生命周期摆布。断点续传是文件系统天然提供的能力，第十个小时的行为和第一轮完全一致。

第二，恢复成本低。有磁盘计划兜底，会话重启后智能体直接从当前阶段继续，不用把项目重新扫一遍。

第三，完成门控。Stop 钩子会核对计划里的完成标记，防止智能体在任务只做了七成时就开始写总结。

第四，本地化完善。官方提供包括简体中文在内的五个语言变体，且是真正的全量本地化，脚本、模板、用户可见输出都翻好了。

三、适用场景

最受益的是长时任务：大型重构、多模块迁移、从零搭一个完整项目，这类工作注定跨越多个会话，落盘计划是刚需。

第二类是多智能体并行开发，隔离目录让每条工作线有自己的计划文件，互不污染。

第三类是人机协作交接：findings.md 记录了每个决策的来龙去脉，同事接手或者第二天你自己回头看，都有迹可循。

四、安装教程

一条命令全局安装：

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

中文变体把技能名换成 planning-with-files-zh 即可。完整的各平台安装路径（包括原生插件方式）见仓库 docs/installation.md。

常见问题：安装后钩子没生效，检查所用智能体是否支持生命周期钩子，不支持的话技能退化为普通技能，每轮注入需要手动触发；npx 报权限错误多半是全局目录问题，换用户级安装路径或用管理员终端。

五、使用示例

在任务开始时让智能体初始化计划：

把这次数据库迁移任务建成一个计划，用 planning-with-files 管理

智能体会在项目根目录生成 task_plan.md，内容大致是分阶段的复选框列表：第一阶段备份数据库，第二阶段写迁移脚本，第三阶段灰度验证，第四阶段全量切换。执行过程中它把「生产库时区是 UTC+8，别用默认值」这类发现写进 findings.md。中途你敲了 /clear 或者会话崩了，新会话开始时钩子自动把计划注入，智能体打开 task_plan.md 看到前两阶段已打勾，直接从第三阶段接着干，不用你重新解释背景。

六、常见问题

和内置的 todo 有什么区别？内置待办活在上下文里，随窗口重置消失；这套计划活在磁盘上，每轮重新注入，还带完成门控。

会不会把仓库弄乱？三个文件默认 gitignore，也可以选择提交让团队共享计划，由你决定。

跨会话统计数据安全吗？常规恢复只读项目文件；读取本地会话记录做汇总属于显式的 catchup 模式，需要你主动开启。

七、总结

Planning with Files 没有用任何复杂技术，就是把「重要的事写到磁盘上」这条老原则搬进了智能体工作流，效果却立竿见影。对于经常让智能体跑长任务的开发者，这是那种装完就回不去的基础设施级技能。