从架构评审录音写 ADR：把“为什么”留在代码旁边

2026-10-18

每个代码库里都有一部分，在下一个读它的人看来像是错的。一个没人记得是谁加的中转进程，一张每周清空一次的表，一个本可以直接调用却用了队列的地方。理由几个月前在架构评审上被当面讲过，讲的人早已调到别的团队。新来的工程师只有两个选择：花一周到处打听，或者把它“修好”。

其实有一条更短的路。录下架构评审，在有人说出决定、权衡或被否决的方案时按一下快捷键，再把录音分享到 Architecture 频道。 标记会一直落在那句话上，带着时间和说话人的名字。评审一结束，Claude Code、Cursor 或 Claude 里的 AI 助手就通过 MCP 读取这些标记，为仓库起草一份 Architecture Decision Record（ADR，架构决策记录）。几个月后，讨论依然在那里，等着任何一个问“为什么”的人。

本指南以 Speak-Y macOS 应用为准，已于 2026 年 10 月 18 日核实，面向团队已经在工作区里分享会议的技术负责人。如果你还没有工作区，请先创建一个。

为什么“为什么这样设计？”总是没有答案

办法早在 2011 年就有人提出了。Michael Nygard 的文章 Documenting Architecture Decisions（2026 年 10 月 18 日核实）建议为每个重要决策写一份简短的记录——标题、背景、决策、状态、后果——放在仓库里、代码旁边。他的理由正是上面那个问题：新加入项目的人如果不知道某个决定为什么这样做，就只能盲目接受，或者盲目推翻。ADR 社区网站把这些记录的集合称为项目的决策日志。

采用了 ADR 的团队，仍然会在三个可以预见的地方丢掉“为什么”：

• 背景是事后拼凑的。 记录在评审之后凭记忆写成，由恰好有空的人来写。最先淡忘的，是那些决定了这个决策的约束条件。
• 被否决的方案缩成一行。 “我们考虑过 CDC”说明不了它为什么落选，而这恰恰是下一个人再次提出它之前最需要知道的。
• 记录根本没写。 下午 4 点结束的评审，要和明天到期的代码抢时间。

录音把这三样都留了下来。标记让它们能被找到，助手在细节淡忘之前把它们变成草稿。

一次性设置：三种标记和一个 Architecture 频道

标记。 Speak-Y 自带一种笔记类型，即 ⌥1 上的 标记此刻。在 设置 → 笔记 中添加三种自己的类型：点击 添加笔记类型，在 类型名称 中输入 Decision，点击 保存，然后点击 设置快捷键 并按下 ⌥2。用同样的方法把 Trade-off 设在 ⌥3，把 Rejected 设在 ⌥4。每种标记对应记录中的一个部分：

• Decision —— 团队同意要构建的东西。它成为 ADR 的决策。
• Trade-off —— 团队为此接受的代价。它成为后果。
• Rejected —— 落选的方案及其原因。它成为考虑过的备选方案。

背景就是标记周围的讨论，助手会从转写中读取。Nygard 的格式没有单独列出落选方案的部分；MADR 模板有，即 Considered Options。

频道。 为架构评审建一个公开频道，命名为 Architecture，让每位工程师都能加入。在工作区的 ⋯ 菜单中选择 New channel。涉及安全的设计评审——威胁模型、认证流程——请放到私密频道；如何取舍，见会议频道里谁能看到什么。

评审中：先说出组件名，再按键

评审开始时，在 Speak-Y 里开始会议录音。不会有机器人加入通话：Speak-Y 在你的 Mac 上录制麦克风和通话的声音，所以在 Zoom、Google Meet、Teams 或会议室里都一样好用。请告诉大家评审正在录音。

转写只知道说出口的内容，所以三个习惯很有回报：

1. 讨论一个组件之前先说出它的名字。 说一句“payments-service 里的支付事件发布器”，之后的每个标记都能按工程师日后会搜索的名字被找到。
2. 等理由说完再按。 一个标记覆盖按键之前 15 秒的转写，所以带着“因为”的那句话会落在标记之内。
3. 落选的方案也要标记。 落在“双写在两次写入之间服务崩溃时会丢事件”这句话上的 Rejected 标记，就是能为下一次评审省下半小时的那一行。

通常由主持评审的技术负责人来录音和按键。快捷键在任何应用里都能用，图表或代码可以一直开在面前。

评审之后：姓名、标签、To channel

趁大家记忆犹新，在录音窗口里花两分钟：

1. 给说话人写上名字。 点击 Speaker 1、Speaker 2 等，输入真实姓名。一个标记有多大用处，取决于它旁边的名字。
2. 打上标签。 加上服务名和你即将写的记录编号，例如 payments-service 和 adr-0012。助手和队友都靠这些标签找到这次评审。
3. 检查标记。 转写上方的标签块按类型计数：全部笔记 · 8、Decision · 3、Trade-off · 3、Rejected · 2。
4. 分享。 点击转写下方的 To channel，选择 Architecture。带姓名和时间戳的转写、AI 摘要和待办事项会进入频道，并经过端到端加密；音频留在你的 Mac 上。
5. 显示标记。 标记默认是私人的。点击转写上方的 仅自己可见 标签块，选择 在 # Architecture 中显示 — 频道成员可见，让标记随录音一起过去。

根据标记起草 ADR

只需把助手连接到 Speak-Y MCP 服务器一次：在侧边栏底部的账户菜单中打开 连接 AI 助手，或打开 设置 → 集成，然后点击 Claude、ChatGPT 或 Cursor 旁边的 连接。对 Claude 来说，一次点击会同时设置好 Claude Desktop 和 Claude Code。服务器在所有套餐中都免费。

然后在仓库里这样问：

根据带 adr-0012 标签的 payments-service 评审起草 ADR 0012：背景、决策、 后果和被否决的方案。注明每一点是谁在什么时候说的。

助手按标签找到评审并读取它。除了转写，Speak-Y 还会把标记作为一个列表交给它——每个标记带着它在录音中的偏移、类型、说话人和那句话的开头几个字——所以草稿返回时就有三个决策、三项被接受的代价和两个被否决的方案，每一项都带着名字和时间。在 Cursor 中，除非你修改设置，助手每次运行工具前都会先征求你的同意。

提交之前先修改草稿。有三个字段归你，而不归助手：

• 状态。 Proposed 还是 accepted，是团队的决定，转写说不出来。
• 负责人。 下个季度谁来回答关于它的问题。
• 指回原处的链接。 写清楚讨论在哪里——频道、日期和标签——让下一位读者能重温当时的推理。录音在频道里是端到端加密的，所以这个指引对工作区里的队友有效，对外部公众无效。

几个月之后：新来的工程师问为什么

仓库里的 ADR 用一页纸回答了是什么。当它回答得不够时，讨论就在一步之外。

在应用里。 你邀请的队友在任意套餐下都可免费加入。新工程师加入工作区后，就能看到公开的 Architecture 频道及其全部历史。打开它，点击频道页眉里的放大镜，输入组件名，例如 outbox。搜索会读取频道内每次评审的转写，并显示匹配的行及其时间。

在编辑器里。 在 Cursor 或 Claude Code 中，开着代码问：

为什么 payments-service 把事件写进 outbox 表，而不是直接发布到 Kafka？ 当时否决了什么？

助手搜索这位工程师能看到的录音，找到那次评审，并据此回答：决策是什么，谁反对双写、为什么反对，以及团队换来了什么、接受了什么。把同样的方法用在一般代码问题上，见在 Cursor 中为语音编程提供会议上下文。

评审录音不能取代什么

录音保存的是推理过程。有四样东西仍然要放在别处：

• 图表。 白板、幻灯片和时序图不在录音里。请在 ADR 中附上它们的链接。
• 最终状态。 Decision 标记记录的是在场的人达成了一致；它后来是否被取代，要看仓库里的记录。
• 在聊天里做的决定。 在 pull request 讨论串里做出的选择从未进入评审。请直接写进 ADR。
• 代码本身。 如果代码和 ADR 不一致，真正运行的是代码。请更新记录或代码——录音只能告诉你当初的意图。

限制与费用

• 时长。 2026 年 10 月 18 日在 speak-y.com 核实：Free 在 30 分钟时停止会议录音，Pro（每月 $10）为 60 分钟，Pro+（$15）和 Max（$30）为四小时。较长的设计讨论需要 Pro+，或者在一小时处休息一下。
• 只由一人录音。 两个人同时录同一场评审，会得到两份各缺一半的标记列表。
• 频道在 Mac 上。 工作区和频道在 macOS 应用里。创建工作区需要 Pro 或更高套餐；队友在任意套餐下都可免费加入。

简而言之

三种笔记类型——Decision、Trade-off、Rejected——分别设在 ⌥2、⌥3 和 ⌥4。评审中：说出组件名，等理由说完，按下按键。评审之后：姓名、标签、To channel → Architecture、显示标记。然后在仓库里向助手问一个问题，你要做的就是修改 ADR 草稿，而不是凭记忆从头写。Teams 页面介绍了工作区和频道，不用手写的团队决策日志把同样的思路用在了产品决策上。

FAQ

怎样记下一个架构决策当初为什么这样做？

用 Speak-Y 录下架构评审，在有人说出一个决定、一个权衡或一个被否决的方案时按下快捷键。把录音分享到团队频道，例如 Architecture。频道会保存带姓名和时间戳的讨论，通过 MCP 连接的 AI 助手可以把这些标记变成提交到仓库的 Architecture Decision Record 草稿。

Claude Code 或 Cursor 能根据会议录音写 ADR 吗？

能写草稿。连接到 Speak-Y MCP 服务器后，助手会按标签找到这次评审，读取转写和标记列表（每个标记带类型、时间和说话人），填好背景、决策、后果和被否决的方案。状态、负责人和最终措辞由提交这个文件的工程师决定。

新来的工程师怎样弄清一个服务为什么是这样设计的？

有两种方式。在 Speak-Y macOS 应用中打开 Architecture 频道，按组件名搜索；或者在编辑器里问助手，例如 Cursor 或 Claude Code，这个服务为什么这样工作。助手会搜索这位工程师能看到的录音，并回答谁在什么时候说了什么。

Speak-Y 会录下评审时展示的白板或图表吗？

不会。Speak-Y 录制的是发起录音的那台 Mac 上的声音：麦克风和通话应用的声音。图表、幻灯片和白板不在录音里。讨论一个组件之前先把它的名字说出来，图表则在 ADR 里附上链接。

这套做法要花多少钱？

MCP 服务器在所有套餐中都免费。创建团队工作区需要 Pro 或更高套餐，队友在任意套餐下都可免费加入。2026 年 10 月 18 日在 speak-y.com 核实：Free 在 30 分钟时停止会议录音，Pro（每月 $10）为 60 分钟，Pro+（$15）和 Max（$30）为四小时。