適合性ルール（ガードレール）

適合性ルールは、アーキテクチャ上の意思決定に照らしてコード変更を検証する決定論的なチェックです。命名規則、技術的制約、レイヤー境界、セキュリティパターンを強制します — AI は一切関与しません。

サイドバーの エージェントハブ に移動して、適合性ルールを管理します。

なぜ適合性ルールが必要なのか？

AI コーディングエージェント（Claude Code、Cursor、Copilot）は、コードを生成する際にあなたのアーキテクチャ上の意思決定を知りません。適合性ルールは、これらの意思決定を実行可能な制約としてエンコードします：

• テクノロジーレーダーで PostgreSQL と定めている場合、エージェントは MongoDB を使用できません
• アーキテクチャでサービスレイヤーを必須としている場合、エージェントは HTTP ハンドラーにデータベース呼び出しを置けません
• チームで構造化ログを使用している場合、エージェントは fmt.Println を追加できません

ルールは 決定論的 に評価されます — LLM も確率的な出力もありません。同じコードからは常に同じ結果が得られます。

ルールタイプ

Archyl は 7 種類の適合性ルールをサポートしています：

必須パターン

コード内に存在しなければならないパターン、または存在してはならないパターンをチェックします。

設定：

• File glob — パターンに一致するファイルのみをチェックします（例：*.go、*.{ts,tsx}）
• Forbidden patterns — 見つかると違反になる正規表現パターン
• Required patterns — 見つからないと違反になる正規表現パターン

ファイル glob はブレース展開に対応しています：*.{js,jsx,ts,tsx} はすべての JavaScript ファイルと TypeScript ファイルに一致します。

命名規則

ファイル、型、関数の命名パターンを検証します。

設定：

• Patterns — スコープ（ファイル/型/関数）+ 正規表現 + 説明のリスト

技術的制約

コンテナで使用できる言語とライブラリを制限します。

設定：

• Allowed languages — カンマ区切りのリスト（例：go, typescript）
• Forbidden imports — 1 行に 1 つのインポート

レイヤー境界

クリーンアーキテクチャ、ヘキサゴナルアーキテクチャ、または DDD のレイヤー間インポートルールを強制します。

設定：

• Layers — 各レイヤーを、名前、パスパターン（glob）、許可するインポート元で定義します
• レイヤー名をクリックすると、インポート権限を切り替えられます

契約準拠

エンドポイントのハンドラーファイルに、適切な API 契約のドキュメントが含まれていることを検証します。

設定：

• Contract type — HTTP (OpenAPI)、gRPC、GraphQL、または AsyncAPI
• Endpoint file patterns — エンドポイント定義を含むファイルを指定する glob
• Strict mode — 有効にすると、契約ドキュメントのない一致ファイルはすべて違反になります

依存関係ルール

アーキテクチャ境界間で禁止するインポートパスを強制します。

設定：

• Scope — コンテナレベルまたはコンポーネントレベル
• Forbidden pairs — 互いに依存してはならないソースとターゲットのパスパターン（例：**/service/** -> **/handler/**）

イベントチャネル準拠

イベントのプロデューサー/コンシューマーのパターンが命名規則に従っていることを検証します。

設定：

• Producer patterns — イベントを生成するコードを識別する正規表現パターン（例：kafka\.Send）
• Consumer patterns — イベントを消費するコードを識別する正規表現パターン
• Topic regex — 有効なトピック名が一致しなければならないパターン（例：^[a-z]+\.[a-z]+\.[a-z]+$）

ルールパック

パックは、ワンクリックでインストールできる厳選されたルールのコレクションです。ルールを 1 つずつ追加する代わりにパックをインストールすれば、スタックに合った完全なルールセットが手に入ります。

ツールバーの Packs をクリックすると、利用可能なパックを閲覧できます。

アーキテクチャパック

言語パック

ドメインパック

ルールカタログ

Archyl には、23 の技術にわたる 169 個の組み込みルール のカタログが付属しています。エージェントハブで カタログを閲覧 をクリックすると、カタログを参照できます。

対応技術

Go、TypeScript、JavaScript、Python、Java、Kotlin、Rust、C#、C/C++、Ruby、PHP、Swift、React、Vue、Angular、Next.js、Docker、Kubernetes、Terraform、SQL、Shell、YAML、GitHub Actions

カテゴリ

カタログ内のルールをクリックすると追加できます — 設定フォームには値が自動的に入力されます。

重大度レベル

各ルールには、その影響度を決める重大度があります：

重大度が「重大」または「高」の違反が 1 件でも見つかると、適合性チェックは 失敗 します。「中」と「低」の違反はレポートされますが、チェックは失敗しません。

適合性ダッシュボード

エージェントハブの ダッシュボード タブでは、すべてのプロジェクトにわたる適合性チェックの概要をリアルタイムで確認できます。

表示内容

• 統計カード — 合計チェック数、合格率（色分け表示）、合格数、不合格数
• 合格 / 不合格比 — 割合をひと目で把握できるビジュアルバー
• 最新チェックのバナー — 直近のチェックのステータスと、完全なレポートへのリンク
• 最近のチェック一覧 — すべてのチェックを、ステータス、トリガー種別、プロジェクト名、ファイル数、違反数、経過時間とともに表示

フィルタリング

上部の プロジェクトのドロップダウン でチェックをプロジェクトごとに絞り込めます。すべてを表示するには「すべてのプロジェクト」を選択します。

チェックレポート

チェックをクリックすると、完全なレポートを詳しく確認できます：

• 重大度の内訳バー — 重大/高/中/低の違反の割合を示すビジュアル表示
• ファイル別にグループ化された違反 — 各違反の重大度、タイトル、説明、提案を表示する折りたたみ可能なセクション
• チェックのメタデータ — トリガー種別、コミット SHA、開始時刻、所要時間

各チェックレポートには、それぞれ 共有可能な URL があります（例：/agent/dashboard/:checkId）。

チェックの削除

複数選択 を使って、チェックを一括削除できます：

1. 各チェックの横にあるチェックボックスをクリックするか、「すべて選択」を使用します
2. 表示される赤い Delete ボタンをクリックします
3. チェックとその違反は完全に削除されます

CI/CD 統合

適合性ルールは、プルリクエストごとに自動で実行できます。セットアップ手順については GitHub Actions 統合 を参照してください。

仕組み

1. GitHub で PR が作成または更新されます
2. Archyl GitHub Action が変更されたファイルを取得します
3. ファイルが評価のために Archyl API に送信されます
4. 結果が PR コメントとコミットステータスチェックとして表示されます
5. 重大度が「重大」または「高」の違反が見つかった場合、ワークフローは失敗します

PR コメント

違反が見つかると、Archyl は PR に詳細なコメントを投稿します：

• 重大度別の違反数をまとめたサマリーテーブル
• ファイルごとの違反と、その説明および提案
• 以降のプッシュでは、コメントは重複して投稿されず、更新されます

ルールの管理

ルールの作成

1. Packs をクリックしてスタックに合った厳選ルールセットをインストールするか、
2. カタログを閲覧 をクリックして 169 個の組み込みルールから選んで追加するか、
3. カスタムルール をクリックして新しいルールを手動で作成します

ルールの有効化/無効化

ルールの横にあるスイッチを切り替えると、そのルールを有効化または無効化できます。無効化されたルールは評価されません。

ルールの編集

ルールの編集アイコン（鉛筆）をクリックすると、名前、説明、重大度、設定を変更できます。

ルールの削除

削除アイコン（ゴミ箱）をクリックし、確認します。この操作は元に戻せません。

ルールのフィルタリング

• 検索 — ルール名または説明で絞り込みます
• タイプフィルター — タイプのピルをクリックすると、特定のタイプのルールだけを表示します

MCP 統合

適合性ルールには、MCP サーバーを通じて AI エージェントからアクセスできます：

利用可能な MCP ツール

エージェントからのチェック実行

run_conformance_check ツールを使うと、AI エージェントはコミット前にコードを検証できます。エージェントは作業中のファイルを送信します：

{
  "projectId": "your-project-uuid",
  "changedFiles": [
    { "path": "internal/handler/user.go", "status": "modified" }
  ],
  "fileContents": {
    "internal/handler/user.go": "package handler\nimport..."
  }
}

レスポンスには以下が含まれます：

• passed — チェックに合格したかどうか（重大度が「重大」または「高」の違反がないこと）
• violations — 重大度、ファイルパス、タイトル、提案を含む違反のリスト
• rulesEvaluated — 評価されたルール
• filesAnalyzed — 分析されたファイルの数
• checkId — チェック ID（ダッシュボードで確認できます）

エージェントはこのフィードバックを使って、コードがコミットされる前に違反を修正できます。

エージェントコンテキスト

MCP ツール get_agent_context は、アーキテクチャブリーフィングの一部として、有効なすべての適合性ルールを返します。作業を始める前にこのツールを呼び出す AI エージェントは、どのガードレールを守るべきかを把握できます。

REST API

# Rules
GET    /api/v1/conformance/rules              # List rules
POST   /api/v1/conformance/rules              # Create rule
POST   /api/v1/conformance/rules/bulk         # Create multiple rules (used by packs)
GET    /api/v1/conformance/rules/:id          # Get rule
PUT    /api/v1/conformance/rules/:id          # Update rule
DELETE /api/v1/conformance/rules/:id          # Delete rule
POST   /api/v1/conformance/rules/:id/toggle   # Enable/disable

# Checks
POST   /api/v1/projects/:id/conformance/check # Trigger check with changed files
GET    /api/v1/conformance/checks             # List all checks (org-wide, ?projectId= filter)
GET    /api/v1/conformance/checks/:id/report  # Get check report with violations
POST   /api/v1/conformance/checks/delete      # Bulk delete checks { ids: [...] }

# Stats
GET    /api/v1/conformance/stats              # Org-wide statistics
GET    /api/v1/projects/:id/conformance/stats  # Project statistics

すべてのエンドポイントで認証が必要です（JWT、または変更操作には書き込みスコープを持つ API キー）。