只写在回复里的待办，等于没有

agent 干活时顺手发现的问题，最常见的去处是回复末尾的一句话：

「另外，XX 这里有个隐患，可作为后续优化。」

这句话写得没毛病，问题在于它写在哪。会话一关，它就跟着整段对话沉下去了，没人会回头翻聊天记录找它。下次有人踩到同一个坑，又是从头查起。

7 月底我在公司仓库里加了一个记待办的 skill，提交说明里把这个问题写得很直白：

AI 会话里发现的「不在当前 scope 的隐患/遗留项」默认归宿是回复文本里一句「可作为后续优化」，随会话结束彻底丢失，没人回看。

解决办法也很朴素：写成文件，跟代码一起提交。

一条待办，一个文件

仓库里有个目录叫 ledger（账本），一条待办一个 Markdown 文件，文件名是「日期-简短英文名」。文件头有几个固定字段：标题、下一步具体做什么、证据（精确到文件和行号）、哪天记的。正文写清楚这是个什么问题、为什么这次没顺手修、影响有多大。

写成文件以后，待办就跟代码待在一个地方了。它有 commit 记录，能 review，能 grep，开新会话的 agent 也能读到。规则文件里有一句话：

躺在工作区的 ledger 等于没写。

写了没提交，跟写在回复里差不多。

后来发现，光提交还不够。8 月有一次，我发现一个功能分支上囤了 20 条记 ledger 和改文档的 commit，可那个分支要修的东西，早就通过另一个 PR 合进 main 了。这些待办一直跟着一个没人再看的分支，跟没写一样。最后全部挪到一个基于 main 的干净分支，单独提 PR 合进去。后来规则文件里加了一句：ledger 和纯文档改动不搭功能分支的车，单独基于 main 提。

裁决了归档，不删

一条待办处理完，不删文件，而是用 git mv 挪进 archive/ 子目录，文件头补两个字段：结果和日期。结果只有四种：做完了、不做了、重复了、过时了。正文末尾写上做掉它的 PR 号，或者为什么不做。

为什么不删？举个真实的例子。7 月 27 日记过一条，说某个前端状态的判断用了一个过时的引用，可能让状态条的文字和实际弹出的卡片对不上。10 月 15 日整理 ledger 时一查，那段判断代码已经不存在了，相关的旧功能在另一个 PR 里整个下线了。于是这条标成「过时」归档，正文末尾写着是哪次提交让它过时的。

要是当时直接删掉，几个月后有人看到类似的问题，就不知道它曾经被记过，也不知道它是怎么没的。archive/ 留下来的，是一份决策记录。

记下来的，比消化掉的多

说点不那么好看的数字。到今天，这个 ledger 里还没裁决的有 328 条，已经归档的 221 条。光是 9 月一个月记下、到现在还没处理的，就有 201 条。

记录的速度，一直比消化的快。10 月 17 日做过一次批量清理，对照代码把 342 条没裁决的逐条过了一遍，只归档了 25 条，其余的都还有没做完的部分，只能留着。

ledger 目录的说明文件里有一节叫「健康指标」，开头一句是：盯的不是「记了多少条」，而是消化速率。

9 月底还有一次，agent 帮我 review 一个同事的 PR，把发现的几个问题都记进了 ledger。我回它：「不用，你直接修改就行了，不用提ledger」。

这句话让我把规则想清楚了一点。ledger 是给「这次确实不打算做」的事准备的，不是给「懒得现在做」的事准备的。能顺手修的，拆个 PR 修掉；只有明确不做、或者现在做不了的，才记账。不然账本只会越记越厚，最后变成另一个没人看的地方。

可以直接抄的版本

规则文件里这样写：

## 待办
- 准备在回复里写「以后再做 / 本次不展开 / 后续优化」之前，先判断：
  能顺手修的，单独提 PR 修掉；确实不做的，写进 docs/ledger/，不要只写在回复里
- 一条一个文件：docs/ledger/<YYYYMMDD>-<slug>.md，随 commit 提交，不搭功能分支的车
- 裁决后 git mv 到 docs/ledger/archive/，补 resolution 和 resolved 两个字段，不删文件

每条的模板：

---
title: 一句话说清是什么问题
next_action: 下一步具体做什么
evidence: [path/to/file.ts:123]
created: 2026-11-04
# 裁决时补：
# resolution: done | wontfix | duplicate | obsolete
# resolved: 2026-11-20
---
为什么这次没修，影响有多大。
裁决时在末尾写：做掉它的 PR 号，或者不做的理由。

开头那句「可作为后续优化」，规则并没有不让 agent 说。它要的只是，这句话后面能跟着一个文件路径。