planning-with-files：让AI代理的规划在上下文崩溃后依然存活

你是否曾经因为 /clear 一次，AI 代理就把之前的规划忘得一干二净？planning-with-files 正是为彻底解决这一痛点而生。它是一个基于 Python 的 Agent Skills 标准开源项目，将 task_plan.md、findings.md、progress.md 三个 Markdown 文件持久化到磁盘，并在每一轮对话中自动重新注入上下文。无论你的 AI 编码代理经历多少次上下文压缩、崩溃还是手动清理，规划都稳稳地留在磁盘上——Manus 同款“上下文工程”模式，现已支持 Claude Code、Codex CLI、Cursor 等 60+ 代理。

截至收录：
planning-with-files stars数：26205
planning-with-files forks数：2191

planning-with-files项目目录截图

planning-with-files核心亮点

🌟 亮点一（崩溃免疫）：三文件模式将规划完整存于磁盘，即使上下文窗口被清空、代理崩溃或遭遇模型压缩，下一轮对话会自动恢复全部状态，无需重新描述目标。
🎯 亮点二（三文件工作流）：task_plan.md 追踪阶段与进度、findings.md 沉淀研究发现、progress.md 记录会话日志，形成一套结构化、可版本化的人工智能工作记忆。
🔄 亮点三（60+ 代理覆盖）：基于 Agent Skills 开放标准，支持 Claude Code、OpenAI Codex CLI、Cursor、GitHub Copilot、Continue 等主流工具；一条命令即可完成安装。
🚀 亮点四（性能验证）：内部基准测试显示，使用该技能后上下文恢复仅需 5.0 轮对话（无技能时需 13.3 轮），文件模式遵循率达到 96.7%（30 项断言中 29 项通过），且恢复会话后 pytest 全绿（77/77）。

planning-with-files快速开始

只需几步，你就能在本地运行起 planning-with-files：

1. 安装：
   “`bash
   # 方式一：Claude Code 插件安装（推荐，包含技能、钩子、斜杠命令）
   /plugin marketplace add OthmanAdi/planning-with-files
   /plugin install planning-with-files@planning-with-files

   方式二：其他 60+ 代理，一行命令

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

   方式三：通过 npm 锁定版本

   npm install planning-with-files
   “`

2. 开始规划：在代理对话中直接输入 /plan（或要求代理“plan this task”），技能会自动为多步骤任务创建三个规划文件。
3. 验证安装：运行 /plan-doctor 执行安装自检，确认规划注入、钩子注册与完成门控全部正常。

planning-with-files应用场景

场景一：长时运行的任务：在需要运行数小时乃至数天的自主编码任务中，代理需要频繁经历上下文压缩。planning-with-files 的 PreCompact 钩子和会话恢复机制能确保任务目标不漂移、进度不丢失，是构建“自动驾驶”式开发管线的理想基础设施。

场景二：多步骤复杂开发：面对 3 步以上的开发任务（如功能开发+测试+文档），代理可以先将任务拆解为阶段化的 task_plan.md，再通过钩子在每一步决策前重新注入当前阶段状态，有效避免 50 次工具调用后“目标漂移”的常见问题。

用户案例：Manus AI（被 Meta 以 20 亿美元收购）正是“Markdown 文件即工作记忆”这一模式的先驱；如今，Claude Code、OpenAI Codex CLI、Cursor、GitHub Copilot、Continue、Kiro、OpenCode 等主流 AI 代理的用户都在使用 planning-with-files 来改善其长期运行的代理工作流。

planning-with-files链接

OthmanAdi / planning-with-files项目地址：https://github.com/OthmanAdi/planning-with-files

本文地址：https://www.tgoos.com/46201