planning-with-files是开源社区最近疯传的一个Skill，发布仅四天收获3.3k star。目前还在持续增长。
本文将带你深入代码层，看这个项目的Skill是如何用仅用几百行指令和三个Markdown文件，就在你的本地终端里模拟了价值20亿美元的Agent核心工作流。
项目地址：https://github.com/OthmanAdi/planning-with-files
Manus的六大上下文工程原则
Manus之所以能从众多Agent创业公司中突围，并非因为它拥有更强的模型，而是它重新定义了模型与上下文交互的方式。在 planning-with-files 项目的 reference.md 中，详细记录了这六大原则：
- 原理：不要依赖易失的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在当前目录维护三个文件：
task_plan.md（指挥塔 寄存器）
这是整个架构的核心。它不存储具体知识，只存储元数据。
- 作用：定义目标、拆解阶段、追踪进度、记录错误。
- 关键机制：它是Agent的“罗盘”。无论任务进行到第几步，Agent必须在每次行动前读取此文件。
2. notes.md（知识库 堆内存）
- 作用：存储调研笔记、网页摘要、中间代码。
- 关键机制：“Store, Don’t Stuff”。当Agent搜索到大量资料时，禁止直接输出到对话框，必须写入此文件。这保持了对话上下文的清爽。
3. [deliverable].md（产出物 IO缓冲区）
- 作用：最终的交付结果（如
game.py或report.md）。 - 关键机制：将“思考过程”与“最终结果”物理隔离。
三文件如何工作？
对于Claude Code用户来说，安装这个Skill后，最直观的变化是你的工作目录下会多出三个文件。但这不仅仅是文件，它们构成了一个基于文件的状态机（File-Based State Machine）。
Claude Code识别到复杂任务，Skill激活。它首先创建 task_plan.md。 这不是普通的文档，它是Agent的程序计数器（Program Counter）。
Goal（全局指令）。
- 它将任务拆解为
Phases（指令流水线）。 - 它标记了
Status（当前指针位置）。
此时，无状态（Stateless）的LLM第一次拥有了“状态”。
阶段1：Read-Before-Decide（对抗遗忘）
在开始写任何代码之前，Skill强制Claude执行 read_file task_plan.md。 这一步至关重要。
- 有了这一步，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，关键点如下…”。
Skill剖析
这个Skill的神奇之处在于它并没有修改Claude的模型权重，完全通过 SKILL.md 中的Prompt Engineering实现。
让我们看看 planning-with-files/SKILL.md 的关键片段：
description，自动挂载此Skill。
2. 负面约束 (Negative Constraints)：
3. 循环定义： Skill显式定义了 Read Plan -> Act -> Update Plan 的闭环逻辑，将Agent从线性的问答机器变成了有状态的循环执行者。
如何安装与使用
安装
在你的终端中运行（假设你已配置Claude Code）：
|
|
验证
重启Claude Code，输入： > /skills 你应该能看到 planning-with-files 出现在可用Skill列表中。
使用
直接对Claude说：
“研究一下Rust语言在嵌入式开发中的优势，并写一份报告。”
你会看到Claude自动：
- 创建
task_plan.md。 - 规划“搜索”、“阅读”、“撰写”三个阶段。
- 执行搜索，将结果写入
notes.md。 - 每完成一步，自动更新
task_plan.md的Checkbox。 - 最后生成报告。
结语
尽管业界对于Manus是否具备底层技术壁垒存在争议，但不可否认，它依然属于Context Engineering的优秀范例。
这说明除了提升模型本身以外，构建良好的认知架构（Cognitive Architecture） 同样重要。通过简单的文件读写和流程约束，就能让现有的模型发挥出超越参数规模的稳定性。
对于每一位AI开发者来说，理解并掌握这种“文件即记忆”的设计模式，是2026年的必修课。
来已来，有缘一起同行！
- 转载请与本喵联系，私自抓取转载将被起诉
🎉让我们一起创造更多美好！ 🎉
如果您觉得这篇文章对您有帮助感谢您为我**【点赞】、【在看】**
<您为我点赞在看，只有我能看到>
👉微信号：xiumaoprompt添加请注明来意！
来源: 微信公众号