本記事は、Mediumに掲載した記事の日本語版です。英語版もあわせてご覧いただけます。チームリーダー・マネージャー向けの推奨構成として、導入手順、セキュリティ、データプライバシー、部門ごとのカスタマイズ方法を解説します。
文書管理
| 項目 | 内容 |
|---|---|
| 目的 | AIコーディングエージェント向けにリポジトリを準備するための、ツールに依存しない統一的な方法を定める |
| 対象ツール | Claude Code、OpenAI Codex、GitHub Copilot、Google Antigravity、チャット型LLM |
| 想定読者 | チームリーダー、エンジニアリングマネージャー、IT／インフラ管理者 |
| ステータス | 推奨構成（導入前に自組織のポリシーに合わせて調整してください） |
| 見直し周期 | 四半期ごと、または各ツールのプロジェクト指示の読み込み方法が変更されたとき |
1. 背景
現在、多くのチームは1つのAIツールだけを使っているわけではありません。ターミナルでClaude Codeを好むメンバーもいれば、IDE内でCopilotを使うメンバーも、CodexやAntigravityを試しているメンバーもいます。これまで各ツールは、それぞれ独自の指示ファイル、独自の規約、独自のプロジェクト理解の仕方を前提としていました。
その結果、指示が重複して内容が食い違い、エージェントがリポジトリを誤解します。そして最も懸念すべきなのは、エージェントがどのデータにアクセスできるのかを一貫して管理できていないことです。
本SOPでは、4つのツールすべてが読み込める単一の共通構成を提案します。同様に重要な点として、セキュリティとデータプライバシーを後付けではなく、導入作業の一部として扱います。
2. 基本原則：信頼できる唯一の情報源
業界では、リポジトリのルートに置く AGENTS.md というプレーンなMarkdownファイルが事実上の標準になりつつあります。Codex、Copilot、Antigravityはこれをネイティブに読み込みます。Claude Codeは独自の CLAUDE.md を読み込みますが、このファイルから1行で AGENTS.md をインポートできます。つまり、チームが管理するファイルは1つだけで、すべてのツールが同じ指示を受け取ります。
ツールの仕様は頻繁に変わります。展開する前に、各ベンダーの公式ドキュメントで最新の動作を確認してください。
3. 役割と責任
-
チームリーダー／マネージャー：
AGENTS.mdとセキュリティ設定を管理し、両者の変更を承認します。チームが承認済みのツールとプランのみを使用していることを確認します。 - エンジニア： 指示に従い、コンテキスト文書を最新の状態に保ちます。エージェントが提案したすべての変更を、マージ前にレビューします。
- セキュリティ／IT部門： AIツールに公開してよいデータとそうでないデータを定義し、除外設定や権限設定を定期的に見直します。
4. 推奨リポジトリ構成
図1. 複数のエージェントを使うチーム向けの推奨リポジトリ構成（イメージ）
この構成は3つの層から成ります。ルートには共通の指示書である AGENTS.md と、1行だけの CLAUDE.md を置きます。docs/ai/ フォルダには、エージェントに読ませるより詳しいコンテキストとして、プロジェクトの目的、アーキテクチャ、規約、セキュリティルールを置きます。権限設定などのツール固有の設定は、各ツール専用のフォルダに最小限だけ配置します。
5. 手順
手順5.1：AGENTS.md を作成する
以下のテンプレートを使い、リポジトリのルートにファイルを作成します。内容は簡潔に保ってください。このファイルは毎回のセッションで読み込まれるため、長いほどコストと精度の両面で不利になります。指示は日本語で書いても問題ありません。
# AGENTS.md — AIコーディングエージェント向け指示書
## プロジェクト概要
- 目的：<1行で>
- 担当：<チーム／部門>
- 環境：<言語、OS、クラウド、サーバー>
## リポジトリ構成
- docs/ai/ — エージェント向けコンテキスト（作業前に必ず読む）
- src/ — アプリケーションコード
- infra/ — インフラ設定（サニタイズ済み）
## 作業方法
- ビルド：<コマンド>
- テスト：<コマンド>
- Lint：<コマンド>
## ルール
- 複数ファイルを変更する前に、計画を提示すること。
- .env、*.pem、*.key、secrets/ を読み取り・出力・変更しないこと。
- 本番環境に対してコマンドを実行しないこと。
- 承認なしに依存関係を追加しないこと。
- 変更は小さく保ち、PRの説明に内容を記載すること。
## 人間にエスカレーションする場合
- 認証、決済、個人情報に関わる変更
- 手元にない権限や認証情報が必要なタスク
図2. エディタで表示した完成版の AGENTS.md（イメージ）
手順5.2：Claude Code と連携させる
ルートに CLAUDE.md を作成し、次の1行だけを記載します。
@AGENTS.md
Claude Code専用の指示がある場合は、この行の下に追記します。共通の内容はすべて AGENTS.md に残します。
手順5.3：コンテキスト文書を追加する
docs/ai/ フォルダを作成し、次の4つの短い文書を置きます。
-
CONTEXT.md：目的、担当者、環境 -
ARCHITECTURE.md：システムの全体構成 -
CONVENTIONS.md：命名、スタイル、ブランチ運用 -
SECURITY.md：何が機密で、なぜ機密なのか
エージェントがこのフォルダを読むよう、AGENTS.md から参照してください。
手順5.4：技術的な管理策を設定する
多くのチームが省略しがちですが、最も重要な手順です。第6章を参照してください。
手順5.5：各ツールで動作を確認する
チームで使う各ツールで新しいセッションを開き、「このリポジトリで与えられているルールを要約してください」と尋ねます。回答が AGENTS.md の内容を反映していなければ、設定は未完了です。次に、意図的に保護対象のファイルを読むよう指示し、ブロックされることを確認します。
図3. 保護対象ファイルの読み取りが拒否ルールによってブロックされる様子（イメージ）
手順5.6：維持・管理する
AGENTS.md はコードと同じように扱います。変更はプルリクエストを通し、チームリーダーがレビューします。エージェントが同じミスを繰り返す場合は、たいてい指示が不足しているサインなので、そのたびに見直してください。
6. セキュリティとデータプライバシーの管理策
マネージャーが最も注意を払うべき章です。AIコーディングエージェントはファイルを読み、コマンドを実行し、外部サービスに内容を送信します。そのひとつひとつが、データの取り扱いに関する判断です。
図4. データの境界。特定の種類のデータは決して境界を越えてはなりません（イメージ）
6.1 指示は「お願い」であり、「管理策」ではありません
AGENTS.md に「.env を読まないこと」と書いても、それはモデルが通常は従うガイドラインであり、保証ではありません。強制力はツール側の設定で持たせる必要があります。
Claude Codeでは、.claude/settings.json に拒否ルールを追加します。
{
"permissions": {
"deny": [
"Read(**/.env)",
"Read(**/.env.*)",
"Read(**/secrets/**)",
"Read(**/*.pem)",
"Read(**/*.key)"
]
}
}
GitHub Copilotには、ビジネス向けプランでリポジトリや組織単位のコンテンツ除外設定があります。Codexにはサンドボックスと承認モードがあり、Antigravityにも独自の権限設定があります。チームで使うすべてのツールで同等の管理策を設定してください。なお、.gitignore はセキュリティ境界ではありません。
6.2 シークレットはワークスペースに置かないでください
最も安全なシークレットは、エージェントが到達できないシークレットです。シークレット管理ツールやVaultを使い、本番環境の認証情報を開発者のローカル環境に置かないでください。
6.3 指示ファイルに機密情報を書かないでください
AGENTS.md と docs/ai/ フォルダはリポジトリにコミットされ、毎回のセッションでAIツールに送信されます。パスワード、社内IPアドレス、顧客名、個人情報を含めてはいけません。
6.4 承認済みのツールを、承認済みのプランで使ってください
個人向けプランと法人向けプランでは、データの保持期間、モデルの学習への利用、契約上の保護が異なることがよくあります。各ベンダーと法務部門に条件を確認し、会社のコードを個人アカウントで扱わせないでください。
6.5 操作には人間の承認を必須にしてください
コマンドの実行やファイルの編集の前に確認を求めるよう、エージェントを設定します。デプロイ、データベース、インフラに関わる操作は特に重要です。どのエージェントにも、本番環境への直接アクセスを与えてはいけません。
6.6 プロンプトインジェクションに注意してください
Webページ、Issueのコメント、外部のファイルなど、エージェントが読み込む内容には、隠れた指示が含まれている場合があります。エージェントがデータ内の指示に従わないようにし、不審な動作は人間が確認してください。
6.7 適用される法令を遵守してください
コードやデータに個人情報が含まれる場合、AIツールでの処理は自組織のプライバシーポリシーと適用法令に従う必要があります。日本の個人情報保護法、インドのデジタル個人データ保護法（2023年）、欧州のGDPRなどが該当します。
6.8 レビューと記録を徹底してください
エージェントが作成したすべての変更は、マージ前に人間がレビューします。ツールが利用ログや監査ログを提供している場合は、セキュリティ部門が定期的に確認します。
チームリーダー向けクイックチェックリスト
- 使用中のすべてのツールで、拒否ルールまたは除外ルールが設定されている
- リポジトリにもエージェントの実行環境にも、シークレットが存在しない
- 指示ファイルに機密情報が含まれていない
- 承認済みのツールとプランのみが使用されている
- エージェントはコマンド実行前に承認を求める設定になっている
- エージェントによる変更は、すべてマージ前にレビューされている
7. 付録A：チャット型ツールの場合
リポジトリにアクセスできないチャット型LLMを使う必要がある場合は、リポジトリを1つのテキストファイルにまとめることができます。このファイルには、ディレクトリツリー、コンテキスト文書、そしてタグで明確に区切った各ファイルの内容が含まれます。
以下のスクリプトはPythonの標準ライブラリのみでこれを行います（Python 3.7以上）。機密情報らしきファイルはデフォルトで除外し、除外したファイルの一覧も出力します。