AI Agent 每次收尾必须"干净"，拖延清理等于不清理

先厘清术语

在正式讨论之前，先解释 3 个关键词，读者在阅读本文前必须先理解：

Clean State（干净状态）：session 结束时系统必须处于的状态——build 通过、test 通过、进度已记录、无残留 artifact

Entropy（熵）：复杂系统若不加以管理，自然会越来越乱的趋势

Technical Debt（技术债）：由"先赶进度，以后再改"所积累的成本

做个比喻：codebase 就像"公共厨房"，第一个人把咖啡杯随手放下，第二个人觉得"反正已经乱了"就又放了一个。一周后桌子就埋进了杯子堆里。

问题：session 结束时留下一桌子烂摊子

Agent 跑了一下午，修改了 20 个文件、提交了代码，然后 session 结束。下一个 session 启动后发现：build 挂了、test 红了、debug 文件散落各处、feature list 没有更新、进度完全不透明。

新 session 的前 30 分钟都花在了"搞清楚上个 session 干了什么"上。

Entropy 是万物的"默认值"

Lehman 的软件演化定律指出：持续变化的系统会不可避免地变得越来越复杂，如果不主动管理的话。这对 AI coding agent 尤为真实 [2]。

在 Codex 实验的 5 个月里，OpenAI 发现了一个令人担忧的现象：agent 会复制 repository 中已有的 pattern，即使那些 pattern 本身并不一致或并非最优。随时间推移，这种复制导致 drift 不断累积 [1]。

OpenAI 如何解决：从"周五再收拾"到系统化

最初 OpenAI 团队每周五用 20% 的时间手动清理"AI slop"，但这种方法显然无法扩展。最终他们找到了 3 条系统性方案：

将"golden rules"嵌入 repo，例如"用 shared utility 而非手转 helper""不要凭空猜测 data structure"，规则必须具体、可机械执行、可自动化验证。

设立定期 cleanup workflow，Codex 后台任务持续扫描 deviation、更新 quality score、发起 refactoring PR，大部分可在 1 分钟内 review 并自动合并。

一次性捕获"人类口味"，然后强制执行到底——review comment、refactoring PR、用户反馈的 bug 统统转化为 doc 更新或嵌入为 tooling。

技术债是高利贷，每次还一点几乎总是比积累到一次性还一大笔更划算。

Clean State 不只是"代码能编译"

Clean state 必须满足 5 个条件：

5 个"干净 session"的条件

Build 通过，下一个 session 不需要先修 build error。

所有 test 通过，包括本次 session 之前已有的 test，session 不能把已有功能弄坏。

进度已记录，记录在机器可读的 artifact 中（feature list、progress）。

无残留 artifact，无 debug log、无临时文件、无遗留的注释代码、无悬而未决的标记。

startup path 可用，下一个 session 可直接开始工作，无需手动干预。

"以后再收拾" = 永远不收拾

最常见的思维陷阱："这个 session 没时间收拾，下次再说。"

但下一个 session 不知道你留下了什么，它只看到乱糟糟的代码和不确定的状态。它得花时间猜"哪部分代码是有意留的，哪部分是临时的。"

更糟糕的是：每个 session 都有自己的目标。新 session 来是为了做新工作，不是来收拾旧摊子的。它会忽略那些乱糟糟的东西，直接在上面叠加新工作，让混乱加倍。

说明一切的数据：12 周

12 周 agent 驱动开发项目的两种方案对比 [3]：

12 周后：build pass rate 相差 29 个百分点，startup time 相差 85%。

以下技巧总结自 Learn Harness Engineering 课程 [3]：

1. Clean State 是"完成"的必要条件

session 完成 = 工作通过验证 AND clean state check 通过，二者缺一不可 = session 尚未完成。

## Session Exit Checklist
- [ ] Build passes (npm run build)
- [ ] All tests pass (npm test)
- [ ] Feature list updated
- [ ] No debug code remaining (console.log, debugger, leftover markers)
- [ ] Standard startup path available (npm run dev)

2. 使用双模式 cleanup

Immediate cleanup（每个 session 结束时）：清理临时 artifact、更新 feature list、验证 build+test。

Periodic cleanup（每周）：全盘扫描、处理积累的结构性问题、更新 quality document。

3. 维护 Quality Document

一份活跃文件，持续为每个模块打分：

# Quality Document

## User Authentication Module (Quality: A)
- Verification passing: Yes
- Agent understandable: Yes
- Architecture boundaries: Compliant

## Payment Module (Quality: C)
- Verification passing: Partial (payment callback untested)
- Agent understandable: Difficult (logic spread across 3 files)
- Architecture boundaries: Violations present

新 session 读取后能立即知道该先处理哪里。

4. 逐步简化 harness

每个 harness component 的存在都是因为模型"还做不到"。但模型进步后，这些假设就过时了。

Anthropic 的实验：最初 harness 有 sprint-splitting 机制（把任务拆成小块让 Sonnet 4.5 逐块完成）。Opus 4.6 发布后，模型已能自行拆分任务，于是删除了该机制，builder agent 连续运行 2 小时也没有 drift。

实践建议：每月选 1 个 component，临时关闭、跑 benchmark，如果结果没有变差就永久删除。

5. Cleanup 必须是幂等的

cleanup 脚本必须能安全重复运行：

rm -f /tmp/debug-*.log          # -f 防止文件不存在时报错
git checkout -- .env.local      # 恢复到已知状态
npm run test                    # 验证 cleanup 没有破坏任何东西

注意：不要过度清理

也有需要警惕的一面："过度清理"也有成本。

Over-cleanup 浪费时间——每个 session 花 5 分钟做清理，好；但如果花 30 分钟做不必要的 cleanup，就是过高的成本。

harness 本身的混乱——有时候"乱"在 harness 里，而不是 codebase 里。逐步简化 harness（第 4 条技巧）和清理代码同样重要。

不是每个 project 都要做所有事情——1 个人的小项目可能不需要完整的 quality document，先从简单的 checklist 入手。

我认为这是区分"存活的项目"和"慢慢腐烂的项目"的"纪律"：entropy 是默认值，只有主动的清理才能对抗它。

因为数据很明确：12 周不清理，build pass rate 下跌 32 个百分点，startup time 膨胀 12 倍；而持续清理的项目几乎不衰退。

如果你只能做到两件事——设置 session exit checklist + 做每周 cleanup——你的项目就不会慢慢腐烂。

现在你的 repo 里有 session exit checklist 了吗？你多久清理一次 agent 生成的代码？欢迎在评论区分享。

[1] OpenAI. "Harness Engineering: leveraging Codex in an agent-first world". 2026. https://openai.com/index/harness-engineering/

[2] Lehman. "Programs, Life Cycles, and Laws of Software Evolution". 1980. https://ieeexplore.ieee.org/document/1702314

[3] Learn Harness Engineering, Lecture 12. 2026. https://github.com/walkinglabs/learn-harness-engineering

本文分析素材来自 OpenAI、IEEE 和 walkinglabs/learn-harness-engineering。数据截至 2026 年 8 月 23 日。Nokka