AGENTS.mdとHUMAN.mdの違いと書き方

AGENTS.mdとは

AGENTS.mdは、リポジトリのルートに置くプレーンなMarkdownファイルです。コーディングエージェントに、そのプロジェクトでの作業方法を指示します。公式サイトでは、「エージェント向けのREADMEです。AIコーディングエージェントがプロジェクトで作業するために必要なコンテキストと手順を提供する、専用かつ予測可能な場所」と説明されています。この形式はLinux Foundation傘下のAgentic AI Foundationが管理しています。2026年7月時点で、Codex、Cursor、Jules、Devin、GitHub Copilotを含む20を超えるエージェントが読み取ります。

この規約が存在する理由は実務的です。チームに加わった人はREADMEを読み、ビルドコマンドを推測します。推測が間違っていれば、誰かに尋ねます。エージェントは質問できません。pnpm testを使用するプロジェクトでnpm testを実行し、失敗を確認して別の方法を試します。そのたびにトークンを消費します。実際のコマンドを一度書いておけば、この種の失敗をまとめて防げます。

必須フィールドはありません。サイトにも明記されています。「AGENTS.mdは標準的なMarkdownにすぎません。好きな見出しを使用できます。エージェントは提供されたテキストを解析するだけです」。これが仕様のすべてです。価値は形式にはありません。すべてのツールが確認するパスにファイルを置くことに価値があります。

ファイルの配置場所と優先されるファイル

最初のファイルはリポジトリのルートに配置します。モノレポでは各サブプロジェクト内に追加できます。ルールは単純です。「agents はディレクトリツリー内で最も近いファイルを自動的に読み込むため、最も近いファイルが優先されます」。2つのファイルが競合する場合は、編集中のファイルに近いほうが優先されます。チャットに入力した内容は、両方のファイルより優先されます。

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

階層化は活用する価値があります。あるフォルダーでは正しく、次のフォルダーでは正しくない内容を指定する唯一の方法だからです。「すべてのエンドポイントで入力を検証する」というルールは、エンドポイントの近くに配置します。ルートのファイルに記述すると、関係のないすべてのタスクで読み込まれ、効果がありません。

AGENTS.md に記載する内容

コードを読んだだけではエージェントが判断できない内容を記載します。まず、正確なビルド、テスト、lint のコマンドを、ターミナルに貼り付けられる形式で示します。1つのテストを実行するコマンドも追加してください。全体のテストスイートしか実行方法を知らないエージェントは、全体のテストスイートを40回実行してしまうためです。ツールのデフォルトと異なる規約を記載します。エージェントはデフォルトをすでに把握しているため、必要なのはプロジェクト固有の変更点だけです。使用している場合は、コミットメッセージの形式と pull request のルールも記載します。

記載する内容は、主張を検証できる程度に具体的にします。「インデントには2スペースを使用する」は、実際にそうなっているかを確認できるため、有効な指示です。「コードを適切に整形する」は、検証できる内容がないため不十分です。場所についても同様です。「API handler は src/api/handlers/ に配置する」は、「ファイルを整理しておく」より明確です。

禁止事項にも記載する価値があります。「npm run build によって生成されるため、dist/ 以下のファイルは絶対に編集しない」と書けば、特定の誤りを防止できます。原因も示しているため、エージェントは記載されていない同等のケースにも適用できます。

これらのファイルに決して含めてはいけないもの

これらのファイルには、秘密情報を決して記載しないでください。ファイルは git にコミットされ、すべてのセッション開始時にコンテキストへ読み込まれ、すべてのリクエストでモデルプロバイダーに送信されます。AGENTS.md に記載した API key は、リポジトリの履歴と第三者のログに残る API key です。秘密情報を貼り付けるのではなく、場所を示してください。「データベースのパスワードは .env にあります。このファイルは gitignore の対象です。読み取る前に確認してください」と記載します。より広い範囲の原則については、エージェントの手の届かない場所に認証情報を保管するで説明しています。

エージェントが確認すれば導き出せる情報は省いてください。ディレクトリ一覧の貼り付け、依存関係一覧のコピー、フォルダー名を並べ直しただけのアーキテクチャ概要は、どれも記載した翌週には古くなります。その間、すべてのセッションでコンテキストを消費します。落とし穴と理由は残してください。インベントリは削除してください。

CLAUDE.md は同じ考え方を Claude Code に適用したものです

Claude Code は CLAUDE.md を読みますが、AGENTS.md は自動では読みません。プロジェクトファイルは ./CLAUDE.md または ./.claude/CLAUDE.md に配置し、すべてのプロジェクトに適用する個人設定は ~/.claude/CLAUDE.md に配置します。Linux では、組織がマシン全体に適用するファイルを /etc/claude-code/CLAUDE.md に配置できます。検出されたファイルはファイルシステムのルートから作業ディレクトリまで順番に連結されるため、セッションを開始した場所に最も近いファイルが最後に読み込まれます。

リポジトリにすでに AGENTS.md がある場合は、2つ目のコピーを管理しないでください。これをインポートし、Claude 固有の内容だけを追加します。

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

追加する内容がない場合は、シンボリックリンクを使用できます。

ln -s AGENTS.md CLAUDE.md

成功時、コマンドは何も出力しません。次のセッションで /context を実行し、Memory files の下に CLAUDE.md が表示されることを確認します。その一覧にない場合、ファイルは読み込まれていないため、内容は適用されていません。ファイルを自分で作成する代わりに初期ドラフトを生成するには、/init を実行します。コードベースを読み取り、開始点となるファイルを生成します。CLAUDE.md がすでに存在する場合は、上書きせずに改善案を提示します。

各ファイルは約 200 行以内にしてください。長いファイルはウィンドウの容量を多く消費し、指示への準拠率が低下します。その容量を他に何が使用しているか確認したい場合は、エージェントのコンテキストウィンドウに実際に何が入るかで詳しく説明しています。

1点、強調しておく必要があります。AGENTS.md はガイダンスであり、権限システムではありません。内容は通常のコンテキストとして渡されるため、モデルはそれを読み、通常は従います。ただし、指示に反する操作をブロックするものではありません。「main には絶対に push しない」のように毎回必ず守る必要があるルールには、hook または permission setting を使用してください。これらはコードとして実行され、モデルが従うかどうかの判断に依存しません。

これらのファイルを自動生成するツール

2026年7月30日のGitHub trendingリストにある2つのプロジェクトは、この慣行が向かっている方向を示しています。

agent0ai/dox（2026年7月時点で1,368 stars）は、AGENTS.mdファイルのツリーを最新に保つためのframeworkです。packageもruntimeも提供しません。agent0ai/doxのAGENTS.mdの内容を自分のroot AGENTS.mdにコピーすれば、それがインストールになります。既存のprojectでは、agentに次のように指示します。

Initialize DOX tree for this project now.

agentは子AGENTS.mdファイルとそのindexを作成し、何かを編集する前にそのツリーを確認します。また、変更が反映された後に、影響を受けるdocumentationを更新します。この仕組みの前提は、agentが作業の副作用として保守するdocumentationは正確な状態を保つ一方、人が手動で更新するdocumentationはそうならないということです。

HUMAN.md、同じ仕組みを自分自身に向ける

Intuition-Lab/personal-model（2026年7月時点で1,260 stars）は、このパターンをリポジトリではなく個人に適用します。このプロジェクトでは、HUMAN.mdを自分で入力するファイルではなく、システムの出力として位置付けています。つまり、「現在重要なこと、普段どのように判断するか、注意がどこへ向かっているかを表す、生きたモデル」です。macOS 13以降でローカル実行し、macOSの権限を許可するとアクティビティを取得し、その結果をMCP（model context protocol）経由でエージェントに公開します。簡単なインストール手順は次のとおりです。

uv tool install personal-model
persome onboard
persome model open --after 30

この機能の大部分の利点を得るために、そこまで必要ではありません。手書きのHUMAN.mdは約20行で十分です。自分の役割、タイムゾーン、実際に使用するstack、すでに決定済みで再検討したくない事項、そしてどの程度の説明を求めるかを記載します。これはプロジェクトファイルが削減するのと同じ、繰り返しの説明を省きます。ただし、対象が1段階上のレイヤーになります。

注意点が1つあります。HUMAN.mdは人のプロフィールなので、定義上センシティブです。public repositoryには置かないでください。~/.claude/CLAUDE.mdに置くか、プロジェクトrootのgitignoredなCLAUDE.local.mdに置いてください。このファイルはcommit済みのファイルと一緒に読み込まれ、同じように扱われます。

コピーして使える基本テンプレート

意図的に短くしています。該当しないセクションは削除し、最新の状態を維持できないセクションは追加しないでください。

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

記述したら、その場で修正します。行を追加する目安は、同じ修正をチャットに2回入力したことです。この1つのルールにより、ファイルの有用性を保ち、誰も読まない文書へと肥大化するのを防げます。機械も例外ではありません。安定したら、ファイルはリポジトリとともに移動します。エージェントがラップトップ以外の場所で実行される場合に、特に重要です。自分のサーバーでコーディングエージェントを実行するで、この構成を説明しています。

FAQ

AGENTS.mdはCLAUDE.mdと同じファイルですか？

2つのファイル名で表した同じ考え方です。Claude CodeはCLAUDE.mdを読み込み、接続しない限りAGENTS.mdを無視します。1つのファイルを正本として管理し、もう一方から正本へリンクしてください。方法は、CLAUDE.mdの先頭に@AGENTS.mdと記述するか、ln -s AGENTS.md CLAUDE.mdを使用します。完全なコピーを2つ別々に管理すると、1か月以内に内容が食い違います。

AGENTS.mdを書けば、エージェントは必ず従いますか？

いいえ。内容はコンテキストとして渡されるため、モデルはそれを読み、通常は従います。ただし、内容に反する操作をブロックするものはありません。曖昧な指示は最も確実性が低く、相反する指示を記載した2つのファイルがあると、エージェントは任意に一方を選択します。毎回必ず守る必要があるルールには、hookまたはpermission ruleを使用してください。これらはモデルの判断にかかわらずclientによって適用されます。

AGENTS.mdはgitにコミットすべきですか？

はい。build command、構成、規約など、プロジェクトに関して常に当てはまる内容はコミットしてください。このファイルの目的は、チームメンバーのエージェントも自分のエージェントと同じコンテキストで開始できるようにすることです。個人的な内容や特定のマシンに固有の内容は、別のgitignored fileに記載してください。credentialsはどちらにも記載しないでください。

HUMAN.mdとは何ですか。必要ですか？

HUMAN.mdは、プロジェクトではなく個人を表すmachine-readable profileです。自分の役割、制約、すでに決定した事項を記載し、毎回のsessionで同じ判断をやり直さないようにします。開始にtoolingは必要ありません。user-level instructions fileに手書きの20行を記載するだけで、利点の大部分を得られます。個人データとして扱い、pushするrepositoryには含めないでください。