クイックサマリー: 本記事は、Claude Code・Codex CLI・Cursor・Kiroなど複数のAIコーディングエージェントが1つのリポジトリに混在するとき、プロジェクトルールを二重管理せずに整備する方法の実践ガイドです。共通ルールをAGENTS.mdに置き、CLAUDE.mdから@AGENTS.mdで参照する構成を軸に、AWSが公開するOSSリポジトリの「事前生成＋配置」方式まで解説します。対象CLIはClaude Code / Codex CLI / Cursor / Kiro / Windsurf / Gemini CLIなどです。
複数AIエージェント混在リポジトリで何が起きるのか
チーム開発の現場で、AさんはClaude Code、BさんはCodex CLI、CさんはCursorを使う——こうした状況は珍しくなくなりました。各エージェントはそれぞれ独自の「プロジェクトルールファイル」を読みに行くため、同じ内容を別形式で何度も書く必要が生じます。Zennに投稿された開発者の記事（Zenn: 複数のAIコーディングエージェントが混在するリポジトリで、ルールをどう整備するか）では、この課題が「放置するとファイル同士の内容がズレていき、ツールによってAIの振る舞いが変わってしまう」と整理されています。
各ツールが読むルールファイルは次の通りです。
- Claude Code →
CLAUDE.md - Codex CLI →
AGENTS.md - Cursor →
AGENTS.md（対応済み。.cursor/rules/は補助のルール機構として併存） - Windsurf →
.windsurfrules - Kiro →
.kiro/steering/
この記事でわかることは以下の4点です。
- 「1リポジトリ=1AI」に統一する案がなぜ機能しにくいのか
- AGENTS.mdを本体にしてCLAUDE.mdから参照する具体的な設定手順
- AWSのOSSリポジトリに学ぶ「事前生成＋配置」方式の仕組み
- チーム構成別（社内チーム / OSS / 個人）の使い分け指針
なお、ここで扱うルールファイルはすべてプレーンなMarkdownで、特定ベンダーのクローズドな仕様ではありません。参考にするAWSのサンプルリポジトリもOSSとして公開されています。
「1リポジトリ=1AI」に決め打ちすべきか
最初に思いつくのは「リポジトリごとに使うAIを1つに決める」案ですが、前述のZenn記事では3つの理由から万能ではないと指摘されています。
- タスクごとの向き不向き: 複数ファイルにまたがるリファクタリングはClaude Code、個人のフロー作業はCursorが向いている、という使い分けができなくなります
- OSSではコントリビューターの環境を強制できない: 「Claude Code専用です」と宣言しても、Codexしか使えない人には何も渡りません
- 将来の乗り換えコスト: 特定ツール専用の書き方に全振りすると、乗り換えのたびに書き直しが発生します
フリーランスや副業エンジニアが複数案件を掛け持ちする場合、案件ごとに違うツールを強制されると学習コストが跳ね上がります。また、SIerや受託開発の現場では顧客側のセキュリティポリシーで使えるツールが制限されることもあり、「メンバー全員が同じエージェントを使える」前提はそもそも成立しにくいのが実情と考えられます。
設定手順: AGENTS.mdを本体にCLAUDE.mdから参照する
Claude Codeの公式ドキュメントによると、Claude CodeはCLAUDE.mdを読み、AGENTS.mdは読みません。ただし、CLAUDE.mdから@記法で別ファイルをインポートできることが公式に案内されています。この機能を使うと、共通ルールの本体をAGENTS.mdに置いたまま、Claude Codeにも同じ内容を読ませられます。
手順1: 共通ルールをAGENTS.mdにまとめる
# AGENTS.md
## コーディング規約
- TypeScript strict モードを使用する
- コンポーネントは PascalCase で命名する
## テスト
- 変更後は npm run test を実行する手順2: CLAUDE.mdを「薄いラッパー」として作成する
# CLAUDE.md
@AGENTS.md
## Claude Code 向けの追加ルール
- `src/billing/` 配下の変更は plan モードを使うことこう書くと、Claude Codeはセッション開始時にAGENTS.mdの内容を読み込んだうえで、その下に書いたClaude固有の追加ルールも読みます。内容の二重管理が発生しません。
手順3（代替案）: シンボリックリンクを使う
Claude固有の追記が不要なら、公式ドキュメントではシンボリックリンクでも十分とされています。
ln -s AGENTS.md CLAUDE.mdただしWindows環境ではシンボリックリンクの作成に管理者権限またはDeveloperモードが必要なため、Windowsユーザーが混在するチームでは@AGENTS.mdによるインポート方式が推奨されています。
動作確認: すでにAGENTS.mdがあるリポジトリでClaude Codeの/initコマンドを実行すると、その内容を読み取って生成するCLAUDE.mdに自動的に組み込む機能も用意されています。設定後はClaude Codeで新規セッションを開始し、AGENTS.mdに書いたルール（例: 命名規約）について質問して、正しく認識されているか確かめるとよいと考えられます。
大規模運用の参考例: AWSの「事前生成＋配置」方式
より多くのツールをカバーしたい場合の参考実装として、AWSが公開しているOSSリポジトリ「sample-well-architected-skills-and-steering」があります。このリポジトリでは、Well-Architected FrameworkのベストプラクティスをKiro、Kiro CLI、Claude Code、Cursor、Codex、Windsurf、GitHub Copilot、Gemini CLIなど13ツール向け（README記載）に、それぞれのネイティブな設定形式で提供しています。
仕組みは魔法のような自動変換ではなく、install.shというインストーラーがadapters/ディレクトリに事前用意された各ツール向けファイルを、正しい場所にコピーまたはシンボリックリンクするだけの素朴なものです。
# Claude Code 用ファイルをインストール
install_claude_code() {
copy_or_link "$SCRIPT_DIR/adapters/claude-code/CLAUDE.md" "$base/CLAUDE.md"
}
# Cursor 用ファイルをインストール
install_cursor() {
copy_or_link "$rule_file" "$base/.cursor/rules/$rule_name"
}「共通ルールセットを1箇所で管理し、ツールごとの翻訳済みファイルを用意して、インストール時に配置する」という構成は、自前のチームリポジトリにもそのまま応用できる考え方です。
実際の開発フローに組み込む方法
実務での運用イメージを、チーム構成別に整理します。
ケース1: Web受託チーム（Claude CodeとCursorが混在）。共通のコーディング規約・テストコマンド・ディレクトリ構成をAGENTS.mdに集約し、CLAUDE.mdは@AGENTS.md＋Claude固有ルール（planモード必須の領域指定など）だけの薄いファイルにします。Cursor向けには.cursor/rules/に同内容のルールを配置し、更新はAGENTS.mdを起点にPRで行うルールにすると、レビューで差分が可視化されます。
ケース2: OSSメンテナー。コントリビューターの環境を制御できないため、共通ルールの置き場所としてAGENTS.mdを採用しておくと扱いやすくなります。AGENTS.mdは複数のAIツールが参照する共通フォーマットとして対応ツールが増えつつあり、Claude Codeからも上記の方法で参照できます。
ケース3: 個人開発者のローカル設定。個人の好みやマシン固有の設定は、CLAUDE.local.mdやsettings.local.jsonなどGit管理外のローカル専用ファイルに分離し、命名規則をあらかじめチームで決めておくと運用しやすくなります。共有ルールと個人設定が混ざらないため、「自分の環境だけAIの挙動が違う」といった混乱を防げます。
管理方式の比較表
どの方式を選ぶべきかの判断材料として、3つのアプローチを比較します。
| 方式 | 対応CLI | ライセンス/形式 | 更新の手間 | 特徴 |
|---|---|---|---|---|
| CLAUDE.md単独管理 | Claude Codeのみ | プレーンMarkdown | 最小 | チームのツールが実質1つに決まっている場合は最もシンプル |
| AGENTS.md本体＋@参照 | Claude Code / Codex CLI ほかAGENTS.md対応ツール | プレーンMarkdown | 小 | 二重管理なし。Claude固有ルールだけCLAUDE.mdに追記できる |
| adapters事前生成＋配置（AWS方式） | Kiro / Claude Code / Cursor / Codex / Windsurf / Copilot / Gemini CLI など13ツール | OSS（サンプル公開） | 中（アダプター保守が必要） | 大規模・多ツール環境向け。install.shで一括配置 |
注意点・制約
- ルールファイルはコンテキストを消費します: ルールファイルの内容はセッション開始時にAIのコンテキストへ読み込まれるため、肥大化するとトークン消費が増えます。常時必要なルールだけを置き、特定タスク用の手順は別ファイルに分離する設計が現実的です
- 「作れば良い」わけではない: 元のZenn記事では、AGENTS.mdの規格を検証した研究で「自動生成したコンテキストファイルはむしろタスクの成功率を下げる」という結果があることも紹介されています。内容の質が伴わないルールファイルは逆効果になり得ます
- Windowsのシンボリックリンク制約:
ln -s方式は管理者権限またはDeveloperモードが必要です。混成チームでは@AGENTS.mdインポート方式が安全です - 外部通信について: ルールファイル自体はローカルのMarkdownであり、それ単体が外部送信されるものではありませんが、AIエージェントがセッションで読み込んだ内容は各ツールのAPI経由でモデルに送られます。機密情報をルールファイルに書かない運用は必須です
- 変化の速い分野である点: この分野は半年後には別の定番が現れている可能性もあります。「ルール本体を1箇所に置き、各ツール向けに配る」という発想自体は今後も有効と考えられますが、各ツールの対応状況は定期的な確認が必要です
まとめ
- 複数のAIコーディングエージェントが混在するリポジトリでは、共通ルールをAGENTS.mdにまとめ、CLAUDE.mdから
@AGENTS.mdで参照する構成が二重管理を減らす有力な選択肢です - Claude Code側は@インポート・シンボリックリンク・
/initでのAGENTS.md取り込みと、この運用を前提にした機能を公式に用意しています - 多ツール・大規模環境では、AWSのOSSサンプルのような「事前生成＋配置」方式（adapters＋install.sh）が現実的な運用モデルになります
こんなチームにおすすめ: メンバーごとに使うAIツールが違う、OSSでコントリビューターの環境を制御できない、将来のツール乗り換えに備えたい。不向きなケース: チーム全員が単一ツールに統一済みなら、そのツール専用ファイル1本の管理で十分です。さらに詳しい@インポート記法やメモリ管理の仕様は、Claude Code公式ドキュメントのメモリ管理のページを参照してください。
コメント