planning-with-files Skill：让 AI Agent 任务规划永不死机的磁盘记忆术

Skill超级捕获手 技术创作者 2026-08-17 11 阅读

planning-with-files 是目前最受欢迎的 AI 编程 Agent 规划技能，通过在磁盘持久化 task_plan.md、findings.md、progress.md 三个文件，让 Agent 在上下文窗口崩溃、/clear、或压缩后仍能完整恢复工作进度。其核心创新是把”上下文窗口”类比为易失性 RAM、把文件系统类比为持久化 Disk，从根本上解决了长程任务中目标漂移、记忆断裂、重复试错等顽疾。该 Skill 支持 60+ Agent 平台（Claude Code、Codex、Cursor、OpenCode 等），benchmark 恢复率 96.7%，测试套件 417 个全绿，2025 年底至 2026 年初在 GitHub 狂揽 26k+ Star，是 Agent Skills 生态里增长最快的生产级工具之一。

功能与原则

planning-with-files 的核心功能是为 AI 编码 Agent 提供持久化、崩溃可恢复的 Markdown 规划系统。它不强加额外的 AI 能力，而是将 AI 的工作记忆外置到磁盘文件，让每次对话都从上一次真实的进度恢复，而不是从零开始。

设计原则三条：

  • 文件即单一真相来源（File as Single Source of Truth）：所有目标、发现、进度不留在上下文里，而是写入磁盘文件。
  • 上下文极简主义（Context Minimalism）：上下文窗口只放当前 turn 最必要的信息，大量背景数据存在文件里，按需注入。
  • 确定性完成门（Deterministic Completion Gate）：所有规划阶段逐项勾选，全部完成后才释放 Stop 信号，避免 Agent 提前退出。

认可度

  • GitHub Star：26,208（截至 2026-08-17），Forks 2,197
  • 2026 年 2 月单月增长 11.7k Star，腾讯科技、CSDN 等多家中文技术媒体专题报道
  • 被 Manus 公司收购时的核心工作流理念（Manus 以 20 亿美元被 Meta 收购）所启发
  • 支持平台：Claude Code、Codex、Cursor、OpenCode、Pi Coding Agent 等 60+ Agent，跨平台采用率高

链接

GitHub：https://github.com/OthmanAdi/planning-with-files

原作者

OthmanAdi（GitHub username），独立开发者，专注于 AI Agent 的工作流增强工具。除 planning-with-files 外还维护多个 Agent Skills 相关项目，在 GitHub 上持续活跃更新（最新 commit 2026-01-04）。

介绍

Every AI coding agent loses its working memory when the context window resets——这句话是项目的核心出发点。当你在 Claude Code 里跑了 50+ 工具调用后，上下文窗口满了，/clear 一执行，所有 TodoWrite 列表、已完成的工作、发现的问题全部消失。Agent 重新上线时只能重新理解项目、重新探索进度，效率大打折扣。

planning-with-files 用三个磁盘文件解决这个问题：

  • task_plan.md：阶段规划 + Checkbox，完成即勾选，是 /clear 后的恢复点
  • findings.md：研究笔记和决策记录，随工作积累不断追加
  • progress.md：Session 日志和测试结果，记录每一步实际做了什么

平台在每一次 turn 开始时通过 Hook 机制自动将这三次文件内容 Re-inject 回上下文窗口。无论上下文被 /clear、崩溃还是模型压缩（Wipe）清空，只要文件在磁盘上，Agent 下一次启动就能读到完整的历史上下文并继续工作。

v2.36.0+ 还支持并行任务隔离：并行任务每个放在 .planning/YYYY-MM-DD-slug/ 子目录里，通过 .active_plan 选择当前激活的任务集。

特点

  • 崩溃恢复：/clear、崩溃、compaction 后 Session Catchup 平均 5.0 turn 恢复 vs 裸 Agent 13.3 turn（内部 benchmark）
  • 60+ Agent 兼容：Claude Code 插件市场、npx skills、npm 包、Pi Coding Agent、ClawHub 等多路安装
  • 无平台绑定：遵循 Agent Skills 标准（agentskills.io），不依赖特定模型或 API
  • Hook 自动化：5 个生命周期 Hook（Claude Code）/ 7 个（Codex）/ 8 个（Pi），让文件写入和计划注入全自动，无需手动触发
  • Gated 模式：可选”完成门”，所有规划阶段勾选完毕才允许 Agent 停止，防止提前退出
  • 测试覆盖：417 个测试全绿，持续集成保障跨版本稳定性

使用方法

安装（以 Claude Code 插件方式为例）：

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

其他 Agent（60+ 通用）：

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

触发方式：
– 输入 /plan（Claude Code 插件）
– 或直接对 Agent 说”plan this task”，Skill 会自动识别多步骤任务并自触发

手动创建三个文件（Skill 自动管理，一般无需手动）：

your-project/
├── task_plan.md    ← 阶段规划 + Checkbox
├── findings.md     ← 研究笔记/决策
└── progress.md     ← Session 日志/测试结果

启用 Gated 模式（在项目配置中）：

{
  "planningWithFiles": {
    "gateCompletion": true
  }
}

使用场景与人群

适用场景：
– 复杂多阶段项目（重构大型代码库、构建新功能、迁移系统）
– 长程任务（超过 50 tool calls 的工作流）
– 需要跨 Session 持续工作的项目（不是一次对话能完成的）
– 并行多任务管理（同时处理多个 Feature Branch）

目标用户：
– Claude Code / Codex / Cursor / OpenCode 重度用户
– 需要 AI Agent 处理复杂项目的开发者
– 关注 AI 工程化、追求 Agent 产出稳定性的团队

输入与输出案例

案例 1：大型代码重构

输入（对 Agent）：

“重构我们整个 API 层，从 REST 迁移到 GraphQL，要改 40+ 个文件，每个文件都要改路由、Schema 和 Resolver。”

Agent 行动：
1. 自动创建 task_plan.md（阶段规划：分析现有路由 → 定义 Schema → 逐文件迁移 → 测试验证）
2. 在 findings.md 记录每个文件的修改决策
3. progress.md 记录每个文件的完成状态

中途 /clear 触发上下文丢失 → 下一次 Agent 启动，读取三个文件，从当前进度继续，无重复劳动。

案例 2：Bug 修复长任务

输入：

“修复身份验证模块的 Token 刷新 Bug，涉及 8 个服务，测试覆盖要补全。”

Agent 创建三个文件，逐阶段推进。每个阶段的发现写入 findings.md，测试结果写入 progress.md。即使上下文压缩，Skill 也能让后续 Session 恢复到”修复 Token 刷新 → 补充测试 → 端到端验证”的具体阶段，而不是从头探索。

GitHub: https://github.com/OthmanAdi/planning-with-files

评论区

0 条评论

登录后可评论。

Skill超级捕获手 11 阅读