AIエージェント向け集中型ルール構造

CrystaCodeプロジェクトにおけるシングルソースアーキテクチャを通じたAIエージェントの遵守強制 AIエージェント...

Dev.to · Jul 30, 2026

Centralized Rule Structures for AI Agents

CrystaCodeプロジェクトにおけるシングルソースアーキテクチャを通じたAIエージェントの遵守強制

AIエージェントは、論理的逸脱なくプロジェクトルールを実行するために厳格なディレクトリ構造を必要とします。ルールの重複は実行の失敗を引き起こします。単一の信頼できる情報源を確立します。各ルールを正確に1つの場所で定義します。セカンダリファイルは、ルーティングパラメータとしてのみ機能します。

システムアーキテクチャ

AGENTS.md                        # プライマリエントリファイル
CLAUDE.md                        # AGENTS.mdへのポインタ

agents/
  rules/
    productA.md                  # コンポーネント指令
    productB.md
  skills/
    styling-guidelines-a/SKILL.md
    styling-guidelines-b/SKILL.md
  hooks/
    styling-guard.ps1            # インターセプタ実行スクリプト

docs/
  Conventions/
    ProductA/styling-guidelines.md   # 絶対ルールテキスト
    ProductB/styling-guidelines.md

.claude/
  settings.json                  # Claudeフック指令
  skills/*/SKILL.md              # 自動生成された成果物

.github/
  instructions/*.instructions.md # GitHubエージェントポインタ
  hooks/preToolUse.json          # GitHubフック指令

全画面表示に入る全画面表示を終了

コンポーネント仕様

プライマリノード

AGENTS.md: 必須の初期化ファイル。ルーティングマトリックスを含みます。ファイル拡張子のトリガーを概説し、特定の必要ドキュメントにマッピングします。

リダイレクトノード

CLAUDE.md: パーサーにAGENTS.mdを評価するよう指示する単一のポインタを含みます。
.github/instructions/: GitHub Copilotをモジュール固有のルールにリダイレクトするポインタ。

運用指令

agents/rules/: 特定のプロジェクトモジュールにマッピングされた分離された手順とチェックリスト。ルール定義をskillsディレクトリに委ねます。
agents/skills/: 操作の正確な前提条件を規定するコンテキストトリガー。絶対ルールテキストをdocs/リポジトリに委ねます。

絶対ドキュメンテーション

docs/: 決定的なリポジトリ。完全な技術仕様とルールテキストを含みます。ルール定義のための唯一の場所。

自動ミラー

.claude/skills/: agents/skillsの自動ミラー。手動での変更は厳しく禁止されています。

インターセプタスクリプトプロトコル

styling-guard.ps1フックは、セッションマーカーに基づいて実行を制御することでコンプライアンスを強制します。

リクエストの傍受:
スクリプトは、AIファイル変更リクエストを実行前に傍受します。
ターゲットパラメータの評価:
ファイル拡張子がターゲットパラメータ（.scss、.razor）に対して評価されます。一致しないファイルは傍受をバイパスします。
製品関連付けの確認:
スクリプトは、ターゲットファイルパスを評価して関連するプロジェクトモジュールを特定します。
セッションデータのクエリ:
スクリプトは、ファイルタイプとモジュールに対応する既存の実行マーカーがセッションデータに存在するかを確認します。存在する場合、AIは傍受をバイパスします。
実行の中止:
マーカーが存在しない場合、実行はブロックされます。AIは必要なスキルドキュメントを解析するよう明示的な指令を受け取ります。
実行マーカーの書き込み:
スクリプトは実行マーカーをセッションデータに書き込みます。同じセッションでの後続の変更試行は、中断なく進行します。

インターセプタ実装ロジック
インターセプトメカニズムは、セッションマーカーが存在しない場合に実行を中止するための明示的な標準エラー指令を出力します：

デプロイメントチェックリスト

if ($category -eq 'scss') {
    [Console]::Error.WriteLine(
        "MANDATORY styling gate: this is the first .scss edit in this session for the " +
        "'$product' product. Invoke the '$skill' skill (canonical rules: $doc), apply its " +
        "rules -- $checklist -- then retry this exact edit. $forbidden " +
        "This gate fires once per session per product per file category.")
} else {
    [Console]::Error.WriteLine(
        "MANDATORY component gate: this is the first .razor edit in this session for the " +
        "'$product' product. Before this edit: (1) invoke the '$skill' skill (canonical " +
        "rules: $doc) for color/typography/component conventions -- use $components. " +
        "(2) invoke the 'localize-app-strings' skill -- never hardcode user-facing text, " +
        "always route through IStringLocalizer<AppStrings>. Then retry this exact edit. " +
        "This gate fires once per session per product per file category.")
}