三个文件，两万星：Planning with Files如何让AI Agent不再忘事

2025年12月，Meta花20亿美元收购了一家新加坡AI公司。

这家公司叫Manus，成立8个月，年化收入超过1亿美元。核心产品是一个"自主AI Agent"——你给任务，它自己执行，不问你。

Manus的秘密武器不是某个模型，而是一套工作方法：用Markdown文件做"外部记忆"。

2026年1月，GitHub上出现了这个工作法的开源实现。不到半年，两万两千星。

人们给它起了个名字：Planning with Files。

一、这是啥：三个文件解决四个问题

1.1 AI Agent的"金鱼记忆"困境

用过Claude Code、Cursor或Codex的人都知道一个痛点：Agent做长任务时，会"忘记"自己在干什么。

不是比喻。是字面意义上的遗忘：

上下文重置 = 记忆清零
当你运行 /clear 或上下文窗口满了，Agent的"记忆"被压缩或丢弃。之前做的计划、犯的错误、学到的东西，全部消失。TodoWrite工具在上下文重置后也不见了。

目标漂移
50个工具调用之后，Agent可能已经完全忘了最初的任务目标。它一直在做"看起来相关"的事，但方向已经偏离。

错误不累积
Agent犯了错，纠正后继续。但错误记录没有保存。下次遇到同样的问题，它会再犯一次同样的错。

上下文膨胀
Agent把研究发现、中间结果、错误日志全部塞进上下文窗口。窗口越来越满，留给实际推理的空间越来越小。

Manus团队把这四个问题归结为一句话："Agent把上下文窗口当RAM用，但RAM是会丢的。"

1.2 解决方案：三个文件

Planning with Files的核心极简：对每个复杂任务，创建三个Markdown文件。

task_plan.md    → 任务计划：阶段、进度、检查点
findings.md     → 研究发现：中间结论、数据、引用
progress.md     → 会话日志：做了什么、遇到什么、下一步

核心原则：

• 上下文窗口 = RAM（易失，有限）
• 文件系统 = Disk（持久，无限）
• 任何重要的东西，写进文件

这不是什么新技术。程序员用todo.txt、research.md、log.md做笔记已经有几十年。但Planning with Files的巧妙之处在于：它不是给人看的，是给AI Agent看的。

三个文件的设计针对Agent的特定行为模式：

• task_plan.md 用checkbox格式（- [ ]），因为Agent能识别并更新进度
• findings.md 用结构化格式，因为Agent需要快速检索已有结论
• progress.md 用时间戳日志，因为Agent需要"回忆"之前做了什么

1.3 为什么三个文件刚好

不是两个，不是四个，是三个。

task_plan.md（计划层）

• 任务分解为阶段和子任务
• 每个子任务有checkbox，完成时打勾
• Agent在每次行动前重读计划，确保不偏离

findings.md（知识层）

• 研究发现、数据提取、引用来源
• 避免重复搜索：Agent先查findings.md，已经有结论就直接用
• 替代上下文膨胀：不把所有研究发现塞进prompt，而是存文件

progress.md（日志层）

• 会话级别的操作记录
• 错误日志：什么失败了、为什么失败、怎么解决的
• 会话恢复：上下文重置后，Agent读progress.md"回忆"之前做了什么

三个文件对应Agent工作的三个维度：未来（计划）、现在（知识）、过去（日志）。

二、为什么火了：Meta收购Manus之后

2.1 Manus的20亿美元神话

Manus AI于2025年3月推出，由新加坡公司Butterfly Effect（中国团队）开发。8个月内年化收入（ARR）超过1亿美元。2025年12月，Meta以约20亿美元收购。

Manus的核心产品：一个"通用AI Agent"，能自主执行多步骤任务（市场调研、编码、数据分析、文件管理）。它基于Claude LLM，集成29个工具，无需人工干预即可端到端完成任务。

但Manus真正的护城河不是技术栈，而是工作方法。

Manus团队公开说过：

"Markdown是我的磁盘上的工作记忆。由于我迭代处理信息，且主动上下文有限，Markdown文件作为笔记的草稿板、进度的检查点、最终交付成果的构建模块。"

这句话描述的就是Planning with Files的三文件模式。Manus把这套方法产品化，变成了用户看不见的"底层机制"。

2.2 开源复制：Planning with Files的诞生

2026年1月，Ahmad Othman Adi在GitHub上发布了planning-with-files。这不是复制Manus的产品，而是复制Manus的工作方法——用Claude Code的skill/plugin机制，把三文件工作流植入任何Agent。

项目描述直接点明：

"Claude Code skill implementing Manus-style persistent markdown planning — the workflow pattern behind the 💲2B acquisition."

这句话的潜台词：Manus值20亿，不是因为某个模型，而是因为这套工作模式。这套模式可以复制到任何Agent上。

2.3 为什么突然火了

几个因素叠加：

Meta收购的背书
20亿美元收购把Manus的工作方法推到了聚光灯下。人们在问：Manus到底做对了什么？答案是context engineering（上下文工程），而三文件模式是context engineering的核心。

Agent生态的成熟
2025-2026年，Claude Code、Codex CLI、Cursor、Gemini CLI等Agent工具普及。用户发现：Agent能写代码，但做长任务会"跑偏"。三文件模式恰好解决了这个痛点。

跨平台兼容性
planning-with-files支持17+平台（Claude Code、Cursor、Codex、Gemini、Copilot、Mastra、Kiro、Continue、Pi、OpenClaw...）。安装一行命令：

npx skills add OthmanAdi/planning-with-files

Benchmark验证
项目用Anthropic的skill-creator框架做 formal evaluation：

• 30个客观可验证断言，有skill时96.7%通过（29/30），无skill时仅6.7%（2/30）
• 盲测A/B对比，有skill 100%获胜（3/3）
• 三文件模式遵循率：有skill 5/5，无skill 0/5

这些数据说明三文件模式不是"感觉更好"，而是** objectively better**。

三、怎么用：工作流详解

3.1 安装与启动

Claude Code插件安装：

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

Agent Skills标准安装（通用）：

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

启动命令：

• /plan 或 /planning-with-files:plan — 开始规划会话
• /plan:status — 查看当前进度

3.2 工作流：从任务到完成

Step 1：创建计划（task_plan.md）
Agent收到任务后，首先创建task_plan.md。格式示例：

# Task Plan: 竞品分析报告

## Phase 1: 数据收集
- [x] 搜索竞品A的产品页面
- [x] 提取竞品A的定价信息
- [ ] 搜索竞品B的产品页面
- [ ] 提取竞品B的定价信息

## Phase 2: 分析对比
- [ ] 整理定价对比表
- [ ] 分析功能差异
- [ ] 撰写结论

## Phase 3: 输出
- [ ] 生成Markdown报告
- [ ] 导出为PDF

Step 2：执行与记录（progress.md）
每执行一个工具调用，Agent在progress.md记录：

## 2026-01-15 22:32
- 操作：搜索竞品A产品页面
- 结果：找到3个产品版本，定价分别为💲29/💲49/💲99/月
- 下一步：提取竞品B信息

## 2026-01-15 22:35
- 操作：搜索竞品B
- 结果：页面404，尝试缓存版本
- 错误：Wayback Machine无缓存
- 解决方案：改搜竞品C作为替代

Step 3：发现归档（findings.md）
有价值的研究发现存入findings.md：

## 竞品定价对比
| 竞品 | 基础版 | 专业版 | 企业版 |
|------|--------|--------|--------|
| A    | 💲29    | 💲49    | 💲99    |
| C    | 💲19    | 💲39    | 💲79    |

## 关键差异
- 竞品A支持API访问，竞品C不支持
- 竞品C有更友好的移动端界面

## 来源
- 竞品A定价页：https://...
- 竞品C定价页：https://...

3.3 Hooks：自动化的"记忆触发器"

Planning with Files的核心机制是hooks——在Agent生命周期的关键点自动执行动作。

PreToolUse Hook（工具使用前）

• 自动重读task_plan.md
• 确保当前行动与计划一致
• 如果计划已过期，提醒更新

PostToolUse Hook（工具使用后）

• 检查是否产生新发现
• 提醒更新findings.md或progress.md
• 执行"2-Action Rule"：每2个查看/浏览操作后保存发现

Stop Hook（会话结束前）

• 检查task_plan.md是否所有checkbox已打勾
• 如果有未完成任务，提醒继续或记录原因
• 生成会话摘要

SessionStart Hook（会话启动时）

• 检查是否有之前的会话数据
• 如果有，生成"catchup报告"，让Agent快速恢复上下文

这些hooks把"记笔记"从可选行为变成强制行为——Agent不会忘记更新计划，因为它在每次行动前后都被hook触发。

3.4 会话恢复：上下文重置也不怕

当你运行 /clear 或上下文窗口满了时，Planning with Files自动：

1. 检查之前会话的数据（IDE的session store）
2. 找到planning文件最后更新的时间
3. 提取该时间之后的对话（可能丢失的上下文）
4. 生成catchup报告，展示给Agent

这意味着：即使上下文被清空，Agent也能在几秒内"回忆"起之前做了什么。

四、安全边界：为什么能信任这套机制

4.1 文件系统作为"可信存储"

上下文窗口的问题之一是不可信——Agent可能会"幻觉"出自己做过的事，或者忘记真正做过的事。文件系统存储是可信的：写进去就是写进去了，不会凭空消失，也不会被篡改（除非有明确操作）。

4.2 篡改检测（Attestation Locking）

v2.37.0引入了一个安全机制：

• /plan-attest 命令锁定task_plan.md，生成SHA-256哈希
• 后续hooks检测到文件被篡改时，会阻止注入并提醒用户
• 使用原子temp-rename + 可选flock，防止并发写入竞争

这意味着：即使Agent被恶意prompt诱导修改计划，篡改会被检测出来。

4.3 权限隔离

• 脚本使用POSIX标准（/usr/bin/env bash），兼容NixOS等系统
• PowerShell版本使用RemoteSigned执行策略（非Bypass）
• 路径净化：防止路径遍历攻击
• 内容注入防护：prompt injection delimiters隔离代码与数据

4.4 沙盒运行时支持

BoxLite集成支持：在硬件隔离的micro-VM中运行Claude Code + planning-with-files，确保即使skill本身有漏洞，也不会影响主机系统。

五、追问：三个文件的局限与边界

5.1 不是所有任务都需要三文件

项目文档明确说：

• 用：多步骤任务（3+步骤）、研究任务、构建项目、跨多个工具调用的任务
• 不用：简单问题、单文件编辑、快速查询

三文件模式有 overhead：创建文件、更新checkbox、写日志。对于"帮我把这段代码格式化"这种任务，三文件是负担。

5.2 文件系统的延迟 vs 上下文的即时

文件系统存储是持久的，但读写有延迟。如果Agent每次行动前后都要读写文件，会不会拖慢速度？

项目的答案是：hooks是异步的，文件读写用缓存（mtime-keyed SHA-256 cache）。实测延迟在毫秒级，不影响交互体验。

5.3 多任务并行：plan隔离问题

如果同时处理多个任务，不同任务的plan文件会冲突吗？

v2.36.0引入了 parallel plan isolation：

• 使用 .planning/YYYY-MM-DD-slug/ 目录隔离不同任务
• set-active-plan.sh 切换活跃计划
• resolve-plan-dir.sh 解析当前计划目录

这意味着：Agent可以同时管理多个任务，每个任务有独立的plan文件。

5.4 人工干预与Agent自主的边界

Planning with Files假设Agent会自主更新plan文件。但如果Agent"误解"了任务，更新了错误的计划，错误会被固化到文件中，并在后续session中持续传播。

项目的设计哲学是：Agent负责执行，人负责监督。task_plan.md的checkbox给人提供了快速检查进度的入口。如果计划偏离，人可以手动纠正。

5.5 对非技术用户的门槛

虽然安装简单（一行命令），但理解三文件的工作逻辑需要一定的认知投入。非技术用户可能不知道task_plan.md和findings.md的区别，也不会主动查看progress.md。

项目正在通过IDE集成降低门槛：hooks自动处理大部分工作，用户只需要在需要时查看进度。

六、结语：从"写Prompt"到"写计划"

Planning with Files代表了一种范式的转移：

• 2023：Prompt Engineering（怎么问）
• 2024：System Prompt Engineering（怎么设置偏好）
• 2025：Context Engineering（怎么管理上下文）
• 2026：Plan Engineering（怎么管理任务结构）

每一次转移都在做同一件事：让AI从"回答问题"变成"完成任务"。

三文件模式的本质不是技术创新，而是组织创新——它把人类项目管理的方法（计划、记录、归档）适配到AI Agent的行为模式上。

Meta花20亿美元买Manus，买的不是模型，而是这套工作方法。Planning with Files把这个方法开源了，让任何Agent都能用。

两个文件系统调用（读plan、写progress），换来的是Agent不再"忘事"。这交易很划算。

核心参考文献

1. Othman, A. (2026). Planning with Files. GitHub: OthmanAdi/planning-with-files. https://github.com/OthmanAdi/planning-with-files
2. Manus AI (2025). Context Engineering for AI Agents. Manus Blog.
3. MegaOneAI (2026). Manus Review 2026: Can Meta's 💲2B AI Agent Replace Your Workflow? https://megaoneai.com/reviews/manus-review-2026-meta-ai-agent-workflow/
4. The AI Insider (2026-01-02). Meta Acquires AI Agent Startup Manus in 💲2B Deal. https://theaiinsider.tech/2026/01/02/
5. Anthropic (2026). Skill-Creator Framework Evaluation. planning-with-files benchmark.

#AIAgent #规划文件 #Manus #Meta #上下文工程 #ClaudeCode #技能 #小凯