プロジェクトの混乱を終わらせる意思決定システム: アーキテクチャ決定記録 (ADR) (Adr)

プロジェクトの混乱を終わらせる意思決定システム: アーキテクチャ決定記録 (ADR)

最近のソフトウェア プロジェクトにおける最大の問題は、多くの場合、コードの品質ではありません。本当の危険は、はるかに潜伏性の場所、忘れられた決定から発生します。

企業チームの大部分は依然として、プロジェクトの運命を決定するアーキテクチャ上の決定を「前回の会議で話し合った」レベルで管理しています。しかし、プロジェクトが成長し、チームが変わり、時間が経つにつれて、それらの会議は消えていきます。

次のような迷惑な疑問が残ります。

• 「なぜこのシステムをマイクロサービスにしたのですか？誰が決めたのですか?」
• 「なぜこのデータベースを選択したのでしょうか。代替案を検討しましたか?」
• 「私たちが現在経験しているこの問題を予見していましたか?」

これらの質問に対する明確な答えがない場合、または提示する書類がない場合。それはあなたのプロジェクトが技術的な混乱に陥っていることを意味します。

この時点で、ADR (アーキテクチャ決定記録) システムが機能し、プロジェクトが人に依存するのを防ぎます。

ADR とは何ですか? (文書ではなく、建築の記憶)

ADR は、ソフトウェア プロジェクトで行われた重要な決定を、短く、明確かつ永続的な方法で記録するシステムです。ただし、これを退屈な技術文書と混同しないでください。

すべての ADR は、次の 4 つの基本的な質問に答えるライブ記録です。

1. 私たちはどのような決断を下しましたか?
2. なぜ購入したのですか? (どういう背景がありましたか?)
3. 代替案は何でしたか? (何を排除しましたか?)
4. トレードオフは何ですか? (この決定にはどのようなコストやリスクがかかりますか?)

ADR はプロジェクトの「記憶」です。コードは変更される可能性があり、テクノロジーは変更される可能性があり、CTO さえも変更される可能性があります。しかし、ADR のおかげで、決定のロジックはプロジェクトに残ります。

タスクと ADR の重要な違い

多くのチームは、Jira チケットやタスクが「決定」であると誤解しています。ただし、両者の間には大きな違いがあります。* タスク: 「これをやってください」と彼は言います。アクション指向です。

• ADR (決定): 「なぜこれを行うのか?」と言う。それは戦略指向です。

簡単な例で説明しましょう。

• タスク: 「バスケットのエンドポイントを改善する」。 (このタスクは終了し、アーカイブされます。)
• ADR: 「カート構造は別個のサービスにする必要がありますか、それともメイン アプリケーション内に残す必要がありますか?」 (この決定は、プロジェクトのアーキテクチャに何年にもわたって影響を与えます。)

タスクは終了し、ADR は存続します。

ADR とはどのようなものですか?

ADRの作成は何日もかかる仕事ではありません。むしろ、明確さが求められます。シンプルで効果的な ADR テンプレートを次に示します。

ADR-007: Redis キャッシュの使用

ステータス: 承認されました

コンテキスト: API の応答時間が増加し、データベースの負荷が増加し始めました。読み取り操作の数は書き込み操作をはるかに上回ります。

決定: Redis キャッシュは、頻繁に読み取られるエンドポイントで使用されます。

代替案: データベース インデックスの最適化または CDN の使用が検討されましたが、インスタント データが必要なため除外されました。

結果:

• (+) 応答時間 (レイテンシー) が減少します。
• (+) データベースの負荷が減少します。
• (-) キャッシュクリア（無効化）の複雑さが追加されます。

ご覧のように;決定だけでなく、その理由と結果も明確に明らかにします。

なぜ ADR は単なる「技術的」主題ではないのでしょうか?

マネージャーまたはプロジェクト所有者として、ADR をリクエストすることはプロジェクトを保護することになります。 ADR システムは以下を提供します。

• 速度: 同じアーキテクチャに関する議論がスプリントごとに繰り返されるわけではありません。決断は下されました、旅は続きます。
• オンボーディングの容易さ: 新しい開発者は「なぜ?」と疑問に思うかもしれません。 「」と尋ねるのではなく、ADR ログを読むことでプロジェクトの全履歴を理解します。* 技術的負債の管理: 無意識ではなく、リスク (トレードオフ) を受け入れることで前進します。

私のサービスに ADR を適用するにはどうすればよいですか?

私のプロジェクト管理および技術コンサルタントの仕事において、ADR の作成は「雑務」ではなく、提供の規律です。

プロジェクトに参加すると、通常、最初の 7 日間で次のことを実装します。

1. ADR ログ構造の確立: 決定事項を保存する場所 (Jira、Git、Notion など) を決定します。
2. 重要な決定の記録: 現在のアーキテクチャの X 線を撮影し、遡及的に行われた重要な決定を明確にします。
3. ロードマップの形成: 私たちは機能だけではなく、これらのアーキテクチャ上の決定に基づいて配信ロードマップに優先順位を付けます。

これにより、経営陣と技術チーム間の完全な透明性が確保されます。 「スコープ ドリフト」（スコープの拡張）が防止され、プロジェクトは個人の記憶ではなくシステム自体に委ねられます。

結果

コードが変わります。会議はあっという間に過ぎてしまいます。しかし、意思決定はプロジェクトの基礎を形成します。

プロジェクト内で意思決定が宙に浮いていて、同じ問題が何度も議論されていると感じる場合は、「意思決定の記憶」が必要です。

「テクノロジー スタックとアーキテクチャ」フォルダーは、これらの決定が存在する最も自然な場所です。

---

Confluence 構造を使用して、5 つのステップでこのシステムをセットアップしましょう。

ステップ 1: 「意思決定ライブラリ」を作成する

スクリーンショットの「Technology Stack and Architecture」フォルダーの下に新しいホームページを開いてみましょう。

• ページ名: アーキテクチャ決定ログ (ADR)
• 目的: このページは独立した決定ではありません。これは、すべての決定がリストされるメイン テーブル (インデックス) です。したがって、チームの新しいメンバーがここをクリックすると、プロジェクトの全履歴がリストに表示されます。#### ステップ 2: グローバル テンプレートを準備する 毎回最初からページを作成するのが好きな人はいません。 Confluence では、「グローバル テンプレート」またはこのスペース専用のテンプレートを作成する必要があります。 テンプレートの内容は、前に説明したとおりである必要があります。
• タイトル: ADR-XXX: [短いタイトル]
• ステータス: (これについてはステップ 3 で詳しく説明します)
• コンテキスト: 何が問題ですか?
• 決定: 私たちは何をしているのでしょうか?
• 結果: コストと利益。

ステップ 3: ビジュアル「ステータス」マクロを使用する

Confluence の最大の強みの 1 つはステータス マクロ機能です。このマクロをテンプレートの先頭に追加します。色によって脳は数秒以内に状況を認識できるようになります。 標準のカラーコードは次のとおりです。

• 🟢 承認済み (緑): 決定が下され、実装されています。
• 🟡 提案済み (黄色): 議論に応じますが、まだ承認されていません。
• 🔴 拒否 (赤): 提案されましたが、受け入れられませんでした (これを隠すことも教訓です)。
• ⚪ 非推奨 (灰色): 以前は有効でしたが、現在は新しい決定 (例: ADR-009) に置き換えられています。

ステップ 4: ページ ツリー (階層) を編集する

作成する新しい ADR ページ (例: ADR-001: Redis Cache) を、最初のステップで開いたアーキテクチャ決定ログ ページの子ページとして配置します。 ビューは次のようになります。``` 📂 Teknoloji Yığını ve Mimarisi └── 📂 Architecture Decision Log (ADR) ├── 📄 ADR-001: Redis Cache Kullanımı ├── 📄 ADR-002: Auth Provider Seçimi └── 📄 ADR-003: ...

これが「魔法」の部分です。 🪄 リストを 1 つずつ手動で作成するのではなく、Confluence の自動化を使用しましょう。
各 ADR ページ (テンプレート) に「ページ プロパティ」マクロを追加し、ステータス、意思決定日、意思決定者などの概要情報を追加します。
メイン ページ (アーキテクチャ決定ログ) に移動し、「ページ プロパティ レポート」マクロを追加します。
このマクロは、サブページから概要情報を取得し、メイン ページ上に常に最新の自動テーブルを作成します。