Planning with Files
让编码代理用磁盘计划跨越清空、崩溃与压缩。
- Star 数
- ★ 28k
- 最近更新
- 1 天前
- License
- MIT
- 主语言
- Shell
- FA 评分
- 73/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 兼容但需适配Codex · Claude Code
- 费用
- 免费，无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 使用 Claude Code 重构认证中间件的工程师，需要在 /clear 后从未完成的测试阶段继续。
- 不适合
- 需要所有平台都具备完整生命周期钩子的团队
- 需要自动归档并纳入版本控制的规划记录的团队
- 寻求长期跨会话知识检索的用户
- 源码审查
- 73/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
Planning with Files 是面向 AI 编码代理和长任务的持久化规划技能。它在项目中维护 task_plan.md、findings.md 与 progress.md 三个 Markdown 文件，将阶段、研究发现、操作日志和测试结果保存到磁盘。Claude Code、Codex 等增强集成会通过生命周期钩子在每轮重新注入计划，并在压缩或停止前提示或检查进度。它还提供会话恢复、计划 SHA-256 证明、并行任务隔离目录和可选的完成门控。该项目以 Claude Code 插件或 Agent Skills 安装方式交付；非增强平台可使用同一文件模式，但未必拥有完整的钩子自动化。
对于多步骤任务，技能先创建 task_plan.md、findings.md 和 progress.md；任务阶段与复选框写入 task_plan.md，新发现追加到 findings.md，已执行操作和测试结果记录到 progress.md。UserPromptSubmit 钩子会把磁盘中的计划以 ===BEGIN PLAN DATA=== 区块注入上下文；Claude Code 还列出 PreToolUse、PostToolUse、Stop 和 PreCompact，Codex 则配置 SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PreCompact 和 Stop 等钩子。session-catchup 会检查相应 IDE 的会话存储、比较规划文件更新时间并生成补同步信息。可选的 /plan-attest 使用 SHA-256 锁定 task_plan.md，/pwf --autonomous 或 --gated 可启用长运行模式，.planning/YYYY-MM-DD-slug/ 与 .active_plan 用于隔离并行计划。
- 使用 Claude Code 重构认证中间件的工程师，需要在 /clear 后从未完成的测试阶段继续。
- 用 Codex CLI 处理包含调研、修改和验证的长任务，希望每轮都能看到当前计划。
- 同时推进多个互不相关任务的开发者，需要用 .planning/YYYY-MM-DD-slug/ 分开保存各自的计划状态。
- 维护 Cursor、GitHub Copilot 或 Kiro 工作流的团队，希望在支持钩子的宿主中加入计划注入和完成检查。
- 在会话崩溃或上下文压缩后接手项目的编码代理用户，需要从磁盘中的阶段、发现和日志重新定位工作。
如何安装或部署这个 Agent？
Claude Code 插件方式：先运行 /plugin marketplace add OthmanAdi/planning-with-files，再运行 /plugin install planning-with-files@planning-with-files。其他支持 Agent Skills 的代理可在 shell 中运行 npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g；该方式需要可用的 npx 与网络访问。插件方式包含斜杠命令和钩子；技能方式可能因项目未接受信任或前置钩子未注册而没有钩子。
如何使用这个 Agent？
在 Claude Code 中输入 /plan 或 /pwf 创建规划文件并开始会话；也可直接要求代理“plan this task”。执行过程中将发现写入 findings.md、将操作和测试结果写入 progress.md，并在 task_plan.md 勾选完成阶段。需要长运行模式时，可用 /pwf --autonomous 或 /pwf --gated；需要诊断安装和注入时运行 /plan-doctor。Pi 上先由技能创建文件，再以 /plan-execute 显式激活钩子。
这个 Agent 有哪些优点和局限？
- 三文件结构把活动执行状态落盘，并通过每轮计划注入降低 /clear、崩溃和压缩导致的上下文丢失。
- 为 Claude Code 和 Codex 提供明确的生命周期钩子配置，而不仅是提示词式规划。
- 提供会话恢复、SHA-256 计划证明、JSONL 运行账本和并行计划隔离等针对长任务的机制。
- 仓库同时提供 Claude Code 插件、Agent Skills 安装和多平台镜像，覆盖增强与标准两类集成。
- 完整自动化依赖宿主平台钩子；标准 Agent Skills 路径可能只提供文件模式，且安装后可能静默缺少钩子。
- 规划文件默认被 gitignore，完成后不会自动归档；根目录计划会被下一项任务覆盖，需自行保留重要记录。
- 会话恢复依赖特定 IDE 的本地会话存储和路径解析，发布记录显示该功能曾出现跨平台与特殊路径问题。
- 96.7% 通过率及恢复轮次来自作者运行的内部评测，衡量的是文件模式遵循和重定位成本，不能视为独立的长期任务效果验证。
这个 Agent 与同类方案有什么区别？
它与记忆工具的定位不同：向量库或知识图谱用于跨会话回忆事实，而本项目管理当前任务的阶段、依赖、错误和完成状态。它也不是 Claude Code Plan Mode 的替代品；Plan Mode 用于设计并批准方案，本项目用于在执行期间持久化并重新注入实时计划。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Planning with Files 当前 | 73 · 存在缺口 | Agent 插件 / 技能免费 | ★ 28k | 1 天前 | Shell | Codex · Claude Code |
| jev-axi 安全判断 CLI | 90 · 表现良好 | 命令行工具免费 + 模型费 | ★ 47 | 13 天前 | TypeScript | Claude Code |
| Elephant-Goldfish Model (EGM) | 75 · 表现良好 | Agent 插件 / 技能免费 + 模型费 | ★ 12k | 今天 | Python | Codex · Claude Code |
| Finding-Unknowns Skills | 76 · 表现良好 | Agent 插件 / 技能免费 | ★ 362 | 1 个月前 | Python | Claude Code · Claude.ai |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：脚本以最小权限运行，无网络调用，文件操作限于项目目录；有用户确认机制（如Pi的/plan-execute）；数据流透明（文档说明注入格式和钩子）；敏感数据处理有SHA-256校验和路径隔离；无外部依赖；外部影响限于本地文件写入；回滚机制有限（无自动回滚，但可手动恢复）；来源归属明确（MIT许可，作者署名）。扣分：回滚机制不完善，未提供自动回滚或备份。
证据显示：脚本逻辑一致，测试覆盖同步和跨项目保护；依赖可用性高（无外部依赖，使用系统工具）；失败消息明确（如plan-doctor）。扣分：未发现明显缺陷，但静态审查无法验证运行时行为。
证据显示：面向多种AI代理和场景，提供详细的分层支持；能力边界清晰（如钩子限制）；触发机制精确（如/plan命令）；环境适配广泛（支持多种IDE和操作系统）。扣分：部分平台支持可能未完全验证。
证据显示：信息架构清晰（README、docs、tests）；安装说明详细；命名稳定（版本化命令）；示例和FAQ丰富；已知限制有说明；MIT许可明确；版本变更记录存在；维护责任明确（作者维护）。扣分：版本变更记录可能不完整。
证据显示：输出可用性高（计划文件格式清晰）；边际价值高（解决上下文丢失问题）；成本效益合理（安装简单，性能开销小）。扣分：成本效益未量化，缺乏性能基准。
证据显示：声明可追溯（README引用文档和测试）；跨来源佐证有限（主要依赖自身文档）；事实与推断分离（明确标注内部基准）。扣分：跨来源佐证不足，缺乏独立验证。
- 静态审查无法验证运行时行为，建议进行实际测试。
- 回滚机制不完善，建议在关键操作前备份计划文件。
- 跨来源佐证不足，建议参考独立评估或社区反馈。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v3.28.0 v3.28.0 - Archive and restore finished plans
发布说明摘录
Added - Opt-in archive and restore for named plans. set-active-plan.sh --archive <id> (PowerShell: -Archive <id>) previews the move to .planning/.archive/<id>/, --yes (-Yes) applies it, and --restore <id> moves a plan back the same way. The directory moves with its sidecars in a single rename. Nothing is deleted and nothing is archived automatically. The shared .active_plan pointer is cleared only when it names the archived plan, and an ID must match the directory name exactly, including case. --list --archived lists archived plans, and the JSON inventory reports `archived_ …在 GitHub 查看 ↗ -
v3.27.0 v3.27.0 - Agent-readable plan inventory
发布说明摘录
Planning agents can request a bounded JSON inventory from the existing listing helpers with --list --json or PowerShell -List -Json. It includes root and named planning-file paths, availability, phase metadata, shared defaults and explicit selection uncertainty. Inventory remains read-only and runs only when requested. Claude plugin commands now follow the selected-plan and initializer contracts. The updates preserve valid pinned legacy roots, initialize from the validated project root, keep status reads compact and delegate attestation to the shipped helpers. …在 GitHub 查看 ↗ -
v3.26.0 v3.26.0 - Claude subagent isolation and hook fixes
发布说明摘录
Added Claude Code can suppress plan context and progress reminders for subagent tool calls with PWF_SKIP_SUBAGENTS=1. The default is unchanged. The opt-in also fails closed when the hook cannot classify its input (#348). Fixed - Preserve existing Codex hook registrations during setup and avoid nested hook directories (PR #345, #343). - Keep Copilot PreToolUse output neutral while using supported context events (PR #346, #344). - Honor PLANNING_DISABLED=1 across Gemini lifecycle hooks, including SessionEnd (PR #347, #329). Thanks …在 GitHub 查看 ↗