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

ネスト構造は積極的に使う価値があります。あるフォルダーでは正しく、次のフォルダーでは正しくない内容を指定する唯一の方法だからです。「すべての endpoint で入力を検証する」というルールは、endpoint の近くに配置します。ルートファイルに記述すると、関係のないタスクでも毎回読み込まれ、メリットがありません。ルートファイルにすでにサービスごとのセクションが増えている場合は、ネストした構成に分割するのが解決策です。どのルールを下位階層へ移し、どれを最上位に残すかも整理できます。

AGENTS.md に記載する内容

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

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

禁止事項にも記載する価値があります。「npm run build によって生成されるため、dist/ 以下のファイルは絶対に編集しない」と書けば、特定のミスを防げます。原因も示しているため、エージェントは明記されていない同等のケースにも適用できます。対象範囲のルールもここに記載します。エージェントの判断に任せると、依頼した範囲を超えて変更してしまうためです。広くコピーされているあるスキルは、動作する最小限の変更だけを要求することに終始します。

1 つのファイルに決して入れてはいけないもの

これらのファイルには、秘密情報を決して入れないでください。ファイルは git にコミットされ、すべてのセッション開始時にコンテキストへ読み込まれ、リクエストごとにモデルプロバイダーへ送信されます。AGENTS.md に API key を記載すると、その API key はリポジトリの履歴と第三者のログに残ります。秘密情報を貼り付けず、参照先を示してください。「データベースのパスワードは .env にあります。このファイルは gitignore の対象です。読み取る前に確認してください」と記載します。より広い運用上の原則については、agent が認証情報にアクセスできないようにする方法で説明しています。

agent が見れば導き出せる情報は省いてください。ディレクトリ一覧の貼り付け、依存関係一覧のコピー、フォルダー名を言い換えただけのアーキテクチャ概要は、どれも記載した翌週には古くなります。その間も、セッションごとにコンテキストを消費します。落とし穴とその理由は残してください。インベントリは削除します。理由は分けて記載する価値があります。通常と異なる構成になっている理由を agent が確認できないと、その構成を黙ってリファクタリングしてしまうためです。これは、このファイルの隣に DESIGN.md を置くことにも当てはまります。

CLAUDE.md は、同じ考え方を Claude Code 向けにしたものです

Claude Code は CLAUDE.md を読み込みますが、AGENTS.md は自動では読み込みません。プロジェクトファイルは ./CLAUDE.md または ./.claude/CLAUDE.md に置き、すべてのプロジェクトに適用する個人設定は ~/.claude/CLAUDE.md に置きます。Linux では、組織がマシン全体に適用するファイルを /etc/claude-code/CLAUDE.md に配置できます。検出されたファイルはファイルシステムの root から作業ディレクトリまで順に連結されるため、セッションを起動した場所に最も近いファイルが最後に読み込まれます。そのディレクトリで起動するすべてのセッションが同じ設定群を読み込むため、1 台のマシンで 2 つのセッションを並行して実行しやすくなります。また、それらのセッションは実行中に相互に作業を引き渡せます。

リポジトリにすでに 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 はガイダンスであり、権限管理システムではありません。内容は通常のコンテキストとして渡されるため、モデルは読み取り、通常は従います。しかし、内容に反する操作を防止する仕組みはありません。作成したルールがいつの間にか無視され、理由も分からない場合は、文言を 3 回目に書き直す前に、指示が無視される理由を確認してください。「main には絶対に push しない」のように毎回必ず適用すべきルールには、hook または permission setting を使用します。これらはコードとして実行され、モデルが従うかどうかの判断に依存しません。

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

2026 年 7 月 30 日の GitHub trending list に掲載された 2 つのプロジェクトから、この慣行がどの方向に進んでいるかが分かります。

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

Initialize DOX tree for this project now.

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

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 行で十分です。自分の役割、タイムゾーン、実際に使用しているスタック、すでに決定済みで再検討したくない事項、そしてどの程度の説明を求めるかを記載します。プロジェクトファイルが繰り返しの説明を省くのと同じ効果を、1 つ上のレイヤーで得られます。

注意点が 1 つあります。HUMAN.md は個人のプロフィールであるため、性質上センシティブです。公開リポジトリには置かないでください。~/.claude/CLAUDE.md に配置するか、プロジェクトルートの gitignored CLAUDE.local.md に配置します。このファイルはコミット済みのファイルと一緒に読み込まれ、同じように扱われます。

コピーして使える最小テンプレート

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

# 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 つのルールにより、ファイルを有用な状態に保てます。また、人間も機械も読まない文書へ肥大化するのを防げます。内容が安定したら、リポジトリと一緒に移行できます。エージェントが自分の laptop 以外の場所で実行される場合に、特に重要です。自分のサーバーで coding agent を実行するでは、その構成を説明しています。

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 を使用してください。モデルの判断にかかわらず、クライアントによって強制されます。

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

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

HUMAN.md とは何ですか。作成する必要はありますか？

HUMAN.md は、プロジェクトではなく個人の機械可読なプロファイルです。自分の役割、制約、すでに決定した事項を記載し、毎回のセッションで同じ決定をやり直さないようにします。開始に tooling は必要ありません。user-level instructions file に自分で 20 行ほど記述するだけで、その効果の大部分を得られます。個人データとして扱い、push する repository には含めないでください。