guard

@codapult/guard

AI コーディングエージェント向けのアーキテクチャガードレール

@codapult/guard は、ローカルファーストでモデルに依存しない、AI コーディングエージェント向けのアーキテクチャガードレールソフトウェアです。JavaScript および TypeScript プロジェクトで、アーキテクチャの逸脱を検出し、承認済みのソフトウェアアーキテクチャルールを適用し、コードの変更をチェックできます。

Guard はコードベースの構造を学習し、レビュー可能なメモリとしてプロジェクトのアーキテクチャを記録するとともに、チームが承認したルールに照らして今後の変更をチェックします。AI コーディングエージェントをそれらのルールに接続し、対象となるアーキテクチャ回帰を変更が引き起こした場合は、決定論的な証拠を返します。プロジェクト固有の同じチェックをローカルと CI で実行できます。

1つの変更で効果を確認

SaaS プロジェクトに、次のように確立された境界があるとします。

Client → Server Action → Service → Repository → Database

AI エージェントが、その境界を越えるコードを生成することがあります。コード自体は有効な TypeScript であってもです。

Client → Database

プロジェクトが対応するインポートルールまたは決定論的なコントラクトを明示的に承認すると、Guard は変更されたファイルをチェックし、一致する違反を決定論的に報告します。

Codapult Guard (changed files)
Scanned 1 source file(s); suppressed 12 baseline finding(s).

src/app/settings/page.tsx:1 [client-no-persistence-import]
  Client modules should not import persistence-layer modules.
  import: @/lib/db/client

✗ 1 issue(s) found
Exit code: 1

ファイルパス、ルール ID、メッセージ、件数はプロジェクトによって異なります。これは実際の CLI 出力形式です。Guard は、すべての Client → Database の依存関係が禁止されているとは推測せず、提案を黙って有効にすることもありません。まずチームが該当するポリシーを承認します。その後、既存の指摘事項はベースラインとして記録でき、新たに一致する違反はゲートで失敗となり、エージェントが修正するための限定的な証拠を提供します。

Guard は、すべてのプロジェクトに同じアーキテクチャを使うよう指示するものではありません。 既存のアーキテクチャを検出し、何をポリシーにするかをチームが決められるようにします。

コア機能は汎用です。特に有力な第一級のユースケースは Next.js SaaS と AI 支援開発で、サーバー／クライアント境界、ルート、永続化、認証、課金、バックグラウンドジョブ、環境設定、AI 連携が含まれます。

Guard が存在する理由

AI エージェントは、構文的には有効でも実際のプロジェクトのアーキテクチャに違反するコードを生成することがあります。たとえば、クライアントコンポーネントがサーバー専用コードをインポートする、既存の認証境界を迂回する新しいアクションを追加する、ルートがデータベースに直接書き込む、すでに存在するサービスを変更によって重複させる、といったケースです。

既存のツールは引き続き不可欠ですが、それぞれ異なる問題を解決します。

ツールのカテゴリ	主な問い	Guard との関係
TypeScript	コードは型として正しいですか？	プロジェクトの型チェックを任意のゲートとして使用します。
ESLint / Biome	コードは言語とスタイルのルールに従っていますか？	それらのリントルールを重複して実装しません。
テスト	動作は実行可能な期待値と一致していますか？	有効化されている場合は設定済みのチェックを実行しますが、テストの代わりにはなりません。
SAST / 依存関係スキャナー	既知のセキュリティリスクや依存関係のリスクはありますか？	アダプターに接続できます。アーキテクチャと変更の影響に重点を置きます。
PR レビューサービス	レビュアーが検討すべき意味上の懸念は何ですか？	選択した AI ホスト向けに、範囲を限定して情報を秘匿したレビュー用パケットを生成します。
Guard	プロジェクトのアーキテクチャは悪化していますか？	プロジェクト固有のアーキテクチャの記憶と回帰ゲートを維持します。

インストール

要件：Node.js >=20.19 と JavaScript または TypeScript プロジェクト。

pnpm add -D @codapult/guard
# or
npm install --save-dev @codapult/guard

このパッケージは codapult-guard バイナリを公開します。

pnpm exec codapult-guard init

npm パッケージのスコープは @codapult/guard です。実行可能ファイル名は、見つけやすさとスタンドアロン製品名との一貫性を保つため、意図的に codapult-guard のままにしています。

60 秒で始めるクイックスタート

プロジェクトのルートから実行します。

# 1. Build the initial project model and baseline
pnpm exec codapult-guard init

# 2. Inspect only new and changed architecture findings
pnpm exec codapult-guard check --changed

# 3. Prepare deterministic context for an AI review
pnpm exec codapult-guard review --requirement docs/acceptance.md

# 4. Run the configured completion gate
pnpm exec codapult-guard verify --json

init は保護されており、既存のベースラインを上書きしません。プロジェクトの記憶を意図的に置き換える場合に限り、init --force を使用してください。ベースラインをリセットせずに検出済みの事実を更新するには、analyze を使用します。

運用モデル

Guard は、事実、ポリシー、検証、判断を分離します。

レイヤー	含まれるもの	生成方法
事実	AST、ファイル、インポート、依存関係、ルート、呼び出し、機能、グラフ、Git 履歴	決定論的なローカル検出
ポリシー	ルール、コントラクト、規約、ベースライン	観測された提案とチームによる明示的な承認
検証	変更ファイルのチェック、影響分析、コントラクト、プロジェクトのチェック、レビュー用パケット	ローカル CLI、MCP、CI、既存のプロジェクトツール
判断	合格、不合格、警告、レビューが必要、未設定	Guard の証拠を使用する開発者または AI ホスト

Guard は、UI → actions → services → repositories → database という固定のアーキテクチャを前提としません。プロジェクトにその構造が見られる場合は検出できますが、観測されたパターンが強制可能になるのは、明示的に承認された後に限られます。

ポリシーのパスは、プロジェクト相対パスとして検証されます。Guard は、パスの上位階層への移動、絶対パス、プロジェクトのルート外を指すシンボリックリンクを拒否します。また、インポート境界のチェックでは、インポート、再エクスポート、リテラル形式の動的インポートを対象とします。

ポリシーの適用範囲と状態の変更

Guard はプロジェクトレベルでポリシーを保存しますが、各ポリシー項目はより狭い境界を対象にできます。

ポリシー項目	適用範囲の制御
ルール	files、インポートパターン、ルールの種類
コントラクト	scope、entrypoints、インポート／パッケージの制約、必須の呼び出し
予算	scope、メトリクス、上限、重大度、記述された理由
ベースライン	すでにレガシー債務として受け入れられた、完全一致する検出結果のフィンガープリント
免除	所有者、理由、有効期限を指定した、有効な検出結果のフィンガープリント1つ

通常のチェックによって、ソースコード、ルール、コントラクト、ベースライン、免除が変更されることはありません。ポリシーを変更するコマンドは明示的です。init、rules approve、contracts approve|reject、baseline accept|remove、waiver add|renew|remove が該当します。analyze は派生したプロジェクトの事実を更新し、verify はプロジェクトで設定されたコマンドを実行してローカルの実行マニフェストを記録する場合がありますが、どちらも承認済みポリシーを変更しません。

変更契約とホスト／CI 制御の全容については、 ポリシー変更の制御を参照してください。

Guard が検出するもの

このモデルはフレームワークを認識しますが、特定のフレームワークには依存しません。

領域	検出される証拠の例
JavaScript / TypeScript	AST モジュール、宣言、呼び出し、ディレクティブ、エイリアス、再エクスポート、動的インポート
Next.js / React	App Router のルート、ルートメソッド、Server Actions、クライアント／サーバーの境界
API の境界	ルートハンドラー、API モジュール、エントリーポイント、影響範囲のパス
データ	ORM パッケージ、スキーマ、マイグレーション、リポジトリ、永続化の境界
機能	認証、決済、メール、AI/RAG、キュー、ストレージ、キャッシュ、検索、分析、コンテンツ
運用	環境変数の参照、設定、デプロイ、オブザーバビリティ、ウェブフック
リポジトリの構成	ワークスペース、パッケージスクリプト、依存関係、循環参照、インポートのホットスポット、Git の履歴
テスト	テストファイル、テストスクリプト、ワークスペースのチェック、変更されたファイル

機能は証拠であり、必須要件ではありません。Vite アプリ、Express サービス、Hono プロジェクト、Node パッケージ、モノレポ、Next.js SaaS のいずれも、同じ Guard コアを利用できます。

Guard とは何か — そして、何ではないか

Guard は、AI を活用した開発のためのアーキテクチャ制御プレーンです。ローカルの事実、承認済みポリシー、決定論的な検証を用いて、プロジェクト固有の境界と変更による影響を保護します。

Guard は ESLint、TypeScript、テスト、SAST、汎用の PR ボットに取って代わるものではありません。これらのツールはそれぞれ異なる問いに答えます。Guard は、その結果を AI コーディングエージェントがリポジトリを変更する前後に必要とするアーキテクチャ上の記憶と結び付けます。

通常のループ

init once → edit → check --changed → review → verify → commit / merge
                         ↘ analyze after structural changes

1. init はプロジェクトのメモリを構築し、初期ベースラインを確立します。
2. check は現在のプロジェクトをスキャンします。check --changed は、変更箇所に絞った高速なアーキテクチャゲートです。
3. review は、AI ホスト向けに範囲を限定して機密情報を除去した差分パケットを準備します。LLM は呼び出しません。
4. verify は Guard ポリシー、設定済みのプロジェクトチェック、アダプター、ランタイム診断、契約の検証を実行します。
5. audit は、ベースラインで受け入れられた指摘も含め、現在の状態全体を検査します。

変更内容を絞って説明するには、codapult-guard impact <file...> または同等の codapult_guard_impact MCP ツールを使用します。依存関係グラフの両方向、つまり変更されたモジュールが使用するものと、影響を受ける可能性がある推移的な呼び出し元を報告します。review には同じ影響範囲パケットに加え、型付きの Git 変更（added、modified、deleted、renamed）も含まれます。

Guard の状態は .codapult/guard/ に保存されます。

.codapult/guard/
├── project.json       discovered project model
├── architecture.json  observed architecture and capabilities
├── conventions.json   recurring project conventions
├── rules.json         active and proposed deterministic rules
├── contracts.json     project-specific boundaries and required calls
├── proposals.json     evidence and approval history
├── baseline.json      accepted pre-existing findings
├── agent.json         AI-host completion-gate configuration
├── waivers.json       time-bounded exceptions to active findings
└── history/           project snapshots and local verification run manifests

チームでガードレールを共有する場合は、ポリシーとベースラインのファイルをコミットしてください。キャッシュの生成物はプロジェクトのポリシーに従って破棄可能なものとして扱い、シークレットは決してコミットしないでください。

ベースラインのフィンガープリントには行番号が含まれないため、書式や行の移動によって同じ指摘が再生成されることはありません。一方、ルールと影響を受けるファイル／インポートの識別情報は含まれるため、名前変更やモジュールの移動によって新しいフィンガープリントが生成される場合があります。ベースラインへの受け入れ前に、明示的に確認してください。

一時的な免除

ベースラインには、Guard の導入時点で存在していたレガシーな指摘が記録されます。免除はこれとは異なり、アクティブな指摘を一時的に 1 件抑制するもので、所有者、理由、有効期限を指定する必要があります。

codapult-guard waiver add <fingerprint> \
  --owner platform-team \
  --reason "Migration in progress" \
  --expires 2026-12-28
codapult-guard waiver list
codapult-guard waiver renew <id> --expires 2027-01-31 --reason "Migration continues"
codapult-guard waiver remove <id> --reason "Migration completed"

Guard は、免除が設定済みの警告期間（デフォルトでは 14 日）内に入ると警告します。有効期限が切れると、元の指摘が再びアクティブになります。保護されたポリシーでは、MCP 経由での免除の変更を禁止できます。これにより、エージェントは免除を提案できますが、自ら承認することはできません。免除は意図的にフィンガープリント単位で適用されるため、違反コードを変更すると免除は無効になります。

チームは、rules.json の waiverPolicy.maxDays を設定して、新しい免除や更新の期間に上限を設けることもできます。

"waiverPolicy": { "warningDays": 14, "maxDays": 90 }

この上限は、現在の操作で要求された付与期間に適用されます。既存の免除が暗黙に削除または書き換えられることはありません。重大度が error の境界の指摘があると check は失敗します。警告レベルの指摘と免除の期限切れリマインダーは、引き続き参考情報として扱われます。

codapult-guard doctor を実行すると、クライアントまたはパッケージの境界が明示的にダウングレードされていることを検出できます。Doctor はこれを警告として報告し、プロジェクトのポリシーは変更しません。

任意のスコープ付き上限

上限はポリシーであり、普遍的なスタイル規則ではありません。サービス、ルートハンドラー、依存関係の多いモジュールなど、対象を明確にしたリスク境界に限って追加してください。

{
  "id": "service-lines",
  "description": "Services must remain reviewable.",
  "metric": "lines",
  "scope": ["src/services"],
  "limit": 300,
  "severity": "warning",
  "reason": "Keep service changes reviewable by one owner.",
  "status": "active"
}

上限は .codapult/guard/rules.json の budgets 配列に指定します。サポートされる指標は lines、bytes、imports です。生成ファイル、スキーマ、マイグレーション、その他のパスは、scope に明示的に含めない限りチェックされません。* などのワイルドカードを使用すると、意図的にプロジェクトのルートを対象にできます。無効なスコープ、絶対パス、親ディレクトリ、存在しないスコープがあると、Guard ゲートは失敗します。上限の変更はポリシー上の判断です。差分を確認し、上限を黙って引き上げるのではなく、記述済みの reason を更新してください。

AI エージェントと MCP

Guard は意図的にモデルに依存しない設計です。ソースコードをリモート LLM に送信せず、それ自体でソースファイルを編集することもありません。モデルの呼び出し、権限、修正ループ、最終判断は AI ホストが担います。

stdio でスタンドアロン MCP サーバーを起動します。

pnpm exec codapult-guard mcp-server

プロジェクトのルートから、そのコマンドを MCP クライアントに登録します。たとえば、Cursor では .cursor/mcp.json を使用できます。

{
  "mcpServers": {
    "codapult-guard": {
      "type": "stdio",
      "command": "pnpm",
      "args": ["exec", "codapult-guard", "mcp-server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

汎用 stdio サーバーを受け入れるクライアントでは、同じコマンドを使用し、作業ディレクトリをプロジェクトのルートに設定してください。Guard はローカルファイルのみを読み取るため、API キーやモデルプロバイダーは不要です。ホスト固有の例は docs/integrations/ にあります。

推奨するエージェントのループ：

task finished
  → codapult_guard_next_action
  → codapult_guard_context
  → codapult_guard_review(requirement, diff)
  → codapult_guard_verify
  → repair reported failures
  → repeat until pass or bounded iteration limit

codapult_guard_context は、ホストがプロジェクトの状態を明確に把握できるようにします。observations は検出された事実のみ、proposals.pendingRules と proposals.pendingContracts は未承認のポリシー提案、policy はアクティブなルール／コントラクトとベースラインおよび免除の状態のみを含み、verification はチェックが実際に実行されたかどうかを報告します。verification.status: "not-run" かつ findings: null のコンテキスト応答は、チェックに合格したことを意味しません。

Cursor、Claude Code、Codex、Gemini CLI、GitHub Copilot、および汎用ホストについては、docs/integrations/ を参照してください。

MCP Registry

Guard は、サーバー名 io.github.codapult/guard として公式の MCP Registry に公開されています。Registry は、公開されている @codapult/guard npm パッケージとその stdio MCP サーバーを見つけるためのレイヤーであり、npm によるインストールや上記のホスト固有の設定に代わるものではありません。確実にセットアップするには、npm パッケージを直接インストールし、以下の MCP 設定を使用してください。

作成エージェントが自分自身のポリシー提案を承認してはならないワークフローでは、rules.json で Guard を保護モードに設定します。

{
  "approval": {
    "mode": "protected",
    "allowMcpApproval": false,
    "requireDistinctActor": true
  }
}

その後、MCP でポリシーを読み取り、提案できますが、承認は CLI または保護された CI/PR プロセスを通じて行います。requireDistinctActor を設定すると、CLI および許可された MCP による承認では GUARD_APPROVER が必要になり、提案が GUARD_PROPOSER を使って生成されていた場合、Guard は同一の宣言済みアクターを拒否します。これらの変数が示すのは宣言された来歴のみです。誰が変更を承認したかの証明は、外部のブランチ保護または署名付き ID が引き続き担います。

保護されたポリシーに対する検証

CI では、ブランチが持ち込んだポリシーのコピーではなく、保護されたベースコミットのポリシーを使ってプルリクエストを検証します。

codapult-guard verify --policy-base "$BASE_SHA" --json

これにより Guard は、ベースコミットのルール、コントラクト、ベースライン、免除、完了ゲート設定を使って、変更されたソースを評価します。結果には policy.source、policy.ref、policy.revision、policy.fingerprint と、チェックアウトされたポリシーがそのベースと異なるかどうかが報告されます。ブランチは、自身のポリシーを緩和したりゲートを無効にしたりして、その緩和されたコピーを同じ検証実行に使用することはできません。

付属の docs/guard-ci.yml は Git の全履歴を取得し、プルリクエストのベース SHA を自動的に渡します。ポリシーの変更に別途承認が必要な場合は、CODEOWNERS または同等のレビュー管理で .codapult/guard/ を保護してください。たとえば、リポジトリの CODEOWNERS に .codapult/guard/* @architecture-owners を追加できます。Guard はポリシーの変更を報告し、レビュー担当者の承認権限はホスティングプラットフォームが適用します。

この実行でポリシーの変更を明示的に失敗させるには、次を追加します。

codapult-guard verify --policy-base "$BASE_SHA" --fail-on-policy-change

これは、ポリシー専用のレビュービューゲートに役立ちます。ソースの検証にベースポリシーを使用することとは意図的に分けてあるため、保護されたレビューのワークフローで、承認済みのポリシー更新をどう扱うかをチームで選択できます。

サポート対象の AI ホスト、CI/PR、ポリシーパック、ツールアダプター、承認ガバナンス、可観測性の統合については、拡張機能マップ を参照してください。

CI

Guard をインストールして初期化したプロジェクトに、利用側のワークフローをコピーします。

cp node_modules/@codapult/guard/docs/guard-ci.yml .github/workflows/guard.yml

または、docs/guard-ci.yml からコピーできます。このワークフローはプロジェクトの検証を実行し、Guard の検出結果を GitHub コードスキャン用の SARIF としてエクスポートします。プルリクエストでは、ライフサイクルスクリプトを実行せずに依存関係をインストールし、プルリクエストが所有するスクリプトを実行せずに決定論的な Guard チェックを行います。信頼されたプッシュでは、設定されたプロジェクトのチェックを実行できます。

パッケージリポジトリでは、別途、独自のユニットテスト、型チェック、ビルド、パッケージングのチェックを .github/workflows/ci.yml で実行します。一方、フィクスチャのワークフローでは、実際のプロジェクト構成で Guard をテストします。

CLI の概要

コマンド	目的
init	プロジェクトのメモリと初期ベースラインを作成します。
analyze	ポリシーやベースラインを変更せずに、ファクトを更新します。
propose	根拠に基づくルールとコントラクトの提案を生成します。
check [--changed]	有効なポリシーを適用します。--changed を指定すると、検出対象を変更済みファイルと未追跡ファイルに限定します。
audit	ベースラインの検出結果も含め、現在のプロジェクト全体をスキャンします。
review	AI ホスト向けに、範囲を限定したセマンティックレビュー用パケットを作成します。
verify	設定された完了ゲートを実行します。
governance	宣言された提案／承認の来歴と、決定から実行への到達可能性を監査します。
doctor	無効または不足している Guard アーティファクトを診断します。
history / history-diff	プロジェクトモデル、モジュールグラフ、アーキテクチャエッジの変遷を調べます。
impact <files...>	ファイルが影響する依存関係、推移的な依存先、機能、コントラクトを説明します。
policy explain <id>	ポリシー項目、その根拠、承認履歴を説明します。
rules / contracts	ルールを承認し、コントラクトを承認または却下します。
baseline	既存の検出結果を確認するか、意図的に受け入れます。
waiver	所有者が明記された、特定の検出結果に対する期限付きの例外を管理します。

構造に変更を加えた後は、analyze --refresh を実行します。doctor --fix-cache は破棄可能な検出キャッシュのみを削除し、ルール、コントラクト、ベースライン、ソースファイルは変更しません。

Guard の状態は、CLI／MCP の読み取りと書き込みを並行して安全に行えます。導出されたファクトはアトミックな世代として公開され、ポリシーの更新にはリビジョンが使用され、短時間の書き込み競合は解消されるまで待機します。状態ロックを保持したままプロセスが終了した場合は、ローカル PID によって検出され、ロックが復旧されます。連携先で競合の発生をすぐに通知する必要がある場合は、--no-wait を使用します。

コマンド固有のオプションを確認するには、pnpm exec codapult-guard <command> --help を実行します。 すべての verify の実行では、ローカルマニフェストも .codapult/guard/history/runs/<run-id>.json に書き込まれます。このマニフェストには、各ステージの所要時間、実行結果、結果を決定したポリシーゲートが記録されます。また、適用されたポリシーのリビジョンとフィンガープリントも記録されます。ベースの ref が指定された場合は、その ref と、作業ツリーのポリシーに差異があったかどうかも記録されます。承認済みのポリシー判定によって現在のポリシーが適用された場合、マニフェストにはその判定 ID も保持されるため、承認から検証までの関係をたどれます。governance コマンドはこのメタデータを監査し、宣言されたアクターの欠落や重複を報告します。ソースコードや外部テレメトリは含まれません。これらのマニフェストにより、Guard を本番環境のトレーシングシステムや ID／署名台帳にすることなく、失敗した実行の理由を説明できます。

マニフェストには、verification-receipt オブジェクトも含まれます。これは、コミット、ポリシーのベースとフィンガープリント、判定 ID、チェックのステータス、検出件数、コントラクトの問題、免除の状態、Guard のバージョンを記録する、簡潔で機械可読な記録です。コマンド出力やソースコードは意図的に含めていません。このレシートが示すのは Guard の判定内容であり、暗号署名でも CI の ID の証明でもありません。ポリシーのベースが指定されている場合は、ベースとの差分と、変更されている作業ツリーのファイルを分けて記録するため、ローカル検証で不完全な変更セットが気付かれないまま提示されることはありません。

セキュリティとデータの取り扱い

• 決定論的な検出とチェックはローカルで実行されます。
• レビューパケットはサイズが制限され、AI ホストに返される前に一般的なシークレットがマスキングされます。
• Guard は LLM を呼び出さず、プロバイダーの API キーも必要としません。
• プロジェクトのコマンドと外部アダプターは、プロジェクト設定で有効にされている場合にのみ実行されます。
• 既存の検出結果はベースラインとして設定できますが、新たなリグレッションは引き続き確認できます。

検証と証明

リポジトリでは、複数の層を通じて製品を検証します。

• 検出、ポリシー、ベースライン、検証、MCP、出力に関するユニットテストと統合テスト。
• エイリアス、再エクスポート、動的インポート、ルート境界に関する AST の敵対的ケース。
• 違反から修正までのゴールデンエンドツーエンドフロー。
• 実際の Next.js、React/Vite、Node、Hono、モノレポ、Express のリポジトリを対象とした、変更に対するリグレッションチェック。
• 公開されるアーティファクトに意図したビルド出力のみが含まれることを確認する npm pack チェック。

メンテナー向けのチェックをローカルで実行します。

pnpm test
pnpm test:guard:golden
pnpm test:guard:fixtures
pnpm test:guard:fixtures:regression
pnpm release:check

ドキュメント

• Guard の完全ガイド
• AI エージェントとの統合
• ホストとの統合
• CI コンシューマーのワークフロー
• フィクスチャの一覧
• リリース手順

Codapult のその他の情報

SaaS をゼロから始めますか？Codapult は、AI 支援開発向けに構築された、本番環境対応の Next.js SaaS 基盤です。MCP コンテキスト、組み込みの AI、モジュール型アーキテクチャを備え、ソースコードは自分で管理できます。

ライセンス

MIT です。LICENSE を参照してください。