夜雨聆风你是不是也遇到过这样的崩溃瞬间：用 AI 编码助手写一个复杂的重构任务，刚让 Claude 读完整个项目的架构，开了十几个步骤的规划对话框，结果中途终端崩溃，或者手残点了 /clear 清空上下文——然后 AI 瞬间失忆，一切回到原点，得从零开始描述需求？
这种“白干了”的痛，每个深度使用 AI 编程的人都能共鸣。更致命的是，如果你需要多个 AI 代理分工协作（比如一个负责分析代码结构，一个负责写测试，另一个负责部署），它们之间没有共享记忆，彼此都不知道对方做了什么，导致重复劳动甚至冲突。
开源项目 planning-with-files 就是来终结这种混乱的。 它提供了基于文件的持久化计划机制，把你的 AI 任务拆成一个个 Markdown 文件，存放在磁盘上。即使 AI 的上下文被清空、终端崩溃、甚至换个电脑，计划文件和执行状态依然完好无损。Claude Code、Codex CLI、Cursor、Kiro、OpenCode 等 60 多种 AI 编码工具都兼容，因为它是通过一个叫 SKILL.md 的标准文件来注入能力的。
🚀 一、背景揭秘：为什么你需要这个技能/工具？
想象一下，你正在用 Claude Code 完成一个“给网站新增用户登录功能”的任务：
你需要 Claude 先分析现有代码（引入 auth.py、models.py）然后编写登录表单和 JWT Token 逻辑 接着修改前端路由 最后检查测试覆盖率
在传统模式下，你每次和 Claude 对话都是独立的。如果第一步做完后，你说“继续下一步”，Claude 可能已经忘了之前它分析过哪个文件。更惨的是，如果你中途切换窗口、或者 Claude Code 突然报错退出，之前的对话记录就没了——你不得不重新让 AI 读一遍代码，再重新描述需求。
planning-with-files 的核心理念是：把任务计划变成文件，让 AI 自己维护这些文件。 每个任务步骤都是一个 Markdown 文件，里面记录了目标、当前状态（待做/进行中/已完成）、产出的文件列表。AI 每次启动时，都会读取最新的计划文件，知道自己做到了哪一步，哪些东西已经完成。因为文件真的存在磁盘上，所以无论你 /clear 多少次、机器重启几次，进度都不会丢。
这个项目源自一个广为人知的思路——Manus 式的工作流，即用文件系统作为 AI 的“外脑”，代替对话中的隐式记忆。它非常适合：
长时间运行的编码任务（重构、大功能开发） 多代理协作（不同 AI 角色共享同一个计划文件） 与 CI/CD 结合（计划文件跟踪进度，失败后自动续跑）
💡 二、核心功能：3个核心优势深度剖析
1. 崩溃级持久化：Markdown 文件当“存档点”
传统 AI 对话是易失性的，而 planning-with-files 把每个步骤的状态都写进 plans/ 目录下一个 .md 文件中。比如步骤 1 完成后，AI 会在文件中把状态从 pending 改成 completed，并记录产出。下次启动时，AI 直接读取最新的 plan.md（汇总文件），就知道从哪里继续。
这就像是玩角色扮演游戏时手动存档——再也不怕“游戏崩溃”导致进度丢失。而且这个存档完全是人类可读的 Markdown，你可以直接打开编辑，比如手动跳过某个步骤，或者标记某个步骤因为 bug 需要重做。
2. 确定性完成门：确保“做完”而非“说做”
很多时候 AI 会说“我已经修改了文件”，但实际上它可能只是生成了代码却没有写入，或者写错了位置。planning-with-files 规定：只有当任务列表中的每一个步骤都被标记为 completed（并且标记是通过写入文件完成的），系统才认为任务真正完成。 这就避免了 AI 的“嘴炮”行为——它必须实际执行写文件操作来更新状态，否则下一次启动时还是会显示未完成。
这种“完成门”机制，本质上是通过文件系统的事件驱动来保证状态的可靠性。相当于给 AI 设了一个“打卡清单”，只有每个打卡点都真正执行了动作（写入文件），才进行下一步。
3. 多代理共享状态：磁盘就是“黑板书”
如果多个 AI 代理（比如一个负责写代码，一个负责写测试）同时运行，它们可以通过读取同一个 plans/ 目录来获知对方的进度。因为所有计划文件都在本地磁盘上，没有网络依赖，也没有中心服务器。每个代理只需要遵守相同的 Markdown 结构，就可以像协作编辑文档一样协同工作。
这种模式特别适合复杂项目的自动化流水线：例如先由“分析 Agent”生成代码结构，然后由“编码 Agent”填充实现，再由“测试 Agent”写单测，每个 Agent 都检查 plan.md 中对应步骤的状态，只有前一步完成才执行自己的任务。
🛠️ 三、实战教学：手把手带你跑通核心案例
我们以 Claude Code 为例（其他工具如 Cursor 操作类似），实现一个“在已有 Python 项目中新增一个简单的 REST API”任务，并确保会话崩溃后能续命。
步骤 1：配置 SKILL.md 让 AI 学会“文件规划”
planning-with-files 的核心是注入一个 SKILL.md 文件到你的项目根目录。这个文件会告诉 AI 代理“当你要执行多步复杂任务时，请使用基于文件的计划模式”。
克隆项目：
git clone https://github.com/OthmanAdi/planning-with-files.git cd planning-with-files 将 SKILL.md 复制到你的项目中（或直接在项目根目录创建 SKILL.md，内容复制仓库中的文件）。
注意：部分 AI 工具（如 Claude Code）在启动时会自动读取根目录的 SKILL.md。你也可以手动告诉 AI：“请根据 SKILL.md 中的指令进行计划管理。”
步骤 2：启动 AI 代理并下达任务
在项目根目录下启动 Claude Code（或 Codex CLI），然后给出你的任务描述：
请根据 SKILL.md 的指导，帮我完成以下任务：1. 在项目根目录创建一个 plans/ 文件夹2. 分析现有代码，生成一个包含以下步骤的计划文件 plan.md：- 步骤1：在 app/routes.py 中添加一个新的 GET /api/health 端点，返回 {"status": "ok"}- 步骤2：在 tests/test_routes.py 中添加对这个端点的测试- 步骤3：运行测试确保通过 3. 然后按照计划依次执行每个步骤4. 每完成一步，更新 plan.md 中的状态为 completed
AI 会首先读取 SKILL.md，理解它应该用文件来管理计划。然后它会创建 plans/ 目录，并生成类似 plans/plan.md 的文件，内容大概如下：
# 项目计划：添加健康检查端点## 步骤1：添加 API 端点- 状态：pending- 目标：在 app/routes.py 中添加 GET /api/health- 预计产出：修改 app/routes.py## 步骤2：添加测试- 状态：pending- 目标：在 tests/test_routes.py 中添加测试- 预计产出：修改 tests/test_routes.py## 步骤3：运行测试- 状态：pending- 目标：运行 pytest 并确保通过- 预计产出：测试结果
然后 AI 开始执行步骤1。它修改了 app/routes.py 后，会更新计划文件：
## 步骤1：添加 API 端点- 状态：completed- 目标：在 app/routes.py 中添加 GET /api/health- 产出：已添加代码（见文件）
步骤 3：模拟崩溃与恢复
假设执行完步骤1后，你按下 Ctrl+C 终止了 Claude Code，甚至重新打开了终端。当你再次启动 Claude Code 并进入项目目录时，你可以直接说：“继续执行计划，检查上次的进度。”
AI 会读取 plans/plan.md，看到步骤1已完成，步骤2 pending，然后自动从步骤2开始。无需你再次描述任务，也无需重新分析代码。
步骤 4：手动干预计划（高级）
如果你发现步骤1的代码写错了，你可以直接编辑 plans/plan.md，把步骤1的状态从 completed 改回 pending，然后告诉 AI：“步骤1需要重做。” AI 会重新执行步骤1。
这就是文件化带来的控制力：你不是 AI 的乘客，而是项目的“项目经理”。
⚠️ 四、进阶用法与避坑指南
✅ 进阶用法
1. 多代理自动化流水线
如果你有多个 AI 代理（比如不同终端窗口），可以设置每个代理启动时自动读取 plans/plan.md。例如，代理A负责修改代码，代理B负责审查代码。代理B可以检查“步骤1”是否 completed，如果是则开始执行“代码审查”步骤（这个步骤需要在计划文件中提前预定义）。
2. 与 Git 钩子结合
你可以写一个 pre-commit 钩子，检查 plans/plan.md 中是否所有步骤都已 completed，否则阻止提交。这样确保代码库只在完整任务完成后才被推入远程仓库。
3. 使用环境变量控制计划目录
planning-with-files 默认使用 plans/ 目录。你可以通过环境变量 PLANS_DIR 自定义路径，比如 PLANS_DIR=my_project_plans，方便多个项目共用一套 AI 代理配置。
⚠️ 避坑指南
1. AI 可能不理解 SKILL.md
虽然兼容 60+ 工具，但部分 AI 助手（尤其是旧版本）不会自动读取 SKILL.md。你需要明确告诉它：“请参考根目录的 SKILL.md 文件来规划你的工作。” 如果它忽略，可以手动把 SKILL.md 的内容粘贴到对话中作为指令。
2. 计划文件冲突
如果你同时让两个 AI 代理修改同一个计划文件，可能会造成写入冲突（一个写了 completed，另一个写回了 pending）。建议： - 对不同步骤分配不同的代理（计划文件中每个步骤用独立的文件，而不是一个文件里写全部） - 或者使用简单的文件锁机制（比如先创建一个 .lock 文件，代理执行前检查）
planning-with-files 目前没有内置锁，这点对于单代理场景足够，多代理需要自己加小心。
3. 文件系统开销
对于非常长的任务（比如上百个步骤），每次更新都要写磁盘，频繁 I/O 可能稍慢。但实际编码中通常步骤数不多（10-20步），影响可忽略。
4. 不适用于纯对话任务
这个工具专门为“多步、有产出的编码任务”设计。如果你只是想和 AI 聊天、讨论问题，没必要用它。它的真正价值在于自动化工作流中的状态持久化。
5. 隐私与安全
所有计划文件都存储在本地磁盘，没有外传，所以数据安全没问题。但要注意：plan.md 里可能会包含你的项目路径、代码片段等敏感信息，如果项目中其他协作者也能访问，注意不要写入敏感密钥。
🎯 五、总结与选型参考
最终建议： 如果你有过至少一次“AI 做到一半突然失忆”的惨痛经历，花 5 分钟把 SKILL.md 放进项目，绝对值得。它不改变你使用 AI 的方式，只是给 AI 装了一个“持久化硬盘”。而且完全免费、开源，工具链只需一个 Markdown 文件。
你在使用 AI 编程时遇到过哪些离谱的“失忆”事故？ 欢迎留言分享，我们一起探讨更好的解决方案。如果这篇文章对你有帮助，记得点个“在看”，让更多同样被脆皮 AI 折磨的开发者看到。