决策档案里最值钱的是 rejected 桶

发表于 分类于
commit log 记得住每一个做了的决定，却永远不记得那些评估过然后放弃的。在仓库里给决策建档、专门给「被拒绝的方案」留一个桶、并给每次拒绝写上过期条件——这是我用过的性价比最高的工程实践。

六周后回看自己的系统，最贵的问题从来不是”这段代码为什么这么写”——代码就在那里，读就是了。最贵的问题是：“为什么不用那个显而易见的方案？”

当初一定评估过，一定有个好理由，甚至可能激烈讨论过。但 commit log 只保留发生了的事：被拒绝的方案没有 commit，没有 diff，没有任何痕迹。于是六周后的你（或者新同事，或者你的 AI 协作者）兴冲冲地把它重新提出来，把当初的评估原样再走一遍——运气好浪费一下午，运气不好真的实施了，撞上当初预见到的那堵墙。

结论先放前面：在仓库里放一个 .agents/notes/ 目录，一个决定一个文件，分四个桶：implemented（做了的）、proposed（决定了没做的）、rejected（评估后放弃的）、archived（过时的）。其中 rejected 桶最值钱，因为它是唯一保存”没走的路”的地方；而让 rejected 真正好用的关键，是每条拒绝都写上过期条件——什么变化发生时，这个决定应该被重新审视。

形式：一个决定一个文件

这套做法不是我发明的（我从 DeepSeek Harness 的仓库里学来，先用在一个项目，后来所有项目都铺开了）。形式极简，一个 markdown 文件，头部四个字段：

1
2
3
4
5
6
7
8
9
10
11
---
title: 一句话说清这个决定
status: rejected
date: 2026-08-18
scope: hookprobe
---

## Decision   （决定了什么，用现在时态写）
## Why        （理由，带证据和数字）
## Consequences（这个决定的代价和边界）
## Rejected   （顺带评估过并放弃的其他选项）

配一个几十行的脚本在 CI 里检查形状（四个字段齐不齐、scope 在不在枚举里、有没有 Consequences 段），防止它退化成随手的 TODO 堆。

和正式的 ADR（Architecture Decision Record）比，它刻意更轻：不需要评审流程，不需要编号体系，写的时机就是做决定的当下，十分钟内写完。能坚持写的轻量制度，胜过写不动的完备制度。

为什么 rejected 桶最值钱

implemented 桶固然有用，但它有替代品——代码本身、commit message、测试名，都在讲”做了什么、为什么这么做”。被拒绝的决定没有任何替代载体，它要么被写下来，要么彻底蒸发。

举我自己仓库里的三条真实拒绝：

“用一个定时器保持提示词缓存温热”——被拒。算了笔账：省下的缓存费抵不过空转的调用费。这条 note 存在的意义是：每次有人（包括几周后忘了这回事的我自己）看着账单冒出同样的念头，答案和算式已经在那里了。

“换一个更流行的 Agent 引擎”——被拒了两次，这是最有意思的一条。第一次拒绝时对方还是个交互优先的工具，理由很快过时了；三个月后它长出了 RPC 模式、SDK 模式、15 个模型供应商，当初的理由基本失效。于是重新评估——这次把两边的能力逐行列成表格，结论仍然是不换，但理由完全变了：不是”它不够强”，而是哲学冲突——它刻意不做的三样东西（MCP、子任务、宿主侧权限钩子）恰好是我的系统承重的三样。同一个结论，两套完全不同的理由——如果第一次的拒绝没有留档，第二次评估就无从知道”上次拒的理由已经不成立了”，只会凭模糊的印象说”之前研究过，不行”。

“迁移能带来的唯一真收益，已经被更便宜的方式解决了”——这条写在上面那次再评估里，配着一张能力对照表和一个成本估算（迁移要花两三周把四层安全机制用另一门语言重写）。这种带数字的拒绝，是最好的防复议材料。

让拒绝可以过期：revisit 条件

rejected 桶有个天然风险：它会把过时的偏见供奉成教条。”我们试过了，不行”是工程团队里最经不起追问、也最能杀死好主意的一句话。

解法是每条拒绝写上具体的重审触发条件。还是上面那条引擎评估，note 的结尾是三行：

重审触发条件：SDK 的条款或价格让嵌入不可行；系统不再依赖那三样承重机制；或者对方在 RPC 模式里长出宿主侧工具否决——那会推翻对照表里最大的一行。

这三行把”拒绝”从一个立场变成了一个带失效条件的判断。事实上第二次评估正是被触发的——对方的能力变了,于是按约定重新走了一遍。拒绝可以被推翻,但推翻它需要新事实,而不是新一轮的口水。

谁在读这些 note

写下来的东西要有读者才有意义。这套档案的真实读者,按频率排：

  1. AI 协作者。 这是近两年新出现的、也是最高频的读者。AI 结对时最大的隐患是它不知道历史,会热情地重新提出每一个被拒绝过的方案；把 notes 放在仓库里(而不是 wiki 或聊天记录里),它开工前就能读到”这条路试过,此路不通,原因如下”。我的 CI 里 notes 形状检查和单元测试跑在同一个门禁里——因为对 AI 协作者来说,决策档案就是另一种类型的测试。
  2. 六周后的自己。 不解释。
  3. 接手的人。 docs/ 讲系统怎么工作,notes 讲它为什么长成这样——包括为什么不长成那样。后者是文档永远不写、而新人最需要的部分。

收尾

这个实践的全部成本是：做决定的当下多花十分钟,把已经在脑子里的推理写进一个 markdown 文件。全部收益是：每一次”我们要不要试试 X”的讨论,都从零海拔变成了站在上一次讨论的结论上。

从今天起你只需要做一件事：下次你评估了一个方案然后决定不采用时——就是那种”研究了一下午,最后什么代码都没写”的下午——别让它蒸发。给它一个文件,一个 rejected 的状态,和一行”什么情况下该重新考虑”。

那个下午的价值,就这样从零变成了复利。