結論から書くと、受託開発の AGENTS.md に書くべきなのは コードを読んでも分からないこと です。特に、検証のコマンド、やってはいけない操作、人の承認が必要な操作、お客様との約束の4つは最初に書きます。逆に、ディレクトリの説明やコードを読めば分かることは書きません。短いほど、読まれ、守られます。
AGENTS.md とは何か
公式サイトでは、AGENTS.md を「エージェントのための README」と説明しています。AI のコーディングエージェントがプロジェクトで作業するための文脈と指示を置く、決まった場所です。形式は普通の Markdown で、必須の項目はありません。
ファイルの優先順位は、作業するファイルに最も近い AGENTS.md が優先され、チャットで直接指示した内容はそれより優先される、という考え方です。ワークスペース全体の共通ルールと、リポジトリ固有のルールを分けて置けます。
Claude Code を使う場合は、CLAUDE.md との関係を確認しておきます。公式ドキュメントによると、Claude Code は CLAUDE.md が無ければ AGENTS.md を読みますが、CLAUDE.md がある場合は読みません。両方を置くなら、CLAUDE.md に @AGENTS.md と書いてインポートすると、1つのファイルを複数のツールで共有できます。
受託現場で書くべき項目
公式サイトでは、プロジェクトの概要、ビルドとテストのコマンド、コードの規約、テストの手順、セキュリティの注意点などが挙げられています。受託開発では、ここに次の項目を重点的に書きます。
1. 検証のコマンド
最優先です。AI が自分の作業を確かめる手段になります。
環境の起動方法と、テストや構文チェックのコマンドをそのまま実行できる形で書きます。テストがないならないと書きます。「テストがないので、構文チェックと画面確認のみ」と分かれば、AI も確認の方法を変えられます。
2. 人の承認が必要な操作
受託で最も重要な項目です。本番への反映、本番データベースの操作、メールなどの外部送信、課金に関わる操作は、ここで明示して止めます。
3. 触ってはいけないもの
接続情報の入った設定ファイル、自動生成されたファイル、お客様の管理する領域などです。「読み取り禁止」と「編集禁止」は分けて書きます。自動生成されたファイルは、なぜ編集してはいけないのかと正本の場所も書くと、正しく直してくれます。
4. お客様との約束
コードからは絶対に分からない部分です。
- 対応ブラウザや PHP のバージョンなど、契約で決まった条件
- 使ってはいけないライブラリや外部サービス
- コミットや Pull Request に関する取り決め
- 成果物に残してはいけないもの
たとえば、AI の利用をお客様のリポジトリに痕跡として残さない取り決めがあるなら、指示ファイル自体を .git/info/exclude に入れてコミット対象から外す、といった運用も書いておきます。h-system でも、お客様のリポジトリを汚さないために、この方法を使っています。
5. 危険な箇所と、その理由
メール送信の処理、決済、本番データベースに接続する管理画面などです。リストの形でファイル名を書きます。理由も一言添えると、AI が近い場所を変更するときの判断材料になります。
6. 完了報告の形式
受託では、作業の結果をお客様や自分が確認できる形で残す必要があります。変更したファイルの一覧、実行したコマンドとその出力、未完了の項目、人が行う操作を報告に含めるよう指定します。「成功しました」という要約だけでは確認にならないので、実際の出力を貼らせます。
7. Git の運用
ブランチの切り方、コミットの粒度、push や merge をどこまで AI に任せるかを明記します。git add . を禁止して、ファイルを個別に指定させると、無関係なファイルや秘密情報が混ざる事故を減らせます。
書かないほうがよいこと
公式のベストプラクティスの方針は明確です。リポジトリを読んでも分からないこと、毎回調べ直すことになることだけを書く、というものです。アーキテクチャやファイル構成の説明は不要だとも書かれています。自動生成でファイルを作ったあとの仕事は、主に行を削ることだとしています。
長くなると、読み込みの負担が増えるだけでなく、守られにくくもなります。公式の目安は CLAUDE.md 1ファイルにつき200行以内です。
次のようなものは削ります。
- コードを読めば分かる構成の説明
- 「きれいなコードを書く」のように確かめようのない指示
- すでに設定ファイルで自動的に守られているルール
- 古くなった手順
書き方の基準は「確かめられるか」です。公式の例では、「コードを適切に整形する」ではなく「2スペースでインデントする」、「変更をテストする」ではなく「コミット前に npm test を実行する」とされています。
受託案件のサンプル
最初はこの程度の分量で十分です。
# 〇〇株式会社 受注管理システム
PHP 7.4 / CodeIgniter 3 の既存システムの保守案件。
## 検証
- 構文チェック: find . -name '*.php' -not -path './vendor/*' -exec php -l {} +
- 自動テストなし。変更後は docs/check-list.md の該当項目を画面で確認する
## 人の承認が必要な操作（必ず止まって確認する）
- 本番サーバーへの反映
- 本番データベースへの接続・操作
- メール送信を伴う動作確認
## 触らないもの
- application/config/database.php: 読み取り・出力・コミット禁止
- system/ : フレームワーク本体。編集しない
## 危険な箇所
- application/controllers/Billing.php: 請求メールを実送信する
- application/models/Order.php: 集計は月次の帳票と連動。変更は影響範囲を先に報告する
## 案件の取り決め
- PHP 7.4 で動くこと（サーバー移行まで上げられない）
- 新しいライブラリを追加するときは事前に確認する
## Git
- ブランチ: fix/内容 または feature/内容。main へ直接コミットしない
- git add . は使わず、ファイルを個別に指定する上の例はあくまで書き方の見本です。ファイル名などは案件に合わせて変えてください。
書いても守られないものは仕組みで止め、運用で育てる
ここが最も誤解されやすい点です。公式ドキュメントにも、CLAUDE.md は強制力のある設定ではなく文脈として扱われると明記されています。つまり、AGENTS.md に「本番に反映しない」と書いても、絶対に止まる保証はありません。
本当に止めたい操作は、別の層で止めます。
- エージェントの権限設定: 特定のコマンドや、
.envの読み取りを拒否する。権限のルールは、モデルではなく Claude Code 側で強制されます - Git のフック: main への直接の push を拒否する
- 認証情報を渡さない: 本番の接続情報を開発環境に置かないのが、最も確実です
AGENTS.md は「なぜそうするか」と「どう進めるか」を伝える場所、権限設定やフックは「絶対にさせない」ための場所、と役割を分けます。
育て方
最初から完璧を目指す必要はありません。次のように運用します。
- 案件の開始時に、上のサンプル程度の内容で作る
- AI が同じ間違いを2回したら、そのルールを追記する
- 手順やコマンドが変わったら、その変更と同じコミットで更新する
- 定期的に読み返して、不要になった行を消す
判断に迷ったら、その行を消すと AI が間違えるかどうかで考えます。間違えないなら不要です。
引継ぎの場面でも、このファイルは役に立ちます。AI のために書いた検証のコマンドや危険な箇所の一覧は、次に担当する人にとっても必要な情報だからです。納品物に含めるかどうかは案件ごとの取り決めによりますが、そのまま運用資料の下書きにできます。
複数の案件を担当するなら、全案件に共通するルールはワークスペース直下に、案件固有のものは各リポジトリに分けて置くと、重複が減ります。h-system でも、この2段構えで運用しています。
h-system でできること
h-system では、自社の開発で AGENTS.md を整備し、調査、実装、レビュー、テストに AI を組み込んだ流れで開発と運用をしています。AI の取り入れ方は、どこから始めるべきか分からない段階からご相談いただけます。初回相談（オンライン30分程度）は無料で、代表が直接対応します。