Planning with Files —— AI Agent 的持久化工作记忆

发表于 分类于
深入解析 planning-with-files 如何通过三文件模式（task_plan / findings / progress）将 AI Agent 的上下文窗口从挥发性内存扩展为持久化磁盘存储，实现目标不漂移、错误可追溯的工程化工作流。

简介

2025 年 12 月，Meta 以 20 亿美元收购了 AI Agent 公司 Manus。这家成立仅 8 个月的公司，年收入已突破 1 亿美元。Manus 成功的秘诀是什么？上下文工程（Context Engineering）。

Manus 官方博客中有一段话：

“Markdown 是我在磁盘上的’工作记忆’。由于我以迭代方式处理信息，且活跃上下文有限，Markdown 文件充当了便签、检查点和最终交付物的构建块。”

这正是 planning-with-files 技能的核心思想。

问题：AI Agent 的记忆困境

当前主流的 AI 编程 Agent（Claude Code、Cursor、Copilot 等）普遍面临以下问题：

挥发性记忆。 Agent 的 TodoWrite 等工具将任务列表保存在上下文窗口中，一旦执行 /clear 或上下文压缩，所有规划信息就消失了。

目标漂移。 经过 50 次以上的工具调用后，Agent 往往会忘记最初的目标。它开始偏离主干，在无关细节上钻牛角尖。

错误不可追溯。 错误被即时处理但未被记录。当 Agent 再次遭遇同样的失败时，它会重复相同的错误尝试。

上下文膨胀。 所有中间结果都被塞进上下文窗口，而不是写入持久化存储。上下文窗口很快被填满，后续推理质量下降。

方案：三文件模式

planning-with-files 定义了一个简单的三文件工作模式：

task_plan.md    → 追踪阶段与进度
findings.md     → 存储研究与发现
progress.md     → 记录会话日志与测试结果

核心原则只有一条：

上下文窗口 = 内存（易失、有限）
文件系统     = 磁盘（持久、无限）

→ 重要的东西写进磁盘。

task_plan.md —— 任务规划

这是整个工作的「方向盘」，包含：

  • Goal：任务目标
  • Phases：拆分为 3-7 个阶段，每阶段带 [ ] 复选框和 **Status:** pending/in_progress/complete
  • Decisions：重大技术决策及理由
  • Errors：记录所有错误及解决方案

findings.md —— 研究发现

这是「知识库」，存放：

  • 搜索结果、文档链接
  • 技术调研的发现
  • 决策的理由和权衡

progress.md —— 进度日志

这是「工作日志」，按时间线记录：

  • 每个阶段开始/结束时间
  • 执行的操作、修改的文件
  • 测试结果
  • 错误日志（带时间戳）

五大核心规则

规则 含义
先建计划 永远不要在创建 task_plan.md 之前开始工作
2 操作规则 每执行 2 次浏览/搜索操作后，必须更新 findings.md
记录所有错误 即使立即解决的错误也要记录，避免重复踩坑
不重复失败 记录每次尝试，失败后必须换方案
持续完成验证 Stop Hook 自动检查所有阶段是否标记为 complete

Hook 机制：注意力操控

planning-with-files 真正的工程创新在于 Hook 系统。它通过 Claude Code 的生命周期钩子，在关键时刻自动介入：

Hook 触发时机 行为
SessionStart 会话开始时 自动恢复上次会话状态，注入 catchup 报告
PreToolUse Write/Edit/Bash 操作前 重新读取 task_plan.md，将目标刷新到注意力窗口
PostToolUse Write/Edit 操作后 提醒更新阶段状态
Stop Agent 尝试停止时 检查所有阶段是否完成，未完成则阻止退出
PreCompact 上下文压缩前 提醒刷新进度日志，防止信息丢失

PreToolUse Hook 是整套机制的关键——它在每次工具调用前将计划重新注入 Agent 的注意力窗口，从根本上解决了目标漂移问题。

但这也带来了独特的安全风险。2025 年的安全审计揭示了一条危险的攻击链：

WebSearch(恶意站点) → 内容写入 task_plan.md
→ Hook 在下一次工具调用前读取 task_plan.md
→ Hook 在下下次工具调用前再次读取
→ 恶意指令被无限放大

v2.21.0 版本修复了这一问题：从技能声明中移除 WebFetch / WebSearch，并添加了安全边界规则——网页搜索结果只能写入 findings.md，绝不能写入 task_plan.md。

并行计划与目录隔离

v2.36.0 引入了并行计划支持，允许同一仓库中存在多个独立的计划目录：

.planning/
  2026-01-10-backend-refactor/
    task_plan.md / findings.md / progress.md
  2026-01-10-production-incident/
    task_plan.md / findings.md / progress.md

使用 init-session.sh <slug> 创建独立计划，使用 set-active-plan.sh <plan-id> 切换活跃计划。Hook 会自动解析当前活跃的计划目录。

此外，对于跨多个会话的长期运营主题，还提供了 Topic Handoff 模式：

progress.md                 ← 运行时间线和简短索引
handoffs/<topic>.md         ← 当前状态、命令、验证、风险、回滚方案

五问重启测试

判断上下文管理是否扎实，只需回答五个问题：

问题 答案来源
我在哪？ task_plan.md 中的当前阶段
我去哪？ task_plan.md 中的剩余阶段
目标是什么？ task_plan.md 中的 Goal 声明
我学到了什么？ findings.md
我做了什么？ progress.md

基准测试

使用 Anthropic 的 skill-creator 框架进行的正式评估（10 个并行子 Agent，5 类任务，30 项断言，3 次盲测）：

测试配置 通过率 通过数
启用 skill 96.7% 29/30
未启用 skill 6.7% 2/30
差值 +90 个百分点 +27/30

盲测 A/B 对比：启用 skill 的 Agent 在所有 3 次对比中均获胜（评分 10.0 vs 6.0 / 10.0 vs 6.3 / 10.0 vs 8.0）。

未启用 skill 的 Agent 并非产出低劣——它们生成了可运行的代码、合理的研究对比、详细的迁移计划。但没有任何一个遵循了结构化的规划流程。而这正是 skill 的全部价值所在。

多平台支持

planning-with-files 目前已支持 17+ 个平台和 IDE，包括 Claude Code、Cursor、GitHub Copilot、Gemini CLI、Codex、Kiro、CodeBuddy、FactoryAI、OpenCode、Continue、Pi Agent、OpenClaw、Antigravity、Kilocode、AdaL CLI、Mastra Code、Hermes 等。同时提供阿拉伯语、德语、西班牙语、简体中文和繁体中文版本。

适用场景

适合使用：

  • 需要 3 步以上的多阶段任务
  • 调研类任务
  • 构建 / 创建项目
  • 涉及大量工具调用的任务

不需要使用：

  • 简单问答
  • 单文件修改
  • 快速查找

安装与使用

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

安装后使用 /plan 或 /planning-with-files:plan 启动计划会话。

总结

planning-with-files 本质上是一套编码化的工程纪律。Claude 本身能够做规划，这个 skill 并不赋予它新的能力——而是将一套经过验证的结构化工作流编码为可复用的模式。

它巧妙地将「上下文窗口是稀缺资源」这一约束转化为了工程优势：通过文件系统建立持久化工作记忆，通过 Hook 系统实现注意力操控，通过阶段状态追踪确保任务闭环。

Manus 用这套方法在 8 个月内从零做到 20 亿美元估值。而 planning-with-files 将同样的模式以开源、跨平台的方式带给了每一位 AI Agent 用户。

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