Planning with Files：基于文件的 AI 代理规划工作流实践
1. 把规划写进文件：让 AI 代理不再失忆
项目地址：https://github.com/OthmanAdi/planning-with-files
简介：一个将任务规划、进度与知识落地的 Markdown 文件工作流插件，支持 Claude Code、Cursor、Gemini CLI 等。
核心价值：解决 AI 在长任务中上下文漂移、记忆丢失的问题，通过持久化文件实现可追溯的过程记录。
1.1. 前言
在使用 AI 处理复杂任务（如写文章、做调研、改项目）时，常出现前 10 分钟顺畅，随后因上下文重置或工具调用过多导致 AI'遗忘'目标、重复失败的情况。planning-with-files 不依赖更长的 Prompt，而是将重要信息从临时上下文迁移到文件系统，形成持久的工作记忆。
1.2. 背景与痛点：为什么需要'文件化规划'
AI 代理的上下文类似 RAM（有限、易失），而文件系统类似 Disk（持久、容量大）。常见痛点包括：
| 痛点 | 典型表现 | 后果 |
|---|---|---|
| 易失记忆 | 上下文重置后计划和结论丢失 | 返工、重复问答 |
| 目标漂移 | 工具调用多了开始偏题 | 交付不符合目标 |
| 错误不留痕 | 失败未记录，下次重踩坑 | 效率降低 |
| 上下文塞爆 | 资料堆在对话里未写入文件 | 不可追溯 |
解决之道在于将工作流改为'可持久化'。
1.3. 核心观点：3 文件 + Hooks
该模式维护三个核心文件：
task_plan.md → 任务分阶段与状态（计划与对齐）
findings.md → 研究发现与关键决策（知识沉淀）
progress.md → 会话日志、操作记录、测试结果（过程可追溯）
Hooks 负责在关键时点读取/提醒，脚本负责初始化与校验，Session Recovery 负责在 /clear 后补全遗漏信息。
1.3.1. 与'上下文工程'的关系
这是一种偏工程实现的 上下文工程（Context Engineering） 方案。通过将上下文从'聊天记录'迁移到'文件系统'，实现：
- 单一真理来源：以
task_plan.md/findings.md/progress.md为最新事实依据。 - 状态显式化：阶段状态、决策、错误均写在文件中。
- 最小必要上下文：重要信息入盘，按需读取。
- 思考与行动分离：先写发现再执行，减少污染。
1.3.2. Manus 六大上下文工程原则落地
项目在 skills/planning-with-files/reference.md 中总结了 Manus 的 6 条原则，本项目将其转化为可操作的工具：
