planning-with-files 工作流全解三文件协同、Hook 生命周期与跨会话恢复机制【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files导读本文围绕 docs/workflow.md 展开系统讲解 planning-with-files 的核心工作流task_plan.md、findings.md、progress.md三个文件如何在一个复杂 AI Agent 任务中协同运转PreToolUse / PostToolUse / Stop 等生命周期 Hook 如何自动驱动这套流程以及任务结束后计划文件的真实归宿。读完本文你将掌握三文件模式的完整操作规则2-Action Rule、阶段完成与错误处理流程、并行多任务下的 Topic Handoff 模式以及用“5-Question Reboot Test”自检上下文管理是否健壮。一、工作流全景从任务启动到任务完成planning-with-files 面向的是预期需要超过 5 次工具调用的复杂任务。整个工作流可以用一个纵向流程图概括原文档的 Visual Workflow 部分TASK START用户请求复杂任务预期 5 次工具调用 │ ▼ STEP 1: 创建 task_plan.md绝不跳过 │ ▼ STEP 2: 创建 findings.md STEP 3: 创建 progress.md │ ▼ WORK LOOP迭代执行 ├── PreToolUse Hook自动Write/Edit/Bash 操作前读取 task_plan.md刷新注意力窗口中的目标 ├── 执行工作工具调用 │ ├── 研究类操作 → 更新 findings.md │ ├── 实现类操作 → 更新 progress.md │ └── 关键决策 → 同时更新两个文件 ├── PostToolUse Hook自动阶段完成后提醒更新 task_plan.md ├── 每 2 次 view/browser 操作后 → 必须更新 findings.md2-Action Rule ├── 完成一个阶段后 → 更新 task_plan.md 状态 在 progress.md 记录细节 └── 出错时 → 记入 task_plan.md 与 progress.md并记录解决方案 │ ▼ 还有工作要做吗 ├── YES → 回到 WORK LOOP └── NO → Stop Hook自动检查是否所有阶段完成、校验 task_plan.md 状态 │ ▼ 所有阶段完成 ├── YES → TASK COMPLETE交付文件 └── NO → 继续工作回到循环这套流程的核心设计理念是计划文件不是一次性产物而是每个回合都被重新注入 Agent 上下文的“注意力锚点”。Hook 的存在让“重读计划、更新进度、校验完成”从可选的良好习惯变成了机械的自动化行为。源码印证三文件模板从哪里来工作流的第一步“创建三个文件”在仓库中由 scripts/init-session.sh 实现。该脚本支持三种调用形态./init-session.sh # legacy 模式在项目根目录写三个文件 ./init-session.sh Backend Refactor # slug 模式.planning/2026-09-11-backend-refactor/ ./init-session.sh --gated Gated Run # v3 gated 模式额外写入 .mode/.nonce 并自动 attest脚本内部通过write_default_task_plan、write_default_findings、write_default_progress三个函数生成文件骨架。以task_plan.md为例其结构包含## Goal、## Next Step、## Current Phase、## Phases3~7 个可勾选阶段、## Decisions Made、## Errors Encountered等小节且每个阶段都有- **Status:** in_progress/pending这样的状态标记——这些标记正是后续 Hook 判定阶段完成与否的机器可读依据。完整的模板见 templates/task_plan.md、templates/findings.md、templates/progress.md。二、四个关键 Hook 的触发时机与职责工作流中出现的 Hook 交互在仓库的 hooks/hooks.json 中有完整的声明式定义这是 Claude Code 插件路由/plugin install注册的生命周期配置。下表汇总了每个 Hook 的触发时机与行为Hook触发时机行为SessionStartClaude Code 插件会话开始startup/resume/clear/compact 事件静默恢复活动计划无活动计划时不输出任何内容PreToolUse匹配的工具操作之前Write\|Edit\|Bash\|Read\|Glob\|Grep刷新活动计划的上下文重新注入计划内容PostToolUse匹配的写操作之后Write\|Edit提醒 Agent 更新阶段状态Stop宿主尝试停止时仅在 gated 模式下、且所有门控条件全部满足时施加阻塞插件路由与独立 skill 路由的差异值得注意Claude Code 插件在启动时注册这些生命周期 Hook含SessionStart而独立 skill 安装如npx skills add没有SessionStart其 frontmatter Hook见 skills/planning-with-files/SKILL.md 的hooks:段只有在该会话中技能被调用后才激活。因此独立安装的会话恢复能力弱于插件安装。底层分发实现所有 Hook 事件最终都汇入 hooks/claude-hook.sh 这个单一分发器。它按事件名分流session-start→emit_session_start恢复计划上下文user-prompt-submit→emit_context每个回合开始注入计划内容这是“防上下文腐化”的关键机制pre-tool-use→emit_context每次工具调用前注入post-tool-use→emit_post_tool_nudge发出进度提醒且每个回合最多一次v3.16.0 起通过turn_marker_path令牌文件做节流pre-compact→ 输出systemMessage提醒在压缩前刷新进度stop→ 转交 scripts/gate-stop.sh 判定是否允许停止。值得注意的是 v3.17.0 之后的优化当系统 PATH 上有 CPython 3 时事件优先走单进程实现 scripts/inject-plan.py避免每个事件 fork 约 130 个子进程Git Bash on Windows 场景下曾导致 Hook 超时PWF_FAST_PATH0可强制回退到参考 shell 链。两者输出逐字节一致由 tests/test_inject_plan_python_parity.py 在三条 CI 平台上做对等性校验。三、活动计划的解析顺序Hook 到底读哪个文件工作流中“Hook 读取计划”有一个隐式前提——解析出当前活动的计划目录。仓库用 scripts/resolve-plan-dir.sh 定义了解析顺序$PLAN_ID环境变量 →./.planning/$PLAN_ID/若存在.planning/.active_plan文件内容 → 匹配的目录若存在.planning/下按 mtime 最新的计划目录均未命中 → 输出空调用方回退到 legacy 根目录的./task_plan.md。该脚本是纯sh实现内含多层安全防护slug_is_valid拒绝包含空白、路径分隔符、前导点号的非法 plan idis_within_root用 canonicalize 前缀匹配做包含性校验防止符号链接指向仓库外如/etc的文件被哈希与注入PWF_PLAN_ROOT绝对路径绑定v3.9.0让 cwd 处于共享父目录如/workspace的线程也能锁定真实项目根。从源码看一个已设置的PLAN_ID是绑定binding而非提示issue #237如果它未解析成功解析直接终止输出空结果绝不静默回退到另一个计划。resolve-plan-dir.sh被check-complete.sh、inject-plan.sh、claude-hook.sh等内部共享保证所有消费者对“当前活动计划”的认知一致。四、核心操作规则2-Action Rule、阶段完成与错误处理4.1 2-Action Rule工作流中最重要的防丢失规则是 2-Action Rule每经过 2 次 view/browser/search 操作必须立即更新findings.md。Operation 1: WebSearch → 记录结果 Operation 2: WebFetch → 现在必须更新 findings.md Operation 3: Read file → 记录发现 Operation 4: Grep search → 现在必须更新 findings.md这条规则的动机在于视觉/多模态信息网页截图、图像、PDF 内容一旦离开上下文窗口就不可恢复必须尽快落盘为文本。它在 skills/planning-with-files/SKILL.md 的 Critical Rules 中被列为第二条硬性规则Rule 2并且 SKILL.md 还给出了更细的“读/写决策矩阵”——例如“刚写完文件 → 不要读内容还在上下文中”“查看了图片/PDF → 立即写入 findings多模态信息必须先转文本”。4.2 阶段完成Phase Completion当一个阶段完成时工作流要求两步操作更新task_plan.md状态改为in_progress→complete勾选复选框[ ]→[x]同时刷新## Next Step让下一行动作保持单一明确。更新progress.md记录执行过的操作列出创建/修改的文件记录遇到的问题。4.3 错误处理Error Handling工作流要求错误必须被记录且不允许重复同样的失败动作记入task_plan.md→ Errors Encountered 表格包含 Error / Attempt / Resolution 三列记入progress.md→ 带时间戳的 Error Log记录解决方案永不重复同一条失败的动作。SKILL.md 把这条规则升级为“3-Strike Error Protocol”第 1 次尝试诊断并修复第 2 次换一种方法或工具第 3 次质疑假设、考虑更新计划3 次失败后上报用户。核心约束始终是if action_failed: next_action ! same_action。4.4 完成检查的底层实现工作流图中 Stop Hook“检查所有阶段是否完成”其判定逻辑在 scripts/check-complete.sh 中。它同时统计两种状态格式并取较大值兼容**Status:** complete与[complete]混排的计划没有### Phase标题的计划直接静默退出issue #191避免出现虚假的 “0/0 phases complete” 状态。默认调用是纯告知式advisory输出并始终退出 0[planning-with-files] Task in progress (2/5 phases complete). Update progress.md before stopping.只有在 gated 模式--gate标志 .mode文件含gate标记下它才会走“门控决策表”模式为 gated.mode文件包含gate存在in_progress阶段仅 complete total 不够Stop Hook 输入 JSON 中stop_hook_active不为 true已处于强制续跑状态则放行阻塞计数低于上限默认 20PWF_GATE_CAP可覆盖存在.planning/id/.stop_blocks中init 时重置ledger 自上次阻塞以来有推进停滞则放行停止。只有当全部条件同时成立它才输出{decision:block,...}阻止 Agent 停止并且阻塞原因只含固定模板 阶段名绝不含计划正文——防止计划正文的文本被当作指令执行。五、任务完成后计划文件去了哪里这是一个被原文档特意澄清、且经常被误解的问题计划文件是单个任务的“工作记忆”不是交付物。task_plan.md、findings.md、progress.md以及.planning/slug/目录默认都被 gitignore任务结束时没有任何机制自动归档它们。在 legacy root 模式下下一个任务会直接覆盖task_plan.md在 slug 模式下旧目录只是不再是活动计划。check-complete报告完成时既不移动也不抽取任何内容。这一行为是有意设计的issue #14、#202其哲学是上下文窗口是 RAM文件系统是磁盘——工作记忆应该能扛住/clear和任务中途的崩溃而任何需要长期存活的东西本就应该落在代码、commit、spec 或文档中。如果你希望已完成的计划持久保留原文档给出了三条自持路径把你在意的决策和错误复制进代码注释、commit message、ADR 或docs/笔记把.planning/slug/目录移出被忽略的路径或在一个希望追踪计划的仓库中从.gitignore移除.planning/个人复用场景下把目录保留为未来相关任务的缓存并用PLAN_ID或.active_plan固定它。从源码结构看一个“完成即归档”的扩展把.planning/slug/移入归档目录、并把决策与错误表抽取为 git 跟踪记录完全可以作为 opt-in 扩展叠加在三文件默认行为之上——正如 attestation、gated mode、topic handoff 所做的那样。但目前并未内建原文档也明确表示如果你需要欢迎提 issue 或 PR。六、三文件的职责分工与相互关系工作流用一张文件关系图说明了三个文件的角色task_plan.md ├── Goal你要达成的目标 ├── Phases3~7 个带状态跟踪的步骤 ├── Decisions已做的主要选择 └── Errors遇到的问题 │ └── PreToolUse Hook 在每次 Write/Edit/Bash 之前读取 │ ├──────────────┐ ▼ ▼ findings.md progress.md ├── Research ├── Session log ├── Discoveries ├── Actions taken ├── Tech decisions ├── Test results └── Resources └── Error logtask_plan.md路线图与状态机是/clear之后恢复工作的断点内容会被 Hook 自动注入上下文因此不要把未经验证的网页内容写进去见 SKILL.md 的 Anti-Patterns外部内容只允许进findings.md。findings.md研究笔记与决策沉淀采用“随做随追加”策略progress.md会话日志与测试结果是执行过程的时间线。七、Topic Handoff多主题并行任务的隔离模式三个根文件最适合单一活动任务。当工作分裂为多个互不相关的主题时原文档建议使用隔离的计划目录.planning/ 2026-01-10-backend-refactor/ task_plan.md findings.md progress.md 2026-01-10-production-incident/ task_plan.md findings.md progress.md创建与切换方式scripts/init-session.sh slug创建带作用域的计划slug 模式会在.planning/YYYY-MM-DD-slug/下生成三个文件并把 plan id 写入.planning/.active_planscripts/set-active-plan.sh plan-id切换活动计划指针该脚本也支持无参调用以查看当前活动计划见 scripts/set-active-plan.sh。Hook 的解析优先级为$PLAN_ID→.planning/.active_plan→ 最新的 scoped 计划 → legacy 根文件。对于并行会话最可靠的做法是在每个终端export PLAN_IDslug后再启动 AgentSKILL.md 的 Parallel task workflow 一节给出了终端 A/B 的完整示例。原文档还介绍了一种与根文件并存的**持久化话题交接durable topic handoff**模式progress.md Short runtime timeline, plus links to topic handoffs handoffs/topic.md Detailed current state, commands, validation, risks, rollback, PR links当某个主题横跨多个会话或多个聊天线程时让progress.md充当索引只放简短指针把细节放进handoffs/topic.md。一份合格的交接文档应回答这些问题问题放在哪里现在正在运行什么handoffs/topic.md如何检查它handoffs/topic.md今天改了什么progress.md中的简短指针哪个分支/commit/PR 重要progress.md中的指针细节在 handoff还有什么风险handoffs/topic.md八、5-Question Reboot Test上下文管理的自检清单原文档给出的这套自检方法用于验证你的上下文管理是否健壮——无论经历多少次/clear或压缩只要你能独立回答这五个问题就能无缝恢复问题答案来源我在哪里task_plan.md中的当前阶段我要去哪里task_plan.md中的剩余阶段目标是什么task_plan.md中的 Goal 陈述我学到了什么findings.md我做了什么progress.mdSKILL.md 在此基础上补充了第 6 问“我接下来要做什么”答案来源是task_plan.md的 Next Step 字段——这正是模板中“每当阶段状态变化就刷新 Next Step”规则的意义所在。九、进一步阅读docs/quickstart.md5 步完成第一次规划会话docs/troubleshooting.mdHook 静默失效时的排查以及/plan-doctor自检docs/long-running-agent-tasks.mdgated/autonomous 模式、完成门控、运行 ledger 的深入说明skills/planning-with-files/SKILL.md完整规则集Critical Rules、安全边界、反模式templates/task_plan.md任务计划文件模板可直接复制使用。【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考