AGENTS.mdを実務向けに設計する方法
導入：AGENTS.mdは「長い説明書」ではなく作業境界を伝える文書
AGENTS.mdは、Codexが作業を始める前に読むプロジェクト向けの指示書です。コーディング規約だけでなく、作業対象、検証方法、外部への書き込み、停止条件まで共有できます。
ただし、あらゆる注意を1ファイルへ詰め込むと、適用範囲や優先順位が分かりにくくなります。実務では「どこで有効か」「何を完了とするか」「何をしてはいけないか」を、確認可能な形で短く書くことが重要です。
結論：共通ルールと局所ルールを分け、検証可能な動詞で書く
実務向けのAGENTS.mdは、次の5点を押さえると運用しやすくなります。
- リポジトリ全体のルールはルートに置く
- 特定ディレクトリだけのルールは対象に近い場所へ置く
- 「適切に確認する」ではなく、実行するコマンドや合格条件を書く
- 外部書き込みや破壊的操作には対象、承認、停止条件を書く
- 秘密情報や環境固有の接続値は書かず、安全な参照方法だけを示す
OpenAIの公式ドキュメントによると、Codexはプロジェクトルートから現在の作業ディレクトリまで指示ファイルを探索し、ルート側から順に結合します。現在のディレクトリに近い指示ほど後に読み込まれるため、より具体的な指示として優先されます。この仕組みに合わせ、全社・リポジトリ共通事項と、サービス固有事項を分離します。
使い方：設計から確認までの手順
1. 作業を「読取・変更・検証・外部反映」に分ける
最初に、AIへ任せる作業を4種類に分けます。
- 読取：コード、設定、ログ、文書の確認
- 変更：ファイルの作成・編集
- 検証：テスト、lint、ビルド、差分確認
- 外部反映：push、デプロイ、チケット更新、メッセージ送信
とくに外部反映は、変更とは別の権限として扱います。「編集してよい」ことを「本番へ反映してよい」ことと同一視しないでください。
2. 適用範囲を決める
全ディレクトリに共通するルールだけをルートのAGENTS.mdへ置きます。特定サービスでテストコマンドや禁止事項が異なる場合は、そのサービスのディレクトリへAGENTS.mdまたはAGENTS.override.mdを置きます。
公式仕様では、各ディレクトリで AGENTS.override.md、AGENTS.md、設定済みの代替ファイル名の順に確認され、1ディレクトリにつき最大1ファイルが採用されます。overrideが存在するディレクトリでは通常のAGENTS.mdが併用されるわけではない点に注意が必要です。
3. 完了条件をコマンドと結果で書く
「十分にテストする」では、実行者ごとに判断が変わります。次のように具体化します。
- 変更後に
npm testを実行し、終了コード0を確認する - API仕様を変更した場合は
docs/api.mdも更新する - テストが3回連続で同じ外部サービス障害により失敗したら、変更を増やさず失敗内容を報告する
コマンドだけでなく、失敗時に再試行するのか、停止するのかも決めておくと、無制限な試行を防げます。
4. 外部副作用と停止条件を書く
外部サービスへ作用する処理は、対象と許可された手段を限定します。たとえば「指定されたブランチへの通常pushだけを許可し、force pushは禁止」「デプロイは承認済みwrapperだけを使う」のように記述します。
次の場合は停止して報告する、と明記しておくと安全です。
- 対象リポジトリや環境を一意に確認できない
- 検証が失敗した
- 既存の未コミット変更と競合する
- 秘密情報または個人情報を扱う必要が生じた
- 指示された手段が利用できず、別経路が必要になる
5. 読み込まれた指示を確認する
作成後は、Codexに有効な指示元と内容の要約を尋ねます。ルートとサブディレクトリの両方から起動し、期待した順序で読み込まれるかを確認します。公式ドキュメントでも、リポジトリルートと対象サブディレクトリで有効な指示ファイルを確認する方法が案内されています。
テンプレート
以下は、値をそのまま流用するのではなく、対象プロジェクトに合わせて埋めるためのひな型です。
# Project Instructions
## Scope
- Work only in: <対象ディレクトリ>
- Preserve unrelated existing changes.
## Allowed work
- Read files needed for the requested task.
- Edit files only within the stated scope.
- Run the following verification commands:
- `<test command>`
- `<lint command>`
## Completion criteria
- Requested behavior is implemented.
- Required tests pass with exit code 0.
- Changed documentation matches the implementation.
- Final report lists changed files and verification results.
## External side effects
- Do not deploy, push, publish, or message external services unless the task explicitly requests it.
- If external reflection is authorized, use only `<approved wrapper or workflow>`.
## Stop conditions
- Stop and report if the target cannot be identified safely.
- Stop and report if required verification fails after the documented checks.
- Stop and report before handling credentials, personal data, or production secrets.
## Security
- Never place credentials, private keys, tokens, or real connection values in source files, examples, logs, or reports.
- Refer to secret names or approved secret-management procedures only.「失敗したら適切に対応する」のような曖昧な表現は避け、失敗の判定と、その後に許される行動をセットで書きます。
適用例：Webアプリのリポジトリ
たとえば、ルートにフロントエンドとAPIが同居する構成を考えます。
repository/
├── AGENTS.md
├── frontend/
│ └── AGENTS.md
└── services/
└── api/
└── AGENTS.override.mdルートには、作業可能範囲、秘密情報の扱い、共通の最終報告形式を書きます。frontend/AGENTS.md にはUIテストとアクセシビリティ確認を、services/api/AGENTS.override.md にはAPI専用のテスト、マイグレーション禁止、本番DBへ接続しないことを書きます。
この分け方なら、API作業にだけ必要な注意を全作業へ重複させず、対象に近い場所で具体化できます。ただしoverrideは同じディレクトリの通常ファイルより優先されるため、置き換えた結果、必要な局所ルールが抜けていないか確認してください。
注意点
AGENTS.mdだけをセキュリティ対策にしない
AGENTS.mdは行動を伝える仕組みであり、OS権限、sandbox、ネットワーク制御、リポジトリ保護、バックアップの代わりではありません。重要な制約は、技術的な権限制御と検証工程でも実施します。
CIで判定できる規則を重複させすぎない
フォーマットやlintの詳細を長く列挙するより、正規のコマンドを示し、詳細は設定ファイルとCIを基準にします。公式ドキュメントも、レビュー規則は簡潔にし、フォーマットやlintの確認はCIへ任せる考え方を示しています。
秘密情報と環境固有値を書かない
実在するホスト名、ユーザー名、秘密鍵、トークン、パスフレーズをテンプレートへ載せてはいけません。「環境変数 SERVICE_TOKEN を承認済みの秘密管理から供給する」のように、名前と手順だけを示します。ログや最終報告にも値を出さないことを明記します。
人の確認やロールバックを省略しない
料金、法務、個人情報、本番データ、公開コンテンツなど影響の大きい変更は、人の確認を完了条件へ含めます。バックアップ、段階的反映、ロールバック手順も、対象システムの運用設計として別途用意してください。
公式・一次情報
公式のPromptingガイドでは、重要な依頼に「目的」「文脈」「出力」「境界」を含める考え方が示されています。AGENTS.mdでも同じ観点を使うと、成果物と禁止事項を混同せず整理できます。
関連記事
AIやITを業務へ導入する際は、指示書だけでなく、権限、検証、担当者の確認を含む運用全体を設計する必要があります。課題整理から運用設計までの支援内容は、IT・業務改善支援をご覧ください。
