開発チーム内の設計意図と技術用語を統一するArchitecture Decision Records（ADR）の運用手順
はじめに
こんにちは、NKKTech Global 技術チームです。
既存のコードベースを読んでいるとき、以下のような疑問を抱いた経験はないでしょうか。
- 「なぜこのライブラリではなく、あえて別のマイナーな技術が選ばれているのか？」
- 「このREST APIとgRPCの境界線は誰が、どういう前提で決めたのか？」
- 「仕様書に書かれている『テナント』と『アカウント』は同じ意味なのか？」
口頭やSlackのスレッドで行われた意思決定は、数ヶ月も経てば「暗黙知」となり、担当者の退職や異動とともに永遠に失われます。特に多国籍チームやリモート環境では、この**「文脈の断絶」が再設計の手戻りやコミュニケーションコストの増大**を招きます。
この問題を解決する業界標準の手法が、**ADR（Architecture Decision Records: アーキテクチャ決定記録）**です。本記事では、チームにADRを無理なく定着させる実践的な運用フローを解説します。
1. ADRとは何か？ なぜWikiではなくリポジトリで管理するのか？
ADRとは、**「重要なアーキテクチャ上の決定、その背景、およびトレードオフ（影響）」**を、短く構造化されたMarkdownドキュメントとして記録するプラクティスです。
なぜ Notion や Confluence ではなく Git なのか？
多くのチームが社内Wikiでドキュメント管理を試みますが、コードと離れた場所にあるドキュメントは必ず陳腐化します。
| 比較項目 | 社内Wiki (Notion / Confluence) | Git管理のADR (docs/adr/) |
|---|---|---|
| コードとの同期 | 乖離しやすい（更新忘れが頻発） | PRでコードと同時にレビュー・マージ可能 |
| 変更履歴 | 誰がいつ変えたか追いにくい | Git Blame / Commit履歴で完全追跡 |
| 開発者の導線 | エディタからブラウザへの移動が必要 | VS CodeやIDE内で完結 |
| 合意プロセス | コメントが散乱しやすい | Pull Request上でレビュー・承認を完結 |
2. 実践的なADRテンプレート (0000-use-madr-template.md)
NKKTech Globalでは、シンプルで実用性の高い MADR (Markdown Architectural Decision Records) をベースに、**「用語定義（Glossary）」**を追加したカスタムテンプレートを採用しています。
# [ADR-000X] [タイトル：例: 状態管理ライブラリにZustandを採用する]
- **起草日:** 2026-10-20
- **起草者:** 山田 (Tech Lead) / Nguyen (Senior Frontend Dev)
- **ステータス:** [提案中 (Proposed) | 承認済 (Accepted) | 却下 (Rejected) | 廃止 (Deprecated) | 置換 (Superseded)]
- **関連Issue / PR:** #142
## 1. コンテキストと問題提起 (Context)
*現在、どのような課題や技術的制約に直面しているかを簡潔に記述します（2〜3段落程度）。*
- Redux Toolkitを運用しているが、ボイラープレートが多く、オンボーディングの学習コストが高い。
- パフォーマンス向上のため、不要な再レンダリングを削減したい。
## 2. 検討した選択肢 (Considered Options)
1. **Redux Toolkitの継続利用**
2. **Jotai (アトム型)**
3. **Zustand (Flux型・軽量)**
## 3. 決定内容 (Decision)
**Zustand** を新規機能開発における標準の状態管理ライブラリとして採用する。
### 決定理由
- バンドルサイズが極めて小さく（約1KB）、フックベースで直感的に書けるため。
- 学習曲線が緩やかで、新規参画メンバーの立ち上がりが最も早いため。
## 4. トレードオフと影響 (Consequences)
### ポジティブな影響 (Pros)
- コンポーネント内の記述量が約40%削減される。
- レンダリングパフォーマンスが向上する。
### ネガティブな影響 / リスク (Cons)
- 既存のReduxコードと共存する移行期間が発生する。
- DevToolsの機能はReduxほどリッチではないため、デバッグ手順の再整備が必要。
## 5. 技術用語・ドメイン概念の定義 (Terminology)
*チーム内で解釈の齟齬を防ぐため、本決定に関わる重要用語を明記します。*
- **Global Store:** アプリ全体で共有するユーザー認証状態。
- **Feature Store:** 特定画面内（例: 注文フロー）のみで閉じる一時的状態。
3. ADRの運用ライフサイクルとGitワークフロー
ADRの作成は特別な会議ではなく、日常のPull Requestフローに組み込みます。
【重要】過去のADRは「書き換えない・削除しない」
アーキテクチャを変更する場合、古いADRを編集・削除してはいけません。
「ADR-0025: QdrantからPineconeへの移行」 という新しいADRを作成し、以下のように相互リンクを貼ります。
- 古いADR（0012）:
Status: Superseded by [ADR-0025] - 新しいADR（0025）:
Status: Accepted (Supersedes [ADR-0012])
これにより、「なぜかつてその技術が選ばれ、なぜ今変えるのか」の**歴史的文脈（Rationale）**が完全に保存されます。
4. 技術用語を統一する「ユビキタス言語」の組み込み
多国籍チーム（特に英語・日本語・ベトナム語が混在する環境）では、言葉の定義の曖昧さが致命的なバグを生みます。
- 「ユーザー（User）」と「アカウント（Account）」の違いは？
- 「論理削除」と「アーカイブ」の処理基準は？
ADRのセクション5（Terminology）にこれらを定義し、コード上の変数名・DBカラム名・APIリクエストパラメータと1対1で一致させます。
チーム全員が「ADRに定義された共通言語（ユビキタス言語）」で議論できるようになるため、翻訳や説明のオーバーヘッドが激減します。
5. 挫折しないためのADR運用の3大ルール
多くのチームが「ADRを書くのが面倒で形骸化する」という罠に陥ります。以下の境界線を徹底します。
-
すべてのコード変更にADRを求めない（閾値の設定）:
- 書くべき: DBの変更、新しいライブラリ/フレームワークの導入、認証方式の変更、ディレクトリ構造の大規模リファクタリング。
- 書かない: バグ修正、軽微なUI調整、既存パターンのCRUD追加。
-
「1ページ以内」に収める:
完璧な長文論文を目指してはいけません。10分〜15分で読める簡潔さを最優先します。 -
新規参画者のオンボーディング教材にする:
新しいエンジニアが入社した際、「まずはdocs/adr/を上から読んで」と伝えるだけで、チームの技術的歴史と設計思想を自律的にインプットできるようになります。
まとめ：ADRはチームへの「未来のラブレター」である
コードは「How（どう動くか）」を語りますが、「Why（なぜそうしたか）」は語ってくれません。
- 設計の背景とトレードオフをリポジトリに残す。
- 用語の統一により、国境や言語を超えた認識齟齬をゼロにする。
- 過去の経緯を尊重しながら、健全な技術刷新を推進する。
ADRは、未来のチームメンバー（そして半年後の自分自身）に向けた、最も投資対効果の高いエンジニアリング資産となります。
お問い合わせ先
グローバル開発体制におけるアーキテクチャガバナンスの設計、アジャイル開発プロセスの標準化、オフショア・リモートチームの生産性向上に関するご相談は、下記よりお気軽にお問い合わせください。
- Webサイト: https://nkktech.com/
- メール: contact@nkk.com.vn
- LinkedIn: https://www.linkedin.com/company/nkktech
著者：NKKTech Global 技術チーム
私たちは、明文化された設計思想と確かなエンジニアリングで、国境を超えた持続可能なソフトウェア開発を実現します。