投稿者 投稿日: カテゴリー EC×AI活用
AGENTS.md とは、AIコーディングエージェント共通の指示書ファイルのことです。
Claude Code で書いたコードと、Cursor で書いたコードと、Codex で書いたコードの書式がバラバラになる。同じリポジトリなのに、ツールを変えるたびに「命名規則はこう」「テストはこのコマンド」と説明し直している。この重複を消すのが AGENTS.md です。OpenAIが2025年8月に公開し、2025年12月9日にLinux Foundation傘下のAgentic AI Foundationへ移管され、いまでは6万を超えるリポジトリが採用しています。本記事は、EC支援19年・5,000社超の実績を持ち、AI導入支援は2023年から提供する株式会社オルセル（うるチカラ運営）の現場知見にもとづき、楽天RMS連携スクリプトやShopifyテーマ改修といったEC実案件での書き方をプロンプト4本つきで解説します。
ツールごとに設定ファイルを持つ運用が破綻した理由
結論として、AIコーディングツールを2つ以上使う組織では、設定ファイルの共通化が必須になりました。理由は、ツールの入れ替わりが年単位ではなく月単位で起きているからです。
2025年から2026年にかけて、AIコーディング環境は激しく動きました。ツールごとに独自の設定ファイル形式があり、Cursorには .cursorrules、Claude Code には CLAUDE.md、その他のツールにもそれぞれの流儀があります。1つのプロジェクトで3つのツールを併用すると、同じ内容を3か所に書き、3か所とも更新し続けることになります。更新漏れが起きた瞬間、どのツールで作業したかによって成果物が変わります。
Linux Foundationの発表によれば、Agentic AI Foundation は2025年12月9日に設立され、Model Context Protocol（MCP）、Block の goose、そして AGENTS.md の3プロジェクトが最初の貢献として持ち込まれました。OpenAI、Anthropic、Google、AWS などが支援しています。特定ベンダーの持ち物ではなくなったことが、採用を後押ししました。
対応ツールの広がりも実用上は重要です。Codex、Cursor、GitHub Copilot、Gemini CLI、Devin、Factory、Jules、VS Code など、20を超えるツールがネイティブに読み込みます。Claude Code は2026年春に対応を追加しましたが、Claude 固有の設定については従来の CLAUDE.md のほうが表現力があるとされています（両者の使い分けは後述）。
EC開発の現場に引き寄せます。楽天RMSのAPIを叩く在庫同期スクリプト、Amazon SP-API の受注取込バッチ、Shopify のテーマ改修、Merchant Center へのフィード生成。これらは1つのリポジトリに同居していることが多く、それぞれ守るべき制約が違います。RMS のAPIにはレート制限があり、SP-API には認証トークンの扱いがあり、Shopify テーマには Liquid の記法があります。この制約をAIに毎回説明するのは非効率で、説明を忘れれば制限に抵触するコードが生成されます。
とくにEC案件で怖いのは、生成されたコードが「動いてしまう」ことです。文法エラーなら実行時に気づけますが、レート制限を超える並列処理は動いてしまい、しばらくしてからアカウント側で制限がかかります。文字コードを間違えたCSVも生成自体は成功し、モールの取込段階で初めてエラーになります。AIの出力を人間が全部読んでいれば防げますが、実務ではそこまでの余裕はありません。だからこそ、生成の前提として制約を渡しておく必要があります。
制作会社や運用代行に開発を委託している店舗にとっても、この話は他人事ではありません。委託先がどのAIツールを使っているかは、多くの場合こちらからは見えません。共通形式のファイルで制約を渡せるようになったことで、「うちのリポジトリではこう書いてください」を仕様として渡せるようになりました。
AGENTS.mdに書くべき5つの要素
結論から言えば、書くのは「AIが知らないと事故る情報」だけです。理由は、ファイルが長くなるほど費用対効果が落ちるからです。2,500以上のリポジトリを対象にした分析では、150行を超えると効果が頭打ちになり、推論コストが20〜23%増える一方で性能は改善しないという報告があります（第三者による分析のため、数値の再現性は要確認）。技術的な上限は32KiBとされていますが、実務上は150行以内に収めるのが目安です。
書くべき5要素を挙げます。
第一に、環境とコマンドです。依存関係のインストール方法、ビルドコマンド、テストの実行方法、Lintの実行方法。AIが最初に必要とする情報で、ここが書いてあるだけで「とりあえず動かしてみる」の成功率が上がります。
第二に、ディレクトリ構造の意味です。どのフォルダに何が入っているか、触ってよい場所とよくない場所。EC案件なら「本番の商品マスタCSVは data/production 配下にあり、書き換え禁止」といった記述が該当します。
第三に、コード規約です。命名規則、インデント、コメントの言語、エラーハンドリングの方針。ここを書かないと、担当者ごとの好みがそのままコードに出ます。
第四に、禁止事項です。ここが最も重要で、かつ最も書かれていない項目です。「本番環境の認証情報をログに出力しない」「APIのレート制限を超える並列実行をしない」「顧客の個人情報を含むテストデータをコミットしない」。EC案件では、この禁止事項が事故を防ぎます。
第五に、外部サービスの制約です。楽天RMSのAPI仕様、Amazon SP-APIの認証、Shopify Admin APIのスコープ。AIは一般的な知識としてこれらを知っていますが、そのプロジェクトでどのバージョンをどう使っているかは知りません。
逆に、書かなくてよいものも整理しておきます。プログラミング言語の一般的な文法、有名なライブラリの標準的な使い方、AIが学習済みの公開ドキュメントの内容。これらを書き写しても行数を消費するだけで、精度は上がりません。判断基準は「このプロジェクト固有の情報かどうか」です。検索すれば出てくる情報は書かない、と決めてしまうと迷いが減ります。
社内の事情も、必要な範囲だけ書きます。「本番デプロイは店長の承認後」といった業務ルールは、AIが勝手にデプロイを実行しないために有効です。一方で、組織図や担当者の名前まで書く必要はありません。
（用途タイトル：既存プロジェクトからのAGENTS.md生成）
プロンプト1：既存リポジトリからAGENTS.mdの初版を作る
あなたは開発プロジェクトのドキュメント設計者です。
以下のリポジトリ情報から、AGENTS.md の初版を作成してください。
構成する章（この順序で）：
1. プロジェクト概要（3行以内）
2. 環境構築とコマンド（インストール／ビルド／テスト／Lint）
3. ディレクトリ構造と各ディレクトリの役割
4. コード規約（命名／インデント／コメント言語／エラーハンドリング）
5. 禁止事項（必ず5項目以上、それぞれ理由を1行で）
6. 外部サービスの制約（API仕様・レート制限・認証方式）
制約：
- 全体で150行以内に収める
- 抽象的な形容詞（きれいに／適切に／わかりやすく）を使わず、具体的な規則で書く
- リポジトリ情報から確認できない事項は書かない（推測で埋めず「要確認」と記載）
- コマンドは実際にコピーして実行できる形で書く
リポジトリ情報：
- 主要言語とフレームワーク：{言語／FW}
- 連携している外部サービス：{楽天RMS／Amazon SP-API／Shopify Admin API／Merchant Center など}
- ディレクトリ一覧：{tree の出力を貼り付け}
- package.json / requirements.txt の内容：{貼り付け}
- 既存のREADME：{貼り付け}
EC実案件での書き方サンプル
抽象論だと使えないので、EC案件での具体的な書き方を示します。
楽天RMS連携のスクリプトを含むリポジトリなら、禁止事項に「RMS API へのリクエストは1秒あたり1件を超えないこと。超過するとアカウント単位で制限がかかる」と書きます。単に「レート制限に注意」ではAIは判断できません。数値で書きます。
Shopifyテーマの改修なら、「theme/assets 配下の .liquid ファイルを編集する際、既存のセクションIDを変更しない。管理画面のカスタマイズ設定が失われるため」と書きます。理由まで書くことで、AIが例外的な判断をしなくなります。
商品マスタを扱うなら、「data/ 配下のCSVはShift-JISで保存されている。UTF-8で書き出すとモール側の取込でエラーになる」と書きます。文字コードの問題は、書いておかないとほぼ確実に踏みます。
決済まわりに触れるコードがあるなら、「決済処理のロジックは payment/ 配下にあり、このディレクトリの変更は人間のレビューを必須とする」と明記します。AIに触らせない領域を宣言するのも、この文書の役割です。
モールの出店規約に関わる制約も忘れずに書きます。楽天市場向けのメール文面を生成するスクリプトがあるなら、「楽天R-Mail の本文に楽天市場外へのURLを含めない。出店規約で禁止されているため」と明記します。AIは一般的なマーケティングの定石として「自社サイトへ誘導しましょう」という文面を作りがちで、楽天の文脈ではそれが規約違反になります。Amazonについても、「商品紹介コンテンツに外部URLを含めない」と書いておきます。
薬機法や景品表示法に関わる文言生成をコードに含む場合も同様です。「商品説明文の生成では、治る・効く・痩せる・絶対・No.1 といった表現を出力しない」と禁止語を列挙しておきます。生成後に人間がチェックする運用でも、生成段階で減らせるなら減らしたほうが確実です。
書き方の粒度で迷ったら、「新しく入った業務委託のエンジニアに、初日に渡す1枚のメモ」を想像してください。そのメモに書く内容が、おおむね AGENTS.md に書くべき内容と一致します。逆に、そのメモに書かないような細かい実装の話は、コード内のコメントに置くほうが適切です。
（用途タイトル：EC案件向け禁止事項の洗い出し）
プロンプト2：EC開発案件の禁止事項リストを作る
あなたはECシステムの開発リスク管理を担当するエンジニアリングマネージャーです。
以下のプロジェクト構成から、AGENTS.md に記載すべき禁止事項を洗い出してください。
洗い出す観点：
1. 外部APIのレート制限・利用規約に抵触する操作
2. 本番データの破壊につながる操作
3. 個人情報・認証情報の漏洩につながる操作
4. モールの出店規約に抵触するコード（楽天の外部リンク制限など）
5. 文字コード・改行コード起因の破損
各禁止事項について：
- 禁止する操作を具体的に（「〜しない」の形で）
- 禁止する理由を1行で
- 違反した場合に起きること（具体的な障害内容）
- 代替手段があれば1行で
プロジェクト構成：
- 連携先：{楽天RMS／Amazon SP-API／Yahoo!／Shopify／Merchant Center}
- 扱うデータ：{商品マスタ／受注データ／在庫／顧客情報}
- 実行環境：{ローカル／サーバー／CI}
- チーム構成：{人数と役割}
AGENTS.md と CLAUDE.md の使い分け
両方を持つべきか、片方に寄せるべきか。結論としては、共通ルールを AGENTS.md に、ツール固有の指示を各ツールのファイルに置く二層構造が扱いやすい形です。
AGENTS.md には、どのツールで作業しても守ってほしい内容を書きます。コマンド、規約、禁止事項、外部サービスの制約。ここはツール非依存です。
CLAUDE.md には、Claude Code 固有の運用を書きます。サブエージェントの使い分け、スキルの参照、並列実行の方針など、Claude Code にしかない機能に関する指示です。同様に、Cursor 固有の設定は Cursor 側に置きます。
重複を避けるコツは、ツール固有ファイルの冒頭に「共通ルールは AGENTS.md を参照」と1行書いておくことです。内容をコピーせず、参照で済ませます。コピーすると更新漏れが発生し、二層構造にした意味がなくなります。
（用途タイトル：既存設定ファイルの統合）
プロンプト3：バラバラの設定ファイルをAGENTS.mdへ統合する
あなたは開発環境の標準化を担当するアーキテクトです。
以下の複数の設定ファイルを読み、共通部分とツール固有部分に仕分けてください。
仕分けの基準：
1. 共通（AGENTS.mdへ）：どのAIツールで作業しても守るべき内容
2. ツール固有（各ツールのファイルへ）：そのツールにしかない機能に関する指示
3. 矛盾：ファイル間で内容が食い違っている箇所（必ず全件を列挙する）
4. 陳腐化：もう使っていないツール・コマンドへの言及
出力フォーマット：
A. AGENTS.md に入れる内容（150行以内、章立て付き）
B. ツール固有ファイルに残す内容（ツール別）
C. 矛盾の一覧と、どちらを採用すべきかの判断根拠
D. 削除を推奨する記述と理由
現在の設定ファイル：
- CLAUDE.md：{内容を貼り付け}
- .cursorrules：{内容を貼り付け}
- その他：{内容を貼り付け}
運用に乗せるための3つのルール
第一に、更新のタイミングを決めます。おすすめは「AIの出力を人間が同じ理由で3回直したら、AGENTS.md に書く」というルールです。3回同じ指摘をしているなら、それは文書化されていないルールが存在する証拠です。
第二に、レビュー対象に含めます。AGENTS.md の変更をコードレビューの対象に含め、誰が何を変えたかを記録します。この文書はAIの振る舞いを決める設定なので、コードと同じ重みで扱うべきです。
第三に、定期的な棚卸しです。四半期に1回、記述が現状と合っているかを確認します。使わなくなったコマンド、廃止した外部サービス、変わった規約。古い記述が残っていると、AIが古い前提で動きます。
運用でつまずくのは、たいてい第一のルールです。「3回直したら書く」を回すには、直した内容を記録しておく必要があります。レビューコメントを検索できる状態にしておくか、指摘の型をメモに残すか。ここを仕組み化していない組織では、AGENTS.md が初版のまま更新されず、半年後には使われなくなります。
もう1つ、書きすぎの防止も運用課題です。便利だと分かると、あれもこれも書きたくなります。150行の目安を超えたら、何かを削るか外部ファイルへ出す。この判断を四半期の棚卸しでまとめて行うより、追記のたびに「代わりに何を消すか」を考える運用のほうが、結果として整った文書になります。
（用途タイトル：AGENTS.mdの棚卸し）
プロンプト4：AGENTS.mdの記述が現状と合っているか点検する
あなたはコードベースの品質管理を担当するレビュアーです。
以下のAGENTS.mdとリポジトリの現状を突き合わせ、乖離を検出してください。
点検する項目：
1. 記載されているコマンドが実在するか（package.json / Makefile 等と照合）
2. 記載されているディレクトリが実在するか
3. 記載されている外部サービスが現在も使われているか
4. 禁止事項が現在のコードで守られているか（違反箇所があれば指摘）
5. 行数が150行を超えていないか、超えていれば削減候補
出力フォーマット：
A. 修正が必要な記述（現状／あるべき記述／根拠となるファイル）
B. 削除候補（陳腐化した記述と、そう判断した理由）
C. 追記候補（コードに存在するがAGENTS.mdに書かれていない重要な制約）
D. 行数の現状と、150行以内に収めるための削減案
AGENTS.md：{内容を貼り付け}
リポジトリ情報：{tree の出力、package.json、主要な設定ファイル}
費用対効果の見立て
導入コストはほぼゼロです。ファイルを1枚置くだけで、追加のサービス契約は不要です。かかるのは初版を書く工数で、既存プロジェクトなら2〜4時間、新規なら1時間程度が目安でしょう。
効果は2方向に出ます。1つはトークン消費の削減です。毎回のプロンプトに前提条件を書き込む必要がなくなるため、1回あたりの入力トークンが減ります。ただし AGENTS.md 自体が毎回読み込まれるので、ファイルが長すぎると逆効果になります。前述の150行という目安は、この収支から来ています。
もう1つは手戻りの削減です。生成されたコードが規約に合わず書き直す、という往復が減ります。直近の支援案件で観測したのは、AGENTS.md を整備した後、レビューでの指摘件数が体感で半分程度に減ったケースでした。定量化はしていないため参考値ですが、指摘の内容が「規約違反」から「設計の議論」へ移ったという変化は明確でした。
この先の論点
競合の解説が触れていない点を挙げます。AGENTS.md が標準化されたことの本当の意味は、AIツールの乗り換えコストが下がったことではなく、開発ルールが「レビュー可能なファイル」になったことです。
これまで、AIへの指示は個人のプロンプトのなかにありました。誰がどんな前提でAIに書かせたかは追跡できません。AGENTS.md に集約されると、その前提が版管理され、変更履歴が残り、レビューの対象になります。EC事業者にとっては、外注先とのやりとりでこれが効きます。「このリポジトリではこのルールで書いてください」を口頭ではなくファイルで渡せます。
この変化は、開発以外の領域にも広がる可能性があります。いまは開発リポジトリ向けの標準ですが、業務手順をAIに渡すという構造自体は、受注処理や商品登録といった非開発の業務にも当てはまります。実際、ファイル形式で手順を渡す発想はAgent Skillsと共通しており、両者が別々の標準として立ち上がったこと自体が、この方向への収束を示していると読めます。開発の外側でも「AIに渡す設定ファイル」を持つのが当たり前になる日は遠くないでしょう。
もう1つの論点は、Agent Skills との関係です。AGENTS.md がプロジェクト全体の前提を書く場所であるのに対し、Agent Skills は特定の作業手順を書く場所です。前提と手順を混ぜると、どちらも肥大化します。この切り分けについてはClaude Agent Skillsの作り方で整理しました。開発環境まわりの権限設計はAntigravity 2.0の権限設計、並列実行の設計はClaude Codeの並列作業も参考になります。
よくある質問
AGENTS.md はどこに置きますか
リポジトリのルート直下に置きます。サブディレクトリごとに個別の AGENTS.md を置く運用にも対応するツールがありますが、まずはルートに1枚から始めるのが分かりやすいでしょう。モノレポで複数のプロジェクトが同居している場合のみ、階層化を検討してください。
日本語で書いても問題ありませんか
はい、問題ありません。AIは日本語の指示を読めます。ただしコマンドやファイルパスは原文のまま書き、説明文だけ日本語にする形が読みやすくなります。チームに海外メンバーがいる場合は英語のほうが無難です。
CLAUDE.md は削除すべきですか
いいえ、削除しないでください。Claude Code 固有の機能に関する指示は CLAUDE.md のほうが表現しやすいためです。共通ルールを AGENTS.md に移し、CLAUDE.md には Claude 固有の内容だけを残す二層構造にしてください。
150行を超えたらどうすればよいですか
詳細を別ファイルに切り出し、AGENTS.md からは参照だけ書きます。たとえば外部APIの詳細仕様は docs/api-notes.md に置き、「詳細は docs/api-notes.md を参照」と1行だけ残す形です。全部を1枚に詰め込む必要はありません。
エンジニアがいない店舗でも関係ありますか
制作会社や運用代行に開発を委託している店舗にも関係があります。委託先がAIコーディングツールを使う前提で、守ってほしい制約をファイルで渡せるためです。文字コードの指定、触ってはいけないディレクトリ、本番データの扱い。口頭やメールで伝えるより確実です。
何から書き始めればよいですか
禁止事項からをおすすめします。5要素のうち、事故を防ぐ効果が最も大きい項目だからです。過去にヒヤリとした出来事を3つ思い出し、それを「〜しない」の形で書くところから始めてください。コマンドや規約は後からでも足せます。
効果はどう測ればよいですか
レビューでの指摘件数を、規約違反によるものとそれ以外に分けて数えます。AGENTS.md が機能していれば、規約違反による指摘が減ります。減らないなら、書いた内容が守られていないか、そもそも書けていない制約があるということです。
著者：齋藤竹紘（株式会社オルセル 編集長／5,000社以上のEC支援実績／書籍3冊）
参考文献
- Linux Foundation・Agentic AI Foundation（AAIF）設立発表
- Agentic AI Foundation（AAIF）公式サイト
- OpenAI・OpenAI co-founds the Agentic AI Foundation
※うるチカラでは、生成AIの導入支援から運用最適化まで、貴社のEC事業に合わせたカスタマイズ提案を行っています。無料相談（30分）も実施中ですので、お気軽にお問い合わせください。
https://uruchikara.jp/contact/
【監修】齋藤竹紘（株式会社オルセル代表 / 19年・5,000社のEC支援実績）
株式会社オルセル代表取締役 / うるチカラ編集長。19年・5,000社以上のEC支援実績を持ち、楽天市場・Amazon・Yahoo!ショッピング・Shopify・Shopee越境ECの実装ノウハウを保有。AI×ECに関する書籍を3冊執筆。「現場で使えるAI実装」を一次情報として発信しています。
この記事を読んだ人は、こんな記事も読んでいます
