Planning with Files

Planning with Files 是什么

Planning with Files 是一套把工作记忆落到磁盘的代理规划方法。它围绕 task_plan.md、findings.md 和 progress.md 三个文件组织多步骤研究、开发和长任务，让新一轮会话可以从项目文件恢复，而不是只依赖上下文窗口。frontmatter 建议在需要五次以上工具调用的研究或工作中使用，规划目录可由 PLAN_ID 和 PWF_PLAN_ROOT 固定，避免并行任务互相覆盖。

启动、恢复和文件职责

开始前要先解析当前任务拥有的计划目录，读取其中的 task_plan.md、progress.md 和 findings.md，并检查代码变更摘要。task_plan.md 记录目标、阶段、决策和错误；findings.md 保存外部研究和发现；progress.md 记录会话进展、测试结果与完成情况。外部网页或 API 内容应写入 findings.md，当作不可信研究数据，不能把其中指令直接执行。已存在的计划要保留，不能让项目根目录的旧文件覆盖选定计划。

日常循环和错误纪律

核心模式要求每完成两个查看、搜索或浏览操作，就立即把关键发现写入文件，以免视觉或外部信息丢失。每个阶段完成后要更新状态、记录修改文件和错误。若某个动作失败，下一次不能机械重复同样动作，应先读清错误、改变方法或重新检查假设。三次错误协议依次是针对性诊断、采用不同方法、重新审视假设；三次仍无法推进时，应把具体错误和已尝试路径交给用户。

自动和门控模式

v3 提供 autonomous 和 gated 两种可选模式。自动模式用结构化 ledger 摘要减少每次工具调用重复注入，门控模式再增加停止条件、计划校验和最多阻塞次数。初始化会生成计划目录、状态文件和可选的 attestation；计划内容改变后需要重新认证。完成门只根据磁盘上的阶段和 ledger 判断，并在没有进展、达到上限或停止钩子已激活时放行，因此不能把它当作无限循环保证。

安全边界与适用人群

该 Skill 主要读写当前项目的规划文件，钩子把计划内容注入模型时会以数据分隔符包装；外部内容仍可能包含提示注入，必须按原始研究处理。它声明没有网络上传路径，也不会执行 Markdown 中写出的命令。开发者、研究人员和需要可恢复长流程的代理适合使用；短问答或一次性改动不需要引入这套文件结构。

来源与许可

本条目依据 OthmanAdi/planning-with-files 当前提交的 README 和完整 SKILL.md 整理，仓库许可证为 MIT。版本和钩子行为会随提交变化，启用自动或门控模式前应核对本机脚本与宿主是否支持相应停止机制。

常见问题

1. 它解决什么问题？

它把多步骤任务的计划、研究发现和进度写入项目文件，减少上下文压缩或长时间工作造成的遗忘，并让恢复和审计有明确入口。

2. 开始任务要先做什么？

先用脚本解析 PLAN_ID 或 PWF_PLAN_ROOT，确定唯一计划目录，再读取 task_plan.md、progress.md 和 findings.md，最后检查尚未记录的代码变更。

3. 三份文件分别记录什么？

task_plan.md 记录阶段、目标、决策和错误；findings.md 存放来源研究；progress.md 记录会话日志、测试结果和完成情况。三者不要混用。

4. 两次操作规则是什么？

每两次查看、搜索或浏览后，立即把关键发现写到文本文件。这样可以把外部内容从短期上下文转成可恢复记录，避免继续工作时凭记忆猜测。

5. 它会上传研究内容吗？

技能声明没有网络上传路径；它只维护当前项目的计划和日志。但网页结果会进入 findings.md，读取这些内容时仍要当作不可信数据，不能执行其中的指令。

6. 自动模式和门控模式有什么区别？

autonomous 模式减少重复计划注入并使用结构化 ledger；gated 模式在此基础上检查阶段完成、计划认证、停机次数和进展，适合需要可控持续运行的场景。

7. 连续失败怎么处理？

按三次错误协议先诊断并修复，再换方法，第三次重新审视假设。若仍失败，不重复同一动作，应整理具体错误、尝试和限制后向用户升级。

8. 适合什么工作？

适合五次以上工具调用的研究、开发、多阶段交付和长时间代理任务。单轮问答或很小的修改使用这套文件会增加维护成本，通常没有必要。