Kanji
・クラウドエンジニア / フリーランス ・1993年生まれ ・愛媛県出身 / 東京都渋谷区在住 ・AWS歴5年 プロフィールの詳細
目次
日々の開発業務で複数の AI コーディングエージェント(Google Antigravity、Anthropic Claude Code、Kiro、OpenAI Codex)を併用する中で、僕が最も深く悩み、数々の手戻りや予期せぬ事故を経験したのが 「エージェントのルール定義(プロンプト・指示書)の破綻と乖離」 でした。
最初は「丁寧にコーディング規約や禁止事項を書いたドキュメントを用意して、 AGENTS.md や CLAUDE.md にそのまま貼っておけば、どのツールでも賢く動いてくれる」と思っていました。しかし、複数のプロジェクトを回し、リポジトリの規模が大きくなるにつれて、現場では次のような痛烈なトラブルに次々と直面しました:
AGENTS.md
CLAUDE.md
git push origin main
本記事では、これら泥臭い現場の痛みを乗り越えて確立した 「4大AIエージェント(Antigravity / Kiro / Claude Code / Codex)におけるルール定義の完全設計論」 を徹底解説します。
何がすべてのツールで通用する「共通のオープン標準」で、何が各ツール特有の「特化拡張(Superpower)」なのかを白黒つけ、明日から破綻しない ハイブリッド連邦型ルールアーキテクチャ(Federated Rules Architecture) の設計図を公開します。
実務で AI エージェントを日常的に使い倒すエンジニアがほぼ 100% 踏み抜く「3つの罠」があります。
「テストコードは必ず書くこと」「コミットメッセージは日本語で書くこと」「あのライブラリのこのバージョンは非推奨」「AWS IAM の最小権限…」と、プロジェクトの全ルールを単一の AGENTS.md に詰め込むパターンです。
エージェントは毎ターンのプロンプト冒頭にこのルール全文を読み込みます。ルールが 1,000 行(数千〜1万トークン超)に達すると、 毎回のツール実行で高額なトークンコストを垂れ流すだけでなく、LLM の注意機構が飽和し、最も重要な指示を見落とす確率が指数関数的に跳ね上がります 。
「Claude Code には CLAUDE.md 、他のツールには AGENTS.md が必要だから」と、2 つのファイルに同じ内容をコピペして保守するパターンです。 機能追加やルール改定の際、片方のファイルを更新したのにもう片方を更新し忘れ、エージェント A は最新ルールで動き、エージェント B は古いルールで既存コードを破壊的に書き換えるという地獄が始まります。
「main ブランチへの push は禁止」「シークレットはコミットしないで」といった絶対的なセキュリティ・安全管理を、Markdown の自然言語テキスト(丁寧な prose)だけで強制しようとするパターンです。 LLM は確率的モデルであり、どんなに強い口調で書いても、コンテキストが圧迫された時やプロンプトの優先順位が交錯した際に指示をすり抜けます。 「ルールは文章でお願いするのではなく、フックやサンドボックスで物理的に遮断する」 のが鉄則です。
現在主流の 4 大コーディングエージェントにおけるルール処理のメカニズムを、最新仕様に基づき整理しました。
~/.gemini/config/rules/*.md
<repo>/AGENTS.md
~/.kiro/steering/*.md
.kiro/steering/*.md
~/.claude/rules/*.md
~/.codex/AGENTS.md
AGENTS.override.md
config.toml
glob
model_decision
manual
#[[file:...]]
@path/to/file
settings.json
どのツールを使う場合でも、絶対に外してはならない 3 つの普遍的原則があります。
Linux の /etc/ → ~/.config/ → ./ と同じく、エージェントのルールは以下の 3 層で整理し、 「局所(手前)の設定が常に大局(グローバル)をオーバーライドする」 原則を徹底します。
/etc/
~/.config/
./
~/.gemini/config/rules/
~/.claude/rules/
./AGENTS.md
./src/api/AGENTS.md
常時ロードされる AGENTS.md に書くべき内容は 150〜200 行以内 に絞り込みます。 各行について次のテスト(Litmus Test)を実施してください: > 「この行を削除した場合、エージェントは致命的・不可逆的なミスを犯すか?」
リンターやフォーマッタが自動検知できるコードスタイルや、一般的なフレームワークの標準的な書き方はすべて削除します。エージェントが推測できない「プロジェクト固有の奇妙な例外」や「必須ビルドコマンド」だけを残します。
ルールファイルに長大なデプロイ手順やマイグレーション手順を書いてはいけません。 - Rule ( AGENTS.md ) : 「常に守るべき判断基準・制約・禁止事項」のみを定義。 - Skill ( SKILL.md ) / Runbook : 「手順・スクリプト・調査コマンド」として別出しし、エージェントが必要になった瞬間だけオンデマンドで読み込ませる。
SKILL.md
3層カスケードの原則を理解しても、現場のエンジニアが次に必ず頭を抱えるのが 「具体的にどのルールをグローバルに置き、どれをリポジトリ内に置くべきか」 という境界線(Scoping)の設計です。
僕自身、初期の頃は「便利だから」とグローバルに特定のプロジェクト設定を書き込んで別の顧客リポジトリで誤爆したり、逆にリポジトリ内に個人のMac固有パスをコミットしてチームメンバーの環境を破壊したりと、数々の手痛い失敗を繰り返してきました。
現在僕が実務で厳格に適用している「グローバル」と「ワークスペース」の責務境界マトリクスがこちらです。
~/.gemini/...
./.agents/...
features/
components/
/tmp
npm run build
npm test
pytest
npm run dev
tsc --noEmit
ruff check
develop
main
この境界線が曖昧になると、エージェントは一瞬で開発現場を混乱に陥れます。
「毎回設定するのが面倒だから」と、グローバルルール( ~/.gemini/config/rules/ や ~/.claude/rules/ )に AWS_PROFILE=company-prod や特定のローカルパス( /Users/kanji/workspace/client-a/... )を書いてしまうケースです。 別の個人開発プロジェクトやクライアント B の案件を開いた時、エージェントが 無意識にクライアント A のプロファイルや認証情報を使ってコマンドを実行しようとし、最悪の場合は他社インフラへの誤デプロイや権限エラーによる作業停止事故 を引き起こします。
AWS_PROFILE=company-prod
/Users/kanji/workspace/client-a/...
リポジトリの AGENTS.md に、自分の Mac 固有のフルパス( file:///Users/kanji/... )や個人の秘密鍵のパス、ローカル環境限定のエイリアスを書き込んで Git コミットしてしまうケースです。 CI/CD パイプライン(GitHub Actions)や Linux コンテナ、他のチームメンバーの Windows PC で git pull された瞬間、 「ファイルが見つかりません」で全自動ビルドが即死し、Git 履歴にも個人マシンの内部構造が永久に残る という惨事になります。
file:///Users/kanji/...
git pull
「すべてのプロジェクトで役立つから」と、Next.js、Python、Terraform、Docker、Go、Rust、Tailwind のベストプラクティスをすべてグローバルルールに詰め込むケースです。 エージェントは小さなシェルスクリプトを1本作るだけのセッションでも、開始直後から 10,000 トークン超のグローバルルールを強制的に頭に詰め込まれます。その結果、 肝心のユーザー指示を解釈するコンテキスト枠が圧迫され、注意機構が散漫になり、「指示通りに動かない」トラブルの温床 となります。
迷ったときは、次の 2 つのシンプルな問いを自分に投げかけてみてください。
「全プロジェクトで使い回したいが、Terraform を触る時以外はロードしたくない」というルール(例: インフラ命名規則や Dockerfile 作法)は、Antigravity の trigger: glob: "**/*.tf" や Kiro の Steering (Conditional) を使い、 「配置場所はグローバル領域だが、ロードされるのは該当ファイルが開かれた瞬間だけ」 という遅延ロード設計を採用するのが Gen 3 の最も洗練された作法です。
trigger: glob: "**/*.tf"
共通標準を押さえた上で、各ツールの独自機能をどう使い分けるかが現場の腕の見せ所です。
Antigravity の最大の特徴は、 ~/.gemini/config/rules/*.md における YAML Frontmatter 条件指定 です。
--- trigger: glob globs: "**/*.tf, **/*.tfvars, infra/**/*.yaml" description: Terraform and infrastructure naming conventions --- # インフラ命名規則 - リソース名には必ず環境プレフィックス(prd, stg, dev)を含めること。
description
Kiro では、Steering ファイル内に他のファイルを直接埋め込む動的参照がサポートされています。
# API エラーハンドリング規約 エラーレスポンスの型定義は、以下の公式スキーマに厳密に準拠してください: #[[file:src/types/api_errors.ts]]
ドキュメント内にコードの断片をコピペする必要がなく、実コードが更新されればルールの参照先も自動的に最新化されます。さらに /context show コマンドで、現在セッションにどのルールが注入されているかをいつでも可視化・デバッグできます。
/context show
Claude Code はリポジトリルートに CLAUDE.md が存在すると、 AGENTS.md よりも優先して読み込む仕様になっています。 ここで多くの macOS / Linux エンジニアが 「 CLAUDE.md -> AGENTS.md のシンボリックリンクを貼れば解決」 というローカルハックに走りがちですが、 チーム開発や Windows 環境が混ざる現場では致命的なサイレント事故 を引き起こします。
CLAUDE.md -> AGENTS.md
Windows(Git for Windows)のデフォルトではシンボリックリンクが無効( core.symlinks = false )になっています。 Windows ユーザーがリポジトリを git clone すると、 CLAUDE.md は実体へのリンクにならず、 単に AGENTS.md という文字が9バイト書かれただけのプレーンテキスト として生成されてしまいます。 その結果、Claude Code はエラーも出さずに「中身が AGENTS.md という文字だけの空っぽルール」として読み込み、 全ルールが完全に消失した状態で動作する という最悪の挙動に陥ります。
core.symlinks = false
git clone
本命: @AGENTS.md インクルード構文を使う(推奨) CLAUDE.md を実体ファイルとして作成し、先頭に @AGENTS.md と記述します:
@AGENTS.md
@AGENTS.md # Claude Code 固有ルール - (Claude Code だけで適用したい個別ルールがあればここだけに追記)
テキストファイルであるため Windows / Mac / Linux / CI 環境を問わず 100% 確実に展開され、Claude 特有の追加指示も綺麗に分離できます。
代替案: そもそも CLAUDE.md を置かない(フォールバック委譲) Claude Code はリポジトリに CLAUDE.md が一切存在しない場合、 自動的に AGENTS.md を探索してフォールバック読み込みする公式仕様 を備えています。Claude 固有ルールが不要なプロジェクトであれば、 AGENTS.md 1枚だけを配置するのが最もクリーンです。
さらに、絶対に破られてはならない重大なルールはプロンプトの文章で懇願せず、 .claude/settings.json の PreToolUse フックで機械的に遮断します:
.claude/settings.json
{ "hooks": { "PreToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "python3 scripts/secret_guard.py" } ] } ] } }
現場からの警告 1: フックが自分自身をロックする「自爆トラップ」を回避せよ PreToolUse フックで秘密情報(API キーなど)を検査する場合、単純な文字列パターンや単語境界のない正規表現(例: sk-[A-Za-z0-9_-]+ )を使うと、Markdown 内の risk-assessment... といったケバブケース文字列に誤検知して終了コード 2 を返し、 エージェントがすべてのツール(読み込み・編集含む)を実行できなくなる永久ロック事故 が発生します。 必ず単語境界( \b )を厳格に指定し、ローカル開発用の .env やテスト用ダミーファイルを安全にスキップするフェイルオープン設計を徹底してください。
sk-[A-Za-z0-9_-]+
risk-assessment...
\b
.env
現場からの警告 2: 既存ルールの上書き事故を防ぐインストーラーの設計 新しいプロジェクトやチームメンバーのリポジトリに共通ルールパックを展開する際、手動の cp コマンドで既存の AGENTS.md や CLAUDE.md を無警告で上書きしてしまう事故が多発します。自動で既存ファイルを .bak に退避し、マージを促すインストールスクリプト( install.py )を用意しておくのが、チーム開発でのベストプラクティスです。
cp
.bak
install.py
大規模モノレポなどで、親ディレクトリの膨大な規約を特定の安全領域やサブモジュールで完全に遮断したい場合、Codex の AGENTS.override.md が威力を発揮します。このファイルを置いたディレクトリ以下では、上位の AGENTS.md の探索が打ち切られ、クリーンなコンテキストで作業を実行させることができます。
また、Codex のデフォルト読み込み上限が 32 KiB である点にも注意が必要です。巨大なルールを置くと末尾が警告なしで切り捨てられるため、 config.toml の project_doc_max_bytes を調整するか、ルール自体をスリム化します。
project_doc_max_bytes
4 つのツールすべてが同一リポジトリで安全・協調して動く、僕が実践している推奨リポジトリ構成がこちらです。
my-project/ ├── AGENTS.md # 【SSOT】全エージェント共通の基盤ルール(150行以内) ├── CLAUDE.md # Claude用(@AGENTS.md インクルードでWindows互換を完全保証) ├── .kiro/ │ └── steering/ # Kiro 特化のファイルマッチ条件ルール & #[[file:...]] ├── .gemini/ (または global) │ └── rules/ # Antigravity 特化の glob / model_decision 条件ルール ├── .codex/ │ └── config.toml # Codex 用のサイズ上限 & サンドボックス定義 └── .agents/ └── hooks.json # 破綻を防ぐ PreToolUse / PostToolUse フック防御壁
docs/
AI コーディングエージェントのルールは、もはや「プロンプトに注意事項を書き足す」という感覚で管理できる規模を超えつつあります。
この 5 つの柱を意識するだけで、エージェントの手戻りや指示無視は劇的に減り、複数エージェントをシームレスに使い分ける真の自律開発環境が手に入ります。ぜひご自身のリポジトリのルール定義を見直してみてください。
本記事で解説した 4大AIエージェント(Antigravity, Kiro, Claude Code, Codex)完全対応の AGENTS.md テンプレート、hooks.json、Gitガードスクリプト一式をGumroadにて配布準備中です。
本ブログで検証している自律型AIパイプラインと最新LLM推論を実践投入。機関投資家動向・テクニカル指標・マクロ環境を毎日自動スコアリングしています。
Claude Code / Antigravity 等のAIエージェント活用標準化、MCP/RAG長期記憶基盤の構築、AWS・Google Cloud のモダナイズ設計を支援します。