アーキテクチャ変更リクエスト：C4モデルのプルリクエスト
先月、私がアドバイスしているチームのエンジニアが、アーキテクチャ図上のコアサービスの名前を変更しました。議論なし。レビューなし。変更は即座に反映され、3つのチームが次のスタンドアップで、実際のサービスが名前変更されたのか図だけの変更なのかで混乱しました。実際には変更されていませんでした。誰かがラベルが不明確だと思い「修正」しただけでした。
このインシデントが、私たちがしばらく考えていたことを結晶化させました。コードにはプルリクエストがあります。インフラにはplan/applyがあります。データベーススキーマにはマイグレーションがあります。しかしアーキテクチャ図は？編集アクセス権を持つ誰もが、いつでも何でも変更でき、チームの残りのメンバーは……いつか気づきます。
今日、これを変えます。アーキテクチャ変更リクエストが、プルリクエストワークフローをC4モデルにもたらします。
仕組み
コンセプトはあえて馴染みのあるものにしています。GitHubでプルリクエストを開いたことがあれば、すでにこの仕組みがわかります。
まず変更リクエストを作成します。タイトルを付け、何を提案しているのか、なぜなのかを説明します。次に変更を追加します——新しいシステムの作成、既存コンテナの更新、未使用コンポーネントの削除、リレーションシップの変更。各変更は個別の操作です：特定のC4要素に対する作成、更新、または削除。
変更リクエストはドラフトとして始まります。準備ができるまで変更を追加・改良し続けることができます。提案が完了したら、レビューのためにオープンします。
チームメイトはプロジェクトの変更リクエストリストでオープンされたリクエストを確認できます。提案された各変更をレビューし、何が作成、変更、削除されるかを正確に確認できます。レビューを残します：承認、変更リクエスト、またはコメント。必要な承認数に達すると、リクエストをマージできます——すべての変更が1つのアトミックオペレーションとしてライブC4モデルに適用されます。
ビジュアルプレビュー
JSONの塊のようなdiffビューは望んでいませんでした。アーキテクチャはビジュアルであり、アーキテクチャ変更のレビューもビジュアルであるべきです。
すべての変更リクエストには図のライブプレビューが含まれます。プレビューは現在のC4モデルに提案されたすべての変更を重ねて表示します。新しい要素は緑色のハイライトで表示されます。変更された要素はアンバーのリングが付きます。削除される要素は赤いインジケーターが表示されます。C4レベル（システム、コンテナ、コンポーネント、コード）をナビゲートし、すべての深度で提案の完全な影響を確認できます。
これはライブ図に使用するのと同じインタラクティブなReact Flowキャンバスで、同じドリルダウン、ズーム、パンが可能です。唯一の違いはデータです：マージ後にアーキテクチャがどうなるかの計算されたプロジェクションです。
レビュープロセス
レビューはわかりやすいモデルに従います。レビュアーは以下が可能です：
- 承認 — 「良さそうです。準備ができたらマージしてください。」
- 変更リクエスト — 「懸念があります。マージ前に議論しましょう。」
- コメント — 「異議はありませんが、コンテキストを共有します。」
各レビューには詳細なフィードバックのためのフリーテキスト本文が含まれます。変更リクエストはプロジェクトの必要な閾値に対する承認数を追跡します。デフォルトでは1つの承認が必要ですが、プロジェクトごとに設定できます——軽量なトラッキングを望む小チームはゼロ、正式なサインオフが必要な大きな組織は2つまたは3つに。
リクエスト専用モード
さらに踏み込みたいチーム向けに、プロジェクト設定にリクエスト専用モードを追加しました。有効にすると、C4モデルへの直接編集がロックされます。アーキテクチャを変更する唯一の方法は変更リクエストを通すことです。
これは図が読み取り専用になるという意味ではありません。ナビゲート、探索、ADRやドキュメントの要素へのリンク、コメントの追加は引き続き可能です。ただし、変更リクエストワークフローを経ずに要素を移動、名前変更、作成、削除することはできません。
これはアーキテクチャガバナンスが重要な組織向けに構築しました——規制産業、大規模エンジニアリングチーム、共有インフラを管理するプラットフォームチーム。アーキテクチャは制御されたアーティファクトとなり、すべての変更が追跡可能でレビュー済みになります。
アクティビティ追跡
すべての変更リクエストのライフサイクルイベントは、プロジェクトのアクティビティタブに表示されます。リクエストがオープン、クローズ、再オープン、またはマージされると、著者、タイムスタンプ、リクエストタイトルとともに履歴エントリが記録されます。これにより、アーキテクチャがどのように進化したかのタイムラインが得られます——今日の姿だけでなく、それを形作った一連の提案と決定。
ADRとドキュメントリンクと組み合わせることで、完全なナラティブが得られます：何が変わったか（変更リクエスト）、なぜ変わったか（ADR）、そしてより広いコンテキストにどう当てはまるか（ドキュメント）。
変更の構築
変更ビルダーでは、要素ごとに提案を構築できます。各変更に対して以下を指定します：
- オペレーション：作成、更新、または削除
- 要素タイプ：システム、コンテナ、コンポーネント、コード要素、リレーションシップ、またはオーバーレイ
- 要素データ：要素の完全な仕様——名前、説明、テクノロジー、タイプ、直接作成する場合に設定するすべてのフィールド
更新の場合、システムは現在の状態と提案された状態の両方をキャプチャし、レビュアーが何が変わるかを正確に確認できます。削除の場合、既存の要素データは参照用にリクエスト内に保持されます。
オペレーションは自由に混合できます。1つの変更リクエストで2つの新しいコンテナの作成、リレーションシップの更新、廃止されたコンポーネントの削除を行えます。マージ時、すべての変更が一緒に適用されます。
チームにとっての意味
アーキテクチャ変更リクエストは官僚主義を追加するためのものではありません。アーキテクチャの進化を意図的なものにするためです。
コードベースでは、プルリクエストは単なるゲートではなく、コミュニケーションツールです。「これが私の提案で、これが理由です、どう思いますか？」と伝えます。知識共有、早期のミスの発見、共通理解の構築のための自然な機会を作ります。
アーキテクチャも同じ扱いを受けるべきです。誰かが新しいサービスの追加を提案するとき、それは図に表示される前に交わすべき会話です。誰かがコンポーネント階層を再構築したいとき、チームは新しい現実になる前に全体像を見るべきです。
変更リクエストはその会話であり、構造化され追跡可能になったものです。
はじめかた
アーキテクチャ変更リクエストは現在、すべてのチームプランで利用可能です。任意のプロジェクトに移動すると、サイドバーに「リクエスト」セクションがあります。最初のリクエストを作成し、いくつかの変更を追加して、レビューのためにオープンしてください。
ワークフローを強制したい場合は、プロジェクト設定でリクエスト専用モードを有効にしてください。チームのガバナンスニーズに合わせて必要な承認数を設定してください。
アーキテクチャはチームの決定です。ツールがそれを明示するようになりました。
コラボレーティブアーキテクチャについてもっと知りたいですか？C4図のリアルタイムコラボレーションをお読みいただくか、アーキテクチャ決定記録がアーキテクチャの進化の「なぜ」を記録することで変更リクエストをどう補完するかをご覧ください。