arch-check

/arch-check

概要

コードが、掲げているアーキテクチャに引き続き適合しているかを検証します。 アーキテクチャは、個々には妥当に見える小さな変更によって徐々に崩れていきます。たとえば、Domain プロジェクトが EF Core への参照を追加する、あるモジュールが兄弟モジュールの内部に踏み込む、ホストの外部にエンドポイントが定義される、といったケースです。このワークフローでは、ファイルを一つずつ読むのではなく、プロジェクトグラフと依存関係の分析によって、こうした崩れを検出します。

出力：重要度、ファイルと行番号の根拠、具体的な修正方法を含む違反レポート、または適合していることを示すレポートです。

使用するタイミング

• 「アーキテクチャをチェックして」「レイヤー違反はある？」「依存関係の方向」
• リリース前、または大規模な機能の追加後
• アーキテクチャを掲げる、なじみのないコードベースに参加した後
• 複数人が共通モジュールに変更をマージするチームで、定期的に実施する場合
• アーキテクチャを選ぶ場合には使用しません。その場合は architecture-advisor を使用してください

使用方法

ステップ 1：宣言されているアーキテクチャを確認します

優先順位は、プロジェクトの CLAUDE.md、docs/decisions/ 内の ADR、またはユーザーへの確認です。推測で決めてはいけません。基準を誤ると、レポートも誤ったものになります。サポートする 4 つの基準とルールは次のとおりです。

アーキテクチャ	チェックするルール
Vertical Slice	機能間で相互参照しないこと。共有コードは、明示的に共有されたフォルダーまたはプロジェクト経由でのみ使用すること
Clean Architecture	Domain → なし。Application → Domain のみ。Infrastructure → Application。Api → Application（Api → Infrastructure の型参照は禁止し、配線のみ許可）
DDD + Clean	Clean のルールに加え、集約はルート経由でのみ参照し、集約をまたぐ処理にはドメインイベントを使用すること
Modular Monolith	*.Contracts を除き、モジュール間でプロジェクトを参照しないこと。モジュール間の呼び出しには統合イベントまたはコントラクトを使用すること

ステップ 2：プロジェクトレベルの依存関係の方向を確認します（最も低コストで、大半を検出できます）

get_project_graph()

すべてのプロジェクト参照を、基準で許可されている依存関係の矢印と照合します。ここで誤った参照が 1 つでも見つかった場合（Domain → Infrastructure など）、重大度は CRITICAL です。この参照によって、その後のすべての違反が起こり得るためです。

ステップ 3：循環依存を確認します

detect_circular_dependencies()

循環依存は、すべての基準において違反です。依存関係の経路全体を報告します。

ステップ 4：名前空間レベルの漏れを確認します（抜き取りチェック）

プロジェクト参照に問題がなくても、コードから漏れが発生していることがあります。リスクの高い境界を調査します。

get_dependency_graph(symbolName: <a Domain entity>, depth: 2)
   -- Domain types pulling in EF Core, HttpClient, or Infrastructure namespaces?
find_references(symbolName: <a module-internal type>)
   -- referenced from outside its module?
detect_antipatterns()
   -- known structural smells as supporting evidence

基準に応じて調査対象を選びます。Clean では Domain エンティティと Application ハンドラーを 3〜5 個ずつ、Modular Monolith では各モジュールの内部型を、VSA では 2〜3 個の機能フォルダー内の型を抜き取りで確認します。

ステップ 5：プレゼンテーション境界を確認します

get_endpoint_map()

エンドポイントは、ホスト／Api レイヤー（Clean）または所有するモジュール内（Modular Monolith、VSA の機能フォルダー）にのみ配置する必要があります。Application プロジェクトまたは共有プロジェクトに定義されたエンドポイントは、境界違反です。エンドポイントの認証が設定されていない場合は、追加の検出事項として報告します（詳しい調査には /security-scan を使用します）。

ステップ 6：レポート

重要度	意味
CRITICAL	依存方向が誤ったプロジェクト参照、モジュール間参照、循環依存
HIGH	名前空間の漏れ（Domain が Infrastructure／EF の型を使用）、レイヤー外に配置されたエンドポイント
MEDIUM	共有カーネルへのロジックの混入、メンバーへの直接アクセスによる集約の迂回
INFO	認証が設定されていないエンドポイント、確認する価値のあるアンチパターンの検出

各検出事項には、根拠（ファイルと行番号）、基準に違反する理由、修正方法（コードの移動、インターフェイスによる依存関係の逆転、コントラクトプロジェクトの導入、統合イベントの発行）を含めます。CRITICAL の項目は、すぐに修正することを提案してください。

使用する MCP ツール

• get_project_graph — 参照方向の監査（中核となるツール）
• detect_circular_dependencies — 循環依存の検出
• get_dependency_graph / find_references — 名前空間レベルの漏れの調査
• get_endpoint_map — プレゼンテーション境界と認証状況の確認
• detect_antipatterns — 構造に関する追加の根拠

例

User: /arch-check

Claude: Baseline from CLAUDE.md: Clean Architecture (4 projects).

  Project graph (get_project_graph)...
  CRITICAL  Domain → Infrastructure reference (Domain.csproj:14)
            Breaks the dependency rule; makes Domain untestable in isolation.
            Fix: invert — define IEmailSender in Application, implement in
            Infrastructure.
  Cycles (detect_circular_dependencies)... none.
  Leak probes on 4 Domain entities...
  HIGH      Order.cs:8 uses Microsoft.EntityFrameworkCore (Domain must stay
            persistence-ignorant). Fix: move the [Index] config to
            OrderConfiguration in Infrastructure.
  Endpoint map... 23 endpoints, all in Api. 2 unmarked auth (side-finding —
  run /security-scan).

  Verdict: NOT conformant — 1 critical, 1 high. Fix the reference first;
  want me to do it now?

関連項目

• architecture-advisor — ベースラインを選択します（このスキルが役立つようになる前に）
• clean-architecture、vertical-slice、ddd、modular-monolith テンプレート — 適用されるルールです
• /security-scan — 認証に関する副次的な指摘を詳しく確認します
• /health-check — より包括的な評価レポートです。arch-check はそのアーキテクチャ面を詳しく確認します