OthmanAdi/planning-with-files · 上手攻略

  • 仓库：OthmanAdi/planning-with-files
  • 链接：https://github.com/OthmanAdi/planning-with-files
  • 分类：skill
  • 作者：Tom
  • 更新：2026-07-06

是什么

planning-with-files 是一个持久化文件规划技能（SKILL.md 标准），让 AI 编程 Agent 在长运行时任务中不丢失计划、不因上下文丢失（/clear、崩溃、重启）而中断。它模拟 Manus（Meta 以 20 亿美元收购的 AI Agent 公司）的规划风格，把任务计划写在磁盘文件里，让 Agent 每次启动都能恢复现场。

核心设计哲学：计划不活在内存里，活在磁盘上。

解决什么问题

  • 上下文丢失即失忆：Claude Code 等工具遇到 /clear 或上下文窗口耗尽后，Agent 完全丢失之前的进度
  • 长任务无法中断续跑：复杂重构可能耗时数小时，没有机制让 Agent 知道自己"做到哪了"
  • 多 Agent 协作状态同步：多个 Agent 同时处理同一项目时，没有共享状态文件
  • 无法确定性判定完成：Agent 声称"完成了"，但没有客观机制验证是否真正达到目标

快速安装

方式一：Claude Code 插件安装（推荐）

/claude plugin install planning-with-files

方式二：npx 安装（通用）

npx skills add planning-with-files

方式三：手动克隆

git clone https://github.com/OthmanAdi/planning-with-files.git
# 按文档将 SKILL.md 放入 ~/.claude/skills/ 目录

安装后，在 Claude Code 中初始化会话：

# 标准模式
/init-session

# 自主模式（v3+，强模型用，不每步重新注入计划）
/init-session --autonomous

# 门控模式（v3+，带完成判定门，长任务用）
/init-session --gated

核心用法

核心文件

文件 作用
task_plan.md 任务计划，分 phases，含目标、依赖、验收条件
findings.md 调研发现、决策记录
progress.md 进度追踪，记录当前 phase 状态
run_ledger.jsonl v3+ append-only 运行账本，记录每次操作
.attestation 计划完整性签名，防篡改

常用命令（Claude Code 内）

# 初始化会话（创建/恢复 plan）
/init-session

# 开始新目标
/plan-goal "实现用户登录功能，包含注册和找回密码"

/# 循环执行（Agent 自主规划每步）
/plan-loop

# 查看当前状态
/plan-status

# 签署计划（完整性锁定）
/plan-attest

# 恢复（/clear 后恢复上下文）
/restore-context

v3.0 新增：门控模式（Completion Gate）

--gated 模式下，Agent 遇到 /stop 时，钩子（gate-stop.sh）会检查五个条件：

  1. 处于 gated 模式
  2. 有 in_progress phase
  3. stop_hook_active = false
  4. block 次数未超上限
  5. ledger 相比上次有推进

五项全满足才阻断退出，否则正常退出。防止 Agent 被"困在"未完成的 plan 里。

v3.0 新增：自主模式（Autonomous Mode）

--autonomous 下，省去每步重新注入 plan 的开销，适合强模型（Claude Sonnet 4/5、GPT-4o）持续自主工作。每轮开始仍注入 plan，但不再每步强制重注。

支持的 Agent（60+）

Claude Code、Codex CLI、Cursor、Kiro、OpenCode、Cline、Bolt、Continue、Copilot、Fractal（部分）、Gemini CLI 等。

详见仓库 SKILL.md 的 Agent 兼容性列表。

典型适用场景

  1. 大型代码重构：涉及多文件、长链路、可能需要数小时的任务
  2. Manus 式长时 Agent：模拟 Meta收购的 Manus 的规划流程
  3. 多 Agent 协作：不同 Agent 读写同一 task_plan.md，通过磁盘状态同步
  4. 自动驾驶评测：completion gate 提供可量化的完成判定
  5. 上下文受限的长时任务：KV-cache 压缩后，需要 plan 文件来承托记忆

坑与注意

  1. v3.0 有破坏性变化吗：官方明确说明"no breaking changes"，现有安装无需修改，但新功能（gated/autonomous）需手动开启
  2. Windows 路径问题：v3.2.0 修复了 Windows 下 session-catchup.py 不工作的问题，老版本在 Windows 上 /restore-context 可能失效
  3. Slug 模式冲突：v2.40 修复了 slug-mode 与 legacy root 的冲突，如果同时安装了多个变体，可能出现计划目标跳变
  4. Attestation 是可选的：签名机制默认开启但可以关闭，关闭后计划内容可被篡改（适合开发调试）
  5. Plugin vs Skill 差异：/plugin install 会携带 commands/ 文件（含 /plan-goal、/plan-loop），但 npx skills add 不包含，需要直接调用 Claude Code 原生 /goal 和 /loop 命令
  6. Agentfund 类项目：社区出现了基于此 skill 的变体（如众筹 Agent），可能涉及资金风险，请自行判断

与同类对比

工具 持久化方式 门控机制 多 Agent 生态广度
planning-with-files 磁盘 Markdown + JSONL ✅ Completion Gate ✅ 文件共享 60+ Agent
Cline Memory 会话级记忆文件 ❌ ❌ 仅 Cline
Claude Code 内置 /plan 会话级，无文件 ❌ ❌ 仅 Claude Code
Continue 向量数据库 ❌ 有限 Continue 自有
Memex / Kilo 本地知识库 ❌ ❌ 通用

planning-with-files 的核心优势：磁盘即记忆，gate 即合同。把任务计划写死在文件里，任何 Agent 重启都能读取；completion gate 让"做完"有客观标准，不再是 Agent 说了算。

一句话推荐结论

长链路 AI 编程任务必备——planning-with-files 用三个 Markdown 文件和一个完成判定门，让 Agent 真正做到"记着目标、知道进度、做完了就是做完了"，是 Manus 风格 Agent 工作流的平民化实现。

来源：GitHub README (https://github.com/OthmanAdi/planning-with-files)、v3.0.0 release notes、Web Search 社区生态补充