Planning with Files
让编码代理用磁盘计划跨越清空、崩溃与压缩。
按维度查看评分与理由
证据显示：脚本以最小权限运行，无网络调用，文件操作限于项目目录；有用户确认机制（如Pi的/plan-execute）；数据流透明（文档说明注入格式和钩子）；敏感数据处理有SHA-256校验和路径隔离；无外部依赖；外部影响限于本地文件写入；回滚机制有限（无自动回滚，但可手动恢复）；来源归属明确（MIT许可，作者署名）。扣分：回滚机制不完善，未提供自动回滚或备份。
证据显示：脚本逻辑一致，测试覆盖同步和跨项目保护；依赖可用性高（无外部依赖，使用系统工具）；失败消息明确（如plan-doctor）。扣分：未发现明显缺陷，但静态审查无法验证运行时行为。
证据显示：面向多种AI代理和场景，提供详细的分层支持；能力边界清晰（如钩子限制）；触发机制精确（如/plan命令）；环境适配广泛（支持多种IDE和操作系统）。扣分：部分平台支持可能未完全验证。
证据显示：信息架构清晰（README、docs、tests）；安装说明详细；命名稳定（版本化命令）；示例和FAQ丰富；已知限制有说明；MIT许可明确；版本变更记录存在；维护责任明确（作者维护）。扣分：版本变更记录可能不完整。
证据显示：输出可用性高（计划文件格式清晰）；边际价值高（解决上下文丢失问题）；成本效益合理（安装简单，性能开销小）。扣分：成本效益未量化，缺乏性能基准。
证据显示：声明可追溯（README引用文档和测试）；跨来源佐证有限（主要依赖自身文档）；事实与推断分离（明确标注内部基准）。扣分：跨来源佐证不足，缺乏独立验证。
- 静态审查无法验证运行时行为，建议进行实际测试。
- 回滚机制不完善，建议在关键操作前备份计划文件。
- 跨来源佐证不足，建议参考独立评估或社区反馈。
这个 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 有哪些优点和局限？
- 三文件结构把活动执行状态落盘，并通过每轮计划注入降低 /clear、崩溃和压缩导致的上下文丢失。
- 为 Claude Code 和 Codex 提供明确的生命周期钩子配置，而不仅是提示词式规划。
- 提供会话恢复、SHA-256 计划证明、JSONL 运行账本和并行计划隔离等针对长任务的机制。
- 仓库同时提供 Claude Code 插件、Agent Skills 安装和多平台镜像，覆盖增强与标准两类集成。
- 完整自动化依赖宿主平台钩子；标准 Agent Skills 路径可能只提供文件模式，且安装后可能静默缺少钩子。
- 规划文件默认被 gitignore，完成后不会自动归档；根目录计划会被下一项任务覆盖，需自行保留重要记录。
- 会话恢复依赖特定 IDE 的本地会话存储和路径解析，发布记录显示该功能曾出现跨平台与特殊路径问题。
- 96.7% 通过率及恢复轮次来自作者运行的内部评测，衡量的是文件模式遵循和重定位成本，不能视为独立的长期任务效果验证。
如何安装或部署这个 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 与同类方案有什么区别？
它与记忆工具的定位不同：向量库或知识图谱用于跨会话回忆事实，而本项目管理当前任务的阶段、依赖、错误和完成状态。它也不是 Claude Code Plan Mode 的替代品；Plan Mode 用于设计并批准方案，本项目用于在执行期间持久化并重新注入实时计划。