Context Engineering

Planning-with-Files 实测：26k Star 的三文件铁律，让 AI 编程不再失忆

作者
Planning-with-Files 实测：26k Star 的三文件铁律，让 AI 编程不再失忆

你有没有经历过这种崩溃？

花了 2 小时让 Claude Code 做一个 Django 迁移，50+ 工具调用后上下文窗口炸了。/clear 一敲，Agent 一脸茫然问你：”请问您要做什么？”

这不是 bug，这是所有 AI 编程 Agent 的结构性缺陷：上下文窗口 = RAM，关机就清零。Manus AI 在被 Meta 收购前想明白了这件事——用文件系统当持久记忆，而不是把所有东西塞进上下文。

Planning-with-Files 就是这个思路的标准化实现：3 个 Markdown 文件 + Hook 自动注入，让 Agent 的”工作记忆”写在磁盘上，/clear 崩溃、上下文压缩、Session 断裂全不怕。26k Star、96.7% 断言通过率、3/3 盲测 A/B 全胜——这是目前持久化规划领域数据最硬的 Skill。

—

工作原理：三文件 + Hook 注入循环

核心模型

Context Window = RAM（易失、有限）
Filesystem    = Disk（持久、无限）

→ 任何重要东西都写到磁盘上

三个文件各管什么

文件 职责 更新时机
task_plan.md 阶段划分 + 进度追踪 + 决策记录 每完成一个阶段
findings.md 研究笔记 + 发现 + 决策依据 任何新发现
progress.md Session 日志 + 测试结果 全程持续记录

Hook 注入循环（5 个生命周期钩子）

Agent 工作 → 写决策/发现/错误到文件
     ↓
Hook 每轮开始时重新注入文件内容到上下文
     ↓
/clear 或崩溃 → 文件还在 → 新 Session 读文件恢复
     ↓
所有阶段完成 → Stop Hook 检查 → 释放完成信号

5 个 Hook 分别是：

  1. UserPromptSubmit — 每轮用户输入前注入计划
  1. PreToolUse — 每次工具调用前注入计划
  1. PostToolUse — Write/Edit 后提醒更新 progress.md
  1. Stop — 完成检查门控（gated 模式下阻止提前退出）
  1. PreCompact — 压缩前提醒刷盘

与 Manus AI 的关系

2025 年 12 月 Meta 以 20 亿美元收购 Manus。Manus 的核心秘密就是上下文工程：用 Markdown 文件当”磁盘上的工作记忆”。Planning-with-Files 把这个模式打包成了标准化 Skill，装到任何 Agent 上就能用。

—

功能拆解：五大模块逐个分析

1. 三文件模板系统

一句话：标准化的 task_plan.md、findings.md、progress.md 模板，带完整注释说明每个字段的用途。

核心能力：

  • 模板自带 Goal / Next Step / Current Phase / Phases / Decisions / Errors 结构
  • Phase 支持 pending → in_progress → complete 状态流转
  • 决策表和错误表结构化记录，避免重复犯错

适用场景：任何 3+ 步骤或 5+ 工具调用的复杂任务。

2. Hook 自动注入引擎

一句话：5 个生命周期 Hook 让计划文件每轮自动注入上下文，Agent 不需要”记得去读”。

核心能力：

  • UserPromptSubmit / PreToolUse 双保险注入
  • PostToolUse 提醒更新进度
  • Stop Hook 门控完成（gated 模式）
  • PreCompact 压缩前刷盘提醒

适用场景：长任务（50+ 工具调用），防止目标漂移。

3. Session 恢复系统

一句话：/clear 或崩溃后，自动从 IDE Session Store 读取历史对话 + 从文件恢复计划状态。

核心能力：

  • session-catchup.py 自动发现历史 Session
  • 提取上下文丢失后的对话片段
  • 生成恢复报告，帮助 Agent 快速补回状态

实测数据：恢复平均 5.0 turns（裸 Agent 13.3 turns），提速 62%。

适用场景：上下文窗口不够用、需要多次 /clear 的超长任务。

4. 并行任务隔离

一句话：v2.36.0+ 支持 .planning/YYYY-MM-DD-slug/ 目录隔离，多个并行任务互不干扰。

核心能力：

  • .active_plan 文件指向当前激活的计划目录
  • resolve-plan-dir.sh 智能解析计划路径
  • 防止共享父目录的线程注入无关计划

适用场景：多 Agent 并行、多任务交叉执行。

5. v3 长任务增强

一句话：Autonomous 模式 + Gated 完成门控 + Attestation 计划防篡改 + JSONL 运行日志。

核心能力：

  • --autonomous：去掉逐轮计划复述，保留注入
  • --gated：所有阶段完成前阻止 Agent 退出
  • SHA-256 Attestation：计划被篡改时 Hook 拒绝注入
  • JSONL Ledger： append-only 运行日志，可审计

适用场景：数小时级自主运行、需要保证完成质量的无人值守任务。

—

实测数据：有 Skill vs 没 Skill

Benchmark 总览（v2.21.0，claude-sonnet-4-6，2026-03-06）

测试项 有 Skill 无 Skill 差距
断言通过率（30 项） 96.7%（29/30） 6.7%（2/30） +90.0 pp
三文件模式遵循 5/5 0/5 +100%
盲测 A/B 胜率 3/3（100%） 0/3 全胜
平均评分（10 分制） 10.0 6.8 +3.2

Token 成本对比

维度 有 Skill 无 Skill 差距
平均 Token 19,926 11,899 +68%
平均耗时 115s 98s +17%

结论：多花 68% Token 换 96.7% 结构化输出——这是一笔划算的交易。额外 Token 花在创建 3 个文件、填充决策表和错误表上，不是浪费。

Session 恢复实测（v3.4.0 内部基准，2026-07-06）

恢复方式 恢复所需 Turn 数 正确性
Planning-with-Files 5.0 77/77 pytest 全绿
裸 Agent（无规划） 13.3 77/77 pytest 全绿

恢复提速 62%，零正确性惩罚。两者最终都能完成任务，但有 Skill 的快了将近 3 倍。

盲测 A/B 评语摘录

“Output B（有 Skill）满足所有四项结构化工作流期望……Output A（无 Skill）交付了真实可运行的代码，但不符合结构化多阶段规划格式。” — Eval 1 评审

“Output B 还包含了 pytz/zoneinfo 迁移（4.2 特有问题，Output A 完全遗漏）以及 django-upgrade 工具推荐……18,727 字符 vs 12,847，信息密度更高。” — Eval 4 评审

—

安装方式 + 适用场景 + 结语

安装（一行命令）

# Claude Code（插件路由，含 Hook + 斜杠命令）
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

# 60+ Agent 通用（Agent Skills 标准）
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

# npm 锁版本到项目
npm install planning-with-files

安装后输入 /plan 或让 Agent “plan this task” 即可触发。

最适合谁

角色 为什么需要
独立开发者 一个人做复杂项目，需要跨 Session 记住进度
长任务工程师 数小时级 Agent 运行，目标漂移是最大敌人
多 Agent 协作 并行任务隔离 + 计划防篡改
AI 编程初学者 结构化输出强制养成好习惯

不太适合谁

  • 简单 CRUD / 一次性脚本：3 步以内的任务不需要三文件，反而增加摩擦
  • 已有 ECC 等系统级方案的团队：ECC 的 Agent Harness 已经覆盖了规划功能，重复叠加意义不大
  • Token 预算极紧的场景：多花 68% Token 不是所有人都能接受

一句话结语

Planning-with-Files 解决的是 AI 编程中最痛的结构性问题——上下文易失。它的数据足够硬（96.7% 通过率、3/3 A/B 全胜），架构足够通用（60+ Agent、18+ IDE），代价也足够清晰（+68% Token）。如果你的 Agent 经常在长任务中失忆，这是目前最成熟的解法。

—

数据来源：GitHub OthmanAdi/planning-with-files README + docs/evals.md，截至 2026-08-27。

相关阅读：

⚠️ 本文为技术评测，非付费推广。Planning-with-Files 为 MIT 开源项目。