Session: [DATE]【免费下载链接】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-filesReplace[DATE]with the date of this work session.每次新的工作会话例如一天、一次长任务的续跑以日期开启一个新的 ## Session: 小节。它把 progress.md 从单条流水账变成按会话分组的日志配合 task_plan.md 中Continue After Completion规则全部阶段完成后用户追加新需求时新增 Phase 并记录新 Session 条目一起使用。日期建议使用 YYYY-MM-DD 格式与 init-session.sh 生成计划目录的命名YYYY-MM-DD-slug保持一致便于对账。 ### 2.2 阶段状态块Phase 1: [Title] markdown ### Phase 1: [Title] - **Status:** in_progress - **Started:** [timestamp] - Actions taken: - - Files created/modified: -每个### Phase块包含四个字段Status阶段当前状态取值只能是pending、in_progress或complete三选一。模板原文明确要求Use the same status values astask_plan.md这是与自动化机制耦合的关键见下文 2.3。Started阶段启动时间戳记录何时开始做。Actions taken实际执行的动作清单。随着阶段推进追加具体动作Add concrete actions and paths as the phase advances。Files created/modified本次阶段创建或修改的文件路径清单。2.3 状态值的硬约束为什么必须与 task_plan.md 完全一致progress.md 中的**Status:**值不是自由文本而是被 check-complete.sh 等脚本机械解析的标记。该脚本通过 grep 计数task_plan.md中的阶段状态COMPLETE_PRIMARY$(grep -cF **Status:** complete $PLAN_FILE || true) IN_PROGRESS_PRIMARY$(grep -cF **Status:** in_progress $PLAN_FILE || true) PENDING_PRIMARY$(grep -cF **Status:** pending $PLAN_FILE || true)见 scripts/check-complete.sh同时兼容[complete]/[in_progress]/[pending]内联格式并取两种格式计数的较大值以兼容混用计划。这意味着状态值拼写必须精确匹配in_progress而非in-progress、In Progress等变体否则计数为 0阶段完成判定会失真。所有翻译版模板都保留字面英文 token**Status:** complete因此该标记是语言中立的——这正是 SKILL.md 中 parallel-write guardv3.10.0能跨语言检测进度回退的原因guard 比较两次 turn-start 之间已勾选事项与已完成阶段的增减若减少则说明磁盘上的工作被覆盖打印一行告警并指向git diff。check-complete.sh的 Stop hook 在任务未完成时会提示Update progress.md before stopping即停止前先更新进度日志把记录进度作为停止的先决条件写进了钩子行为。2.4 Test Results验证结果台账## Test Results Record each validation command or scenario, its expected result, and the observed outcome. | Test | Input | Expected | Actual | Status | |------|-------|----------|--------|--------| | | | | | |这一表格要求记录每一次验证验证命令或场景Test、输入Input、预期结果Expected、实际观察结果Actual、状态Status。它的价值在于可追溯任何一次测试的预期 vs 实际差异都有据可查而不是只存在于上下文里。支撑完成判定task_plan.md模板中 Phase 4Testing Verification明确要求 Document test results in progress.md即测试结果必须落到这里才能支撑check-complete判定 ALL PHASES COMPLETE。与 leder 联动在 v3 的 autonomous/gated 模式下每次验证或错误可以通过 ledger-append.sh 以结构化事件progress、phase_complete、error、gate_block等写入机器账本见第五节。2.5 Error Log错误与解决台账## Error Log Record errors promptly, including the attempt number and resolution. Change the approach before retrying a failed action. | Timestamp | Error | Attempt | Resolution | |-----------|-------|---------|------------| | | | 1 | |错误日志表记录时间戳、错误内容、尝试次数Attempt模板默认填 1、解决方案Resolution。它的纪律要求是及时promptly记录并且改变方法后再重试失败的动作——这与 SKILL.md 的规则 5Log ALL Errors每个错误都写进计划文件构建知识、防止重复和规则 6Never Repeat Failures一脉相承。SKILL.md 给出了同构的错误记录示例## Errors Encountered | Error | Attempt | Resolution | |-------|---------|------------| | FileNotFoundError | 1 | Created default config | | API timeout | 2 | Added retry logic |配合 3-Strike Error Protocol三次失败后升级给用户ATTEMPT 1: 诊断并修复 → 读懂错误、找根因、精准修复 ATTEMPT 2: 换方案 → 换方法/换工具/换库绝不重复同样的失败动作 ATTEMPT 3: 重新思考 → 质疑假设、检索方案、考虑更新计划 AFTER 3 FAILURES: 升级给用户 → 说明尝试过什么、贴出具体错误、请求指导2.6 5-Question Reboot Check断点恢复的自检锚点## 5-Question Reboot Check Use this table when resuming to confirm the current phase, destination, goal, findings, and completed work. | Question | Answer | |----------|--------| | Where am I? | Phase X | | Where am I going? | Remaining phases | | Whats the goal? | [goal statement] | | What have I learned? | See findings.md | | What have I done? | See above |这是 progress.md 的重启自检锚点恢复会话时用它确认当前阶段、目的地、目标、已学到的内容与已完成的工作。它在task_plan.md模板的## Next Step和## Current Phase基础上把我已经做了什么See above指本文件上方的日志与我学到了什么See findings.md显式挂钩形成完整的状态恢复闭环。SKILL.md 中的 5-Question Reboot Test 给出了同样的五个问题及其答案来源并补充了第六问QuestionAnswer SourceWhere am I?Current phase in task_plan.mdWhere am I going?Remaining phasesWhats the goal?Goal statement in planWhat have I learned?findings.mdWhat have I done?progress.mdWhat am I about to do?Next Step in task_plan.md而整个恢复流程的入口在 SKILL.md 的 FIRST: Restore Project State先调用 scripts/resolve-plan-dir.sh 解析当前任务所属的计划目录优先级PLAN_ID环境变量 →.planning/.active_plan→ 最新 mtime 的计划目录 → legacy 项目根然后读取该目录下的task_plan.md、progress.md、findings.md三份文件。注意PLAN_ID是绑定而非提示若显式 selector 无法解析到目录恢复流程会停止并要求修正 pin绝不回退到另一个任务或根计划issue #237。2.7 文件结尾的更新纪律模板末尾固定一行Update this file after completing a phase, running validation, or encountering an error.即三个触发点必须更新完成一个阶段后、运行验证后、遇到错误后。这与 SKILL.md 规则 4Update After Act完全对应将阶段状态in_progress→complete记录遇到的任何错误记录创建/修改的文件并且每当阶段状态变化还要同步刷新task_plan.md的## Next Step让它指向下一个单一动作。三、更新纪律SKILL.md 中的六条规则围绕 progress.md 的维护SKILL.md 的 Critical Rules 给出了六条可执行的纪律Create Plan First没有task_plan.md不得开始复杂任务不可协商。The 2-Action Rule每 2 次 view/browser/search 操作后立即把关键发现保存到文本文件防止视觉/多模态信息丢失。Read Before Decide重大决策前重读计划文件让目标保持在注意力窗口内。Update After Act每个阶段完成后更新状态、错误、文件清单见 2.7。Log ALL Errors所有错误进入计划文件构建知识并防止重复。Never Repeat Failuresif action_failed: next_action ! same_action——记录尝试过的方法然后改变方法。四、与恢复、循环与压缩机制的联动progress.md 不是孤立文件它被多个生命周期机制读取或写入4.1 /plan-loop 与 loop.md周期性 tick 驱动 progress 更新commands/plan-loop.md插件安装路由提供v2.38.0与 Claude Code 原生/loop组合默认 10 分钟一个 tick重读规划文件、运行check-complete如果自上次 tick 以来没有任何新进展写入progress.md则追加一条总结条目。安装规划感知模板 templates/loop.mdPWF_SKILL_DIR${CLAUDE_SKILL_DIR:-${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}} # user-wide cp ${PWF_SKILL_DIR}/templates/loop.md ~/.claude/loop.md # project-specific cp ${PWF_SKILL_DIR}/templates/loop.md .claude/loop.mdloop tick 的四条动作指令中前两条都直接作用于 progress.md 和阶段状态若上次 tick 后没有条目追加到progress.md追加一条总结提交、修改的文件、错误。若阶段完成将task_plan.md中对应的**Status:**更新为complete。若check-complete还有剩余阶段推进下一个 pending 阶段为in_progress并继续。若check-complete报告ALL PHASES COMPLETE停止。这正是自动续跑工作流的机制底座progress.md 的更新频率是循环是否空转的判据。4.2 PreCompact 钩子与 /clear 恢复Claude Code 的PreCompact钩子matcher*在手动或自动压缩时触发有选中计划时打印诊断提醒和记录的Plan-SHA256无计划时保持静默永不阻塞压缩。由于PreCompact不支持additionalContext钩子无法强制模型在压缩前刷新进度——所以 SKILL.md 的结论是任务期间保持 progress.md 实时更新压缩后从磁盘文件恢复。同理/clear之后依赖session-catchup.py --metadata仅输出同项目会话活动的聚合计数或直接重读三份规划文件来恢复状态。4.3 check-complete 与完成判定check-complete.sh 是完成判定的核心它解析task_plan.md中的### Phase标题数TOTAL与各状态计数输出ALL PHASES COMPLETE (N/N)或Task in progress (N/N phases complete)。无### Phase标题时TOTAL0不输出任何完成状态避免假的0/0。该脚本在 v3 gated 模式下承担终止预言机职责见第五节。注意它提示更新 progress.md 后再停止因此 progress.md 的及时性直接影响停止时的状态报告质量。五、v3 模式下的演进从原始 progress tail 到结构化 ledgerv3autonomous/gated 模式对 progress.md 的注入方式做了一次重要演进理解这一点有助于回答为什么还要维护 progress.md。Legacy 模式默认每轮 turn 注入task_plan.md头部 原始progress.md尾部tail -20 progress.md。优点是直接可见缺点是progress.md不受 attestation 覆盖其中任何类指令文本例如无人值守运行时追加的工具输出都会每轮流入上下文且带时间戳的原始文本会破坏 KV-cache 稳定性。Autonomous/Gated 模式原始progress.mdtail 注入被 ledger-summary.sh 合成的结构化块取代 RUN LEDGER entries: N phases: complete/total complete in_progress: phase heading or none agent name: last event type 该块只包含 tick 数、阶段完成比、in_progress 阶段标题、每 agent 最后事件类型——没有任何来自磁盘的自由文本、没有任何时间戳因此按构造就是 KV-cache 稳定的见 scripts/ledger-summary.sh 头部注释与 reference.md 的 C3 注入规则。机器账本由 ledger-append.sh 写入.planning/id/ledger-agent.jsonlappend-only每行一个 JSON 对象事件白名单为progress phase_complete error gate_block attest notesh scripts/ledger-append.sh phase_complete Phase 3 delivered --agent main --phase 3 --files src/foo.py,src/bar.py写出的行形如{tick:N,ts:ISO8601Z,agent:...,phase:...,event:...,summary:...,files:[...]}tick 为全目录所有 ledger 文件的最大值 1保证并发 agent 共享单调递增计数供 gated 模式的 stall detector 使用。要点v3 模式并没有取消 progress.md而是改变了它的消费方式——人工可读的过程台账仍是主记录orchestrator 负责维护机器账本是其结构化投影供注入和终止判定使用。SKILL.md 的职责划分明确workers 向自己的 ledger 追加条目orchestrator 拥有task_plan.md与共享摘要。六、实战示例一份完整的 progress.md将以上要素组合起来一份符合模板规范、可直接落地的 progress.md 如下假设执行后端重构任务 Phase 2 期间# Progress Log Use this file as the chronological record of work performed, files changed, validation results, and errors. ## Session: 2026-09-10 ### Phase 1: Requirements Discovery - **Status:** complete - **Started:** 2026-09-10T09:00:00Z - Actions taken: - Interviewed user intent; constraints recorded in findings.md - Explored current module layout under src/ - Files created/modified: - findings.md ### Phase 2: Planning Structure - **Status:** in_progress - **Started:** 2026-09-10T10:15:00Z - Actions taken: - Defined API surface for the refactor - Drafted module split in task_plan.md decisions table - Files created/modified: - task_plan.md ## Test Results Record each validation command or scenario, its expected result, and the observed outcome. | Test | Input | Expected | Actual | Status | |------|-------|----------|--------|--------| | unit | pytest tests/test_api.py | 12 passed | 12 passed | pass | | lint | ruff check src/ | 0 errors | 3 unused imports | fail | ## Error Log Record errors promptly, including the attempt number and resolution. Change the approach before retrying a failed action. | Timestamp | Error | Attempt | Resolution | |-----------|-------|---------|------------| | 2026-09-10T10:40:00Z | unused imports in api.py | 1 | Removed imports, re-ran lint | ## 5-Question Reboot Check Use this table when resuming to confirm the current phase, destination, goal, findings, and completed work. | Question | Answer | |----------|--------| | Where am I? | Phase 2 (Planning Structure) | | Where am I going? | Phases 3-5: Implementation, Testing Verification, Delivery | | Whats the goal? | [goal statement from task_plan.md] | | What have I learned? | See findings.md | | What have I done? | See above | --- *Update this file after completing a phase, running validation, or encountering an error.*【免费下载链接】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），仅供参考