持久化文件驱动规划 Skill，让 AI 编程 Agent 在上下文丢失、
/clear、崩溃后仍能继续任务。24.7k stars，MIT 协议，支持 60+ Agent。
核心问题
AI 编程 Agent 的最大弱点：上下文窗口有限，一旦触发 /clear、会话超时或进程崩溃，之前的计划和进度全部丢失，Agent 不得不重头来过。
planning-with-files 通过文件系统作为持久化记忆解决这个问题——计划和进度写入磁盘，Agent 可以随时从中间状态恢复。
核心机制（Manus 模式）
三个关键文件：
| 文件 | 作用 |
|---|---|
task_plan.md | 任务分解计划，Agent 开始前写入，执行中只读 |
findings.md | 研究发现与中间结论，执行过程中持续追加 |
progress.md | 当前进度状态，每步完成后更新 |
这三个文件构成了 Agent 的”外部记忆”，任何恢复场景都能从文件重建上下文。
关键特性
- 确定性完成门（Completion Gate）：任务完成前必须通过
check-complete.sh验证，防止 Agent 提前声称完成 - 多 Agent 共享状态：多个 Agent 通过读写同一组文件协作，无需消息传递
- v3.0+ 三种执行模式：标准模式 / 自主模式（opt-in）/ 有门控模式（gated）
- 多语言支持：中文（简繁）、英语、阿拉伯语、德语、西班牙语
基准表现
- 96.7% 通过率（v2.21.0，claude-sonnet-4-6）
- 3/3 盲测 A/B 胜出
安装
# 通过 npx skills CLI 全局安装
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g支持平台（18+）
Claude Code、Cursor、Codex、GitHub Copilot、Kiro、Gemini CLI、OpenCode、Pi Agent、Continue、CodeBuddy、Factory、Mastra、Hermes、BoxLite 等。
项目结构
planning-with-files/
├── commands/ # /plan、/start 等 Slash 命令
├── templates/ # 三个核心文件的模板
├── scripts/ # init-session.sh、check-complete.sh、attest-plan.sh
├── docs/ # 各平台安装指南
├── skills/ # SKILL.md 多语言变体
└── .claude-plugin/ # Claude Code Plugin 配置
与相关工具的关系
- wezzard-skills — write-plan/execute-plan 同类计划驱动方案，但不做文件持久化
- superpowers — writing-plans/executing-plans 两个 Skill 思路类似，superpowers 更侧重流程纪律
- agent-harness-anatomy — 文件系统作为 Harness primitive 的典型应用
- 12-factor-agents — Factor 5（统一执行状态与业务状态）的直接实践
资源
- GitHub: https://github.com/OthmanAdi/planning-with-files
- 版本: v3.2.0（2026-07-06）