このページの目次

このページの目次

アーキテクチャガバナンス

アーキテクチャの不変条件

AI エージェントが誤って破ってはならないアーキテクチャの境界と不変条件を、ARCHITECTURE.md に明記する。

主な項目は次のとおりである。

  • ドメインロジックを担うレイヤー
  • 外部 API を呼び出せるモジュール
  • 認証の境界
  • 状態管理の境界
  • Databricks へのアクセス境界
  • フロントエンドとバックエンドの責務
  • 依存関係の方向
  • 統合の境界

ARCHITECTURE.md は簡潔に保ち、次の問いに答えるものにする。

現在のアーキテクチャで、何を維持しなければならないか。

この文書がいつ必須になるかは、必須のプロジェクトドキュメントで定める。

アーキテクチャ決定記録

重要なアーキテクチャ上の決定は、共通の ADR テンプレートを使って 1 件ずつ ADR に記録する。

ADR には次の項目を含める。

  • 背景
  • 決定
  • 検討した代替案
  • 判断の理由
  • 帰結

ADR は、コントリビューターや AI エージェントによる意図しないアーキテクチャ変更を防ぐ。アーキテクチャ上の決定を変える必要があれば、ADR も改訂できる。

ユーザーの要求が ADR と競合する場合は、次の手順で対応すること。

  1. ユーザーの実際の意図を理解する。
  2. その ADR が存在する理由を理解する。
  3. 決定を変更した場合の影響を評価する。
  4. 合理的であれば、既存のアーキテクチャと両立する解決策を優先する。
  5. アーキテクチャを本当に変更する必要がある場合は、その影響を説明する。
  6. ADR を明示的に更新するか、新しい ADR で置き換える。

ADR に黙って違反してはならない。

アーキテクチャを変更すべきかどうかユーザーが確信を持てない場合は、変更する前に、影響を分析するのを支援すること。