AI コーディングエージェントを受託開発に組み込む ― AGENTS.md・権限・検証の設計

Claude Code や Codex、GitHub Copilot の coding agent など、コードを読み、書き、コマンドまで実行する「AI コーディングエージェント」が、開発の現場で当たり前に使われるようになりました。一方で「入れてみたが、毎回同じ説明をしている」「勝手に余計なところまで直された」という声もよく聞きます。

この記事は、Web 制作・システム開発のエンジニア、とくにチームでエージェントを使い始めたい人に向けて、2026 年 11 月時点の各ツールの公式ドキュメントをもとに、導入の設計をまとめます。題材は、私たちが普段扱っている Laravel の受託開発です。

なぜ「入れるだけ」ではうまくいかないのか

エージェントは、会話を始めるたびにプロジェクトのことを何も知らない状態から始まります。テストの実行方法も、このリポジトリで使ってはいけないライブラリも、顧客との取り決めも知りません。人が毎回それを口で伝えていると、説明の抜けがそのまま品質のばらつきになります。

もう一つの理由は、エージェントが「実行できる」ことです。チャットで答えを返すだけの AI と違い、ファイルを書き換え、composer や git を動かします。便利な反面、何をどこまで任せるかを決めておかないと、確認の手間が増えるか、確認が抜けるかのどちらかになります。

つまり、チームで使うには次の 3 つを用意する必要があります。

プロジェクトの取扱説明書：エージェントが最初に読む、現場のルール
任せる範囲の設定：許す操作・確かめる操作・禁じる操作
完了の基準：何が通れば「できた」と言えるか

以下、この順に見ていきます。

AGENTS.md：エージェントが最初に読む「現場の取扱説明書」

AGENTS.md とは

AGENTS.md は、コーディングエージェント向けの説明をリポジトリに置くための、オープンな形式です。公式サイトでは「エージェントのための README」と説明されていて、決まった項目はなく、ふつうの Markdown で書きます。現在は Linux Foundation 傘下の Agentic AI Foundation が管理しています。

対応しているツールは多く、公式サイトには Codex、Cursor、Gemini CLI、GitHub Copilot の coding agent、Devin、Junie などが並んでいます。ツールごとに別の説明ファイルを書き分けなくてよいのが、いちばんの利点です。

読み込み方も確かめておきます。

入れ子にできる：サブディレクトリにも置けて、編集するファイルにいちばん近い AGENTS.md が優先されます。管理画面と API で約束事が違うときなどに便利です。
Codex：リポジトリのルートから作業中のディレクトリまで順に AGENTS.md を集めてつなげます。合計の上限は既定で 32 KiB（project_doc_max_bytes）で、それを超えた分は読まれません。
GitHub Copilot：いちばん近い AGENTS.md を使います。リポジトリ直下の CLAUDE.md や GEMINI.md を代わりに使うこともできます。
Claude Code：独自の CLAUDE.md を読みます。公式ドキュメントでは、CLAUDE.md に @AGENTS.md と 1 行書いて読み込ませる方法が案内されています。

CLAUDE.md

@AGENTS.md

## Claude Code だけに伝えたいこと
- 大きな変更は、先に plan モードで計画を見せてから着手する

書くこと・書かないこと

Claude Code のベストプラクティスには、判断の基準として「それはコードを読めばわかることか？」という問いがあります。わかるなら書かない、というのが原則です。ディレクトリ構成の説明や、README の写しは、エージェントが自分で読めるので要りません。説明ファイルは毎回読み込まれるので、長いほど本当に大事な指示が埋もれます。Claude Code では 1 ファイル 200 行以内が目安とされています。

書く価値が高いのは、次のようなものです。

書くもの	例
実行するコマンド	テスト・静的解析・整形のコマンドを正確に
コードを読んでも誤解しやすい箇所	名前と中身が合っていない古いクラス
リポジトリの外で決まったこと	顧客と合意した対応ブラウザ、触ってはいけない機能
二度以上注意したこと	同じ間違いを繰り返されたら、ここに足す

書き方は具体的に、命令の形で書きます。「きれいに書く」ではなく「vendor/bin/pint で整形する」のように、守れたかどうかを判定できる書き方にします。

Laravel 案件のひな形

案件の最初に置くことを想定した、汎用のひな形です。コマンドは案件に合わせて書き換えてください。

AGENTS.md

# 開発メモ（エージェント向け）

## コマンド
- テスト: `php artisan test`（変更したら必ず実行し、全件通してから完了とする）
- 整形: `vendor/bin/pint`
- 静的解析: `vendor/bin/phpstan analyse`

## 約束事
- DB の変更は必ずマイグレーションで行う。既存のマイグレーションファイルは書き換えない
- 画面の文言は `lang/ja` に置き、Blade に直接書かない
- 新しい Composer パッケージは入れる前に理由を書いて確認を取る

## 触らないもの
- `.env` と `config/services.php` の認証情報
- `app/Legacy/` 以下（顧客の既存システムとの連携。改修は別契約）

## 完了の報告
- 変更したファイル、実行したテストと結果、確かめられなかった点を書く

Laravel なら、公式の Laravel Boost を入れるのも手です（2026 年 11 月時点の最新は v2.10.4）。composer require laravel/boost --dev のあと php artisan boost:install を実行すると、Laravel や Livewire、Pest などのバージョンに合ったガイドラインを AGENTS.md・CLAUDE.md に書き込み、データベースの構造やエラーログ、ドキュメント検索をエージェントに渡す MCP サーバーも設定してくれます。既存の AGENTS.md がある場合は、Boost 用の区切りの中だけを書き換えるので、自分たちのルールと同居できます。案件独自のガイドラインは .ai/guidelines/ に置けます。

権限とサンドボックス：任せる範囲を設定で決める

AGENTS.md は、あくまでお願いです。Claude Code の公式ドキュメントも、CLAUDE.md は「強制される設定ではなく文脈」だと明記していて、必ず守らせたいことは設定やフックに書くよう案内しています。そこで、任せる範囲はツールの設定で決めます。

まず、操作を 3 段階に分けて考えます。

区分	操作の例	扱い
任せる	ファイルを読む、テスト・整形・静的解析を実行する	確認なしで許可
確かめる	パッケージの追加、`git push`、外部への通信	実行前に人が確認
禁じる	`.env` や鍵ファイルを読む、本番環境への接続	拒否

Claude Code では、これをリポジトリの .claude/settings.json に書いてチームで共有できます。

.claude/settings.json

{
  "permissions": {
    "allow": [
      "Bash(php artisan test *)",
      "Bash(vendor/bin/pint *)",
      "Bash(vendor/bin/phpstan *)"
    ],
    "ask": [
      "Bash(composer require *)",
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

ルールは「拒否 → 確認 → 許可」の順に評価されるので、許可のルールで拒否を上書きすることはできません。ただし、公式ドキュメントは、コマンドのルールは文字列の照合なので、sh -c を挟むなどの書き方まで止められるわけではない、とも注意しています。本当に守りたい境界は、OS の仕組みで閉じ込めるサンドボックスに任せます。Claude Code では sandbox.enabled を true にすると、シェルのコマンドが作業ディレクトリの外に書き込めなくなり、通信は許可したドメインだけに絞られます。

Codex も考え方は同じです。sandbox_mode で read-only・workspace-write・danger-full-access のどれかを選び、approval_policy で確認のしかたを決めます。既定では通信がオフになっていて、必要なときだけ開ける作りです。なお、以前あった approval_policy = "untrusted" は廃止されているので、古い記事の設定を写すときは注意してください。

「テストが通ったら完了」を仕組みにする

Claude Code のベストプラクティスでいちばん強調されているのは、エージェント自身が結果を確かめられるようにすることです。「合格か不合格かを返す、実行できるもの」を渡す、と書かれています。テストや静的解析がその役になります。

ただ、AGENTS.md に「テストを実行すること」と書くだけでは、忘れられることがあります。そこで フック（決まったタイミングで自動で動くコマンド）を使います。次の例では、ファイルを編集するたびに Pint で整形し、作業を終えようとした時点でテストが落ちていれば、終了を止めて直させます。フックのコマンドが終了コード 2 を返すと、その操作は止まり、エラー出力がエージェントに伝わります。

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | grep '\\.php$' | xargs -r vendor/bin/pint || true" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "php artisan test 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

テストの量が多い案件では、Stop のたびに全件を流すと待ち時間が長くなります。その場合は、変更に関係するテストだけを流すスクリプトにするなど、速さとの釣り合いを取ってください。

手元の仕組みに加えて、最後の砦は CI とレビューです。

graph LR A[エージェントが実装] --> B[フック: 整形・テスト] B --> C[プルリクエスト] C --> D[CI: テスト・静的解析] D --> E[人のレビュー] E --> F[マージ]

エージェントにはプルリクエストを作るところまでを任せ、マージは人が行う、という線を引いておくと、責任の所在がはっきりします。レビューでは、差分そのものに加えて「エージェントの完了報告と差分が合っているか」を見ると、見落としに気づきやすくなります。

受託開発ならではの注意点

自社サービスと違い、受託開発では、コードも情報も顧客のものです。導入前に、次のことを決めておきます。

契約と顧客の了承：顧客のコードを外部の AI サービスに送ってよいかは、契約や秘密保持の取り決め次第です。案件ごとに確かめ、必要なら AI ツールを使うことを伝えて了承を得ます。
使うツールとプランのデータの扱い：入力したコードが学習に使われるか、どこに保存されるかは、ツールと契約プランによって違います。チームで使うツールとプランを決め、利用規約を確かめておきます。
秘密情報を渡さない：.env や本番の接続情報は、上の deny とサンドボックスで読めないようにします。動作確認には、ダミーの値を入れた .env.example やテスト用の DB を使います。
本番に触らせない：エージェントが動くのは開発環境だけにします。Laravel Boost も開発用（--dev）として入れるもので、データベースへの問い合わせは読み取り専用のトランザクションで実行されますが、つなぐ先は開発用の DB にとどめます。
案件ごとに設定を分ける：AGENTS.md と .claude/settings.json は各リポジトリに置き、案件の事情（触らない範囲、対応ブラウザなど）を書き込みます。

導入の進め方チェックリスト

最初から大きな機能を任せると、うまくいかなかったときに原因を切り分けられません。次の順で広げていくのがおすすめです。

社内のリポジトリ 1 つで試す（顧客の案件は、契約を確かめてから）
AGENTS.md にコマンドと「触らないもの」だけを書く。足りない説明は、使いながら足す
権限を設定し、.env を読めないようにする。できればサンドボックスを有効にする
テストを書く・バグを直すなど、結果を確かめやすい小さな作業から任せる
フックで整形とテストを自動にする
プルリクエストを作るところまでを任せ、マージは人が行う運用を決める
同じ注意を 2 回したら AGENTS.md に足す、を習慣にする

まとめ

エージェントは毎回まっさらな状態から始まります。現場のルールは AGENTS.md に、コードを読んでもわからないことだけを短く書きます。
AGENTS.md はお願いにすぎません。必ず守らせたいことは、権限の設定とサンドボックスで決めます。
「テストが通ったら完了」をフックと CI で仕組みにし、最後は人がレビューしてマージします。

エージェントに社内のデータや機能をつなぐ MCP サーバーの仕組みは、当ブログの「MCP とは何か」の記事もあわせてご覧ください。開発チームへの AI エージェントの導入や、既存の Laravel プロジェクトでの整備についてお困りでしたら、お気軽にご相談ください。

参考リンク

AGENTS.md 公式サイト: https://agents.md/
Codex: AGENTS.md の読み込み: https://learn.chatgpt.com/docs/agent-configuration/agents-md
Codex: 承認とセキュリティ: https://learn.chatgpt.com/codex/agent-approvals-security
GitHub Docs: リポジトリのカスタム指示: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
Claude Code: メモリ（CLAUDE.md）: https://code.claude.com/docs/en/memory
Claude Code: ベストプラクティス: https://code.claude.com/docs/en/best-practices
Claude Code: 権限の設定: https://code.claude.com/docs/en/permissions
Claude Code: フック: https://code.claude.com/docs/en/hooks-guide
Claude Code: サンドボックス: https://code.claude.com/docs/en/sandboxing
Laravel Boost: https://laravel.com/docs/boost

#ai #laravel #claudecode #security

AI コーディングエージェントを受託開発に組み込む ― AGENTS.md・権限・検証の設計

なぜ「入れるだけ」ではうまくいかないのか

AGENTS.md：エージェントが最初に読む「現場の取扱説明書」

AGENTS.md とは

書くこと・書かないこと

Laravel 案件のひな形

権限とサンドボックス：任せる範囲を設定で決める

「テストが通ったら完了」を仕組みにする

受託開発ならではの注意点

導入の進め方チェックリスト

まとめ

参考リンク

Related

Node.js 26 が LTS に ― 22・24 からの移行で確かめたい変更点と手順

Claude Code クラウドセッションの環境設計 ― ネットワーク・秘密情報・セットアップの決め方

Claude Code のクラウドセッションとは ― 制作会社に任せる前に確認したい 7 つのこと

お問い合わせ

WEB

CONSULTING