Planning with Files：基于文件的持久化规划技能
让编码代理把计划写在磁盘上
把复杂任务的计划、发现和进度持久化，能明显降低长任务中的上下文遗失。
核心流程有跨平台测试、版本化脚本和明确恢复规则，固定版本通过静态语法检查。
有路径约束、提示注入防护和安全说明；自动 hooks 会执行本机脚本并重新注入工作区计划内容。
公开测试、变更记录、安全策略和自建对照评测齐全，但尚无独立第三方复现。
三文件工作流直观；自动 hooks、模式选择和较长说明增加首次配置成本。
近期持续发布，安全修复、测试与发行记录清楚。
- 自动 hooks 会运行本机脚本；只在可信工作区启用，并先审查 hook 配置。
- 计划文件会被反复注入上下文；不要把不可信内容直接写入这些文件。
- 作者评测显示会增加时间与 Token 开销，长任务收益更明显。
它能做什么 & 适用场景
Planning with Files 面向 AI 编码代理和长期运行的代理任务，通过 task_plan.md、findings.md 和 progress.md 在磁盘上保存计划、发现与进度。它旨在帮助代理应对上下文丢失、/clear 和崩溃，并提供可选的自主模式与完成门控。项目支持 Claude Code、Codex CLI、Cursor、Kiro、OpenCode 等平台，并通过 SKILL.md 标准覆盖 60 多个代理。
该技能将复杂任务拆分为阶段，并要求代理优先创建持久化的 Markdown 规划文件。它可在工具调用或会话开始等生命周期节点重新读取计划、记录研究发现和错误、提示同步进度，并在支持的平台上检查任务是否完成。v3 还提供可选的 autonomous 和 gated 模式、运行日志、计划哈希校验以及并行计划隔离相关能力。
- 需要跨多个阶段、多个工具调用完成的代码开发任务
- 需要持续记录资料、结论和错误的研究任务
- 可能经历 /clear、上下文压缩或会话恢复的长期代理运行
- 需要在文件系统中共享任务状态的多代理协作
- 需要在停止前检查所有计划阶段是否完成的项目工作流
优缺点一览
- 将执行状态保存到磁盘，能够跨上下文丢失、/clear 和崩溃恢复
- 同时提供计划、发现和进度三类文件，职责划分清晰
- 支持 Claude Code、Codex、Cursor、Kiro、OpenCode 等多个代理生态
- 提供可选的自主模式、完成门控、运行日志和 SHA-256 计划校验
- 仓库提供多语言技能变体、平台安装指南和 Windows 相关支持说明
- 技能依赖本地文件系统和 shell/生命周期钩子，纯模型 API 环境不能直接执行
- 不同代理的钩子、命令和安装方式并不完全相同，跨平台使用可能需要对应适配
- README 没有提供缓存中的 SKILL.md 原文，因此无法独立核验其完整 frontmatter 和正文细节
- 自动化门控和会话恢复能力取决于所使用代理是否支持相应的钩子或生命周期事件
如何安装
通用技能安装命令为：npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g。README 还提供了阿拉伯语、德语、西班牙语、简体中文和繁体中文变体的对应安装命令。Claude Code 的插件安装方式为：/plugin marketplace add OthmanAdi/planning-with-files，然后执行 /plugin install planning-with-files@planning-with-files。
如何使用
安装后，对复杂任务使用 /planning-with-files:plan 或 /planning-with-files:start；Claude Code 中也可使用 /planning-with-files:status 查看进度。技能通常会创建 task_plan.md、findings.md 和 progress.md：前者记录阶段，第二个保存研究发现，第三个保存会话日志和测试结果。README 建议遵循“先创建计划”、每两次查看或浏览操作后保存发现、记录所有错误并避免重复失败等规则。
对比同类
它与向量数据库、知识图谱等代理记忆工具的定位不同：Planning with Files 主要管理当前任务的阶段、依赖、进度和完成状态，而不是长期事实检索。README 将二者描述为互补关系。与仅依赖上下文中的待办事项相比，它把重要状态写入 task_plan.md、findings.md 和 progress.md，以便在会话恢复后重新读取。