アーキテクチャガバナンス
アーキテクチャの不変条件
AI エージェントが誤って破ってはならないアーキテクチャの境界と不変条件を、ARCHITECTURE.md に明記する。
主な項目は次のとおりである。
- ドメインロジックを担うレイヤー
- 外部 API を呼び出せるモジュール
- 認証の境界
- 状態管理の境界
- Databricks へのアクセス境界
- フロントエンドとバックエンドの責務
- 依存関係の方向
- 統合の境界
ARCHITECTURE.md は簡潔に保ち、次の問いに答えるものにする。
現在のアーキテクチャで、何を維持しなければならないか。
この文書がいつ必須になるかは、必須のプロジェクトドキュメントで定める。
アーキテクチャ決定記録
重要なアーキテクチャ上の決定は、共通の ADR テンプレートを使って 1 件ずつ ADR に記録する。
ADR には次の項目を含める。
- 背景
- 決定
- 検討した代替案
- 判断の理由
- 帰結
ADR は、コントリビューターや AI エージェントによる意図しないアーキテクチャ変更を防ぐ。アーキテクチャ上の決定を変える必要があれば、ADR も改訂できる。
ユーザーの要求が ADR と競合する場合は、次の手順で対応すること。
- ユーザーの実際の意図を理解する。
- その ADR が存在する理由を理解する。
- 決定を変更した場合の影響を評価する。
- 合理的であれば、既存のアーキテクチャと両立する解決策を優先する。
- アーキテクチャを本当に変更する必要がある場合は、その影響を説明する。
- ADR を明示的に更新するか、新しい ADR で置き換える。
ADR に黙って違反してはならない。
アーキテクチャを変更すべきかどうかユーザーが確信を持てない場合は、変更する前に、影響を分析するのを支援すること。