Progress Log【免费下载链接】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-filesUse this file as the chronological record of work performed, files changed, validation results, and errors.Session: [DATE]Replace[DATE]with the date of this work session.文件头明确界定了 progress.md 的四种记录对象**执行的工作work performed**、**变更的文件files changed**、**验证结果validation results**、**错误errors**。每次新的工作会话Session都应追加一个 ## Session: [日期] 区块而不是覆盖旧内容——这保证了日志的时间顺序完整性也是后续重启恢复时能回溯到任意历史会话的前提。 ### 2.2 阶段Phase进度区块 markdown ### Phase 1: [Title] - **Status:** in_progress - **Started:** [timestamp] - Actions taken: - - Files created/modified: - Use the same status values as task_plan.md: pending, in_progress, or complete. Add concrete actions and paths as the phase advances. ### Phase 2: [Title] - **Status:** pending - Actions taken: - - Files created/modified: -这是模板中与task_plan.md耦合最紧密的区块要点有三状态值必须与 task_plan.md 完全一致只有pending、in_progress、complete三个取值。这不是随意的约定——check-complete.sh 用grep -cF **Status:** complete和grep -cF **Status:** in_progress精确统计阶段完成数ledger-summary.sh 也使用完全相同的 grep 模式任何拼写偏差都会导致完成门禁completion gate误判。模板还兼容[complete]/[in_progress]/[pending]内联格式两种格式按字段取较大值混合计数。记录粒度是具体动作 具体路径Actions taken与Files created/modified要求写出真实操作和文件路径而不是模糊描述。从源码结构看这正是为了让后续会话或另一个 Agentworker能从日志中精确还原已做的工作。开始时间戳Started是可选增强项模板在 Phase 1 中示范了Started: [timestamp]Phase 2 则省略——说明时间戳按需添加但注意 v3 的 ledger 摘要注入见第五节会刻意剥离时间戳以保证 KV-cache 稳定。2.3 测试结果表## Test Results Record each validation command or scenario, its expected result, and the observed outcome. | Test | Input | Expected | Actual | Status | |------|-------|----------|--------|--------| | | | | | |测试结果表要求每次验证都记录四要素测试名称、输入、预期结果、实际结果外加状态列。这与仓库的测试驱动理念一致——check-complete.sh 本身就是验证所有阶段是否完成的校验工具而tests/目录下 90 个测试文件如 test_phase_status_locking.py、test_check_complete_resolver.py验证的正是这套规划机制自身的可靠性。progress.md 中的测试结果表让预期 vs 实际的偏差显式化任何未通过的测试都会在日志中留下可追踪的记录。2.4 错误日志表## Error Log Record errors promptly, including the attempt number and resolution. Change the approach before retrying a failed action. | Timestamp | Error | Attempt | Resolution | |-----------|-------|---------|------------| | | | 1 | |错误日志表与 SKILL.md 的Critical Rules直接呼应Rule 5: Log ALL Errors——每个错误都必须记入规划文件这能积累知识并防止重复Rule 6: Never Repeat Failures——if action_failed: next_action ! same_action日志要记录尝试过的方案并强制改变下一次行动。模板中的Attempt列从 1 开始递增配合 SKILL.md 的3-Strike Error Protocol使用效果最佳第 1 次尝试诊断修复第 2 次换一种方法绝不复用失败的相同动作第 3 次重新审视假设、考虑更新计划3 次失败后升级给用户。错误日志就是这套协议的落地载体。2.5 五问重启检查表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 |这是模板中最具实战价值的区块专门服务于会话中断后的状态恢复。五个问题的答案来源在 SKILL.md 的 5-Question Reboot Test 中给出问题答案来源Where am I?我在哪task_plan.md 中的当前阶段Where am I going?要去哪剩余阶段Whats the goal?目标是什么计划中的目标陈述What have I learned?学到了什么findings.mdWhat have I done?做了什么progress.md 上方记录注意最后一行——我做了什么直接指向 progress.md说明 progress.md 是恢复会话时唯一可信的已完成工作证据源。配合 SKILL.md 的Read vs Write Decision Matrix中Resuming after gap → Read all planning files的指引中断恢复的标准动作就是读取 task_plan.md目标与阶段、findings.md已学知识、progress.md已完成工作再用这个表格确认五个答案即可无缝继续。模板结尾的*Update this file after completing a phase, running validation, or encountering an error.*是对更新时机的总纲阶段完成时、运行验证后、遇到错误时三个触发点覆盖了整个任务生命周期。三、与 task_plan.md 的状态联动与更新纪律progress.md 不是孤立文件它与 task_plan.md 存在强制的状态联动。SKILL.md 的 Update After Act 规则规定每完成一个阶段必须将阶段状态从in_progress更新为complete在两个文件中同步记录遇到的任何错误记录创建/修改的文件同时刷新task_plan.md的## Next Step使其指向下一个单一动作。模板开头 Use the same status values astask_plan.md 的说明正是为了保证这种双向一致progress.md 里的阶段记录与 task_plan.md 里的状态字段必须使用同一组字面量**Status:** complete等因为 check-complete.sh 和 ledger-summary.sh 都基于这些精确字符串做机械统计——这也是为什么所有语言的 i18n 模板如 planning-with-files-zh 的 progress.md都刻意保留英文的**Status:** in_progress原文以便并行写入守卫等机制在语言无关的前提下工作。任务全部完成后若用户提出新需求规则是Continue After Completion在 task_plan.md 追加新阶段Phase 6、Phase 7……并在 progress.md 中新增一个 Session 记录然后按常规流程继续——progress.md 作为追加式日志天然支持这种持续增长。四、progress.md 与生命周期 Hook 的注入机制源码级progress.md 的价值不仅在于人工阅读更在于它会被系统自动注入到 Agent 的上下文中。理解这一点你才会明白为什么模板要求具体动作 具体路径的记录格式。4.1 默认模式raw tail 注入在 inject-plan.sh 的默认legacy分支中每次 Hook 触发都会执行tail -20 $PROGRESS_SOURCE_SNAPSHOT 2/dev/null | sed -E s/T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9])?Z/T00:00:00Z/g; ... | head -c 32769 $RAW_PROGRESS这段代码揭示了三层设计只注入最近 20 行tail -20把 token 开销限制在固定预算内同时head -c 32769设置 32KB 硬上限防止单次注入失控时间戳归一化用sed把所有 ISO 时间戳含时区偏移替换为T00:00:00Z形式这是 KV-cache 稳定性的关键——同一内容在不同时刻注入时字节级一致避免缓存失效快照隔离注入读取的是私有目录中的快照文件$PROGRESS_SOURCE_SNAPSHOT而非实时文件保证注入内容在 Hook 执行期间不被并发写入破坏。4.2 PostToolUse 的进度提醒skill-hook.sh 在每次工具调用后通过additionalContext发出提醒[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status.这条提醒每轮最多触发一次配合 SKILL.md 的2-Action Rule每 2 次查看/浏览/搜索操作后立即把关键发现保存到文件与Read Before Decide重大决策前先读计划文件形成先记录、后决策的闭环防止多模态信息图片、PDF、浏览器结果在上下文滚动中被丢失。4.3 PreCompact 钩子中的进度检查Claude Code 的PreCompact事件上下文压缩前会输出诊断提醒inject-plan.sh[planning-with-files] PreCompact: context compaction is about to occur. Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase. task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.这正体现了 progress.md 的抗上下文丢失价值即使会话经历/clear或上下文压缩三个规划文件始终留在磁盘上下次提示词到来时会被重新读取任务状态不会丢失。五、v3 模式下的演进从 raw tail 到结构化 ledger 摘要v3 引入了自治autonomous与门控gated两种可选模式其中对 progress.md 最大的改变是注入内容从原始 tail 替换为结构化 ledger 摘要。从 ledger-summary.sh 的头部注释可以看出设计动机This replaces rawtail -20 progress.mdinjection in autonomous mode. The output is synthesized from the machine ledger and task_plan.md status counts only: NO free text from disk reaches the model context, and there are NO timestamps, so the injected block is KV-cache stable by construction.原因在于安全模型progress.md 不受 attestation哈希见证保护未经审核的长时运行中追加到 progress.md 的任意文本例如工具输出、抓取的页面摘要会在每轮被注入上下文构成提示注入面。v3 因此改为注入固定形状的合成摘要块 RUN LEDGER entries: N phases: complete/total complete in_progress: phase heading or none agent name: last event type 【免费下载链接】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），仅供参考