適合性ルール (Guardrails) - Archyl Docs

C4 model、技術的意思決定、コーディング標準に対してコード変更を検証する決定論的なアーキテクチャルールを定義します — AI は不要

適合性ルール (Guardrails)

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

サイドバーの Agent Hub に移動して適合性ルールを管理してください。

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

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

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

ルールは決定論的に評価されます — LLM なし、確率的出力なし。同じコードは常に同じ結果を生成します。

ルールタイプ

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

必須パターン

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

ユースケース 例
デバッグログの禁止 fmt.Println、console.log、print() を禁止
セキュリティリスクの禁止 eval()、innerHTML、ハードコードされたパスワードを禁止
エラーハンドリングの要求 シェルスクリプトで set -euo pipefail を要求
標準の強制 SQL クエリでの SELECT * を禁止

設定：

  • File glob — パターンに一致するファイルのみをチェック（例：*.go、*.ts）
  • 禁止パターン — 見つかった場合に違反をトリガーする正規表現パターン
  • 必須パターン — 欠落している場合に違反をトリガーする正規表現パターン

命名規則

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

スコープ 例
ファイル Go ファイルは snake_case.go でなければならない
型 エクスポートされた型は PascalCase でなければならない
関数 関数は動詞で始まるべき（Get、Create、Delete）

設定：

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

技術的制約

コンテナで許可される言語とライブラリを制限します。

ユースケース 例
言語ロック バックエンドは Go のみ
依存関係の禁止 lodash 禁止（ネイティブ JS を使用）
移行の強制 moment.js 禁止（date-fns を使用）

設定：

  • 許可された言語 — カンマ区切りリスト（例：go, typescript）
  • 禁止インポート — 1行に1つのインポート

レイヤー境界

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

レイヤー インポート可能な対象
Domain なし（純粋なビジネスロジック）
Service Domain のみ
Adapter Domain、Service
Infrastructure Domain のみ

設定：

  • レイヤー — 各レイヤーに名前、パスパターン（glob）、許可されたインポートソースを定義
  • レイヤー名をクリックしてインポート権限を切り替え

契約準拠

コードのエンドポイントが Archyl に保存された API 契約と一致するかを検証します。

設定：

  • 契約タイプ — HTTP (OpenAPI)、gRPC、GraphQL、または AsyncAPI
  • エンドポイントファイルパターン — エンドポイント定義を含むファイルの glob
  • 厳格モード — 有効時、契約にないエンドポイントは違反をトリガー

依存関係ルール

コンポーネント間の依存関係が C4 リレーションシップモデルと一致することを確認します。

設定：

  • スコープ — コンテナレベルまたはコンポーネントレベル
  • リレーションシップの存在を要求 — すべてのコードインポートに対応する C4 リレーションシップが必要
  • 禁止ペア — 相互に依存してはならない特定の要素ペア

イベントチャネル準拠

コード内のイベントプロデューサー/コンシューマーが宣言された EventChannel と一致するかを検証します。

設定：

  • プロデューサーパターン — イベント生成コードを識別する正規表現パターン
  • コンシューマーパターン — イベント消費コードを識別する正規表現パターン
  • Topic 正規表現 — コードから topic 名を抽出するパターン

ルールパック

パックはワンクリックでインストールできるルールのキュレーションされたコレクションです。ルールを一つずつ追加する代わりに、パックをインストールしてスタックに合った完全なルールセットを取得できます。

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

アーキテクチャパック

パック ルール数 強制する内容
Clean Architecture 5 domain/service/adapter/infra レイヤー境界、モジュール分離
Hexagonal Architecture 4 Ports & Adapters パターン、コア分離
Domain-Driven Design 3 DDD レイヤー、CQRS コマンド/クエリ分離

言語パック

パック ルール数 カバー内容
Go Backend 26 エラーラッピング、goroutine安全性、コンテキスト伝播、命名、panic禁止、init()禁止
React Frontend 23 TypeScript厳密性、コンポーネントパターン、データフェッチ、DOM操作禁止
Next.js Full-Stack 20 Reactルール + SSR安全性、windowガード、localStorageフック
Python Backend 16 例外処理、asyncパターン、型ヒント、グローバルステート禁止
Java Backend 11 Spring DIパターン、例外処理、System.exit禁止
Rust Backend 8 unwrap/unsafe禁止、適切なエラー型、todo!()禁止
Kotlin / Android 5 null安全性、不変性、println禁止
Vue Frontend 10 v-html禁止、TypeScript厳密性、innerHTML禁止
.NET / C# Backend 5 asyncパターン、例外処理、ILogger
Swift / iOS 3 Optional安全性、強制アンラップ禁止

ドメインパック

パック ルール数 カバー内容
Security Essentials 17 ハードコードされたシークレット、インジェクション、脆弱な暗号、TLS、CORS
DevOps & Infrastructure 24 Docker、Kubernetes、Terraform、GitHub Actions、シェルスクリプト
API Best Practices 9 ステータスコード、SQL安全性、契約ドキュメント、ハードコードされたURL禁止
Testing & Reliability 5 テストスキップ禁止、.only()禁止、sleep禁止、TODO禁止
Event-Driven Architecture 3 Kafka/RabbitMQトピック命名、ハードコードされたトピック禁止

ルールカタログ

Archyl には24の技術にわたる 170+の組み込みルールのカタログが付属しています。Agent Hub の Catalog をクリックしてカタログを閲覧できます。

対応技術

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

カテゴリ

カテゴリ 例
Architecture & Design Clean Architecture、Hexagonal、DDD、MVC、handler-service-repository
セキュリティ ハードコードされたシークレット禁止、eval() 禁止、SQL インジェクション禁止、TLS 無効化禁止、CORS ワイルドカード禁止
コード品質 デバッグログ禁止、空の catch ブロック禁止、bare except 禁止、any 型禁止、unwrap() 禁止
Infrastructure & DevOps Docker バージョンの固定、K8s リソース制限、特権コンテナ禁止、Terraform タグ
命名規則 言語ごとの snake_case、PascalCase、camelCase
テストと信頼性 スキップされたテスト禁止、.only() 禁止、TODO/FIXME 禁止
パフォーマンス 同期 sleep 禁止、N+1 クエリ禁止、ループ内の await 禁止
API とデータ 生 SQL 禁止、適切な HTTP ステータスコード、リクエストボディの検証

カタログ内の任意のルールをクリックして追加できます — 設定フォームが自動的に事前入力されます。

重大度レベル

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

重大度 意味 例
Critical マージ前に修正必須 ハードコードされたシークレット禁止、eval() 禁止、レイヤー境界違反
High マージ前に修正すべき デバッグログ禁止、Docker バージョンの固定、Go での panic 禁止
Medium 都合の良い時に修正 命名規則、any 型禁止、JS での var 禁止
Low 情報提供 TODO/FIXME 禁止、React でのインラインスタイル禁止

ルール管理

ルールの作成

  1. Packs をクリックしてスタックに合ったキュレーションされたルールセットをインストールするか、
  2. Catalog をクリックして170+の組み込みルールから選択して追加するか、
  3. Custom をクリックして新しいルールを手動で作成

ルールの有効化/無効化

任意のルールの横にあるスイッチを切り替えて有効化または無効化します。無効化されたルールは評価されません。

ルールの編集

任意のルールの編集アイコン（鉛筆）をクリックして、名前、説明、重大度、または設定を変更します。

ルールの削除

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

ルールのフィルタリング

  • 検索 — ルール名または説明でフィルタリング
  • タイプフィルター — タイプのピルをクリックして特定のタイプのルールのみを表示

CI/CD 統合

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

動作の仕組み

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

PR コメント

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

  • 重大度別の違反数を含むサマリーテーブル
  • ファイルごとの違反（説明と提案付き）
  • コメントは後続のプッシュで更新されます（重複しません）

MCP 統合

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

利用可能な MCP ツール

ツール 説明
list_conformance_rules オプションのプロジェクトフィルター付きですべてのルールを一覧表示
create_conformance_rule 新しいルールを作成
update_conformance_rule ルールの設定、重大度、または有効状態を更新
delete_conformance_rule ルールを削除
get_agent_context アクティブな guardrails を含む完全なアーキテクチャコンテキストを取得

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

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

コンテキストには以下も含まれます：

  • C4 model（システム、コンテナ、コンポーネント、リレーションシップ）
  • 根拠付きのアクティブな ADR
  • 技術スタック
  • API 契約
  • イベントチャネル

REST API

適合性ルールは REST API からも利用できます：

GET    /api/v1/conformance/rules              # ルール一覧
POST   /api/v1/conformance/rules              # ルール作成
POST   /api/v1/conformance/rules/bulk         # 複数ルール作成（パック使用時）
GET    /api/v1/conformance/rules/:id          # ルール取得
PUT    /api/v1/conformance/rules/:id          # ルール更新
DELETE /api/v1/conformance/rules/:id          # ルール削除
POST   /api/v1/conformance/rules/:id/toggle   # 有効化/無効化
POST   /api/v1/projects/:id/conformance/check # 変更ファイルでチェックをトリガー
GET    /api/v1/projects/:id/conformance/checks # チェック履歴一覧
GET    /api/v1/conformance/checks/:id/report  # チェックレポート取得
GET    /api/v1/projects/:id/conformance/stats  # プロジェクト統計取得

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