AI Agent の指示ファイル、無理に共通化するのをやめた

AI Agent Claude Code

この記事は 2026 年 2 月時点の各ツール公式ドキュメントに基づいている。AI Agent の仕様変化は速いので、最新の公式ドキュメントもあわせて確認してほしい。

この記事の対象

  • Claude Code / Codex / Cursor / GitHub Copilot のうち 複数を併用 していて、指示ファイルの管理に悩んでいる人
  • CLAUDE.md と AGENTS.md を symlink で繋いだり、共通化しようとしたことがある人
  • 「同じことを複数のファイルに書いている」ことに DRY 違反を感じている人

逆に、1つの AI Agent しか使っていない場合はこの記事の内容はあまり関係ない。

結論

  • CLAUDE.md / AGENTS.md / .cursor/rules/ を symlink で一本化しようとしたが、調べるほど 各ツールの指示体系が違いすぎて 共通化のメリットが薄いとわかった
  • 仕様が標準化されていない領域（パスベースルール、コマンド、フック等）は 個別最適の方がいい。無理に DRY にすると各ツールの強みを殺す
  • 他ツールの commands や rules を使い回したいなら、symlink ではなく AI に変換させればいい

具体的な構成例は推奨構成を参照。

過去の自分への訂正

以前、symlink で統一する AI エージェントルール置き場という記事を書いた。AGENTS.md を正本にして CLAUDE.md を symlink で繋ぎ、複数ツールのルールを一元管理しようという内容だ。

あの記事を書いた時点では「これでいける」と思っていた。が、あれから Codex・GitHub Copilot・Claude Code・Cursor の 4 ツールについて最新の動向を改めて追ってみたところ、共通化は得るものより失うものの方が大きい という結論に至った。

この記事は過去の自分へのセルフアンサーだ。

指示体系は想像以上にバラバラ

「CLAUDE.md と AGENTS.md に同じこと書いてる……DRY に反してない？」という感覚は自然だと思う。自分もそう思っていた。だから symlink で繋ごうとした。

だが実際に並べてみると、共通化できる部分は驚くほど少ない。

メインの指示ファイルからして違う

ツール メインファイル グローバル設定
Codex AGENTS.md ~/.codex/AGENTS.md
GitHub Copilot .github/copilot-instructions.md VS Code / JetBrains の設定
Claude Code CLAUDE.md ~/.claude/CLAUDE.md
Cursor .cursor/rules/*.mdc (.md も可) Cursor Settings > Rules

Codex は AGENTS.md をネイティブに読み、Copilot と Cursor も AGENTS.md に対応している。が、Claude Code は CLAUDE.md が正本で AGENTS.md は未対応だ（Issue #6235 で 3,600 以上の reaction がある要望）。

入口からして揃っていない。

パスベースルールの glob 構文が非互換

ツール ファイル glob の書き方
Codex サブディレクトリの AGENTS.md glob なし（ディレクトリ配置のみ）
Copilot .github/instructions/*.instructions.md applyTo: "**/*.ts,**/*.tsx"
Claude Code .claude/rules/*.md paths: ["src/api/**/*.ts"]
Cursor .cursor/rules/*.mdc globs: ["**/*.ts"]

frontmatter のフィールド名が applyTo / paths / globs。フォーマットもカンマ区切り / YAML 配列。これは symlink でどうにかなる話ではない。

スキルだけは標準化されている

唯一の良い話がスキルだ。4 ツールすべてが Agent Skills オープンスタンダードに準拠していて、SKILL.md のフォーマットが共通化されている。

skill-name/
├── SKILL.md          # YAML frontmatter + Markdown（必須）
├── scripts/          # 実行可能コード（任意）
├── references/       # 参照ドキュメント（任意）
└── assets/           # テンプレート・リソース（任意）

ただしディスカバリパスはバラバラだ。

ツール ディスカバリパス クロスツール走査
Codex .agents/skills/ なし
Copilot .github/skills/ .claude/skills/ も走査
Claude Code .claude/skills/ なし
Cursor .cursor/skills/ .claude/skills/ + .codex/skills/ も走査

Cursor が他ツールのパスを走査してくれるのは助かる。が、全ツールがそうしてくれるわけではない。

コマンドは完全にツール固有

再利用可能な指示テンプレート（コマンド / プロンプト）は 標準化されていない。

ツール パス 呼び出し方
Codex ~/.codex/prompts/*.md（非推奨 → Skills へ） /prompts:name
Copilot .github/prompts/*.prompt.md /prompt-name
Claude Code .claude/commands/*.md（レガシー → Skills へ） /command-name
Cursor .cursor/commands/*.md /command-name

引数の構文も $ARGUMENTS / ${input:name} / $1〜$9 と互換性がない。ここを共通化しようとするのは無理がある。

共通化できるもの・できないもの

調査結果を整理するとこうなる。

対象 共通化 理由
プロジェクト知識（概要・規約・ドメイン知識） できる プレーン Markdown で表現可能
スキル（SKILL.md） できる Agent Skills 標準に 4 ツールとも準拠
ディレクトリベースのスコープ できる AGENTS.md のネスト配置は標準仕様
パスベースルール（frontmatter） できない applyTo / paths / globs で構文が非互換
スラッシュコマンド / プロンプト できない パス・構文・引数が全ツールで異なる
エージェント定義 できない Claude Code と Copilot のみ対応、フォーマットも異なる
フック できない 対応ツールはあるがイベント名・設定形式が異なる
権限・実行ポリシー できない 完全にツール固有

注意すべき点が 2 つある。

まず「スコープ制御」は粒度で扱いが分かれる。サブディレクトリに AGENTS.md を配置する粗粒度のスコープは標準仕様として共通化できる。一方、frontmatter の glob パターンによる細粒度の制御はツールごとに構文が異なり、共通化できない。

次に「コマンド」はビルド・テストコマンド（pnpm test 等）ではなく、AI Agent のスラッシュコマンドやプロンプトテンプレートを指す（.claude/commands/、.cursor/commands/、.github/prompts/）。ビルド・テストコマンドはプロジェクト知識として AGENTS.md に書ける。

共通化できるのは「プロジェクト知識」「スキル」「ディレクトリベースのスコープ」の 3 つで、それ以外——パスベースルール、スラッシュコマンド、エージェント定義、フック、権限——は全部ツール固有だ。しかもこの「共通化できない部分」が指示体系の大部分を占める。

標準化されるまでは個別最適でいい

ここからが本題だ。

DRY はコードの原則であって設定ファイルの原則ではない

Sandi Metz の有名な言葉がある。

"duplication is far cheaper than the wrong abstraction" （重複は間違った抽象化よりはるかに安い） — The Wrong Abstraction

Kent C. Dodds も AHA Programming で "Avoid Hasty Abstractions"（性急な抽象化を避けよ）と言っている。Dan Abramov は Goodbye, Clean Code で、重複排除のリファクタが将来の変更を何倍も複雑にした経験を語っている。

ルールファイルはコードではない。重複があってもコンパイルエラーにならないし、テストが落ちることもない。一方で、DRY のための接続インフラ（symlink、生成スクリプト、import チェーン）のメンテナンスコストは確実に発生する。

自分はこう考えている。仕様が標準化されていない領域を無理に DRY にするのは、間違った抽象化だ。 パスベースルールの glob 構文が applyTo / paths / globs と分かれているのは、まだ業界が合意に至っていないからだ。標準化される前に共通化層を作り込んでも、標準が決まったときに全部書き直しになる。

共通化層は負債になる

「1 ファイルで管理できる！」と思って始めた共通化が、実際にはこうなる。

AGENTS.md              ← 正本
CLAUDE.md              ← @AGENTS.md で参照
.claude/skills -> symlink
.cursor/skills -> symlink
.codex/skills  -> symlink
.github/skills -> symlink

「1 ファイル + N 個の接続」。共通化する前より管理対象が増えている。

symlink を公式にサポートしているのは Codex と Claude Code の 2 つだけ だ。

ツール symlink 対応
Codex 公式ドキュメントに記載あり
Claude Code 対応（CVE-2026-25724 は v2.1.7 で修正済み）
Copilot 公式記載なし
Cursor 公式に保証されていない

4 ツール中 2 ツールでしか保証されていない仕組みに依存するのは危うい。

仕様変更が速すぎる

  • Cursor: .cursorrules → .cursor/rules/*.mdc へ破壊的変更
  • Codex: Custom Prompts が非推奨になり Skills へ移行
  • Claude Code: Commands がレガシーとなり Skills へ統合中

共通化層を作り込むほど、仕様変更の影響をもろに受ける。半年前の「これでバッチリ」が半年後に動かなくなるリスクは高い。

使い回したいなら AI に書かせればいい

「でも .claude/rules/typescript.md の内容を Cursor でも使いたいんだけど」という声はあるだろう。わかる。

これに対する自分の答えは、symlink ではなく AI に変換させる だ。

AI への依頼:
「.claude/rules/typescript.md の内容を
 .cursor/rules/typescript.mdc に Cursor の形式で複製して」

AI が frontmatter の paths → globs 変換を含めて適切な形式で生成してくれる。commands も同じだ。.claude/commands/review.md を .cursor/commands/review.md に変換してもらえばいい。引数構文の $ARGUMENTS → Cursor 形式への変換も AI が勝手にやってくれる。

この方法の利点は明確だ。

  • 各ツールのネイティブ形式になる — glob 構文も引数構文もツールに最適化される
  • symlink の信頼性問題がない — 実ファイルなのでどのツールでも確実に動く
  • 仕様変更時は再生成するだけ — 変換ロジックをメンテする必要がない

AI Agent のルールを AI Agent に書かせる。考えてみれば当然の帰結だと思う。

推奨構成

自分がたどり着いた方針はこうだ。

AGENTS.md は「ツール非依存の共通知識」として薄く使い、各ツールの制御はネイティブ形式で書く。標準化された部分だけ共有し、それ以外は個別最適。使い回したいときは AI に変換させる。

ディレクトリ構成

project-root/
├── AGENTS.md                          # 共通知識: プロジェクト概要、大原則
│                                      #   Codex / Copilot / Cursor が直接読む
│
├── CLAUDE.md                          # Claude Code 用
│                                      #   @AGENTS.md で共通知識を取り込み
│                                      #   + Claude 固有の指示
│
├── .claude/
│   ├── rules/                         # Claude 固有: パスベースルール
│   │   └── typescript.md              #   paths: ["**/*.ts"]
│   ├── skills/                        # skills（Claude + Cursor + Copilot が読む）
│   │   └── my-skill/SKILL.md
│   └── agents/                        # Claude 固有: カスタムサブエージェント
│       └── reviewer.md
│
├── .cursor/
│   ├── rules/                         # Cursor 固有: パスベースルール
│   │   └── typescript.mdc             #   globs: ["**/*.ts"]
│   └── commands/                      # Cursor 固有: コマンド
│       └── review.md
│
├── .github/
│   ├── copilot-instructions.md        # Copilot 固有: リポジトリ全体ルール
│   ├── instructions/                  # Copilot 固有: パスベースルール
│   │   └── typescript.instructions.md #   applyTo: "**/*.ts"
│   └── agents/                        # Copilot 固有: カスタムエージェント
│       └── reviewer.agent.md
│
└── サブディレクトリ/
    └── AGENTS.md                      # ネスト配置: サービス固有の知識

symlink は基本的に使わない。ただしスキルは例外だ。 SKILL.md のフォーマットは Agent Skills Standard で標準化されており、どのツールでも同じファイルがそのまま使える。.claude/skills/ を正本にすれば Cursor と Copilot はクロスツール走査で読んでくれる。Codex 用に .agents/skills/ が必要なら symlink で繋いでも問題ない。スキルは標準化されている唯一の領域なので、ここだけは正本を一箇所に置く運用が成立する。

AGENTS.md の使い方

AGENTS.md には 知識 を書く。制御 は書かない。

# プロジェクト概要

このプロジェクトは ... というアーキテクチャで構成されている。

## ディレクトリ構成

- `src/api/` — REST API のエンドポイント
- `src/domain/` — ドメインロジック
- ...

## 開発ルール

- テスト実行は `pnpm test`
- コミットメッセージは Conventional Commits に準拠

「〇〇すること」ではなく「〇〇という構成になっている」。制御指示（glob スコーピング、権限、フック）はツール固有ファイルに任せる。

CLAUDE.md の使い方

@AGENTS.md

## Claude Code 固有の指示

- PR 作成時は必ず `gh pr create` を使うこと
- ...

@AGENTS.md で共通知識を取り込んで、Claude 固有の指示だけ追記する。

やってはいけないこと

  1. AGENTS.md を唯一の正本にしてツール固有ファイルを廃止する — 各ツールの強みが死ぬ
  2. スクリプトで AGENTS.md から各ツール固有ファイルを自動生成する — 生成ロジックが新たな負債になる
  3. symlink で全部繋ぐ — 2/4 ツールでしか保証されていない
  4. パスベースルールを共通化しようとする — glob 構文が完全に非互換
  5. コマンド / プロンプトを共通化しようとする — 標準化されていない。使い回したいなら AI に変換させる

まとめ

軸 内容 共通化
何を知っているべきか プロジェクトの構造・規約・ドメイン知識 できる（AGENTS.md）
何ができるか 再利用可能なスキル できる（SKILL.md）
どう振る舞うべきか パスベースルール・権限・フック できない（ツール固有）
何を繰り返し実行するか スラッシュコマンド・プロンプトテンプレート できない（ツール固有）

ディレクトリベースのスコープ制御（AGENTS.md のネスト配置）は「知識」の軸に含まれ、共通化できる。ツール固有なのは frontmatter のパスベースルールによる細粒度の制御だ。

「知識」と「スキル」は共有し、「制御」と「コマンド」は個別最適。使い回したいなら AI に変換させる。

前回の記事では「symlink で繋げば解決」と書いた。あれは間違いだった。正確には、あの時点では間違いではなかったのかもしれないが、各ツールの仕様がここまで分岐した今となっては、共通化のコストがメリットを上回っている。

結局のところ、AI Agent の指示体系はまだ標準化の途上にある。スキル（SKILL.md）は Agent Skills Standard で足並みが揃ったが、パスベースルール、コマンド、フック、権限は合意に至っていない。標準化されていないものを無理に統一しても、標準が決まったときに全部やり直しだ。

今は各ツールの強みをフル活用しつつ、ツール間の橋渡しは AI に任せる。これが 2026 年 2 月時点の最適解だと思っている。

参考資料

公式ドキュメント

標準仕様

関連記事

異なるアプローチの記事

以下の記事は AGENTS.md を正本にした一元管理を推奨しており、本記事とは反対の立場をとっている。