【开源】12.1K Star！用 Markdown 给大模型装上“外挂大脑”，不写后端、不搭平台，这个开源项目让你用 Git 管理 AI 任务流

理解问题的本质——为什么传统对话模式会失效

1.1 对话历史的天然缺陷

在深入了解 Planning-with-Files 之前，我们需要先理解一个根本性的问题：为什么传统的对话模式无法支撑复杂的 AI Agent 任务？

传统的 AI 对话模式是这样工作的：每一轮对话都会被追加到对话历史中，AI 在生成回复时会参考这些历史记录。这种模式对于简单的问答场景完全够用，但当任务变得复杂时，问题就开始浮现。

对话历史的三大硬伤：

第一，线性结构的局限性。 对话历史是严格按时间顺序排列的线性结构。想象一下，如果你在进行一个需要多次迭代的开发任务，中间经历了多次方案调整、错误修正，这些信息全部混杂在一起。AI 要从中提取有效信息，就像在一堆杂乱的纸条中找关键内容一样困难。

第二，噪声信息的累积。 在实际工作中，我们会产生大量的"试错信息"——比如某个方案试了不行、某段代码有 bug 需要修改。这些信息虽然在当时有意义，但对于后续任务来说就是纯粹的噪声。传统对话模式会保留所有这些噪声，导致 AI 的注意力被严重分散。

第三，状态更新的混乱。 当任务涉及多个步骤时，每个步骤的状态（待处理、进行中、已完成）都在不断变化。对话历史中会充斥着各种状态的更新信息，AI 需要从头到尾梳理才能知道当前的真实状态。这不仅效率低下，还容易出错。

1.2 上下文窗口的物理限制

除了信息质量的问题，还有一个更现实的限制：上下文窗口的容量是有限的。

即使是最先进的大模型，其上下文窗口也有上限。当对话历史超过这个上限时，早期的内容就会被截断。这意味着什么？意味着 AI 可能会"忘记"任务最初的目标和背景。

更糟糕的是，上下文越长，AI 的注意力就越分散。研究表明，大模型在处理长上下文时，对中间部分内容的关注度会显著下降（这就是著名的"中间丢失"问题）。

1.3 问题的症结：对话流不适合当"大脑"

综合以上分析，我们可以得出一个核心结论：

对话流（Chat）只适合短暂的指令交互，而不适合作为 AI Agent 的长期记忆载体。

这就好比人类的工作方式：我们不会把所有的工作内容都记在脑子里，而是会使用笔记、文档、待办清单等外部工具来辅助记忆和管理任务。AI Agent 也需要类似的"外部大脑"。

这正是 Planning-with-Files 要解决的核心问题。

🤔 planning-with-files

最近在 GitHub 上看到一个非常有意思的项目——planning-with-files。

短短时间就冲上了12K+ Star，作者是独立开发者Othman Adi。它本质上是一个Claude Code Skill，但解决的问题，却是所有用大模型写代码、做研究的人都会遇到的痛点：AI 太容易“失忆”，长任务做到一半就跑偏了。

它的核心思路很直接：把计划、任务、上下文和运行状态，全部用 Markdown 文件存在本地或 Git 仓库里。

简单说，就是把“文件系统”当成 AI 的外挂硬盘 + 记事本 + 进度表。

如果你也经常被 AI 的“金鱼记忆”困扰，或者想把 AI 的工作流真正工程化，这个项目值得你花时间了解一下。

---

🤔 为什么需要 planning-with-files？

先问大家一个问题：你有没有遇到过这种情况？

让 AI 写一个中等规模的功能，聊着聊着，它突然问你：“你到底想实现什么来着？”

让它研究一个复杂问题，前面 30 轮对话的信息，到后面它基本就忘了。

同一个错误，AI 反复踩坑，因为它根本不记得自己之前是怎么失败的。

这背后其实是三个硬伤：

• 上下文窗口有限：大模型能同时记住的内容就那么多，聊多了，早期的关键信息就被挤出去了。
• 状态只存在内存里：一旦你清空对话、重启终端，AI 就“失忆”了，前面干了啥、卡在哪，全没了。
• 缺少统一的“工作记忆”：搜索结果、代码片段、错误日志散落在各处，AI 无法形成连贯的认知。

业内把这叫做“上下文工程”（Context Engineering）——与其指望模型自己长记性，不如用工程化的方式，把记忆外置到文件系统中。

而planning-with-files做的，就是把这套思路做成了一个开箱即用的 Claude Code Skill。

---

🚀 项目由来：逆向工程 Manus

说到这里，就不得不提Manus。

这家公司被 Meta 以约20 亿美元收购，核心卖点不是模型有多大，而是它做复杂任务时极其稳定的表现。Manus 把自己的秘诀总结为一套“上下文工程原则”，其中最核心的一条就是：

Markdown 是我在磁盘上的工作记忆。

Manus 会把目标、计划、调研笔记、最终产出，全部用 Markdown 文件管理。每次行动前读计划，行动后写笔记，这样即使执行几十上百步，它也不会迷路。

planning-with-files的作者 Othman Adi 把这套工作流“逆向工程”出来，做成了一个开源的 Claude Code Skill。你可以理解为：

Manus 的核心工作流 + 上下文工程原则 = planning-with-files

它的目标很明确：让普通开发者也能用上 Manus 那套强大的上下文工程能力，而不只是大厂玩家。

---

🗂️ 核心用法：三文件工作流

安装好这个 Skill 后，每当你开启一个复杂任务，它就会在当前目录生成一套“三文件工作流”：

task_plan.md：总指挥

记录任务目标、拆解的阶段、当前进度、下一步要做什么，以及遇到的错误和解决方案。相当于 AI 的“项目计划 + 进度表 + 错误日志”。

notes.md或 findings.md：知识库

存放调研资料、网页摘要、代码片段、临时想法。AI 会把长文本“卸载”到这里，而不是塞满上下文，从而节省 Token 并保持思路清晰。

[deliverable].md：最终交付物

比如 report.md、game.py等。它只存放最终产出，把“思考过程”和“最终成果”物理隔离，方便你直接使用或二次加工。

这个 Skill 还会强制 AI 遵循一套严谨的工作循环：

读计划 → 执行一步 → 写笔记/更新计划 → 检查错误 → 回到读计划

通过这种机制，AI 在多轮对话后依然能清楚地知道“我是谁、我在哪、我要干嘛”。

---

👍 核心优点

真正的“断点续传”

即使你清空对话、重启终端，只要 task_plan.md和 notes.md还在，AI 就能立刻从上次中断的地方继续，完全不用担心“做到一半全没了”。

与 Git 工作流无缝集成

所有计划和记录都是纯文本 Markdown，天然支持版本控制、差异对比和代码审查。团队可以对任务变更进行评审，出了问题也能轻松回滚。

极致的 Token 效率

长文档、搜索结果都存到文件里，上下文里只保留必要的摘要和路径。这不仅省钱，也让 AI 更容易抓住重点，减少“被无关信息淹没”的情况。

高度可扩展

它只是一个 Skill，你可以很方便地在现有项目中引入，或者基于它的思路开发自己的 Agent。社区也有基于它思想用 Go 实现的版本，说明这套模式具有很强的通用性。

对开发者友好

你不需要学习新的复杂平台，只需要会用 Git 和 Markdown 就行。AI 帮你把流程固化下来，你负责决策和把关，这才是真正的“人机协作”。

---

⚔️ 同类方案对比

方案类型	代表项目	核心思路	优缺点
AI 规划插件	planning-with-files	用文件做外部记忆，强制 AI 遵循“读-做-记”的循环。	优点：轻量、与开发工具深度集成、适合工程化。 缺点：目前主要绑定 Claude Code，通用性有待扩展。
通用 Agent 框架	LangChain, AutoGen, CrewAI	通过代码定义 Agent、任务和工具，流程更灵活。	优点：灵活性高，可定制性强。 缺点：需要编写代码，对工程能力要求高，状态管理需自行设计。
云端 AI 工作台	Notion AI, Coda Brain	在 SaaS 产品内提供 AI 辅助的笔记、文档和项目管理功能。	优点：开箱即用，协作方便。 缺点：数据在对方平台，定制性和可控性弱，与本地代码库集成不便。

简单来说，planning-with-files的优势在于它足够轻、足够贴近开发者的日常工具链，同时又把“上下文工程”的核心思想真正落地了。

---

🎯 适用场景

• 多步骤复杂任务：如从零开始搭建一个项目、重构一个复杂模块。
• 深度研究：如技术调研、竞品分析、撰写长篇报告。
• AI 技能开发：作为你自己的“Agent 脚手架”，沉淀最佳实践。
• 团队知识沉淀：用 Git 管理 AI 的工作记录，形成可追溯的知识库。

当然，它也不是万能的。对于“帮我写个冒泡排序”这种一句话就能搞定的小问题，用它反而有点“杀鸡用牛刀”。

---

🔗 项目地址

如果你也想试试给 AI 装上“外挂大脑”，不妨去看看这个项目：

最后想说，planning-with-files 真正打动我的，不是它有多少 Star，而是它用一种非常朴素的方式，把“工程化”的思想带给了 AI 应用。

它让我们意识到：与其等待更强的模型，不如先把流程和记忆管理好。

毕竟，再聪明的 AI，也需要一个靠谱的记事本。