planning-with-files —— 基于文件的持久化规划系统，专为 AI 编码代理与长时间运行的代理任务设计

这是什么

planning-with-files 是一个面向 AI 编码代理的持久化、基于文件的规划技能。它让代理在磁盘上维护 task_plan.md、findings.md 和 progress.md 三个文件，从而在上下文被清除（/clear）、会话丢失甚至崩溃后仍能恢复工作状态。该项目由 OthmanAdi 开发，主语言 Python，GitHub 星标 24533。v3.0.0 新增了可选自主模式与门控模式（completion gate），代理在计划实际完成前会被门控机制保留，不会提前结束。该技能通过 SKILL.md 标准可安装在 60+ 款 AI 代理上，包括 Claude Code、Cursor、Codex、Gemini CLI 等。

解决的问题

AI 编码代理（如 Claude Code）普遍面临三个痛点：

• 易失性记忆：TodoWrite 等工具在上下文重置后消失，代理丢失所有未保存的进度。
• 目标漂移：经过 50+ 次工具调用后，原始目标逐渐被遗忘，代理可能偏离任务主线。
• 隐藏错误：失败不被记录，导致同样错误重复发生，浪费 token。
• 上下文臃肿：所有信息塞进上下文窗口（RAM），而非存储到文件系统（磁盘）。

该项目的核心洞察是：上下文窗口 = 易失性 RAM，文件系统 = 持久化磁盘。任何重要信息都应写入磁盘，而非依赖短暂的上下文。

核心功能

1. 三文件结构：代理自动创建 task_plan.md（跟踪阶段与进度）、findings.md（存储研究结果与发现）、progress.md（会话日志与测试结果）。三者共同形成代理的“磁盘工作记忆”。

2. 自动会话恢复：当上下文填满并执行 /clear 时，技能自动检测上一次会话数据（利用 IDE 的 session store，如 ~/.claude/projects/ 或 ~/.codex/sessions/），找到规划文件最后更新时间，提取可能丢失的对话，给出同步报告，让代理从中断处接续工作。

3. 门控完成验证（v3.0.0 可选）：启用后，代理在计划未实际完成时不会停止，防止过早退出。支持自主模式（autonomous mode）和门控模式（gated mode），后者在停止前强制检查进度。现有配置不受影响。

4. 并行计划隔离（v2.36.0+）：使用 .planning/YYYY-MM-DD-slug/ 目录隔离不同计划，避免冲突。同时支持 Codex 会话隔离。实验性分支已合并至 master。

5. 多 IDE 支持：为 60+ 个 IDE 提供专用钩子配置（PreToolUse/PostToolUse/Stop），自动在工具调用前重新读取计划、在文件写入后提醒更新进度、在停止前验证完成。支持的 IDE 列表包括 Claude Code、Cursor、Codex、Gemini CLI、Autohand Code、BoxLite 等 18 个平台（另有 40+ 通过 Agent Skills 标准兼容）。

6. 多语言版本：默认英文，另有阿拉伯语、德语、西班牙语、简体中文、繁体中文版，通过不同后缀的 SKILL.md 切换。

7. 高级功能（Claude Code 专属）：通过 /plugin marketplace add 安装插件后，可使用 /planning-with-files:plan、/planning-with-files:start 等命令，并可选择将技能复制到本地 ~/.claude/skills/ 以实现无前缀的 /planning-with-files 命令。

亮点 / 与同类相比

• 采用 Manus 已验证的模式：Meta 于 2025 年 12 月以 20 亿美元收购的 AI 代理公司 Manus，其核心秘密正是“上下文工程”——使用 Markdown 文件作为磁盘上的工作记忆。planning-with-files 实现了这一模式，并大规模推广。
• 经过形式化评估：使用 Anthropic 的 skill-creator 框架（v2.22.0）对 claude-sonnet-4-6 模型进行评估，10 个并行子代理、5 种任务类型、30 条可客观验证的断言、3 次盲 A/B 比较，文件模式保真度达 96.7%（注意：此数字仅衡量三文件结构的创建与维护，未覆盖长期自主运行中的目标漂移；新版模型和自主模式暂未纳入）。
• 轻量零侵入：无需修改代理代码，只需安装一个 SKILL.md 即可。与其他上下文管理方案（如昂贵的 fine-tuning、专用中间件）相比，它的开销极低——每个工具调用前仅通过钩子读取文件，自主模式下甚至只在会话开始和阶段切换时注入，减少强模型上的 per-tool-call 开销。
• 故障恢复能力强：自动恢复因 /clear 或崩溃丢失的上下文，这在长时间多步骤任务中极为关键。其他方案往往需要用户手动重放对话或重新开始。
• 社区驱动：项目发布不到 24 小时即爆发增长，贡献者列表在 CONTRIBUTORS.md 中公开。支持社区反馈持续迭代。

适合谁用 / 上手

适合：

• 使用 Claude Code、Cursor、Codex、Gemini CLI 等 AI 编码代理进行多步骤复杂任务的开发者（3 步以上任务）。
• 需要长期研究、构建项目，或频繁进行大量工具调用的用户。
• 对代理的目标漂移和错误重复感到头痛，希望有可靠进度追踪的人。
• 希望借鉴 Manus 模式的项目团队或个体。

不适合：

• 解决简单问答、单文件编辑或快速查找——此类场景三文件模式过于笨重，应跳过。

上手步骤：

1. 确保你的 IDE 支持 Agent Skills 规范（大多数现代编码代理已支持）。若 IDE 使用旧版 Rules 系统，可使用 legacy-rules-support 分支。
2. 在终端中执行安装命令（以默认英文版为例）：

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

   若需简体中文版，替换为 --skill planning-with-files-zh。
3. （可选）Claude Code 用户可通过插件市场安装高级功能：

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

4. 在代理中触发规划：输入 /planning-with-files:plan（自动补全可简写 /plan），代理会自动创建三个文件，按提示开始工作。
5. 进阶使用：
   • 使用 task_plan.md 分解阶段，findings.md 记录研究结果，progress.md 记录会话日志。
   • 遵守“创建计划优先”“每 2 次查看/浏览器操作后保存发现”“记录所有错误”三条实践规则。
   • 可通过 "autoCompact": false 禁用自动压缩以最大化上下文（在清除前）。

完整文档参见 docs/installation.md、docs/quickstart.md 和 docs/workflow.md。