让编码智能体用一份日志衔接长任务

AI 编程任务一长，最先失真的往往是进度记录：计划还停在最初版本，代码已经改了几轮；上下文一压缩，Agent 又得重新摸索。作者给 Claude Code 做了一套约定，把目标、子任务、决策和完成证据都放进 progress.md，再用 hooks 在压缩前后接续工作。

这套做法值得看的地方，是它把「记得做什么」和「凭什么算做完」放到了一起。但文件合并只是入口，真正决定效果的是更新纪律、恢复机制，以及证据能否支撑完成声明。

为什么作者把计划也塞进了进度日志

计划回答「做什么、为什么」，日志回答「现在走到哪了」。两者更新频率不同，分开存看起来很合理。

作者遇到的问题却来自实际工具链。上下文压缩后，hook 会恢复 progress.md 的末尾内容，单独的 plan.md 不会自动回来；旁边的时间线面板也只读一个文件；两个文件各自维护，计划和进度容易脱节。

所以作者把计划移进日志，并明确要求 Agent 不再创建 plan.md。每个任务段落同时保存目标、分组子任务、决策说明，以及目标对应的证据。

原文用一个日期为 2026-11-06 的登录任务演示格式：目标是用户通过 Google 登录，新用户进入 dashboard 才算完成。任务拆成 OAuth 和 Sessions 两组，记录 callback route 已有 6 个测试通过、完整测试套件仍在后台运行、session expiry 尚未完成；另留一条说明，解释为什么为了服务端退出登录而选择 cookies，而非 JWT。

这只是格式示例，不能当成作者完成了该登录功能的实测报告。它说明的是：文件要让接手者同时看到验收标准、当前状态和关键取舍。

任务完成必须有证据，Agent 自己说做完了不算。

作者要求，只有测试、命令结果或 PR 能证明工作完成时，才能勾选子任务。(background) 和 (subagent) 则说明任务如何执行，让计划兼有派工信息。不过标签只是记录方式，原文没有证明它们会自动触发后台执行或子 Agent。

压缩上下文后，怎样接着干活

作者的 progress-log skill 把上下文压缩（compaction）和结构化笔记接在一起：任务推进时更新文件，在一组工作结束后提醒压缩，并告诉压缩器哪些内容要保留、哪些可以丢弃，之后再恢复日志。

大白话解释，就是把聊天窗口当工作台，把文件当交接记录。窗口里的讨论可以缩短，下一轮仍能从记录里找到继续工作的入口。

Claude Code 在压缩前触发 PreCompact hook；压缩后恢复会话时，由 matcher 包含 compact 的 SessionStart hook 接续。这套提醒机制需要 Claude Code hooks 和 Python 3，配置步骤位于仓库的 hooks-setup.md。

作者援引 Anthropic 的上下文工程指南，以及 Chroma 的 Context Rot 研究，支持压缩对话、持久化笔记和控制输入长度的方向。但原文没有给出安装前后的 token 用量、费用或任务成功率。节省 credits 是作者的诉求，还不是文中已经量化的收益。

作者还把它类比为写到文件里的 ReAct。2022 年的 ReAct 研究强调交替进行推理、行动与观察结果；这里的证据栏，相当于把部分观察结果留下来，供人核查。这个类比能解释工作循环，但日志记录的并不是模型完整的推理轨迹。

原文也没有展开压缩器规则的具体内容。既然恢复的是日志末尾，较早的目标和约束能否始终被带回，仍取决于实现，不能仅凭「写进文件」就认定上下文不会丢失。

时间线让记录更容易看见，也带来了格式约束

作者另做了 progress-timeline，把日志显示在聊天旁边：绿色表示完成，黄色表示进行中，灰色表示计划中；出现新计划时，面板会自动打开。

面板从仓库 how-saket-claudes 的 plugin marketplace 安装，原文命令如下：

claude plugin install progress-timeline --marketplace iaintsaket/how-saket-claudes

要留意这一行安装的是 progress-timeline 面板，progress-log 的压缩提醒还需要前面提到的 hooks 配置。

它也有明确限制：面板只识别约定格式，文件可以由任何人或工具写入；宽终端中才会主动打开，窄终端需要手动运行 /progress-timeline。面板固定停靠右侧，不能调整位置。

可视化降低了查看进度的成本，却没有替代核验。绿色状态仍然来自日志中的声明。

我的判断

我认同把目标、状态和证据放在一起，尤其适合一个 Agent 连续推进、需要多次压缩上下文的任务。读记录时不用再猜「完成」指代码写好了，还是验收真的通过了。

但「删掉 plan.md」不是普适结论。作者的选择有很强的工具前提：恢复 hook 和面板都围绕一个文件工作。如果团队已经用 issue、PR 和设计文档分别管理执行状态、代码审查与长期决策，额外维护一份完整日志也可能增加同步负担。

证据质量同样需要判断。6 个测试通过，只能证明这些测试通过；PR 的存在，也未必证明用户能完成登录。证据应当对应目标，而非只证明 Agent 执行过某个动作。

原文展示了工作约定和可用界面，没有与双文件方案做对照，也没有给出错误率或节省成本的数据。因此，这是一套有道理的工程经验，适合小范围试用，还不足以证明单文件方案普遍更优。

能拿来做什么

• 给持续多轮的前端或 Node 任务写清验收条件，例如登录改动要求新用户最终进入 dashboard，并把能验证这条路径的结果记在目标旁边。
• 在日志里区分已通过的局部测试和仍在运行的完整测试套件，后台任务未返回结果前，保留其未完成状态。
• 使用 Claude Code 时，先验证一次压缩后的交接效果：检查 Agent 能否找回当前目标、未完成事项和关键决策，再决定是否接入时间线面板。
• 已有 issue 和 PR 流程的团队，可以先借用「完成声明必须附证据」这条规则，再按实际接续问题决定是否合并计划与日志。