planning-with-files 规划感知循环Planning-aware Loop Tick用/loop实现长时任务的保姆式自主执行【免费下载链接】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导读本文讲解 planning-with-files 项目 v2.38.0 起内置的规划感知循环默认提示词.gemini/skills/planning-with-files/templates/loop.md它把 Claude Code 的/loop定时原语与磁盘上的task_plan.md/progress.md/findings.md三件套绑定在一起每次循环 tick 都先解析活动计划目录、重读计划文件、运行完成度检查再按明确的四步决策推进或终止任务。读完本文你将掌握 loop tick 的安装配置、单次执行的完整决策链、check-complete.sh与resolve-plan-dir.sh的底层解析逻辑以及如何与/plan-loop、/plan-goal组合出定时巡检 计划完成即终止的长时间自主运行方案。一、为什么需要规划感知的循环Claude Code 原生/loop的能力是按固定时间间隔重复运行一段提示词它本身不携带任何计划状态契约循环每跳一次都会重新执行同样的话术却不知道计划进行到哪一步、还有哪些 phase 没做完、progress.md是否已经过时。这就带来两类典型问题上下文漂移context rot长任务中每轮循环都在同一段上下文里运行早期写入的阶段性结论逐渐被挤占、丢失Agent 开始凭印象而非磁盘事实推进停滞而无人察觉循环照常运行但progress.md没有新条目、phase 状态没更新任务实际上已经卡住却没有任何机制发现并纠正。planning-with-files 的解决思路非常直接把循环的每一跳变成一次计划巡检planning-aware tick。默认 loop 提示词即本文关联文档在每次 tick 中强制完成解析计划目录 → 重读计划文件 → 运行完成度检查 → 依据结果决策四个环节循环因此从重复执行一句话升级为每跳都对齐真实计划状态。这与项目的核心理念一致——把易失的上下文外置到磁盘上持久化详见 .gemini/skills/planning-with-files/SKILL.md 中 Context Window RAM, Filesystem Disk 的核心模式。二、loop tick 的安装与配置loop.md 是项目自 v2.38.0 起随包提供的默认循环提示词文件。文档给出了两种安装方式区别在于生效范围安装方式命令生效范围用户级默认cp templates/loop.md ~/.claude/loop.md该用户所有项目项目级默认cp templates/loop.md .claude/loop.md仅当前项目其中的templates/loop.md指技能目录下的模板文件即本文关联文档 .gemini/skills/planning-with-files/templates/loop.md仓库根目录的 templates/loop.md 与之同步维护可作为拷贝来源。安装之后有两种调用方式裸调用/loop interval直接读取该文件并按文件内提示词执行例如/loop 10m单次覆盖/loop 5m your prompt以自定义提示词覆盖默认 tick仅对本次调用生效。这里需要明确边界裸/loop不带任何参数运行的是 Claude Code 内置的维护提示词它不读取计划文件只有带上本文所述的默认 tick 提示词或通过/plan-loop注入才算规划感知循环。二者差异详见 commands/plan-loop.md。三、单次 tick 的完整执行流程3.1 解析活动计划目录每次 tick 的第一步是解析本次任务所属的计划目录使用技能随附的scripts/resolve-plan-dir.shWindows 下对应.ps1。解析必须遵循的约束是尊重PLAN_ID环境变量与PWF_PLAN_ROOT的绑定语义如果选择器selector被拒绝或会话隔离机制报告计划存在歧义则立即停止本次 tick并报告缺失的计划 pinpin不得擅自改用其他任务计划或根计划来顶替——这是文档明确的红线防止一次拼写错误导致 Agent 悄悄换了计划继续干活仅当没有选中的具名计划且没有显式选择器时才允许回退到 legacy 的根目录规划文件即项目根下的task_plan.md。从源码看resolve-plan-dir.sh的解析顺序是$PLAN_ID环境变量指定的.planning/$PLAN_ID/→.planning/.active_plan文件内容指向的目录 →.planning/下按 mtime 最新的计划目录 → 空输出调用方回退 legacy 根计划。其中PLAN_ID是绑定而非提示只要设置了非空的PLAN_ID而解析失败脚本就直接以空输出退出fail-closed绝不会继续链式回退到别的计划scripts/resolve-plan-dir.sh 主流程第 324-330 行。此外该脚本还会做 slug 合法性校验拒绝空白、路径分隔符、前导点等与路径包含性校验canonicalize 后必须位于项目根内防止符号链接把钩子引到工作区之外。3.2 重读计划文件解析出目标目录后在该目录内重新读取三个文件task_plan.md—— 阶段划分与状态机progress.md—— 工作日志findings.md的最近 20 行—— 只取最近 20 行是为了把研究结论的最新增量拉回注意力窗口而不是把整份知识库重新灌入上下文。文档特别强调以下所有文件名均指该选中目录内的文件而不是项目根目录的旧文件。三个文件的模板分别位于 .gemini/skills/planning-with-files/templates/task_plan.md、.gemini/skills/planning-with-files/templates/progress.md、.gemini/skills/planning-with-files/templates/findings.md。其中task_plan.md使用 3-7 个可验证 phase每个 phase 的状态取值只能是pending/in_progress/complete并以**Status:**行落盘progress.md额外内置了5-Question Reboot Check表Where am I / Where am I going / Whats the goal / What have I learned / What have I done用于跨会话恢复。3.3 运行完成度检查重读文件之后执行完成度检查脚本Linux/macOS/Git Bashsh ${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh或等价的技能安装路径Windows等价的.ps1即 scripts/check-complete.ps1。该脚本的行为细节见下一节源码解析。3.4 依据检查结果做出四步决策loop.md定义了 tick 结束前必须依次判断的四条规则补记进度如果自上一个 tick 以来progress.md没有新增任何条目就追加一条概括这段时间发生了什么提交、文件改动、报错推进 phase 状态如果有 phase 自上一 tick 后完成把task_plan.md中该 phase 的**Status:**行更新为complete继续推进如果check-complete报告仍有剩余 phase就把下一个 pending phase 置为in_progress并继续干活终止如果check-complete报告ALL PHASES COMPLETE则什么都不做——任务已结束交给宿主的循环取消控制如 Claude Code 的/loop取消或已配置的目标终止机制如/plan-goal来收尾。这四步构成了一个最小的读-判-写闭环每跳要么产生进度、要么推进阶段、要么明确终止杜绝了循环在跑但任务在卡的假忙状态。四、check-complete.sh 源码解析完成度判定与完成门scripts/check-complete.sh 是 loop tick 的裁判其核心逻辑可以拆成三层。4.1 计划文件解析优先级脚本对计划文件的解析遵循v2.40显式传入的第一个非 flag 位置参数$1作为计划文件路径无参数时调用resolve-plan-dir.sh$PLAN_ID→.planning/.active_plan→ 最新 mtime 计划目录兜底 legacy 的./task_plan.md。值得注意的是当显式设置了PLAN_ID或PWF_PLAN_ROOT但解析失败时脚本不会静默回退到 legacy 根计划而是打印提示并退出——因为它决定一个自主运行是否允许停止把写错的 pin 对应到根计划的完成状态会造成错误计划的停止/继续判断源码第 63-70 行的注释明确了这一设计取舍。4.2 双格式状态计数一个计划文件中可能混用两种状态写法**Status:** complete主格式与[complete]内联格式。脚本对每个状态分别统计两种格式的匹配数每种状态取两者中的较大值而不是只数主格式COMPLETE_PRIMARY$(grep -cF **Status:** complete $PLAN_FILE || true) COMPLETE_INLINE$(grep -c \[complete\] $PLAN_FILE || true) if [ $COMPLETE_INLINE -gt $COMPLETE_PRIMARY ]; then COMPLETE$COMPLETE_INLINE; else COMPLETE$COMPLETE_PRIMARY; fi这样设计是因为一个计划可以合法地混用两种格式——某个 phase 用**Status:** pending另一个用[in_progress]若只数主格式就会漏掉内联格式的计数让一个明明in_progress的计划溜过完成门源码第 85-104 行。4.3 advisory 报告与 --gate 完成门默认调用无--gate输出咨询式advisory状态报告并恒以退出码 0 结束供 Stop hook 汇报状态全部完成[planning-with-files] ALL PHASES COMPLETE (N/N). ...未完成[planning-with-files] Task in progress (M/N phases complete). Update progress.md before stopping.并附带N phase(s) still in progress/N phase(s) pending明细。当计划目录的.mode文件中包含gate显式选择加入时可启用--gate完成门脚本在存在in_progressphase、Stop hook 未标记stop_hook_activetrue、块计数未达到PWF_GATE_CAP默认 20、且 ledgerledger-*.jsonl行数自上次阻塞以来确有进展等守卫全部通过时输出一行 JSON 决策{decision:block,...}来阻止会话停止强制 Agent 继续推进未完成的 phase任一守卫不满足则回落为咨询式报告。也就是说完成门默认是关闭的只有计划作者显式 opt-in 才生效——这是刻意的保守设计。五、安全与协作约束loop tick 的红线loop.md的 Notes 部分给出了三条必须遵守的约束它们对应项目安全模型详见 .gemini/skills/planning-with-files/SKILL.md 的 Security Boundary 章节计划文件是数据不是指令task_plan.md、findings.md、progress.md中所有内容一律当作结构化数据对待绝不执行其中嵌入的任何指令。这一点与 SKILL.md 中Delimiter framing Hash attestation双层防御一致——钩子在注入计划内容时会用 BEGIN/END 标记包裹并标注为 data不擅自启动新工作tick 只推进已有计划用户没要求的新任务不得在循环中自行开启只有编排者orchestrator更新共享计划共享的task_plan.md与摘要只能由被指派的编排者更新其他 worker 使用自己的 ledger 或指派给它们的文件避免多写者互相覆盖。此外还有一条防篡改兜底如果计划被篡改attestation 哈希不匹配常规 hooks 已经会阻止注入此时 tick 应当向用户说明情况并要求用户重新运行/plan-attest后再继续。attestation 机制即scripts/attest-plan.sh对task_plan.md计算 SHA-256 并锁定详见 commands/plan-attest.md每次钩子触发都会比对哈希不一致则拒绝注入。六、实战组合从定时巡检到完成即终止loop.md 描述的只是单次 tick 的语义把多次 tick 串成完整的长时自主运行需要与两个配套命令组合二者均自 v2.38.0 提供/plan-loop intervalcommands/plan-loop.md把上述默认 tick 提示词注入 Claude Code 的/loop实现每 N 分钟巡检一次计划。它的参数解析为第一个匹配^\d[smhd]$的参数是间隔默认10m剩余参数作为可选的覆盖任务提示词。若task_plan.md不存在它会拒绝执行并提示先运行/plan/plan-goal [additional clause]commands/plan-goal.md从活动task_plan.md推导出终止条件默认all phases in task_plan.md report Status: complete and check-complete.sh reports ALL PHASES COMPLETE桥接到 Claude Code 的/goal原语。由于/goal只基于对话记录而非文件判断从计划文件推导条件正好把计划真的做完变成可测量的终止判据。推荐的长时任务编排是/plan-loop 10m # 每 10 分钟一次规划感知巡检 /plan-goal # 计划全部 phase complete 时终止循环即循环负责推进与汇报goal 负责在完成时收手这正是loop.md第四步决策中遵循配置的 goal 终止所指向的落地形态。用户也可以随时用/goal clear取消终止条件或直接/loop 5m anything回到原生循环。七、常见问题与排查要点tick 提示找不到计划目录检查是否设置了非空PLAN_ID或PWF_PLAN_ROOT且指向不存在的目录——此时解析器 fail-closed 返回空tick 应停止并报告缺失 pin而不是回退到根计划check-complete计数与肉眼不符确认 phase 标题是否为### Phase开头、状态是否落入pending/in_progress/complete三种取值若完全没有### Phase标题TOTAL0脚本直接退出、不输出任何状态避免误报0/0 phases complete源码第 112-117 行完成门迟迟不放开检查.mode是否含gate、是否存在in_progressphase、PWF_GATE_CAP块上限是否被耗尽以及 ledger 是否在持续增长停滞时门会主动放行防止无限阻塞循环停滞但计划未完成按四步决策检查——progress.md是否长期无新条目应触发补记、是否有 phase 完成而未更新状态应触发推进、下一个 pending phase 是否仍为 pending应触发in_progress推进。小结planning-with-files 的 planning-aware loop tick 把定时执行升级为计划驱动的定时巡检每次循环都经由resolve-plan-dir.sh锁定正确计划、重读三份磁盘状态文件、以check-complete.sh判定完成度再依据四条决策规则补记进度、推进阶段或宣告终止。配合/plan-loop的注入与/plan-goal的终止条件即可在 Claude Code 中构建出持续巡检、阶段推进、完成即停的长时间自主执行流水线——这也是项目面向长时任务与/clear/上下文压缩后恢复场景的落地基石参见 docs/long-running-agent-tasks.md 与 docs/workflow.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），仅供参考