引言
AI 初创公司 Manus 的核心逻辑展示了通过 Markdown 文件管理模式实现高效上下文工程的价值。Planning with Files 这款 Claude Code 插件复刻了这一核心逻辑，解决了 AI 代理在复杂任务处理中普遍存在的记忆易失、目标漂移、错误重复等痛点，让 AI 代理像人类一样拥有'持久化工作记忆'。
项目核心介绍
Planning with Files 是一款为 Claude Code 打造的插件/技能，核心目标是通过持久化的 Markdown 文件体系，替代 AI 代理易失的上下文窗口，解决 AI 处理复杂任务时的诸多问题。
该插件安装便捷，通过 Claude Code 插件市场即可快速部署：
/plugin marketplace add OthmanAdi/planning-with-files /plugin install planning-with-files@planning-with-files
其核心是为每个复杂任务建立三个核心 Markdown 文件：task_plan.md（跟踪任务阶段与进度）、findings.md（存储研究与发现）、progress.md（记录会话日志与测试结果），将 AI 的'内存（上下文窗口）'与'硬盘（文件系统）'做清晰划分，把重要信息全部落地到文件系统中。
安装后 Claude 会自动执行一系列操作：任务开始前创建规划文件、重大决策前重读规划、文件写入后提醒更新状态、将研究发现存储到文件而非上下文、记录所有错误、任务结束前验证完成状态，也可通过 /planning-with-files 手动调用。
创新点与核心优势
核心创新：重构 AI 代理的记忆体系
传统 AI 代理依赖上下文窗口（类似计算机 RAM），存在容量有限、易丢失的问题，而 Planning with Files 将文件系统（类似计算机硬盘）作为 AI 的持久化记忆载体，提出'任何重要信息都写入磁盘'的核心原则，从底层解决了 AI 代理的记忆痛点。
关键优势
- 解决记忆易失问题：替代消失的 TodoWrite 工具，通过持久化文件保存任务信息，上下文重置也不会丢失；
- 避免目标漂移：复杂任务（50+ 工具调用）中，通过重读
task_plan.md锚定原始目标； - 显性化错误追踪：所有错误记录在文件中，避免重复踩坑；
- 优化上下文利用：不再将所有信息塞入上下文，而是分类存储到专属文件，提升处理效率。
同时，插件内置核心规则保障落地效果：任务开始前必须创建规划文件、每 2 次浏览/浏览操作后保存发现、记录所有错误、绝不重复相同失败，让 AI 代理的工作流程更规范。
技术原理与部署实现
技术原理
插件的核心运行依赖 Claude Code 的钩子（Hook）机制，通过不同阶段的钩子触发对应操作：
- PreToolUse 钩子：重大决策前重新读取
task_plan.md，确保决策不偏离目标； - PostToolUse 钩子：文件写入后提醒更新状态，保证信息及时同步；
- Stop 钩子：任务结束前验证所有阶段完成情况，避免遗漏；
- SessionStart 钩子：会话启动时完成初始化，适配 Claude Code v2.1 版本。
部署与文件结构
项目的核心文件结构清晰，便于扩展和维护：
planning-with-files/
├── templates/ # 根级别模板（适配 CLAUDE_PLUGIN_ROOT）
├── scripts/ # 根级别脚本（适配 CLAUDE_PLUGIN_ROOT）
├── docs/ # 文档目录（含安装、快速上手等指引）
├── planning-with-files/ # 插件技能核心目录
│ ├── SKILL.md
│ ├── templates/
│ └── scripts/
├── skills/ # 兼容旧版的技能目录
├── .claude-plugin/ # 插件清单文件
├── .cursor/ # Cursor IDE 适配规则
├── CHANGELOG.md # 版本更新日志
└── LICENSE # 开源协议
部署方式灵活，除了插件市场快速安装外，还支持手动安装、Cursor IDE 适配部署、Windows 系统专属部署方式（具体可参考项目 docs 目录下的 installation.md、cursor.md、windows.md 等文档）。不同版本也可按需安装，如修复模板缓存问题的 v2.1.2 版本，直接通过 /plugin install planning-with-files@planning-with-files 即可部署。
