はじめに
Claude Code、Codex、Antigravity CLI（旧 Gemini CLI）などのAIコーディングエージェントを使っていると、各ツール向けの「ルールファイル」をどう管理するかで悩みます。
たとえば次のようなファイルです。
CLAUDE.md ← Claude Code
AGENTS.md ← Codex / Cursor / Copilot ほか多数
GEMINI.md ← Gemini CLI
「同じ規約を複数のファイルにコピーして、更新漏れで内容がズレる」
これは多くの人が一度は通る道です。
2026年現在、この問題への向き合い方はかなり変わっています。本記事では、
- そもそも今は何が標準なのか
- ファイルの種類（CLAUDE.md / Rules / Skills）をどう使い分けるのか
- 「ルールは多いほど良い」わけではない、という注意点
を入門者向けに整理します。
この記事を書くにあたり、用語と現状は2026年6月時点の各ツールの公式ドキュメント・標準仕様にもとづいて確認しています。AIツール周辺は変化が速いので、実際に導入する前に最新の公式情報も確認してください。
前提が変わった： 今は AGENTS.md という共通標準がある
数年前は、ツールごとに別々の指示ファイルを書く必要がありました。
しかし現在は AGENTS.md という、ツール横断の共通フォーマットが広く普及しています。
AGENTS.md は「エージェント向けのREADME」と呼ばれる、ただのMarkdownファイルです。特別なスキーマはありません。OpenAI Codex、Cursor、GitHub Copilot、Windsurf、Zed、Amp など、主要なツールの多くがこの1ファイルを読みます。
つまり、「同じ内容を何個もコピーする」問題は、標準化によって大部分が解消されつつあるということです。
最初の一手：「複数ファイル」を1つにまとめる
複数ツールを併用していて、AGENTS.md 以外のファイル（CLAUDE.md など）も必要な場合、いきなり凝った仕組みを作る必要はありません。難易度の低い順に、いくつかの定番があります。
方法1：シンボリックリンク（一番簡単）
AGENTS.md を本体にして、他のファイルはそこへのリンクにするだけです。
ln -s AGENTS.md CLAUDE.md
これで CLAUDE.md の実体は AGENTS.md になり、編集箇所が1つになります。小〜中規模ならこれで十分なことも多いです。
repo/
├ AGENTS.md # 共通ルール（本体）
├ CLAUDE.md # → シンボリックリンクで AGENTS.md を参照
方法2：CLAUDE.md から AGENTS.md を import する（環境を跨ぐなら安全）
Claude Code は AGENTS.md をそのままでは読みません（2026年半ば時点）。
そこで、CLAUDE.md から AGENTS.md を取り込む「橋渡し」を1行だけ書きます。
repo/
├ AGENTS.md # 共通ルール（本体）
├ CLAUDE.md # → @AGENTS.md だけ記載（AGENTS.md を展開して取り込む）
CLAUDE.md にこの1行を置くと、Claude Code は読み込み時に AGENTS.md の中身を展開して取り込みます。
Expo の公式ドキュメントも、この「@AGENTS.md の1行だけが書かれた CLAUDE.md」を生成する構成を採用しています。
方法1（シンボリックリンク）との違いは、実体のあるただのテキストファイルである点です。
symlink が正しく復元されるのは Mac / Linux で、Windows では core.symlinks が無効だと（既定でしばしば無効）、中身が「AGENTS.md という文字列だけのファイル」に化けて壊れます。
エラーは出ないのでハマりやすいです。
Mac の人は正常・Windows の人だけ壊れる、という形になり、Windows のメンバーが編集すると壊れた状態がリポジトリ全体に伝播することもあります。
複数の環境で開発する場合は、方法2が安全でコストもかかりにくいです。
方法1も方法2も「1つの本文を使い回す」ためのものです。手軽さなら方法1、環境を跨ぐ安全性と Claude 専用追記の余地なら方法2、と覚えておくとよいでしょう。
その他：生成ツールで単一ソースから各ツール用を作る
ツールごとに微妙にフォーマットが違う場合があります。
- Cursor の
.cursor/rules/ - Copilot の
.github/copilot-instructions.md - Cline の
.clinerulesなどなど…
こうしたケースでは、1つの元ファイルから各ツール用ファイルを生成するツールが便利です。代表的なのが rulesync です。
npm install -g rulesync
rulesync init # .rulesync/ に元ルールを用意
# .rulesync/rules/ にルールを書く
rulesync generate --targets "*" # 各ツール用ファイルを一括生成
.rulesync/ を「唯一の正解ファイル」とし、CLAUDE.md や .cursor/rules/ などを自動生成する発想です。既存の CLAUDE.md から逆に取り込む（import）機能もあります。
ポイント：本記事の元ネタになりがちな「自作の参照レイヤー」は、すでにこうしたツールが実現しています。車輪の再発明をする前に、まず既存ツールを検討してもいいかもしれません。
Skill も同じパターンで一元化する
ここまでは指示ファイル（CLAUDE.md / AGENTS.md）の話でしたが、Skill にもまったく同じ問題が起きます。
Skill のファイルはどのツールでも SKILL.md（大文字）で共通ですが、置き場所だけがツールごとに違うので、放っておくと二重管理になります。
repo/
├ .agents/skills/
│ └ commit/SKILL.md # Codex / Antigravity など用に SKILL.md が必要
├ .claude/skills/
└ commit/SKILL.md # Claude Code 用にも SKILL.md が必要
中身は同じ SKILL.md なのに、ディレクトリだけ分かれている——CLAUDE.md / AGENTS.md と同じ構図です。
対処も指示ファイルと同じで、手でコピーしないのが鉄則です。ただし使える手は少しだけ違います。
-
シンボリックリンク（方法1）：
SKILL.mdを1つ用意し、各ツールのスキルディレクトリへリンクを張る。Windows / WSL / CI で壊れうる点も方法1と同じ注意が必要です。 -
import（方法2）は使えません：
@AGENTS.mdのような「1行で取り込む」記法は指示ファイル専用で、Skill には対応しません。Skill はファイルの置き場所で発見される仕組みのためです。
import は使えませんが、Claude 側にスタブ SKILL.md を置き、その本文から .agents 配下の実体を参照させる手があります。本体（手順）は .agents/skills/ に1つだけ置き、Claude 側は参照だけにします。
---
name: commit
description: 変更ファイルをコミットする。ignore 対象のファイルは対象外とする。
user-invocable: true
---
### 実行
場所: .agents/skills/commit/SKILL.md
概要: コミットスキルを実行する。
repo/
├ .agents/skills/
│ ├ commit/SKILL.md # コミットスキルの実体（メンテはここだけ）
│ └ review/SKILL.md # レビュースキルの実体（メンテはここだけ）
├ .claude/skills/
├ commit/SKILL.md # 実体は .agents 配下を参照（手順の本文は単一管理）
└ review/SKILL.md # 実体は .agents 配下を参照（手順の本文は単一管理）
注意：参照パス（
場所: .agents/skills/...）は実体のディレクトリ名と必ず一致させてください。ズレるとサジェストには出ても本体を読めず空振りします。またdescriptionを実文にしておくと Claude の自動起動が効きます（/commitと明示的に打つ運用だけなら省略しても動きます）。
用語を正しく：CLAUDE.md / Rules / Skills は別物
ここが入門者がいちばん混乱しやすいところです。
「共通ルールをスキルにまとめる」と書かれた記事をよく見かけますが、Claude Code における「Skills」は、規約をまとめたMarkdownのことではありません。
現在のClaude Codeには、目的の違う3つのレイヤーがあります。
| レイヤー | 中身 | いつ読まれるか | 向いている内容 |
|---|---|---|---|
| CLAUDE.md / AGENTS.md | 常時真の前提 | 毎回（常時ロード） | 技術スタック、主要コマンド、短い方針 |
Rules（.claude/rules/*.md） |
パス限定のドメイン知識 | 該当ファイルに触れたときだけ | 「フロントエンドの規約」など範囲が決まったもの |
Skills（.claude/skills/<name>/SKILL.md） |
呼び出し型の手順・能力 | 必要と判断されたときだけ | デプロイ手順、レビュー実行、コード生成など「動作」 |
ざっくり言うと、
- CLAUDE.md / AGENTS.md と Rules は「形容詞」 … プロジェクトが どういうものか を説明する
- Skills は「動詞」 … エージェントが 何をできるか（手順）を定義する
という違いです。コーディング規約やレビュー方針のような「常に守らせたい決まりごと」は、Skills ではなく CLAUDE.md か Rules に置くのが正しい使い分けです。
Rules：範囲を絞って必要なときだけ読ませる
.claude/rules/ にMarkdownを置き、フロントマターで対象パスを指定すると、該当するファイルに触れたときだけそのルールが読み込まれます。
---
paths:
- "src/frontend/**"
---
# フロントエンド規約
- コンポーネントは関数コンポーネントで書く
- スタイルは CSS Modules を使う
これにより、バックエンドの作業中にフロントエンドの規約を読み込む、といった無駄を避けられます（フロントマターを付けないと、CLAUDE.md と同じく毎回読み込まれます）。
Skills：手順や能力をパッケージ化する
SKILL.md は、YAMLフロントマター（name と description）から始まるMarkdownです。
---
name: deploy-pipeline
description: 本番デプロイの手順。リリースやデプロイを依頼されたときに使う。
---
# デプロイ手順
1. テストがすべて通っていることを確認する
2. `make build` を実行する
3. ...
Skills の肝は実行時読み込みです。
-
起動時：すべての Skill の
nameとdescriptionだけが読み込まれる（軽い） -
関連すると判断されたとき：その
SKILL.mdの本体が読まれる - さらに詳細が必要なとき：同梱の参照ファイルやスクリプトが読まれる
この仕組みのおかげで、Skill をたくさん入れてもコンテキストを圧迫しません。しかも SKILL.md の仕様はツール横断の標準になりつつあり、Cursor や Copilot、Codex でも使い回せる方向に向かっています。
まとめると、「規約 → CLAUDE.md / Rules」「手順・能力 → Skills」。記事で『規約をスキルにまとめる』と書くと、読者が公式の Skills 仕様（フロントマター必須・呼び出し型）に当たって混乱するので注意しましょう。
注意：ルールは「多いほど良い」わけではない
ここまで「共通化して再利用しよう」という話をしてきましたが、逆方向の知見もあります。
ETH Zurich の研究グループは、実際のコーディングタスクでコンテキストファイル（AGENTS.md のような指示ファイル）の効果を検証しました（AGENTbench）。結果は直感に反するもので、コンテキストファイルはエージェントの手数とコストを一貫して増やす一方で、最終的な成果（パッチの品質）を改善しなかったというものでした。指示に従ってテストを余計に走らせたり、ファイルを読みすぎたりして、かえって遠回りになる、という分析です。
研究側の推奨はシンプルで、LLMに自動生成させた指示ファイルは省く、人間が書く指示は推論で得られない情報（固有のツール名・カスタムビルドコマンドなど）に限定する、というものでした。
「集約・資産化」自体を否定するものではありませんが、規約を足すほどエージェントが賢くなるわけではないという重要なブレーキです。共通化の目的は「量を増やす」ことではなく、
- 一箇所で管理してズレをなくす
- 各タスクに必要なものだけを読ませる（Rules のパス限定、Skills の実行時読み込み）
- 書かなくても分かることは書かない
だと意識すると、設計がぶれません。
まとめ
2026年時点のメタパターンとして、押さえておきたいのは次の点です。
-
AGENTS.mdが共通標準。まずはこれを中心に据える。複数ファイルが必要なら、シンボリックリンク・@AGENTS.mdの import・rulesyncなどの生成ツールで一元化する。 - CLAUDE.md / Rules / Skills を混同しない。規約は CLAUDE.md か Rules（パス限定）、手順・能力は Skills（呼び出し型・実行時読み込み）。
- ルールは最小限・必要なときだけ。集約の目的はズレをなくすことであって、量を増やすことではない。書かなくても分かることは書かない。
AIコーディングツールは今後も増えたり入れ替わったりします（Gemini CLI → Antigravity CLI の移行はその好例です）
だからこそ、ツールごとの設定を増やすのではなく、標準（AGENTS.md）と適切なレイヤリングを中心に据えておくと、ツールが変わってもルール資産を柔軟に保持できます。