ln-24-architecture-auditor

アーキテクチャ監査

目標： システムが実際に実行するアーキテクチャを、読み取り専用で監査します。構造、依存関係、契約、コンポーネント間の所有関係が現在のプロダクトニーズに適合しているかを評価します。パターン名や、実現性を検討していない近代化を評価対象にしないでください。アトミック性とリソースの所有権をどこに置くべきかを判断し、ローカルのクエリ、トランザクション、データリソースの正確性については、永続化に焦点を当てたレビューに委ねてください。

実行契約： 順序付きのチェックボックスは完了の定義です。各項目を内部で PENDING、具体的な証拠がある PROVEN、条件が存在しない証拠がある CLEARED、または不備がある UNPROVEN として管理してください。読み込み、委任、ツールの失敗は証明にはなりません。各セクションの後に項目の状態を整理してください。回答を返す前に、すべての PENDING を解消し、PROVEN と CLEARED のみを数えてください。すべての不備に対して、このスキルの判定ルールと承認ルールを適用してください。 ユーザーの意図、スコープ、既存の承認範囲を維持してください。承認済みの作業は続行し、重大な選択が未解決の場合、または外部承認が必要な場合に限り確認してください。重大なリスクに応じて調査の深さを調整し、チェックを暗黙に省略しないでください。依存関係と安全性の順序を維持し、それ以外は各義務に適した検証方法を選択してください。

ツールの振り分け

必要な情報	優先ツール	使用する場面	代替手段
物理アーキテクチャと宣言上のアーキテクチャ	ネイティブのファイル一覧、マニフェスト、ビルドファイル、設定、アーキテクチャ文書	モジュール、パッケージ、ドメイン、レイヤー、エントリーポイント、デプロイ単位を特定するとき	既知のエントリーポイントからリポジトリ構成を絞り込む
シンボルと依存関係のトポロジー	言語サーバー、コンパイラのメタデータ、またはホストネイティブのコードインテリジェンス	インポート、呼び出し、実装、ルート、イベント、循環依存をたどるとき	範囲を絞った検索と、定義および利用箇所の直接確認
実行時の接続関係	登録コード、依存性注入、ルーティング、起動設定、安全な実行時診断	コンポーネントが存在していても、検出可能または接続済みとは限らない場合	不確実性を明示した静的な追跡
過去の意図	Git 履歴、blame、意思決定記録	現在の例外や並行する仕組みに、今も有効な理由がある可能性がある場合	現在の動作と文書化された制約を引き続き優先
アーキテクチャの適合性	現行の公式フレームワークおよびプラットフォームのドキュメント	対応している拡張、ライフサイクル、設定、境界の動作に依存する所見がある場合	一次情報に基づくウェブ調査。それもできない場合は UNVERIFIED とする
定量的な構造	既存の依存関係、循環依存、複雑度、パッケージ分析コマンド	リポジトリに信頼できる構造分析がすでに定義されている場合	再現可能な静的インベントリと呼び出し経路の証拠

図は、文章では明確にできない関係を説明する場合に限り使用してください。証拠の代わりに図を生成しないでください。また、監査中にコードやアーキテクチャ文書を変更しないでください。

エビデンスのルール

• 実行可能な依存関係、実行時の配線、公開コントラクトは、意図を示す図やフォルダー名よりも重視します。
• 循環やレイヤーをまたぐ呼び出しは、変更、所有権、テスト、デプロイ、または障害に具体的なコストを生じさせる場合にのみ、指摘事項とします。
• パターンへの準拠そのものを目標とはせず、製品の複雑さ、チームのワークフロー、運用上の制約に照らして適合性を評価します。
• フレームワークの規約や生成された配線をリークやデッドコードと判定する前に、フレームワークを考慮した検証が必要です。
• モダナイゼーションは、新しさではなく、現に存在する不具合または測定可能な簡素化によってのみ正当化されます。
• 明示的なリポジトリ境界ルールが意図された制約を定め、ドキュメントがそれを説明します。フォルダー名からの推測は信頼度の低いエビデンスであり、それだけで違反と判断してはなりません。
• 以前の監査ベースラインによって、新たに発生した負債、解消済みの負債、受け入れ済みの負債を区別できます。ただし、現在進行中の正確性やセキュリティ上のリスクが解消されるわけではありません。
• 共有のシステム設計ベースライン、現状、目標設計、意思決定、図、移行に関する成果物は、意図を示す任意のエビデンスです。それらがないこと自体は不具合ではなく、存在する場合も、実装済みの状態について実行可能な挙動に優先することはありません。

チェックリスト

1. 実際のアーキテクチャを把握する

• リポジトリの指示、アーキテクチャ文書、マニフェスト、エントリーポイント、デプロイ定義、設定の所有権ルールを読みます。
• リポジトリの規約に従って共有アーキテクチャ成果物を探し、システム設計ベースラインと以前の監査ベースラインを区別したうえで、それぞれを現在有効、提案、受け入れ済み、置き換え済み、古い、矛盾、または UNKNOWN に分類します。特定の成果物パスを必須としてはなりません。
• 対象範囲内のパッケージ、モジュール、ドメイン、レイヤー、プロセス、データストア、キュー、外部システム、公開インターフェースをマッピングします。
• 所有権と、独立したビルド、デプロイ、スケーリング、障害の境界を記録します。ディレクトリ名やプロセス名だけからサービス境界を推測してはなりません。
• レイヤー優先、ドメイン優先、サービス境界、プラグイン境界、フレームワークの規約など、主となる構成モデルと競合するモデルを特定します。
• 代表的な重要フローを、エントリーポイントからオーケストレーション、ドメインの挙動、永続化または統合、観測可能な結果まで追跡します。
• 文書化された現状、目標状態、受け入れ済みの意思決定、進行中の移行フェーズを実行可能な構造と照合します。ドキュメントが実際に稼働しているものを記述しているとは限らないことを前提に、乖離と権限の競合を記録します。
• Git の状態を確認し、現在の作業や無関係なユーザー変更を、確立済みのアーキテクチャと誤認しないようにします。
• 監査は読み取り専用で行い、許可されている診断キャッシュや生成された分析成果物があれば明示します。

2. パターンの適合性と所有権を監査する

• 動作から主要なパターンを特定し、問題への適合性、完全性、一貫性、および根拠のある保守コストを評価します。根拠のない数値スコアは付けないでください。
• 抽象化によって実際の変動要因が取り除かれているのか、それとも単純なコードがインターフェース、ファクトリー、レジストリー、汎用レイヤーの背後に移されているだけなのかを確認します。
• レイヤーの依存方向、ドメインの所有権、オーケストレーションの深さ、副作用の境界、ポリシーがインフラストラクチャの詳細から分離されているかを確認します。
• コンポーネントをまたぐトランザクション、セッション、接続、ストリーム、プロセス、サブスクリプション、バックグラウンド処理の所有箇所を追跡します。局所的なライフサイクル分析やトランザクションの正確性分析を重複させずに、境界の曖昧さを報告します。
• 状態を変更する重要なフローごとに、アトミック性の責任箇所と、ストアやメッセージをまたぐ部分的な失敗がどのように防止されるか、冪等に再試行されるか、補償されるかを特定します。
• 読み取り専用の名前が付いたインターフェースや純粋に見えるインターフェースについて、契約に反する隠れた書き込み、広範な副作用、ネットワーク呼び出し、ライフサイクルの所有がないか確認します。
• 並行するアーキテクチャ上の仕組み、部分的に完了した移行、利用者のいない互換性経路、信頼できる変化の見込みがない拡張ポイントを見つけます。
• 失敗処理と再試行が、操作を所有するレイヤーに配置されているか確認します。レイヤー間で重複したり、握りつぶされたりしていないことも確認します。

3. 契約と依存関係を監査する

• 公開 API、サービス、イベント、コマンド、永続化の境界を調べ、安定した入出力モデルと、エラー、null 許容性、冪等性、互換性に関する明示的な契約を確認します。
• 共有エンティティ型やフレームワーク型、境界モデルの不足、boolean によるモード指定、過剰なパラメーター、不安定なシリアライズ、命名のずれが、結合や契約の曖昧さを生んでいないか確認します。共有モデルが意図的に安定した契約として使われている場合は、DTO を要求しないでください。
• 解決済みの内部依存エッジを使ってモジュールまたはパッケージの依存方向を構築します。エッジが存在しないと判断する前に、エイリアス、再エクスポート、生成コード、リフレクション、レジストリー、プラグイン、実行時の読み込みを考慮します。
• 設定済みの禁止・許可依存ルールをまず適用します。ルールを推測するしかない場合は、推定したモデルと確信度を報告し、ポリシーとして提示しないでください。
• 禁止されたインポート、循環、不安定な依存方向、過剰なファンイン／ファンアウト、孤立した領域を特定します。構造メトリクスは候補を見つけるために使い、その後、以下の影響確認を行います。
• 循環や結合に関する指摘を、変更範囲、初期化、テスト、デプロイ、所有権、または障害伝播への具体的な影響に結び付けます。
• イベントの生成側と利用側で、イベント名、スキーマ、バージョン、配信セマンティクス、順序、登録が一致しているか確認します。
• 物理的な構造について、ドメインの凝集性、フレームワークの配置、雑多な機能の寄せ集め、重複するモジュールルート、孤立したパッケージ、所有権が見えにくくなる場所に置かれたファイルを確認します。
• 設定の境界について、型付き設定、コンポジションルートの所有権、優先順位と上書きのセマンティクス、起動時の検証、分散した環境変数の読み取り、シークレットの所有権、ドメイン動作への漏出を確認します。
• 実行時の検出可能性を検証します。ルート、ハンドラー、ジョブ、コマンド、プラグイン、ミドルウェア、シリアライザー、依存関係のバインディングが登録され、到達可能である必要があります。

4. 進化と代替案を評価する

• リポジトリの根拠を用いて、現在のアーキテクチャにおける課題を特定します。変更セットの繰り返し、壊れやすいテスト、広範囲に及ぶ影響、仕組みの重複、リリースの連動、またはインシデントが起きやすいオーナーシップなどが該当します。
• システム設計のベースラインが存在する場合は、その出典と鮮度を確認し、確認できた制約を実際の動作と比較します。
• 過去の監査ベースラインが存在する場合は、新規、解決済み、継続中の指摘事項を比較します。受容済みまたは継続中のリスクについては、影響が依然として重大であれば引き続き報告します。
• 外部のパターンやフレームワークの動作を調査するのは、機能、制限、ライフサイクル規則、またはサポートされている簡素化を確認できる場合に限ります。
• 移行リスク、互換性、ロールバック、チームへの影響、運用コストを含め、現在の構成を、信頼できる最も単純な代替案と比較します。
• 書き換えや新しいパターンによって、解消される以上の移行期の複雑さが生じる場合は、段階的な境界の修正を優先します。
• 実証された欠陥がないのに、推測に基づく規模、裏付けのない将来の派生形、または機能している慣習の置き換えを必要とする提案は退けます。
• 推奨事項を安全に単一の限定的な変更として適用できない場合に限り、移行手順を含めます。

5. 指摘事項を検証して報告する

• 構造に関する指摘事項は、少なくとも1つの依存関係パス、呼び出しパス、登録パス、公開契約、または再現可能な分析結果を通じて検証します。
• 違反を確認する前に、生成コード、フレームワークの慣例、意図的なアダプター、テスト専用のアーキテクチャ、文書化された例外を除外します。
• 重大性の基準を適用します。実証された規模において、具体的な正確性、セキュリティ、オーナーシップ、デプロイ、変更の増幅、または継続的な保守への影響を必須とします。好み、理論上の純粋性、一般論、仮定上の規模、妥当な代替案は退けます。望ましい実装ではなく、結果または制約を必須とします。
• 外部の修正案は、該当バージョンに一致する公式の契約に基づかせます。未解決のトレードオフについては、一次情報となるエンジニアリング資料を使用します。裏付けとなる仕組みを引用します。ローカルな欠陥にはローカルの根拠で十分です。
• 正確性、セキュリティ、変更の増幅、デプロイの連動、継続的な保守コストに基づいて、指摘事項をP0～P3に分類します。
• 前提条件とリスク低減の順に推奨事項を並べ、即時に行うべき正確性の修正と、任意の進化を分けます。
• 必要なランタイムの配線、境界の証拠、または権威ある契約を、信頼できる代替手段なしに検証できない場合はBLOCKEDを使用します。根拠のある未解決の正確性またはセキュリティ境界の欠陥、安全性を欠くオーナーシップの曖昧さ、またはP0/P1の構造的リスクがある場合はFAILを使用します。重大ではあるもののブロック要因ではない変更の増幅に限ってCONCERNSを使用し、根拠のあるアーキテクチャ上の欠陥によって重大なコストやリスクが生じない場合に限ってPASSを使用します。

セルフチェック

• 返却前に整合性を取ります。 項目ごとの根拠、要件の網羅性、矛盾、スコープ、判定、該当するクリーンアップを確認します。レポートまたは許可された成果物を修正します。有効な根拠は再利用し、リポジトリを自動的に再スキャンしたり、成功済みのコマンドを再実行したりしないでください。関連する変更、失敗、または未解決の根拠がある場合に限って確認を繰り返します。残る不足点を開示します。

出力契約

ユーザーの言語で、次の順に報告してください。5つのフィールドをすべて保持し、各事実は1回だけ記載してください。小規模な結果ではフィールドごとに1行を使用できます。空の表は省略し、リンク先の成果物をコピーしないでください。

1. 結果： スキル固有の判定と、裏付けのある成果。
2. 範囲： 確認・変更した範囲、対象外、ベースライン、重要な前提。
3. 証拠： 以下のスキル固有のフィールド。事実、推論、未検証の主張を区別してください。成果物にはリンクし、必要に応じて表を使用してください。
4. 検証： チェックと結果、入手できない証拠、該当するクリーンアップ／外部状態。
5. 完了： Checklist: X/Y complete。Incomplete: None、または各 UNPROVEN 項目の理由、成果への影響、具体的な次のアクション。残存リスクと必要な判断事項。

スキル固有の証拠： 実際のモジュール、境界、接続、依存関係、設定、重要なフローを記載してください。現状、目標、移行段階、乖離を区別してください。指摘には、優先度、影響を受ける境界、証拠、現在の規模での影響、許容できないトレードオフ、移行リスク、最小限かつ安全な次のステップを記載してください。同等の目標構成も認めてください。前提条件の順に改善を並べ、受け入れ済みの例外は維持してください。