ゲーム内の英語を日本語に翻訳するアプリを開発している。
AGENTS.md と CLAUDE.md に何を書くべきか、Claude Code Opus 4.6 に精査させた内容を別プロジェクトでも再現できるようにまとめたもの。

AIコーディングエージェント（Claude Code、GitHub Copilot、Cursor など）を使って開発するとき、プロジェクトルートに置く指示書ファイルがある。

AGENTS.md — OpenAI が提唱し、Linux Foundation の AAIF が管理する全エージェント共通の標準
CLAUDE.md — Claude Code 向けの設定ファイル
.github/copilot-instructions.md — GitHub Copilot 向け

名前はツールごとに違うが、役割は同じ。エージェントが毎セッション開始時に読み込む「ブリーフィング資料」だ。

この記事では CLAUDE.md をベースに書くが、原則は AGENTS.md でもそのまま使える。実際に Next.js は AGENTS.md を作成し、CLAUDE.md をそのシンボリックリンクにして一元管理している。

2025年8月時点で AGENTS.md を採用しているリポジトリは 20,000 以上、12月には 60,000 超と、急速に一般的な慣習になりつつある。

判断基準はたった1つ

「これを削除したらエージェントは間違いを犯すか？」

答えが「はい」なら残す。「いいえ」なら削除する。これに尽きる、と思っている。

このファイルは毎セッション読み込まれるので、書けば書くほどコンテキストを消費する。Anthropic の推奨は 60〜200行、上限は 300行程度。350行を超えるとパフォーマンスが急激に悪化する。

指示が多いほど重要なルールが埋もれて無視される。「あれもこれも」と足すのではなく、「本当に必要か？」と引き算で考えるのがポイント。

書くべきもの（優先度順）

コマンド（最重要）

エージェントはコードからビルド方法やテスト方法を推測できない。Anthropic が最も重視するセクション。

ruff check src/ tests/       — リント
mypy src/                    — 型チェック
pytest tests/ -v             — テスト実行
pip install -e ".[all,dev]"  — 開発環境セットアップ

npm なのか yarn なのか pnpm なのか。make test なのか pytest なのか。こうした「プロジェクト固有のコマンド」がなければエージェントが推測で間違える。

絶対に守るルール（制約）

コードを読んだだけでは気づけない、違反すると壊れるルール。

core/ から PySide6 を import してはならない
requests で verify=False は絶対禁止
APIキーは keyring で保存 — 平文保存禁止

重要なのは「コードから読み取れないもの」に絞ること。リンターの設定で禁止しているルールは ruff や ESLint の設定ファイルから読めるので書かなくていい。

既知の落とし穴

エージェントが初見で踏む可能性が高い、非自明な罠。

自分のプロジェクト（grabtl — ゲーム画面の翻訳ツール）で実際にハマったのが、Windows の OCR ライブラリ（winocr）と翻訳ライブラリ（argostranslate）が同じ DLL の異なるバージョンをバンドルしていて、インポート順序によってプロセスがクラッシュする問題だった。

WinRT/torch DLL 競合: エントリポイントの最初に preload_system_vcrt() を呼ぶ必要がある
Windows OCR 言語パック: OS レベルで別途インストールが必要な場合がある

コードを読んだだけでは理解できないし、エージェントが新しいエントリポイントを作るときに確実に踏む。書くべき典型例。

コーディング規約（デフォルトと異なるもののみ）

設定ファイル（pyproject.toml、.eslintrc など）から読める規約は書かない。読めないものだけ書く。

docstring: Google スタイル
コミットメッセージ: Conventional Commits（feat: / fix: / docs:）

「インデントは4スペース」のように設定ファイルに書いてあるものは不要。

プロジェクト概要（1〜2行）

エージェントが「何のプロジェクトか」を把握するための最小限の説明。

ゲーム内チャットをドラッグ選択で翻訳する Windows デスクトップアプリ。
Python 3.11+ / winocr / argostranslate / PySide6。

技術スタックは1行。詳細な表は不要。

関連ドキュメントへのリンク

設計・アーキテクチャ: docs/architecture.md
セキュリティ設計: docs/security-design.md
コントリビュートガイド: CONTRIBUTING.md

書くべきでないもの

ここが一番重要で、入れてしまいがちなやつを具体的に挙げる。

NG 1：技術選定の理由

コンポーネント	技術	理由
GUI	PySide6 (LGPL v3)	PyQt6はGPLなので企業採用に不向き
OCR	winocr	追加インストール不要で軽量

こういう表は NG。エージェントの作業判断に関係ない。「PySide6 を使え」というルールだけあれば十分で、「なぜ PySide6 か」は docs/architecture.md に書くべきもの。

NG 2：製品の差別化ポイント

固定領域の自動翻訳ではなく「都度ドラッグ」のオンデマンドモデル

APIキー不要で即使えるローカル完結モード

これは人間向けの紹介文で README.md の内容。エージェントがコードを書くときに使わない。

NG 3：セットアップ手順の詳細

import argostranslate.package
argostranslate.package.update_package_index()
available = argostranslate.package.get_available_packages()
pkg = next(p for p in available if p.from_code == "en" and p.to_code == "ja")
pkg.install()

こういう長いスクリプトは CONTRIBUTING.md に書く。指示書には pip install -e ".[all,dev]" の1行で十分。

NG 4：ディレクトリツリー

grabtl/
└── src/
    └── grabtl/
        ├── core/
        │   ├── ocr/
        │   └── translation/
        ├── gui/
        └── cli/

ls や find で確認できる。エージェントはコードを読む能力があるので不要。

NG 5：設定ファイルの複製

インデントは4スペース
行の最大長は100文字
import は isort で整列

pyproject.toml に書いてある。二重管理は不要。

NG 6：自明な指示

読みやすいコードを書いてください
エラーハンドリングを適切に行ってください
テストを書いてください

言われなくてもやる。ノイズになるだけなのが嫌だったので全部消した。

Before / After の比較

57行 → 44行に減らしつつ、エージェントにとって必要な情報は増えた。

セクション	Before	After
プロジェクト概要	6行	2行
技術スタック	12行	削除
コマンド	なし	7行（新規）
コーディング規約	8行	5行
絶対に守るルール	12行	12行
既知の落とし穴	なし	4行（新規）
関連ドキュメント	7行	7行

削除したもの（エージェントの作業に不要）：

差別化ポイント3項目 → README.md に既にある
技術スタック表の「理由」列 → docs/architecture.md に既にある
ruff / mypy の記法 → 設定ファイルから読める

追加したもの（エージェントが間違える原因になる）：

コマンドセクション → 最重要なのに欠けていた
既知の落とし穴セクション → DLL 競合など、コードから読み取れない罠

情報の配置先マップ

置き場所	書く内容
AGENTS.md / CLAUDE.md	コマンド、違反すると壊れるルール、非自明な罠、デフォルトと異なる規約、プロジェクト概要（1〜2行）
README.md	プロジェクト概要の詳細、製品の魅力・差別化
CONTRIBUTING.md	開発環境セットアップの詳細手順
docs/	技術選定の理由、アーキテクチャ詳細、セキュリティ設計
設定ファイル	リンター・フォーマッターのルール

AGENTS.md と CLAUDE.md を両方置く場合

複数のツールを使う可能性があるなら Next.js 方式がおすすめ。メインは AGENTS.md に書いて、CLAUDE.md はシンボリックリンクにする。

ln -s AGENTS.md CLAUDE.md

これで内容を一元管理しつつ、Claude Code と他のツール（Copilot, Cursor 等）の両方に対応できる。
CLAUDE.md 固有の機能（.claude/rules/ によるパス別ルール等）を使いたい場合は、AGENTS.md に共通部分を書き、CLAUDE.md には Claude 固有の追加指示だけを書く方法もある。

感想

エージェント向け指示書は「薄く、鋭く」が鉄則だと思う。

書くもの: コマンド、ルール、落とし穴、デフォルトと異なる規約
書かないもの: コードや設定ファイルから読めるもの、人間向けの説明、自明な指示

判断基準は「これを消したらエージェントは間違えるか？」だけ。毎月見直して不要な指示を削る習慣をつけると、エージェントのパフォーマンスが一番良い状態を維持できると感じる。ゲーム内の英語を日本語に翻訳するアプリを開発している。
AGENT.md, CLAUDE.mdに書くべきものとそうでないものをClaude Code Opus 4.6に精査させ、その内容を別プロジェクトでも再現できるようにClaudeにまとめさせて加筆修正した。

以下本文

AIコーディングエージェント（Claude Code、GitHub Copilot、Cursor など）を使って開発するとき、プロジェクトルートに置く指示書ファイルが重要になってきている。

AGENTS.md — OpenAI が提唱し、Linux Foundation の Agentic AI Foundation (AAIF) が管理する全エージェント共通の標準
CLAUDE.md — Anthropic の Claude Code 向けの設定ファイル
.github/copilot-instructions.md — GitHub Copilot 向け

ツールによって名前は異なりますが、役割は同じ。エージェントが毎セッション開始時にコンテキストに読み込む「ブリーフィング資料」です。

この記事では CLAUDE.md をベースに解説しますが、原則は AGENTS.md でもそのまま適用できます。実際に Next.js は AGENTS.md を作成し、CLAUDE.md をそのシンボリックリンクにすることで内容を一元管理しています。

2025年8月時点で AGENTS.md を採用しているリポジトリは 20,000 以上、12月には 60,000 を超えており、急速に一般的な慣習になりつつある。

たった1つの判断基準

「これを削除したらエージェントは間違いを犯すか？」

答えが「はい」なら残す。「いいえ」なら削除する。これだけです。

このファイルは毎セッション読み込まれるため、書けば書くほどコンテキストを消費する。Anthropic の推奨は 60〜200行、上限は300行程度。350行を超えるとパフォーマンスが急激に悪化するとされている。

指示が多いほど、重要なルールが埋もれて無視される傾向があります。「あれもこれも」と足すのではなく、「本当に必要か？」と引き算で考えるのがポイント。

書くべきもの（優先度順）

コマンド（最重要）

エージェントはコードからプロジェクトのビルド方法やテスト方法を推測できません。Anthropic が最も重視するセクションです。

記載例：

ruff check src/ tests/       — リント
mypy src/                    — 型チェック
pytest tests/ -v             — テスト実行
pip install -e ".[all,dev]"  — 開発環境セットアップ

npm なのか yarn なのか pnpm なのか。make test なのか pytest なのか。こうした「プロジェクト固有のコマンド」はこのファイルになければエージェントが推測で間違えます。

絶対に守るルール（制約）

コードを読んだだけでは気づけない、違反すると壊れるルールです。

記載例：

core/ から PySide6 を import してはならない
requests で verify=False は絶対禁止
APIキーは keyring で保存 — 平文保存禁止

ここで重要なのは「コードから読み取れないもの」に絞ること。たとえばリンターの設定で禁止しているルールは、ruff や ESLint の設定ファイルから読めるので書く必要はない。

既知の落とし穴

エージェントが初見で踏む可能性が高い、非自明な罠です。

自分のプロジェクト（grabtl — ゲーム画面の翻訳ツール）では、Windows の OCR ライブラリ（winocr）と翻訳ライブラリ（argostranslate）が同じ DLL の異なるバージョンをバンドルしており、インポート順序によってプロセスがクラッシュする問題がありました。

記載例：

WinRT/torch DLL 競合: エントリポイントの最初に preload_system_vcrt() を呼ぶ必要がある
Windows OCR 言語パック: OS レベルで別途インストールが必要な場合がある

こうした問題はコードを読んだだけでは理解できず、エージェントが新しいエントリポイントを作るときに確実に踏む。書くべき典型例。

コーディング規約（デフォルトと異なるもののみ）

設定ファイル（pyproject.toml、.eslintrc など）から読める規約は書かない。読めないものだけ書く。

記載例：

docstring: Google スタイル
コミットメッセージ: Conventional Commits（feat: / fix: / docs:）

「インデントは4スペース」のように設定ファイルに明記されているものは不要。

プロジェクト概要（1〜2行）

エージェントが「何のプロジェクトか」を把握するための最小限の説明。

記載例：

ゲーム内チャットをドラッグ選択で翻訳する Windows デスクトップアプリ。
Python 3.11+ / winocr / argostranslate / PySide6。

技術スタックは1行に収める。詳細な表は不要。

関連ドキュメントへのリンク

詳細を知りたいとき参照すべき場所を示す。

記載例：

設計・アーキテクチャ: docs/architecture.md
セキュリティ設計: docs/security-design.md
コントリビュートガイド: CONTRIBUTING.md

書くべきでないもの

ここが最も重要。入れてしまいがちだけど、入れるべきでないものを具体例とともに挙げます。

NG 1：技術選定の理由

以下のような「なぜその技術を選んだか」の表は NG。

コンポーネント	技術	理由
GUI	PySide6 (LGPL v3)	PyQt6はGPLなので企業採用に不向き
OCR	winocr	追加インストール不要で軽量

エージェントの作業判断に影響しません。「PySide6 を使え」というルールだけあれば十分で、「なぜ PySide6 か」は docs/architecture.md に書くべき。

NG 2：製品の差別化ポイント・魅力

以下のような紹介文は NG。

固定領域の自動翻訳ではなく「都度ドラッグ」のオンデマンドモデル

APIキー不要で即使えるローカル完結モード

これは人間に向けた紹介文であり、README.md の内容。エージェントがコードを書くときにこの情報は使わない。

NG 3：セットアップ手順の詳細

以下のような長いセットアップスクリプトは NG。

import argostranslate.package
argostranslate.package.update_package_index()
available = argostranslate.package.get_available_packages()
pkg = next(p for p in available if p.from_code == "en" and p.to_code == "ja")
pkg.install()

開発環境のセットアップ手順は CONTRIBUTING.md に書く。エージェント向け指示書には pip install -e ".[all,dev]" の1行で十分。

NG 4：アーキテクチャの詳細図

以下のようなディレクトリツリーは NG。

grabtl/
└── src/
    └── grabtl/
        ├── core/        # pip install 可能なライブラリ
        │   ├── ocr/     # OCR エンジン
        │   └── translation/ # 翻訳エンジン
        ├── gui/         # PySide6 UI
        └── cli/         # CLI ツール

ディレクトリ構造は ls や find で確認できる。エージェントはコードを読む能力があるので、ファイル構造の説明は不要。

NG 5：リンターやフォーマッターの設定で表現できるもの

以下のような設定ファイルの複製は NG。

インデントは4スペース
行の最大長は100文字
import は isort で整列

これらは pyproject.toml の [tool.ruff] セクションに書かれている。エージェントは設定ファイルを読めるので、二重管理する必要はない。

NG 6：「クリーンコードを書け」等の自明な指示

以下のような一般論は NG。

読みやすいコードを書いてください
エラーハンドリングを適切に行ってください
テストを書いてください

エージェントは言われなくてもこれらを実践する。自明な指示はノイズになるだけ。

Before / After の比較

57行 → 44行に減らしつつ、エージェントにとって必要な情報は増えた。

セクション	Before	After
プロジェクト概要	6行	2行（差別化ポイント削除、技術スタックを1行に集約）
技術スタック	12行	削除（docs/architecture.md に委譲）
コマンド	なし	7行を新規追加
コーディング規約	8行	5行（設定ファイルから読めるものを削除）
絶対に守るルール	12行	12行（そのまま維持）
既知の落とし穴	なし	4行を新規追加
関連ドキュメント	7行	7行（そのまま維持）