《AI 渐进编程》之十：如何和 Agent 续签合同？——修改日志与系统收敛

前一篇我们讲的是 current_task.md，也就是当前这一轮任务怎么写得清楚。
这一篇继续往下，讲的是另一件同样重要的事：

任务做完之后，为什么还要写修改日志？

本书里，这个答案对应的是 revision_log.md。

它记录的不是“文件到底改了什么”，
而是“为什么这么改、这轮改动意味着什么、下一轮还要不要继续”。

1. 为什么还需要修改日志？

很多人一开始会觉得，既然 Git 已经记录了 diff，
那为什么还要再写一个 revision_log.md？

原因很简单：

• Git 记录的是文件变化
• 修改日志记录的是决策语义

这两者不是一回事。

Git 可以告诉你：

• 改了哪些文件
• 哪一行变了
• 什么时候变的
• 谁改的

但它不会主动告诉你：

• 为什么要改
• 这一轮任务的目标是什么
• 这次修改保留了什么
• 还有哪些问题没有解决
• 下一轮应该接着做什么

而这些，正是 revision_log.md 要补上的。

2. 修改日志解决的是什么问题？

revision_log.md 解决的核心问题是：

当下一轮任务开始时，系统不能只看到旧结果，还要知道这些结果是怎么来的。

也就是说，修改日志不是历史装饰，
而是下一轮推进的输入。

它帮助系统回答四个问题：

• 为什么改
• 改了什么
• 验证如何
• 下一步是什么

如果没有这份日志，下一轮 AI 就容易：

• 重新猜一次
• 重复做已经做过的事
• 忽略之前失败过的路径
• 把过期的信息继续当成当前状态

所以，修改日志的意义，不只是“记录”，
而是帮助系统收敛。

3. 修改日志为什么能帮系统收敛？

因为它把一次修改变成了可追踪的状态变化。

如果没有日志，系统每轮都像重新开始：
看见的是文件当前长什么样，
看不见的是它为什么会变成这样。

但有了 revision_log.md，下一轮就可以直接知道：

• 这次是因为 claim 太强才改的
• 只允许改引言，不允许扩大范围
• 哪些句子已经弱化了
• 哪些问题暂时没解决
• 下一轮应该继续检查哪里

这样，系统不是在无限试错，
而是在基于已有轨迹继续往前走。

这就是“收敛”的实际含义：
不是每一轮都完美，
而是每一轮都比上一轮更接近目标，
并且不会重复同一种错误。

4. 日志和 Git 的分工是什么？

这一点要分清楚。

Git Commit

Git 负责保存：

• 文件快照
• 作者
• 时间
• diff
• 可回滚的实际变化

它是文件层面的真实历史。

Revision Log

修改日志负责保存：

• 修改动机
• 任务边界
• 验证结果
• 遗留问题
• 下一轮候选方向

它是任务层面的决策历史。

所以它们是分工关系，不是重复关系。

如果日志只是重复 commit message，
那它就没有提供新状态。
如果日志长到复制每个 diff，
那它又会变成昂贵历史。

好的日志应该保留决策语义，
把文件细节指向 Git。

5. 一条有用的日志应该回答什么？

本书里，一条有用的修改日志至少要回答四个问题：

WHY

为什么要改？

WHERE

改动范围在哪里？

PROOF

通过了什么验证？

IMPACT

还有什么遗留影响？

这四个问题非常重要。
因为它们正好对应下一轮最需要知道的事情。

• 为什么改，决定是否继续相同方向
• 改哪里，决定下一轮读什么文件
• 怎么验证，决定这次修改靠不靠谱
• 还剩什么问题，决定是否要开新任务

6. 一个修改日志长什么样？

以空购物车结算修复为例，日志可以像这样：

## 2026-07-01 — Empty-cart checkout fix
- Task: fix checkout flow only
- Changed: `checkout/service.py`, `tests/test_checkout.py`
- Preserved: auth, payment, unrelated modules
- Validation: empty-cart regression test passed; normal checkout still passes
- State update: recorded edge-case handling and backward-compatibility note
- Next candidate: review legacy caller behavior and add one more boundary test

这条日志的重点不是格式，
而是它把一轮修改的关键语义保留下来了。

下一轮看到它，就会知道：

• 这轮在做什么
• 哪些内容已经处理过
• 哪些问题还没结束
• 下一步不该从零开始

7. 为什么日志不能太长？

如果修改日志写得太长，它就会失去作用。

问题一：像复写全文

如果日志开始复制每一处 diff，那它就不再是日志，而是在重复保存文档。

问题二：像流水账

如果日志只记时间和状态，没说清楚为什么改，那它又没有给下一轮提供有效信息。

问题三：没人维护

如果每次任务都要写很重的日志，最后人和 AI 都会嫌麻烦。

所以，修改日志应该短、稳、聚焦决策语义。
它只保留足够支持下一轮推进的信息。

8. 修改日志和状态有什么关系？

这两者是连着的。

• 状态记录当前事实
• 修改日志记录状态变化原因

也就是说：

• 状态告诉系统“现在在哪里”
• 日志告诉系统“为什么会到这里”

没有日志，状态会变得很难解释。
没有状态，日志又会变成孤立事件。

所以本书把它们分开，是为了让每一轮任务都有清晰的上下文和历史。

9. 什么时候日志会变成负担？

如果日志开始记录太多无关细节，它就会失去价值。

9.1 重复记录文件变化

文件变化已经在 Git 里了，日志不该再重复一遍。

9.2 记录太多解释性废话

日志不是复盘文章，不需要把所有想法都写进去。

9.3 长期不整理

如果旧日志越来越多，却没人归档，它就会越来越难用。

所以日志也要控制粒度，
只保留会影响下一轮判断的内容。

10. 本章小结

这一章想讲清楚的核心是：

revision_log.md 不是补充装饰，而是帮助系统收敛的重要状态。

它记录的不是简单的文件变化，
而是修改背后的原因、边界、验证和下一步候选。
有了它，下一轮 AI 不用重新猜这轮为什么这么改，
而是可以直接基于已记录状态继续推进。

这也就是为什么本书要把 revision_log.md 和 Git 分开：

• Git 负责保存文件历史
• 修改日志负责保存决策语义

下一章，我会继续讲：open_issues.md 为什么要保存那些暂时不能解决，但又不能忘掉的问题。