下一个会话从未见过的决策

一次会议里拍板的架构决定,或一位工程师在 agent 会话里做的取舍,常常到不了下一个人、下一套工具。公开讨论里,团队试着用共享决策日志补上这个缺口;记录缺失或过时,agent 仍会往错误的方向走。

·1 分钟阅读

公开的开发者讨论里,经常会谈到同一个缺口。一个架构决定在会议里拍板,或是某位工程师在 Claude Code 会话里做的。几周后,另一位工程师的 agent 改出了完全相反的结果。Oana Olteanu 把这个问题说得很直白。她问,这是不是已经在造成返工或缺陷;大家现在怎么处理:仓库里的规则、共享记忆、代码审查,还是自己做的工具。

没人想要一份更长的指令。大家是想给决策找个能放的地方,好让下一次会话真的读得到。

决策没有离开那次会话

Iván Spiler 写到,他用自己的 agent 方案做日常开发时,经常撞上这件事。难的不是 agent。一次会话里做出的决策,对下一次会话来说根本不存在。他们的办法是一份共享的决策日志:每个 agent 开始前先读,结束后把新决策追加进去。他说这办法很粗糙,不过大多数冲突就被它挡住了。

blackleg 碰到的是同一类情况:两个人在同一个仓库里跑几天 agent,问题就会出现。第一次会话里的笔记,进不了第二次会话的上下文。那些悄无声息的矛盾,要到代码审查才被发现。他们让每次会话先读一份短的 AGENTS.md,意外的重写少了不少,可会议上口头定下的决策还是会漏掉。他接着问,这些口头决定在进到 agent 之前,别人是怎么记下的。

这不是新问题,只是变得更快了。Microsoft 的 Azure Well-Architected 在 architecture decision records 里写得很直接:一个做了但从未记录下来的决策,多半会被忘掉。同样的争论会再来一轮,后来的改动也可能在不知情的情况下,跟当初的意图相反。

写下来,不等于能一直保持更新

有些团队已经有了共享的架构记录。真正难的,是保持更新。

Ryan 有一个架构仓库,开发者和 agent 都能拉下来对照。他写到,难的是保持更新。这需要很强的纪律。一旦过时,agent 又会往错误的方向走。

这样的提醒,在 coding agent 出现之前就有了。2011 年,Michael Nygard 发表了 Documenting Architecture Decisions。他的看法是:大文档从来不会被持续更新,也没有人会去读。小的、可以分开维护的记录,至少还有被更新的机会。一个项目做下来,最难跟上的往往是决策当初为什么那样做。不知道这些,后来的人只剩两种坏选择:盲目接受,或盲目改掉。他当时写的只是一份很小的经验总结。那种格式从同年 8 月初开始用,只用在几个项目上,先后大约有六到十位开发者参与过。反馈是正面的,尤其对比较长期的意图有帮助。这不是一次大规模的对照研究。

AWS 的规范性指南在 architectural decision record process 里,对怎么保存历史,也是同样的思路。团队接受一份 ADR 之后,它就不可更改。如果有了新的认识,需要不同的决定,就提出一份新的 ADR。新的被接受后,取代旧的那份。Microsoft 的指南把这份日志称为只增不改:1不要回去改已经接受的记录。另写一份新的,标明它取代旧的,并把两份连起来。指南还说,一份没有写明理由的记录,时间久了就会失去价值,因为后来的人无法判断,这个决策现在是否仍然成立。

一份可以被悄悄改写的决策日志,是一份无法信任的日志。一份从不更新的决策日志,则会把下一个 agent 指向错误的方向。

有些决策能被检查,其余的要等到审查

Vini Francisco 介绍了他们团队正在用的做法。仓库里放 ADR,写明决策、原因,以及被排除的替代方案。Agent 改代码之前先读这些记录。能被检查的决策会变成 lint 规则,用来落实架构,比如哪个模块可以引用哪个模块。这样 agent 就无法跟它唱反调:CI 会拦住。他也说了局限。其余那些,目前还没有好办法在审查之前抓住。

这个分法很有用。模块之间的引用边界可以靠 lint 检查。你为什么否决了某个方案,通常检查不了。代码审查仍然可能发现矛盾,但那是在活已经干完之后。下一次会话在动手之前,就需要看到当前的决策,以及理由。

在 Amazon 担任工程经理的 Antonio Torres 写到,他们团队先是在仓库里放引导文件,比如 architecture.md、security.md、testing.md,也在转向规格驱动开发,把规格放进仓库。在他的团队里,他要求每位工程师打开会议摘要,这样讨论过的内容会留下书面记录。这是补上口头决策的一个具体办法。一场会如果什么都不留下,下一个 agent 就看不见。

这些都是公开帖文,不是调查,也没有统计返工花了多少时间。但几边说的是同一类失败:决策已经做了,下一次会话却没见到;或者写下来了,后来过时了;或者只有能被检查的那部分,能在审查前被执行。

给下一次会话一份当前的答案,再加上一条轨迹

可以这样拆:

  • 把决策放在下一次会话真正会读到的地方。 放在仓库里,跟着项目走,而不只留在聊天或会议里。让 agent 开始工作前先读,决策敲定后再追加进去。
  • 要写原因,也要写被排除的方案,而不只写选择。 后来的读者,无论是人还是 agent,都需要这些,才能判断这个决策现在是否还成立。
  • 口头决策要在进入 agent 之前记下来。 如果是在会议上定的,就写进同一份日志。一份短的指令文件装不下每一句口头决定,也不该去装。
  • 不要悄悄改已经接受的记录。 决策变了,就另写一份,把旧的标为被取代,并把两份连起来。当前的答案可以整段重写。你们是怎么走到这一步的,这条轨迹只增不改。
  • 能被检查的约束,变成 lint 或 CI。 其余的,作为当前的答案,留给下一个 agent 去读。审查仍然要抓住 lint 看不见的东西。这很正常。
  • 留意过时。 共享的架构说明一旦过时,agent 还是会按它行事,并往错误的方向走。

比较好用的做法是:一份当前的答案,真相变了就可以整段重写;再加上一条只增不改的轨迹,记录你们是怎么走到这一步的。下一次会话该加载的,是当前的答案。撤销、会议记录、被排除的方案,都属于这条轨迹。

MindMux 做的就是这类记录。它现在能做到的是这些。

MindMux 会从你们已经在和 agent 进行的对话里,整理出背景、决策和约束,写成一份 Markdown 项目大脑。Agent 开始任务前,会通过 MCP 读到它。要把 Claude Code 或 Codex 接到这份大脑,安装 @mindmux/cli,在项目里运行 mmx setup。不想登录 Cloud、只要本地 Brain,用 mmx setup --local。开源、可在本地使用的对应产品是 brain.md:仓库里的一个 brain/ 目录,加上一个小的 CLI(@mindmux/brain-md)。每个页面都保留一层 compiled_truth,也就是当前的答案,以及一条只增不改的 timeline,记录你们是怎么走到这一步的。它就放在 git 里,也不绑死在某个 agent 上。Claude Code、Codex、Cursor,以及任何能读文件的工具,都可以用。

这是跨会话、跨工具的决策记忆。

如果昨天刚定下的决策,下一次会话、换一套工具就已经能看见,那就说明它在起作用。

Footnotes

  1. Microsoft,Maintain an architecture decision record (ADR),Azure Well-Architected Framework。 ↩

分享到