メインコンテンツへスキップ
見出し画像

AGENTS.mdとCLAUDE.md、AI併用時の置き方

    結論:共通ルールは AGENTS.md に1本化し、CLAUDE.md は1行目に @AGENTS.md と書いて取り込むのが、Claude Code・Codex・GitHub Copilot・Cursor を併用するときの最も迷いにくい形です。

    Claude Code は CLAUDE.md があると AGENTS.md を読まない(初期設定の場合)ので、「書いたのに守られない」ときに最初に疑うべきポイントです。

    あわせて、ダウンロードフォルダでAIエージェントを起動しないことも今日から徹底してください。

    はじめに:この記事で解決できること

    AIコーディングツールには、プロジェクトの決まりごとを書いておく「指示書ファイル」があります。ところがツールごとにファイル名と読み方が違うため、X では10月下旬から「AGENTS.md を置いたのに Claude が従わない」という投稿をよく見かけます。

    この記事では、複数のAIツールを使う人向けに次の2つを整理します。

    • どのファイルに、何を書けばよいか

    • 本当に読まれているかを、どう確かめるか

    なお、筆者は4つのツールすべてで読み込み順を実際に試したわけではありません。以下は各社の公式ドキュメントを2026年11月3日夜(日本時間)に読んで整理したものです。「筆者の提案」と書いた部分は公式の推奨ではありません。

    まず押さえる:ツール別の「読む指示書」

    Claude Code(Anthropic)

    • 基本は CLAUDE.md。~/.claude/CLAUDE.md(自分用・全プロジェクト)、./CLAUDE.md(チーム共有)、./CLAUDE.local.md(自分用・このプロジェクトのみ)などがある

    • v2.1.277 以降は AGENTS.md も読める。ただし初期設定では、作業フォルダかその上の階層に CLAUDE.md または CLAUDE.local.md が 1つでもあると、AGENTS.md は読まれない

    Codex(OpenAI)

    • AGENTS.md を読む。~/.codex/AGENTS.md(全体)と、Gitのルートから作業フォルダまでの各階層の AGENTS.md をつなげて使う

    • 同じ場所に AGENTS.override.md があれば、そちらが優先される

    • 合計サイズの上限は初期設定で32KiB。超えた分は読まれない

    GitHub Copilot(GitHub/Microsoft)

    • リポジトリ全体の指示は .github/copilot-instructions.md、特定のファイル向けは .github/instructions/〇〇.instructions.md

    • エージェント向けには AGENTS.md も使え、作業中のファイルに一番近いものが優先される。ルートに置いた CLAUDE.md や GEMINI.md 1つで代わりにすることもできる

    Cursor

    • 細かいルールは .cursor/rules/ の .mdc ファイル(拡張子が .md だと無視される)

    • シンプルに書きたい場合は AGENTS.md をルートや下の階層に置ける。下の階層のものほど優先される

    併用するときのおすすめ構成

    ここからは公式ドキュメントの仕様を組み合わせた、筆者の提案です。

    1. 共通ルールは AGENTS.md に書く

    Codex・Copilot・Cursor はどれも AGENTS.md を読みます。テストのコマンドや命名ルールなど、どのAIにも守ってほしいことはここに集めます。

    2. CLAUDE.md は「読み込みの1行+Claude専用の指示」だけ

    Anthropic の公式ドキュメントには、CLAUDE.md に次のように書く方法が載っています。

    • 1行目に @AGENTS.md(AGENTS.md の中身を取り込む指定)

    • その下に、Claude Code だけに伝えたい指示

    CLAUDE.md を AGENTS.md へのシンボリックリンクにする方法もありますが、公式ドキュメントでは Windows の人がいるなら @AGENTS.md の取り込みを使うよう勧めています。

    3. CLAUDE.local.md を足すときは要注意

    自分用のメモとして CLAUDE.local.md を足すと、それだけで Claude Code は AGENTS.md を読まなくなります(初期設定の場合)。対策は2つです。

    • CLAUDE.md 側で @AGENTS.md を取り込んでおく

    • /config の「Project instructions」を claude-md-and-agents-md(両方読む)にする

    4. 短く、具体的に書く

    Anthropic は CLAUDE.md を 1ファイル200行以内にするよう勧めています。長いほど守られにくくなるためです。「きれいに書く」ではなく「インデントは2スペース」のように、確かめられる書き方にします。

    読まれているかを確かめる方法

    書いただけで安心せず、ツールごとに確認します。

    • Claude Code:/context で「Memory files」の一覧を見る。/memory でも確認できる

    • Codex:リポジトリのルートで「今の指示を要約して」と頼み、内容が返ってくるか見る(公式ドキュメントの確認方法)

    • GitHub Copilot:Copilot Chat の回答の参照一覧に .github/copilot-instructions.md が出ているか見る

    • Cursor:サイドバーの Customize → Rules で、ルールの一覧と状態を見る

    安全面:知らない指示書は「実行ファイル」と考える

    10月22日、セキュリティ企業 Forever Security が、ダウンロードフォルダに仕込まれた AGENTS.md で Codex にマルウェアを入れさせようとする攻撃を実際に見つけたと報告しました。Webサイトはクリックなしでもファイルをダウンロードフォルダに保存できるため、そこでAIを起動すると、仕込まれた指示に従ってしまうおそれがあります。同社の再現では Codex で90%超、Claude Code でも約50%の割合で設定の書き換えが起きたとしています。

    報告で挙げられている対策は次のとおりです。

    • ダウンロードフォルダでAIエージェントを起動しない

    • 自分が書いていない AGENTS.md や CLAUDE.md は、AIに渡す前に自分で読む(クローンしたリポジトリも同じ)

    • ~/.codex/config.toml や .claude/settings.json に、覚えのないサーバー設定や接続先(ANTHROPIC_BASE_URL など)がないか確認する

    • 承認の確認画面やサンドボックスは切らない

    AIツールまわりの安全な入れ方は、以前の記事「その拡張は本物か:Cursorの改ざん版Claude Code拡張事件と、AI拡張の入れ方」でも整理しています。

    まとめ:今日やること

    • 手元のリポジトリに CLAUDE.md・CLAUDE.local.md・AGENTS.md がいくつあるか数える

    • 共通ルールを AGENTS.md に移し、CLAUDE.md は @AGENTS.md + Claude専用の指示だけにする

    • 各ツールで「読まれているか」を1回ずつ確認する

    • ダウンロードフォルダでAIを起動する習慣があれば、やめる

    指示書の仕様は各社とも更新が早いので、迷ったときは下の公式ドキュメントを確認してください。

    参考リンク

     
     
    Claude Code・Codex・GeminiなどのAIエージェントを、開発の実務でどう使うかを書いています。設定手順、ツールの比較、ハマりどころを毎朝更新。エンジニアの仕事と働き方の話もときどき。

    あなたへのおすすめ