CLAUDE.md と AGENTS.md の二重管理、シンボリックリンクで終わらせよう

はじめに

こんにちは！株式会社エクスプラザの Unsu です。

エクスプラザでは、それぞれのプロジェクトに特化したAI開発エージェント用のコンテキストファイルをエンジニアたちでアップデートするようにしています。

ですが、最近エンジニアによっては使う開発エージェントがバラバラで、Claude CodeとCodexの両方はどちらも独自のコンテキストファイル構造を要求しています。

	Claude Code	Codex
コンテキスト	CLAUDE.md	AGENTS.md
コマンド	.claude/commands/	.codex/commands/
スキル	.claude/skills/	.codex/skills/

同じコーディングルールを2箇所に書いて、片方だけ更新して乖離するというミスを犯しそう。

そこでシンボリックリンクで正規ファイルを1つに絞ることにしました。

シンボリックリンクとは？

ファイルやディレクトリへの「ショートカット」のこと。
実体は1つだけなので、どちらのパスから開いても常に同じ内容が読み書きされる。
ln -s 実体 リンク名 で作れる。

やったこと

# AGENTS.md を正規ファイルにし、CLAUDE.md はリンク
ln -s AGENTS.md CLAUDE.md

# .codex/ を正規ディレクトリにし、.claude/ からリンク
ln -s ../.codex/commands .claude/commands
ln -s ../.codex/skills   .claude/skills

結果こうなる。

AGENTS.md                            ← ここだけ編集する
CLAUDE.md                            ← AGENTS.mdと自動で同期

.codex/
├── commands/                        ← ここだけ編集する
│   ├── command1.md
│   ├── command2.md
│   └── command3.md
└── skills/                          ← ここだけ編集する
    ├── skill1/
    ├── skill2/
    └── skill3/

.claude/
├── commands                         ← '../.codex/commands'と自動で同期
└── skills                           ← '../.codex/skills'と自動で同期

AGENTS.mdを編集すれば両エージェントが同じルールを読むようになります。
また、.codex/の中のコマンドやスキルを追加したり編集すれば、.claude/からも自動で同期されるようになります。

検証

この構成でClaude Codeがシンボリックリンク経由のファイルを正しく参照できるか確認してみましょう。

まず、.codex/commands/に置いたカスタムコマンドがClaude Codeから認識されるか試してみます。

/write-と入力すると、リンク先の.codex/commands/に定義した3つのコマンドが補完候補に表示されました。

次に、AGENTS.mdの内容がCLAUDE.md経由で読めるか試してみましょう。

「CLAUDE.mdの内容を要約して」と聞くと、AGENTS.mdに書いたプロジェクト構成やコーディングルールがそのまま返ってきました。

シンボリックリンク経由でも、コンテキストファイル・カスタムコマンドともに問題なく解決できている様子が確認できました。

まとめ

ln -sだけで二重管理が消え、編集箇所が1つになるので乖離が原理的に起きなくなります。複数のAIコーディングエージェントを併用しているなら、最初にこの構成を作っておくと後が楽です。みなさんもぜひ試してみてください！