Session: [DATE]

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-files

Replace[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 guard（v3.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 4（Testing & 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 的规则 5（Log ALL Errors："每个错误都写进计划文件，构建知识、防止重复"）和规则 6（Never 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 | | What's 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 给出了同样的五个问题及其答案来源，并补充了第六问：

而整个恢复流程的入口在 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 规则 4（Update After Act）完全对应：

• 将阶段状态in_progress→complete
• 记录遇到的任何错误
• 记录创建/修改的文件

并且每当阶段状态变化，还要同步刷新task_plan.md的## Next Step，让它指向下一个单一动作。

三、更新纪律：SKILL.md 中的六条规则

围绕 progress.md 的维护，SKILL.md 的 Critical Rules 给出了六条可执行的纪律：

1. Create Plan First：没有task_plan.md不得开始复杂任务（不可协商）。
2. The 2-Action Rule：每 2 次 view/browser/search 操作后立即把关键发现保存到文本文件，防止视觉/多模态信息丢失。
3. Read Before Decide：重大决策前重读计划文件，让目标保持在注意力窗口内。
4. Update After Act：每个阶段完成后更新状态、错误、文件清单（见 2.7）。
5. Log ALL Errors：所有错误进入计划文件，构建知识并防止重复。
6. Never Repeat Failures：if 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.md：

PWF_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.md

loop tick 的四条动作指令中，前两条都直接作用于 progress.md 和阶段状态：

1. 若上次 tick 后没有条目追加到progress.md，追加一条总结（提交、修改的文件、错误）。
2. 若阶段完成，将task_plan.md中对应的**Status:**更新为complete。
3. 若check-complete还有剩余阶段，推进下一个 pending 阶段为in_progress并继续。
4. 若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标题时（TOTAL=0）不输出任何完成状态，避免假的0/0。该脚本在 v3 gated 模式下承担"终止预言机"职责（见第五节）。注意它提示"更新 progress.md 后再停止"，因此 progress.md 的及时性直接影响停止时的状态报告质量。

五、v3 模式下的演进：从原始 progress tail 到结构化 ledger

v3（autonomous/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>.jsonl（append-only，每行一个 JSON 对象），事件白名单为progress phase_complete error gate_block attest note：

sh 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 | | What's 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