Manus之所以能从众多Agent创业公司中突围，并非因为它拥有更强的模型，而是它重新定义了模型与上下文交互的方式。在 planning-with-files 项目的 reference.md 中，详细记录了这六大原则：

1. 文件系统作为外部记忆 (Filesystem as External Memory)

• 原理：不要依赖易失的Context Window。将磁盘视为无限的“外挂内存”，只在Context中保留文件路径。

通过重复进行注意力操纵 (Attention Manipulation Through Repetition)

• 原理：对抗“Lost in the Middle”。在关键决策前反复读取计划文件，强行刷新模型的“注意力权重”。

保留失败痕迹 (Keep Failure Traces)

• 原理：错误是宝贵的资产。显式记录失败尝试，让模型通过“反思”避免死循环，而不是掩盖错误。

避免少样本过拟合 (Avoid Few-Shot Overfitting)

• 原理：在重复性任务中引入受控变体，防止模型陷入机械式的幻觉。

稳定前缀优化缓存 (Stable Prefixes for Cache Optimization)

• 原理：通过固定的文件结构和前置指令，最大化KV-Cache命中率，降低Token成本。

只增不改的上下文 (Append-Only Context)

• 原理：尽量以追加（Append）而非修改（Modify）的方式更新信息，维护上下文的连贯性。

架构落地：三文件模式

planning-with-files Skill将上述抽象原则具象化为一套严格的 “三文件工作流”。

当这个Skill被触发时（例如你要求“帮我策划并开发一个贪吃蛇游戏”），它会强制Claude在当前目录维护三个文件：

1. task_plan.md（指挥塔 寄存器）

这是整个架构的核心。它不存储具体知识，只存储元数据。

• 作用：定义目标、拆解阶段、追踪进度、记录错误。
• 关键机制：它是Agent的“罗盘”。无论任务进行到第几步，Agent必须在每次行动前读取此文件。

2. notes.md（知识库 堆内存）

• 作用：存储调研笔记、网页摘要、中间代码。
• 关键机制：“Store, Don’t Stuff”。当Agent搜索到大量资料时，禁止直接输出到对话框，必须写入此文件。这保持了对话上下文的清爽。

3. [deliverable].md（产出物 IO缓冲区）

• 作用：最终的交付结果（如 game.py 或 report.md）。
• 关键机制：将“思考过程”与“最终结果”物理隔离。

此时，无状态（Stateless）的LLM第一次拥有了“状态”。

阶段1：Read-Before-Decide（对抗遗忘）

在开始写任何代码之前，Skill强制Claude执行 read_file task_plan.md。 这一步至关重要。

• 如果没有这一步，Claude可能会基于上文的闲聊或20轮之前的记忆开始瞎猜。
• 有了这一步，Claude的Context尾部被注入了最新的状态：“我现在处于Phase 2，目标是修改Login接口，且之前在Phase 1已经确认了Token格式。”
• 这相当于在每次CPU时钟周期开始时，强制执行一次Fetch Instruction。

阶段2：Data Offloading（数据卸载）

Claude需要查阅OAuth2.0的最新协议。

• 传统模式：Claude搜索网页，把5000字的协议全文塞进对话框。你的Token在燃烧，模型被无关信息淹没。
• 本模式：Claude搜索网页，提炼核心参数，写入 notes.md。在对话框里，它只说：“协议参数已存入notes。”
• 这相当于操作系统的Swap机制,把不常用的数据换出到磁盘，保持主存（Context Window）的清爽。

阶段3：State Commit（状态固化）

代码修改完成，测试通过。Claude必须编辑 task_plan.md：

• 将 [ ] Phase 2 改为 [x] Phase 2。
• 更新 Status 到 Phase 3。 这相当于Write Back。它赋予了LLM时间感，明确地知道什么是“过去”（已完成），什么是“未来”（待完成）。

它解决了什么？

这套Skill不是为了炫技，而是精准打击了LLM在长程任务中的四大死穴：

痛点1：易失性记忆 (Volatile Memory)

• 现象：多轮对话后，Claude code忘了之前定义的变量或需求。
• 解法：文件系统持久化。即使对话Session重置，只要 notes.md 和 task_plan.md 还在，Agent就能瞬间“恢复记忆”，继续工作。

痛点2：目标漂移 (Goal Drift)

• 现象：执行50步后，Claude code沉迷于细枝末节，忘了原始目标。
• 解法：Read-Before-Decide（行动前读取）。
  • Skill强制规定：Before major decisions, READ task_plan.md。
  • 利用Transformer的近因效应，刚读入的Plan处于Context最末端，权重最高，时刻提醒Agent“不要跑偏”。

痛点3：隐藏错误 (Hidden Errors)

• 现象：API调用失败，Claude code默默重试，导致死循环或成本爆炸。
• 解法：Error Persistence（错误持久化）。
  • task_plan.md 中包含 ## Errors Encountered 章节。
  • Agent被要求将所有失败显式写入。下次读取计划时，它会看到“路径A失败过”，从而自动推理出路径B。

痛点4：上下文填充 (Context Stuffing)

• 现象：把无关紧要的搜索结果全塞进Context，导致模型变笨、变慢、变贵。
• 解法：Offloading（卸载）。
  • 所有长文本默认进 notes.md。Context中只保留一句：“已将搜索结果存入notes.md，关键点如下…”。

https://github.com/OthmanAdi/planning-with-files