アーキテクチャレビューからADRを残す：「なぜ」をコードの隣に

2026-10-18

どのコードベースにも、次に読む人には間違いに見える部分があります。誰が足したのか覚えていない中継プロセス、毎週空にされるテーブル、直接呼び出せば済みそうな場所にあるキュー。理由は何か月も前のアーキテクチャレビューで声に出して説明され、説明した人たちはもう別のチームに移っています。新しく入ったエンジニアの選択肢は2つです。1週間かけて聞いて回るか、「直して」しまうかです。

もっと短い道があります。アーキテクチャレビューを録音し、決定、トレードオフ、却下した案が語られたらホットキーを押し、録音を Architecture チャンネルに共有する。 マークは時刻と話者の名前とともに、その一文に付いたまま残ります。レビュー直後に、Claude Code、Cursor、ClaudeのAIアシスタントがMCP経由でマークを読み、リポジトリ用のArchitecture Decision Record（ADR、アーキテクチャ上の決定の記録）を下書きします。何か月たっても、「なぜ」と尋ねる人のために議論はそこに残っています。

このガイドは、2026年10月18日に確認したSpeak-Y macOSアプリに沿って、チームですでにワークスペースで会議を共有しているテックリード向けに説明します。ワークスペースがまだなければ先に作成してください。

「なぜこういう作りなのか」に答えがないのはなぜか

解決策は2011年に示されています。Michael Nygardの記事Documenting Architecture Decisions（2026年10月18日に確認）は、重要な決定ごとに短い記録（タイトル、コンテキスト、決定、ステータス、結果）を作り、コードの隣のリポジトリに置くことを提案しています。その理由は上の問題そのものです。決定の理由を知らないままプロジェクトに加わった人は、それを盲目的に受け入れるか、盲目的に覆すしかありません。ADRコミュニティのサイトは、こうした記録の集まりをプロジェクトの決定ログと呼んでいます。

ADRを導入したチームでも、「なぜ」は予想どおりの3か所で失われます。

• コンテキストがあとから再構成される。 記録はレビューのあとに、記憶を頼りに、手の空いた人が書きます。決定を左右した制約が真っ先に薄れます。
• 却下した案が1行に縮む。 「CDCも検討した」では、なぜそれが負けたのかがわかりません。次の人がそれをもう一度提案する前に必要なのは、まさにその理由です。
• 記録が書かれないまま終わる。 16時に終わるレビューは、明日締め切りのコードと時間を取り合います。

録音は3つとも残します。マークはそれを見つけられるようにし、アシスタントは細部が薄れる前に下書きにします。

最初に一度だけ：3つのマークと Architecture チャンネル

マーク。 Speak-Yには最初から、⌥1の この瞬間をマーク というノートの種類が1つあります。設定 → ノート で自分用の種類を3つ追加します。ノートの種類を追加 をクリックし、種類の名前 に Decision と入力して 保存 をクリックし、続けて ホットキーを設定 をクリックして⌥2を押します。同じように Trade-off を⌥3に、Rejected を⌥4に設定します。それぞれのマークが記録のセクションに対応します。

• Decision — チームが作ると合意したもの。ADRの決定になります。
• Trade-off — それと引き換えにチームが受け入れたコスト。結果になります。
• Rejected — 負けた案と、その理由。検討した代替案になります。

コンテキストはマークの周りの議論で、アシスタントが文字起こしから読み取ります。Nygard の形式には却下案の専用セクションはありませんが、MADR テンプレートには Considered Options というセクションがあります。

チャンネル。 アーキテクチャレビュー用の公開チャンネルを1つ、Architecture という名前で作り、どのエンジニアも参加できるようにします。ワークスペースの ⋯ メニューで New channel を選びます。脅威モデルや認証フローのような、セキュリティに関わる設計のレビューは非公開チャンネルに分けてください。その選び方は会議チャンネルで誰に何が見えるかで解説しています。

レビュー中：コンポーネント名を言ってから、キーを押す

レビューが始まったらSpeak-Yで会議の録音を始めます。ボットが通話に参加することはありません。Speak-YはあなたのMacでマイクと通話の音を録音するので、Zoom、Google Meet、Teams、会議室のどれでも同じように使えます。レビューを録音していることは全員に伝えてください。

文字起こしにあるのは話された内容だけなので、3つの習慣が効いてきます。

1. 議論の前にコンポーネント名を言う。 「payments-service の決済イベントのパブリッシャー」と言っておけば、そのあとのマークはどれも、エンジニアがのちに検索する名前で見つけられます。
2. 理由が語られてから押す。 マークはキーを押す前の文字起こし15秒分をカバーするので、「なぜなら」を含む一文がマークの中に入ります。
3. 負けた案にもマークを付ける。 「二重書き込みは、2つの書き込みの間でサービスが落ちるとイベントを失う」に付けた Rejected マークは、次のレビューの30分を節約する一行です。

ふだんは、レビューを進めるテックリードが録音してキーを押します。ホットキーはどのアプリからでも使えるので、図やコードを前に開いたままで構いません。

レビューのあと：名前、タグ、To channel

録音のウィンドウで2分、記憶が新しいうちに済ませます。

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の場合、1回のクリックでClaude DesktopとClaude Codeの両方が設定されます。サーバーはすべてのプランで無料です。

そのうえで、リポジトリでこう頼みます。

adr-0012 タグの付いた payments-service のレビューから ADR 0012 を下書きして。 コンテキスト、決定、結果、却下した案。各ポイントを誰がいつ言ったかも書いて。

アシスタントはタグでレビューを見つけて読みます。Speak-Yは文字起こしと一緒に、マークを一覧として渡します。各マークには録音内のオフセット、種類、話者、一文の書き出しが付いています。そのため下書きは、3つの決定、受け入れた3つのコスト、却下した2つの案を、それぞれ名前と時刻付きで返してきます。Cursorでは、設定を変えない限り、アシスタントはツールを実行するたびに確認を求めます。

コミットする前に下書きを手直ししてください。次の3つの項目はアシスタントではなく、あなたが書くものです。

• ステータス。 Proposed か accepted かはチームの決定で、文字起こしからはわかりません。
• 担当者。 来四半期にこの件の質問に答える人です。
• 元の議論への参照。 議論がどこにあるか（チャンネル、日付、タグ）を書いておけば、次に読む人が推論をたどり直せます。チャンネルの録音はエンドツーエンドで暗号化されているので、この参照が使えるのはワークスペースのチームメンバーで、一般には公開されません。

何か月もたって：新しいエンジニアが「なぜ」と尋ねる

リポジトリのADRは、何を決めたかに1ページで答えます。それで足りないとき、議論はすぐそこにあります。

アプリで。 招待したチームメンバーは、どのプランでも無料で参加できます。ワークスペースに加わった新しいエンジニアには、公開の Architecture チャンネルが履歴ごと見えます。チャンネルを開き、ヘッダーの虫眼鏡をクリックして、outbox のようなコンポーネント名を入力します。検索はチャンネル内のすべてのレビューの文字起こしを読み、一致した行を時刻付きで表示します。

エディタで。 CursorやClaude Codeで、コードを開いたまま尋ねます。

payments-service はなぜ Kafka に直接パブリッシュせず、outbox テーブルにイベントを書くの？ 何が却下された？

アシスタントはそのエンジニアが見られる録音を検索してレビューを見つけ、それをもとに答えます。決定の内容、誰がなぜ二重書き込みに反対したか、引き換えにチームが何を受け入れたかです。コードに関する質問全般で同じやり方を使う方法は、Cursorでの音声コーディングに会議のコンテキストを渡すにあります。

レビューの録音が代わりにならないもの

録音は推論を残します。それでも、4つのものは別の場所に置きます。

• 図。 ホワイトボード、スライド、シーケンス図は録音に入りません。ADRからリンクしてください。
• 最終的なステータス。 Decision マークが記録するのは、その場が合意したことです。あとで置き換えられたかどうかは、リポジトリの記録にあります。
• チャットで決まったこと。 プルリクエストのスレッドで決まった選択は、レビューまで届いていません。ADRに直接書いてください。
• コードそのもの。 コードとADRが食い違うなら、動いているのはコードです。記録かコードを更新してください。録音からわかるのは、何を意図していたかだけです。

制限と費用

• 長さ。 2026年10月18日にspeak-y.comで確認したところ、Freeは会議の録音を30分で停止し、Pro（月額$10）は60分、Pro+（$15）とMax（$30）は4時間です。長い設計セッションには、Pro+か、1時間での休憩が必要です。
• 録音者は1人。 同じレビューを2人が録音すると、マークの一覧が半分ずつ2つできます。
• チャンネルはMacで。 ワークスペースとチャンネルはmacOSアプリにあります。ワークスペースの作成にはPro以上が必要で、チームメンバーはどのプランでも無料で参加できます。

まとめ

Decision、Trade-off、Rejected の3つのノートの種類を、⌥2、⌥3、⌥4に。レビュー中は、コンポーネント名を言い、理由が語られるのを待って、キーを押します。レビューのあとは、名前、タグ、To channel → Architecture、マークの表示。そしてリポジトリでアシスタントに質問を1つ。ADRを記憶から書くのではなく、下書きを手直しするだけになります。ワークスペースとチャンネルについてはTeamsページに、同じ考え方をプロダクトの決定に当てはめた例は書かなくても残る意思決定ログにあります。

FAQ

アーキテクチャ上の決定の理由を記録に残すには？

アーキテクチャレビューをSpeak-Yで録音し、決定、トレードオフ、却下した案が声に出されたときにホットキーを押します。録音を Architecture のようなチームのチャンネルに共有します。チャンネルには議論が名前とタイムスタンプ付きで残り、MCPで接続したAIアシスタントがマークをリポジトリ用のArchitecture Decision Recordの下書きにできます。

Claude CodeやCursorは会議の録音からADRを書けますか？

下書きなら書けます。Speak-Y MCPサーバーに接続したアシスタントは、タグでレビューを見つけ、文字起こしと、種類・時刻・話者付きのマークの一覧を読み、コンテキスト、決定、結果、却下した案を埋めます。ステータス、担当者、最終的な文言は、ファイルをコミットするエンジニアが決めます。

新しく入ったエンジニアは、サービスがなぜその作りなのかをどう調べますか？

方法は2つです。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）は4時間です。