Claude Code の AGENTS.md 対応

##TL;DL

2025-09-24 現在においては AGENTS.md 推奨のシンボリックリンクが無難。

1
ln -s AGENTS.md CLAUDE.md

###2025-11-06 追記

https://code.claude.com/docs/en/claude-code-on-the-web#best-practices

Document requirements: Clearly specify dependencies and commands in your CLAUDE.md file. If you have an AGENTS.md file, you can source it in your CLAUDE.md using @AGENTS.md to maintain a single source of truth.

Claude Code の公式ドキュメントは CLAUDE.md 内で @AGENTS.md を使って参照させる方式推し。

1
@AGENTS.md

##AGENTS.md

OpenAI が 2025/08/20 に AGENTS.md を公開した。このサイトでは、コーディングエージェント向けの標準フォーマットの普及を目的としている。

フォーマットといっても決まっていることとしては、

• AGENTS.md というファイル名
• 拡張子から明らかであるが Markdown 形式で記述

の 2 点だけのように見える。

##対応ソフトウェア

AGENTS.md に 2025/08/20 時点で対応している AI コーディングエージェント、ツールは以下の通り。

• Codex from OpenAI
• Amp
• Jules
• Cursor
• Factory
• RooCode
• Aider
• Gemini CLI
• Kilo Code
• opencode
• Phoenix
• Zed
• Semgrep
• Wrap
• Coding Agent from GitHub Copilot
• VS Code
• ONA
• Devin from Cognition

##Anthropic の不在

現時点における AGENTS.md エコシステムの問題点は、最もユーザが多いと思われる CLI ツールである Claude Code を開発している Anthropic の不在だろう。 Claude Code では CLAUDE.md に AGENTS.md 相当のドキュメントを記述する。 Gemini CLI も同様に GEMINI.md だけを見ていたが、AGENTS.md に対応した。しかし、Claude Code は現時点では AGENTS.md に対応するような動きは見られない。

##Claude Code の AGENTS.md 対応

Feature Request: Support AGENTS.md. · Issue #6235 · anthropics/claude-code で議論されているが、対応に向けた動きは見られない。

##ワークアラウンド

Issue では 3 つのワークアラウンドが紹介されている。

• AGENTS.md を読む指示の追加
• シンボリックリンク
• フックの利用

Issue のコメントを見てもらえればそれぞれ難しいことをしているわけではないので直ぐに実践できると思うが、それぞれの方法について解説する。

###AGENTS.md を読むように指示する

Claude Code は @ の後にファイルパスを書くとそのファイルを参照してくれる機能がある。これを利用して CLAUDE.md に以下のように記述しておくことで AGENTS.md を参照させる。

1
@AGENTS.md

• Common workflows - Claude Docs

###シンボリックリンク

CLAUDE.md を AGENTS.md にリネームしてシンボリックリンクを張る。

1
mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md

この対応方法は AGENTS.md の公式サイトでも紹介されている。

###フック

Claude Code にはフックと呼ばれる機能がある。これは、Claude Code の起動時やツールの利用やファイルの編集の前後といったタイミングで任意の処理を実行するための機能となっている。

フックの活用例としては、

• リンター、コードフォーマッターの実行
• テストの実行
• 特定のコマンドの禁止
• 通知のカスタマイズ
• Claude Code のログ記録

がよく見られる。

• Claude CodeのHooksは設定したほうがいい - じゃあ、おうちで学べる
• Claude Code hooksについて解説してみる | DevelopersIO
• Claude Code の Hooks で作業が終わった後にフォーマッターを実行する
• Claude Code の Hooks でタスクの完了をデスクトップ通知する

今回はこのフックを使って Claude Code が起動したタイミングでコンテキストに AGENTS.md を含めるようにする。

最初に .claude/settings.json に次の設定を追加する。

1
{
2
  "hooks": {
3
    "SessionStart": [
4
      {
5
        "matcher": "startup",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/append_agentsmd_context.sh"
10
          }
11
        ]
12
      }
13
    ]
14
  }
15
}

このフックでは Claude Code 起動時にプロジェクトのディレクトリにある .claude/hooks/append_agentsmd_context.sh を実行する。

.claude/hooks/append_agentsmd_context.sh には次のようなスクリプトを記述する。

1
#!/bin/bash
2

3
# Find all AGENTS.md files in current directory and subdirectories
4
# This is a temporay solution for case that Claude Code not satisfies with AGENTS.md usage case.
5
echo "=== AGENTS.md Files Found ==="
6
find "$CLAUDE_PROJECT_DIR" -name "AGENTS.md" -type f | while read -r file; do
7
    echo "--- File: $file ---"
8
    cat "$file"
9
    echo ""
10
done

これにより AGENTS.md ファイルが存在する場合は標準出力に、

1
--- FILE: AGENTS.md ---
2
<AGENTS.md の内容>

が出力されるため Claude Code のコンテキストに AGENTS.md を含めるという目的が達成できる。

##おわりに

この記事では 2025/09/17 現在において Claude Code で AGENTS.md を利用する方法を 3 つ紹介した。フックを利用する方法はやりたいことに対してやらないといけないことが見合っていないように思えた。 Claude Code は CLAUDE.md を読み込むときに特別扱いしている場合（Claude Code のコードを読めばわかりそうだが…）、フックを使う方法は恩恵が受けられない可能性が高い。

そのため、CLAUDE.md で AGENTS.md を読み込むように指示するか、リンクを作成するのが今のところは良さそうだ。

###追記

CLAUDE.md に @AGENTS.md を書く対応は /init を実行したとき CLAUDE.md に指示内容を書いてしまうため、その度に AGENTS.md に変更を反映して CLAUDE.md を戻す作業が発生した。 /init を実行する頻度は高くないが、それでも手間ではあるのでシンボリックリンクを作る対応が無難に感じた。

##参考文献

• ここだめAGENTS.md
• AGENTS.md の概要｜npaka