agents-md-setup は何をしますか？
AGENTS.mdをエージェント/プロジェクト指示の唯一の情報源（単一参照点） とし、各ツールのファイルからシンボリックリンクでそれを指します。1つのファイル、全てのエージェントで読まれる — 重複も乖離もありません。
なぜこのレイアウトか
AGENTS.mdは、クロスツール標準として急速に普及しています（Cursor、Codexなどが読み込みます）。- Claude Codeは
CLAUDE.mdを読みます。プロンプトやスキルでハーネスにAGENTS.mdを代わりに読ませることはできません。しかし、シンボリックリンクCLAUDE.md → AGENTS.mdがあれば、ClaudeはCLAUDE.mdを開いてAGENTS.mdの内容を取得します。それが仕組みであり、他に何も必要ありません。 - 結果：
AGENTS.mdのみを編集すれば、全てのエージェントが同期します。
判断：現在の状態は？
- どちらのファイルもない → 以下のテンプレートから
AGENTS.mdを作成します。 CLAUDE.mdのみ（実ファイル） → それを情報源にします：git mv CLAUDE.md AGENTS.md # 履歴を保持（または追跡されていなければmv）AGENTS.mdのみ → そのまま維持（良い状態です）。- 両方とも実ファイルとして存在 → 盲目的に上書きしないでください。内容を比較し、
AGENTS.mdにマージします（これが正規ファイルとして優先）。内容が異なる場合はユーザーに確認し、その後スタンドアロンのCLAUDE.mdを削除します。 CLAUDE.mdがすでにAGENTS.mdへのシンボリックリンク → 完了済み。停止します。
シンボリックリンクを作成する
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md # Gitは実シンボリックリンクとして保存（モード120000）
コピーではなくシンボリックリンクとしてコミットされたことを確認：
git ls-files -s CLAUDE.md # モードが120000であること
必要に応じて、他のツールも同じファイルを指すようにします：
ln -s AGENTS.md GEMINI.md
mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md
モノレポ（Turborepo / ワークスペース）
リポジトリ全体の規約用にルートAGENTS.md（上記のCLAUDE.mdシンボリックリンク付き）を配置し、独自のルールが必要な各ワークスペースに**スコープ付きAGENTS.md**を追加します — apps/<app>/AGENTS.md、packages/<pkg>/AGENTS.md — それぞれに、そのディレクトリ内から作成される兄弟シンボリックリンク（ターゲットが相対パスになるように）を配置します：
cd apps/web && ln -s AGENTS.md CLAUDE.md # CLAUDE.md -> ./AGENTS.md（同じディレクトリ）
- Claude Codeは、作業しているファイルに最も近い
CLAUDE.mdを読み込むため、ネストされたファイルはルートを置き換えるのではなく補完します。リポジトリ全体の事項はルートに配置し、各ワークスペースにはパッケージ固有の差分のみを配置します — ルートを重複させないでください。 - 各シンボリックリンクは常に自身のフォルダからの相対パス（ワークスペースに
cdした状態でln -s AGENTS.md CLAUDE.md）で作成し、ルートを指すようにしないでください — 相対的な同一ディレクトリのリンクはチェックアウトや移動にも耐えます。 - Turborepo自身はこれらのファイルを読みません（エージェント用です）。そのため**
turbo.jsonの変更は不要**です。もし表示したい場合は、ルートAGENTS.mdにその規約を記載しても構いません。
README
README.mdがない場合は、最小限のもの（プロジェクト名、1行の説明、セットアップ/実行コマンド）をスキャフォールドします。人間向けのドキュメントはREADME.mdに、エージェント向けの指示はAGENTS.mdに保持し、両者をマージしないでください。
Windows / CI の注意（重要）
Gitシンボリックリンクはcore.symlinks=trueが必要で、Windowsのチェックアウトや一部のCIランナーでは壊れる可能性があります（シンボリックリンクがAGENTS.mdを含むテキストファイルとして作成されます）。プロジェクトがWindowsをターゲットとする場合は、フォールバックを推奨します：小さな実CLAUDE.mdファイルで、その内容全体がポインタとなるようにします —
プロジェクトとエージェントの指示については [AGENTS.md](./AGENTS.md) を参照してください。
— ただし、手動（またはチェックによる）で同期を維持する必要があることを受け入れてください。シンボリックリンクが信頼できる環境では、シンボリックリンクの方が優れています。
後で元に戻さないでください
CLAUDE.mdがAGENTS.mdへのシンボリックリンクになっている場合、それは意図的なものです — AGENTS.mdを編集し、シンボリックリンクをコピーで置き換えないでください。
AGENTS.md テンプレート
# AGENTS.md
このリポジトリで作業するAIエージェントと人間のための指示。
`CLAUDE.md`はこのファイルへのシンボリックリンクです。このファイルが情報源です。
## プロジェクト概要
<これが何か、1〜3文で>
## コマンド
- インストール: `…`
- 開発: `…`
- ビルド: `…`
- テスト / リンター / フォーマット: `…`
## 規約
- <コードスタイル、言語/ランタイム、フォーマット>
- コミットメッセージ: <例: Conventional Commits>
- <エージェントがしてはいけないこと、または常に行うべきこと>
## レイアウト
<主要なディレクトリとそれぞれの役割>