Claude Code插件三文件模式解析：复刻Manus上下文工程，打造有记忆的AI编程助手

你有没有遇到过这种情况：让 AI 助手帮忙写代码，聊了十几轮甚至几十轮后，它好像开始“失忆”了。

之前定好的接口规范，它忘了。约定好的变量命名风格，它弄混了。你反复强调的规则，可能被新的对话内容冲刷得无影无踪。

结果就是，你不得不像保姆一样时刻提醒它，效率低下，身心俱疲。

但如果告诉你，现在有一个简单的方法，能让 AI 助手拥有“持久记忆”呢？你只需要在项目中放置三个 Markdown 文件，AI 就能自动记录所有发现、避免重复踩坑，甚至在会话中断后自动恢复进度。这可以将工作效率提升 30%，重复性错误减少 80%。

这并非科幻，而是 Meta 以 20 亿美元收购的 Manus 公司的核心技术思想——“上下文工程”（Context Engineering）。现在，这项技术已被 GitHub 社区成功复刻。

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

什么是 Planning-with-Files？

planning-with-files 是 Claude Code 的一个插件，它完整复刻了 Manus 的“上下文工程”模式。我们可以用一个简单的比喻来理解它。

传统的 AI 编程助手就像一个患有短期失忆的实习生。你下一道指令，它完成一项任务，做完就忘。下次遇到类似问题，它又得重新查阅文档、重新摸索、重新踩一遍坑。效率不高，还需要你全程紧盯。

而 planning-with-files 就像是给这位实习生配备了一个智能笔记本。你要求它将所有探索发现、遇到的错误、项目进度都实时记录在这个本子上。当再次遇到相似问题时，它会先翻看笔记本：“哦，这个问题上周遇到过，当时是这么解决的……” 关键之处在于，这个过程不需要你干预，AI 会自主记录、自主查阅、自主复盘。

此前社区有过各种为 AI 构建记忆系统的尝试，但 planning-with-files 的实现堪称最优雅：仅用三个 Markdown 文件就构建了一套完整的上下文管理系统。

核心原理：三文件工作模式

planning-with-files 的核心即“三文件模式”（3-File Pattern）——在项目的根目录下放置三个具有特定职责的 Markdown 文件。

1. task_plan.md (任务计划书)
这是项目的“战略总纲”，AI 在开始任何实质性工作前必须先阅读此文件。它需要明确三件事：我们的终极目标是什么？当前进行到哪一步了？下一步具体要做什么？
每次 AI 准备编写或修改代码时，都会被引导先阅读此文件，确保行动始终与目标对齐，避免在细节中迷失方向。

2. findings.md (发现记录册)
这是 AI 的“研究笔记”，用于持久化记录所有在开发过程中发现的关键信息。例如，调试时发现某个库在 Node.js 18 版本存在兼容性 Bug，或者某个服务的 API 接口发生了变更。
这些零散却重要的信息，在传统长对话中极易被后续内容覆盖而丢失。planning-with-files 强制 AI 将这些发现结构化地记录在此文件中，构建一个专属项目的知识库。下次遇到相关问题，AI 会优先调取这里的记录，而非盲目地重新搜索。

3. progress.md (进度日志)
这是项目的“工作流水账”，按时间顺序记录所有的尝试及其结果。刚才跑单元测试为什么失败了？失败在哪一行？上一次我们尝试修改了哪个函数？
这个文件的核心价值在于防止 AI 陷入“死循环”——即反复尝试同一种已被证明无效的解决方案。有了清晰的进度日志，你可以直接指出：“这个方案在昨天的 Session 2 中试过了，失败了，原因记录在案，请尝试新思路。”

为什么这三个文件如此有效？ 其核心思想非常直接：上下文窗口（Context Window）如同易失、有限的内存（RAM），而文件系统则是持久、大容量的硬盘（Disk）。将所有重要的上下文信息写入磁盘，而非全部塞进有限的上下文窗口，使得 AI 能够跨越会话保持记忆，并不断积累项目经验。

启用该插件非常简单，只需一行命令：

claude plugins install OthmanAdi/planning-with-files

安装后，AI 会在项目中自动创建这三个文件，并在每次操作前后自动读写它们，实现上下文的持久化管理。对于此类优秀的 开源实战 项目，深入了解其设计哲学总能带来启发。

必备配置与进阶功能

在开始深度使用前，了解其配置选项很有必要。该插件支持包括 Claude Code、Cursor、Windsurf、Zed、VS Code 在内的 14 款主流 IDE，覆盖了绝大多数开发环境。

一个强烈推荐的进阶功能是 “会话自动恢复”。想象这个场景：你让 Claude Code 编写一个复杂功能，中途离开片刻，返回时发现上下文已被重置。传统方式下，你不得不重新描述需求，一切从头开始。而启用恢复功能后，AI 会自动读取 progress.md 和 task_plan.md，瞬间理解项目进度，从中断处无缝衔接。

启用此功能只需在 IDE 的 settings.json 配置中添加一个环境变量：

{
  "env": {
    "PLANNING_WITH_FILES_AUTO_RECOVER": "1"
  }
}

快速上手指南：三分钟实践模板

下面提供一个可直接复制的模板，帮助你立即体验。

第一步：创建核心文件
在项目根目录创建以下三个文件：

task_plan.md

# Task Plan

## Current Status
- Status: in_progress
- Phase: 1/3

## Next Steps
1. [ ] 分析项目需求
2. [ ] 设计技术方案
3. [ ] 实现核心功能
4. [ ] 测试验证

## Final Goal
[清晰描述最终目标，例如：开发一个具备JWT认证的用户登录注册模块]

## Notes
- [任何注意事项，如：需要兼容后端API v2.0版本]

findings.md

# Findings

## Key Discoveries
- [重要发现1，如：`library-x` 在 Node.js 18 下存在内存泄漏，需降级至 16.x]
- [重要发现2，如：第三方服务API的认证头从 `X-Api-Key` 更改为 `Authorization: Bearer`]

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| `Error: Cannot find module 'xyz'` | 1 | 需要运行 `npm install xyz --save` |
| [错误描述] | [尝试次数] | [解决方案] |

## Decisions Made
- [关键决策1，如：选择使用 `axios` 而非 `fetch` 进行HTTP请求]
  - Reason: 需要更好的错误拦截和请求/响应转换器。

progress.md

# Progress Log

## Session 1 - 2023-10-27
- 尝试方案A（使用纯CSS实现动画）：失败
  - 原因：在目标浏览器上存在严重的性能卡顿。
- 切换到方案B（使用 `framer-motion` 库）：进行中

## Session 2 - 2023-10-28
- 完成用户登录表单UI组件
- 发现 `Button` 组件在移动端点击区域过小的问题，已记录至 `findings.md`
- 下一步：集成表单验证逻辑

第二步：开始协作
创建好文件后，你就可以像平常一样对 Claude Code 下达指令了。例如：

请帮我初始化这个React项目，添加路由配置，并使用 planning-with-files 模式记录过程。

接下来，你会观察到 AI 自动执行以下流程：

1. 首先阅读 task_plan.md 以确认项目目标和当前阶段。
2. 在执行过程中，将遇到的技术选型、发现的配置问题等记入 findings.md。
3. 在完成一个子阶段（如“安装依赖”）后，在 progress.md 中更新状态，并相应修改 task_plan.md 中的“Next Steps”。

高效协作的六大准则

项目作者总结了使用此模式时的六条核心准则，对于确保 AIGC 协作效率至关重要：

1. 计划先行：绝不在没有 task_plan.md 或计划不清晰的情况下，启动任何复杂任务。
2. 实时记录：每完成一到两次重要的搜索或代码探索操作后，立即将关键发现写入 findings.md，防止宝贵信息被后续对话冲刷。
3. 决策回顾：在做出关键技术决策前，必须重新阅读 task_plan.md，确保决策与最终目标一致。
4. 阶段同步：每一个开发阶段（如“完成API联调”）结束后，必须更新 task_plan.md（标记任务状态为完成），并在 progress.md 中简述本阶段成果与修改的文件。
5. 错误入库：所有遇到的错误及其解决方案，都必须归档到 findings.md 的“Errors Encountered”部分，这是构建AI经验库的基石。
6. 拒绝循环：如果某个操作失败，应遵循“三步法”：
   • 第一次失败：诊断并尝试修复。
   • 第二次失败：必须更换解决方法，绝不重复执行相同的失败操作。
   • 第三次失败：进行全局反思，质疑最初的技术假设。
   • 三次均失败：明确向用户请求指导和更多信息。

总结：从工具到工作方式的进化

如果你从这篇文章中只记住一个观点，那么请记住：planning-with-files 的本质，不是创造了一个更聪明的AI，而是培养了一个懂得积累经验的数字助手。

你会发现，真正的改变并非“AI突然变聪明了”，而是你的工作模式从“每次对话都从零开始教学”转变为“AI在项目中越用越熟，它记得所有踩过的坑和积累的经验”。这标志着 上下文工程 从概念走向了日常实践。

这不仅是使用了一个新插件，更是一种工作范式的升级。善于利用此类工具的开发者和团队，其 AI 助手会变得越来越“资深”和高效；而仍停留在传统单次对话模式中的人，则可能每次都在重复劳动。

不妨就从今晚开始，创建一个测试项目，运行一遍入门任务，亲身感受“拥有持久记忆的 AI 编程伙伴”如何改变你的开发流程。