クイックサマリー: CLAUDE.md・AGENTS.md・.github/copilot-instructions.md という「ほぼ同じ内容のエージェント向け指示ファイル」の増殖を、symlink（シンボリックリンク）で正本1つに束ねて解決する実践ガイドです。対象は Claude Code / Codex CLI / GitHub Copilot / Cursor などを併用する開発者で、追加ツールなしの Git 標準機能だけで今日から再現できます。発展形として、配線を宣言・検証する OSS ハーネス「basou」の考え方も紹介します。
指示ファイルの増殖という課題 — この記事でわかること
AIコーディングツールを複数併用しているリポジトリでは、Claude Code 用の CLAUDE.md、Codex CLI 用の AGENTS.md、GitHub Copilot 用の .github/copilot-instructions.md と、ほぼ同じ内容の指示ファイルが並びがちです。厄介なのは、これらが静かに乖離することです。片方だけ規約を直し、もう片方が1世代前のまま残ると、ツールによって読んでいるルールが違う状態になります。しかも、どれが最新かは目視では判別できません。
本記事は、Zenn に公開された記事「AGENTS.md / CLAUDE.md / copilot-instructions.md の増殖を、宣言で終わらせる」（一次情報源: blog.tak3.jp）の内容をベースに、この課題の解決手順を整理したものです。
- なぜ「AGENTS.md 1つに統一」では解決しないのか（Claude Code の非対称性）
- symlink で正本を1つに束ねる具体的なコマンドと Git での扱い
- Windows 環境・公開リポジトリでの注意点
- 複数リポジトリに広がったときの発展形（宣言・生成・検証）
なお、記事中で紹介する basou は筆者（tak3氏）自身が開発する OSS のハーネスで、手法自体は symlink と数行のスクリプトだけでも再現できます。
なぜ1ファイルに統一できないのか — 対応状況の整理
AGENTS.md は事実上の共通フォーマットになりつつあります。元記事によると、2026年なかば時点で Agentic AI Foundation（Linux Foundation 傘下）がスチュワードとなり、20を超えるツールが読み、6万を超える OSS リポジトリが採用しています。Codex CLI、Cursor、Windsurf、Aider、Zed など主要ツールはほぼ AGENTS.md に寄っています。
例外が Claude Code です。Claude Code が読むのは CLAUDE.md であって、AGENTS.md ではありません。フォールバックとして読むこともなく、AGENTS.md しかないリポジトリで起動してもエラーは出ず、プロジェクト指示0件のまま静かに動きます。元記事によると、AGENTS.md サポートを求める anthropics/claude-code の issue #6235 には数千のリアクションが集まっていますが、2026年7月時点の公式ドキュメントに対応の気配はありません。
2026年7月時点の対応表は次のとおりです。
- Claude Code: CLAUDE.md（AGENTS.md は読まない）
- Codex CLI: AGENTS.md
- GitHub Copilot: .github/copilot-instructions.md（coding agent は AGENTS.md も読む）
- Cursor: AGENTS.md（.cursor/rules は現役の別機構。旧 .cursorrules は非推奨）
Claude Code を使う限り CLAUDE.md は消せないため、「AGENTS.md に統一して終わり」が成立しない — これが課題の核心です。
導入手順 — symlink で正本1つに束ねる
解決策は、AGENTS.md を正本（hub）とし、他のファイルをそこへ向く symlink（spoke)にすることです。Claude Code が CLAUDE.md を開いたとき、OS が透過的に AGENTS.md の中身を返すため、ツール側は symlink を意識しません。Claude Code の公式ドキュメント自身が ln -s AGENTS.md CLAUDE.md を選択肢として挙げている点も、この手法の裏付けになります。
目指すトポロジは次の形です。
myrepo/AGENTS.md # 正本（ここだけを編集する）
myrepo/CLAUDE.md -> AGENTS.md
myrepo/.github/copilot-instructions.md -> ../AGENTS.md実行するコマンドは3ステップです。
# 既に CLAUDE.md に本文がある場合は、まず実体を AGENTS.md へ移す
git mv CLAUDE.md AGENTS.md
# CLAUDE.md を AGENTS.md への symlink にする
ln -s AGENTS.md CLAUDE.md
# Copilot 用（.github/ の中から見た相対パスに注意）
mkdir -p .github
ln -s ../AGENTS.md .github/copilot-instructions.md相対パスにしておくのがコツです。リポジトリをどこにクローンしても、リンクが repo 内で完結して壊れません。導入後の確認は git ls-files -s で行えます。symlink はモード 120000 の blob として記録されるため、次のように表示されれば成功です。
$ git ls-files -s AGENTS.md CLAUDE.md .github/copilot-instructions.md
120000 … .github/copilot-instructions.md # symlink
100644 … AGENTS.md # 実体
120000 … CLAUDE.md # symlinksymlink はそのまま commit でき、クローン先でも復元されます。
設定例 — ツール固有の指示を足したい場合は import 構文
symlink 完全統一は「全ツールに同じ本文を読ませる」場合の解です。Claude Code にだけ効かせたい規約がある場合は、公式の @path import 構文が使えます。CLAUDE.md をスタブにして、共通本文を参照する形です。
<!-- CLAUDE.md -->
@AGENTS.md
# Claude Code 固有の指示（必要な場合のみ）この方式なら本文の実体は AGENTS.md に一本化されます。ただし import 構文はツール横断で共通ではなく、Copilot の copilot-instructions.md には同じ手が効きません。また「スタブは1行のまま」という規律が崩れると乖離が再発するため、デフォルトでは symlink、ツール別差分が必要になったら import、という使い分けが推奨されます。なお、AGENTS.md のあるリポジトリで Claude Code の /init を実行すると内容を CLAUDE.md に取り込みますが、これは参照ではなくコピーであるため、一本化が目的なら import か symlink が適しています。
実開発フローへの組み込み方 — 職種別ユースケース
この手法が効くのは、複数ツールの併用が日常になっているチームです。具体的なシナリオを挙げます。
- 受託開発チーム: メンバーごとに Claude Code 派と Cursor 派が混在するチームで、コーディング規約を AGENTS.md に一本化。「Claude Code のユーザーだけ古い規約で動いていた」という静かな事故を構造的に防げます。
- OSS メンテナー: contributor に多様な AI ツールで貢献してもらう前提のリポジトリで、AGENTS.md を実体として commit し、CLAUDE.md を symlink にして全ツールに同じガイドラインを届けられます。
- 個人開発者・バイブコーダー: Claude Code で実装し Codex CLI でレビューする二刀流フローで、両者に同じプロジェクト指示を読ませられます。片方だけ直し忘れる同期コストがゼロになります。
さらに CI に検証を組み込むと、配線の腐敗を機械的に検知できます。元記事が示すとおり、git ls-files -s の期待値を diff する数行を CI に置くだけで、「リンクが欠けた・別の場所を指した」を PR の段階で検出できます。Claude Code の hooks でコミット前に同じチェックを走らせる構成も相性が良いと考えられます。
類似アプローチとの比較
| 手法・ツール | 対応CLI・ツール | ライセンス | 最終更新 | 特徴 |
|---|---|---|---|---|
| 全ファイルにコピペ | すべて | — | — | 初回は動くが、修正のたびに N 個の同期義務が発生。腐敗を検知できない |
| @import 構文（CLAUDE.md スタブ） | Claude Code のみ | —（公式機能） | 現行機能 | ツール固有の指示を足せる。Copilot には効かない |
| symlink（本記事の手法） | Claude Code / Codex CLI / Copilot / Cursor ほか | —（OS・Git 標準機能） | — | 実体1つ・透過的。単一リポジトリなら最有力。Windows は要設定 |
| basou | 上記すべて（配線を生成・検証） | OSS（単著者開発） | v0.32.0（2026年） | manifest に正本を宣言し、symlink 生成と drift・プライバシーリスク検証を自動化 |
元記事の筆者自身が「単一リポジトリで、ツール別の差分も要らないなら symlink で終わっていい」と明言しており、basou は複数リポジトリ・公開/非公開混在の段階で検討する発展形という位置づけです。この正直な線引きは、導入判断の参考になります。
注意点・制約・セキュリティ
- Windows 環境: symlink を正しくチェックアウトするには
core.symlinks=trueと開発者モード（または相応の権限）が必要です。設定がない環境では、symlink が「リンク先パスを中身に持つただのテキストファイル」として展開されてしまいます。Windows ユーザーが混在するチームは事前確認が必須です。 - 公開リポジトリのプライバシー: 指示ファイルに非公開の計画情報を含む場合、実体を公開リポジトリの履歴に入れると中身がそのまま公開されます。symlink でも、リンク先のパス（非公開側のディレクトリ構成）は履歴に残る点に注意が必要です。
- 外部通信なし: symlink 方式は OS と Git の標準機能のみで完結し、外部へのデータ送信は発生しません。basou を使う場合も配線の生成・検証はローカルで完結する設計です（
basou project check/wiringは read-only）。 - 解けない課題もある: symlink は「1実体に束ねる」は解きますが、複数リポジトリへの展開や配線の腐敗検知までは解きません。その先は宣言・生成・検証の仕組み（CI の数行から始められます）が必要です。
まとめ
- AGENTS.md が事実上の標準に寄る一方、Claude Code は CLAUDE.md しか読まないため、1ファイル統一は成立しません。AGENTS.md を正本にした symlink 構成が現実解です。
git mv CLAUDE.md AGENTS.md→ln -s AGENTS.md CLAUDE.mdの2コマンドで導入でき、Git は symlink をモード 120000 の blob として素直に運びます（Windows のみ要設定）。- 複数リポジトリ・公開/非公開の混在段階では、「正本を宣言し、配線を生成・検証する」発想への切り替えが有効です。CI の数行からでも始められます。
Claude Code の import 構文やメモリ管理の詳細は、Claude Code 公式ドキュメントの「Manage Claude’s memory」セクションで確認できます。AGENTS.md 仕様の全体像は agents.md 公式サイト を参照してください。
コメント