はじめに
皆さんはADR（Architecture Decision Record）を日頃から書いていますか？
私は片手で数えるほどしか書いたことがなく、まだまだ慣れておらず、書くたびに悩んでいます。
2025年8月にDress Code株式会社に入社し、最初の中規模タスクで早速ADRを書く機会をいただきました。
ADRとは？
Architecture Decision Record（アーキテクチャ決定記録）の略で、システム設計における重要な意思決定とその理由を文書化する手法です。「なぜその技術を選んだのか」「どんな選択肢があったのか」を後から振り返れるように記録します。
世の中にはADRの「こうして書いてるぜ！」というカッコいい記事が多いですが、
「ここで苦しんだけど、こうしたら乗り越えられたよ…！」 という泥臭い記事は少ないので、書いてみることにしました。
この記事はこんな方におすすめ：
- ADR執筆に苦戦している方
- 「情報をどこまで書けばいいの？」と悩む方
- チーム内での設計議論をスムーズにしたい方
同じように苦しんでいる方には共感と学びを、苦労せず書ける方には「こんな所で悩む人がいるのか」という気づきを提供できればと思います。
今回のケース：スクレイピング処理分離の設計判断
まず、今回私がADRを書くことになった背景を簡単に説明します。
弊社サービスでは外部サービス連携機能を提供しており、一部サービスの仕様変更で不具合が発生しました。
修正方法としてスクレイピング処理が必要でしたが、バックエンドに直接実装すると以下の懸念がありました。
- コンテナイメージサイズの増加
- メモリ・CPU消費量の増加
- 他機能への影響
そこで「スクレイピング処理をどう分離するか」の設計判断を記録するためにADRを作成することになりました。
私がADR執筆でハマった2つのポイント
1. 情報の絞り方で混乱
何が起きたか：
検討を進めると、細かな仕様と対策案をどんどん洗い出してしまいます。
例えば：
- 対策案Aを選ぶと対策案Bは不要
- でも対策案Cを選ぶと、さらにa、b、cの選択肢が生まれる
- それぞれに依存関係がある...
気づくと1つのドキュメントに載せるには情報量が膨大になり、収拾がつかなくなって混乱するのが私のよくあるパターンです。
2. 議論の方向性制御で失敗
何が起きたか：
せっかく情報を整理して選択肢を並べても、説明の際に実装の詳細まで触れてしまい：
- 細かな別の解決策を提案される
- 本来その場で深掘りしなくて良い観点の話が広がる
- 合意形成が難しくなる
結果として、なかなか設計の着地点を決められず悩むことが多いです。
乗り越えるために実践した5つのアプローチ
チームメンバーからの助言と、試行錯誤で見つけた解決策を紹介します。
1. スコープ外のことを先に明言する
なぜ重要か：
議論が始まってから「それはスコープ外です」と言うと、相手も自分も後味が悪くなります。
実践方法：
今回のADRでは以下を検討対象とします：
- スクレイピング処理の分離方法
- パフォーマンスへの影響
以下は今回のスコープ外とします：
- 既存の連携機能の見直し
- 他の外部サービスへの対応
判断軸を明記することで、後から掘り返されることが格段に減りました。
2. 結論から話す
基本の型：
結論：○○の方法を採用します
理由：△△だから
代替案：A、B、Cも検討しましたが、××の理由で不採用
効果：
聞く側が「どうなるのか」「どこを評価すべきか」を最初に理解できるため、議論が散らかりにくくなります。
3. 細かい実装方針は書かない
学んだこと：
大枠の方針さえ決まれば、細かい実装での手戻りはそれほど大きくありません。
実践方法：
- 「どのシステム構成でいくか」は書く
- 「どのライブラリや技術を使うか」は書かない
- 判断軸と優先順位を明確にする
ADR共有時の細かい指摘も、方針に沿ったものなら後で検証すればOKです。
4. 松竹梅で選択肢を整理する
先輩からの金言：
「まずはたくさんある方針の中で松竹梅の選択肢を出し、その中から推しの案を選んだ理由を書いたら」
実践例：
- 松（理想案）: 専用マイクロサービス化 → コスト高で却下
- 竹（推奨案）: AWS Lambdaで部分的に分離 → 採用
- 梅（最低案）: 既存サーバー内分離 → 根本解決にならず却下
比較軸が明確になり、後から見返した人の納得感も得やすくなりました。
5. 図を活用して理解を促進する
個人的に一番効果があった方法です。
具体的な取り組み：
- 既存仕様の図解化: Miroで既存システム構成を「パッと見でわかる」図にまとめ
- 改善案の視覚化: 松竹梅の各案を図で表現
- 図＋文章の組み合わせ: 図をメインにして、文章で補足
得られた効果：
- 説明コストが大幅削減
- レビュアーの理解速度向上
- 既存仕様図がオンボーディング資料としても活用可能に
Dress CodeのADR文化
Dress Codeでは創業1年に満たない会社でありながら、ADRを活用した技術的意思決定の文化が既に醸成されています。
弊社のADR活用事例については、以下の記事でも詳しく紹介しています：
単なる文書化ツールではなく、チームの思考プロセスを整理し、より良い意思決定を支援するツールとして活用しています。
今回学んだこと
ADRを書く過程で、改めて以下のことを実感しました：
-
慣れないことをする時は基本に立ち返る重要性
結論から話す、スコープを明確にするなど、ビジネスコミュニケーションの基本が特に重要 -
視覚化の威力
複雑な情報も図にすることで、理解速度と議論の質が劇的に向上 -
チームの助言の価値
一人で悩まず、早めにチームに相談することで解決策が見つかる -
ADRの副次効果
設計を文書化する過程で、既存システムへの理解も深まった
おわりに
改めて見返すと「当たり前」のことが多いかもしれませんが、慣れないことをする時は普段できることも難しくなるものです。
同じように悩んでいる方の共感や学びになれば嬉しいです。「こんなアプローチもあるよ」という意見があれば、ぜひコメントください！
Dress Codeでは、ADRを書くような設計から関わる機会がたくさんあります。こうした技術文化を一緒に育てていける仲間を募集中です！
この記事は実際のプロジェクト経験をベースに執筆していますが、技術的詳細は一部抽象化しています。
Discussion