AGENTS.mdの書き方：Codexにプロジェクトの規則を伝える

要約： AGENTS.mdにはプロジェクトで繰り返し必要な作業規則を書きます。インストールコマンド、検証方法、変更境界を簡潔に残し、現在のコードに合うか管理してください。

1. AGENTS.mdが必要になる場面

Codexへ依頼するたび「このリポジトリはnpm以外のパッケージマネージャーを使う」「生成ファイルは直接変更しない」を繰り返すなら、プロジェクト指示ファイルが有用です。AGENTS.mdは作業の約束をプロジェクトと一緒に管理する文書と考えると分かりやすくなります。

OpenAIの公式文書はCodexが開始時にAGENTS.mdを読み、グローバル指示とプロジェクト指示を組み合わせると説明します。この記事の例は架空のリポジトリの草案です。実際にコマンドを確認せず、そのまま入れないでください。

2. 最初はルートの短いファイルから始める

最初のファイルは初めてリポジトリに入るチームメンバーに必要な案内を基準にしてください。ソースのフォルダー、実行コマンド、修正後の確認を書けば十分です。使わないコマンドや長く未更新の説明は、作業を誤った方向へ送ることがあります。

# 프로젝트 작업 규칙

## 구조
- 화면 코드는 src/ui, 데이터 처리 코드는 src/data에 있습니다.
- generated 폴더의 산출물은 직접 편집하지 마세요.

## 변경 기준
- 기존 공개 함수의 입력과 반환 형식을 유지하세요.
- 요청과 관계없는 파일은 수정하지 마세요.
- 다른 작업자의 변경을 덮어쓰지 마세요.

## 검증
- package.json에서 현재 테스트 명령을 확인해 실행하세요.
- 실행 명령, 결과, 실행하지 못한 이유를 구분해 보고하세요.

コマンドが確実なら「確認して実行」を実際のコマンドに置き換えられます。不明なら任意のnpm testを固定するより設定から探すよう書く方がよいでしょう。規則は立派な宣言より実行可能な案内である必要があります。

3. 下位フォルダーの規則は必要時だけ分ける

公式文書によると、ルートから現在の作業ディレクトリまでの経路の指示を集め、近いディレクトリの指示を後から反映します。各ディレクトリではAGENTS.override.md、AGENTS.mdなどの探索優先順位が適用されます。複数ファイルがあるなら実際の開始位置が重要です。

小さなリポジトリならルートの一ファイルで十分な場合があります。画面とサーバーに異なる検証手順があるなら各領域の個別指示を検討してください。共通規則を下位へコピーすると後で内容が分かれがちです。共通はルート、領域ごとの必須の差だけを下位に残す構成が管理しやすくなります。

4. 記述後は適用内容を確認する

作成で終わらず新作業で読み込む規則を確認してください。次は実行を制限して内容を点検する依頼例です。実作業を任せる前に文書の誤りを見つける用途に使えます。

현재 작업 디렉터리에 적용되는 AGENTS.md 지침을 요약해 주세요.
적용 파일의 경로와 검증 명령을 알려 주세요.
서로 충돌하거나 실행할 수 없는 지침이 있으면 설명해 주세요.
이 요청에서는 파일을 수정하거나 설치하지 마세요.

意図したファイルが回答に抜けたら、作業ディレクトリとファイル名から確認します。変更が未反映に見えたら新セッションで再確認してください。公式文書は実行開始時に指示を構成すると説明するため、既存セッションがいつ更新するか推測するより再確認が明確です。

5. よく失敗する規則と直し方

• 「常に最高品質」など抽象的な規則： 公開API維持、検証コマンドなど確認可能な条件へ変えます。
• 存在しないテストコマンド： 現設定に合わせるか探す場所を案内します。
• 全作業への長い手順の強制： 必須段階と条件付き段階を分けます。
• 互いに矛盾するファイル： 共通規則を整理し、下位領域の例外を明記します。

パスワードやトークンを作業指示に書かないでください。共有リポジトリの文書なら秘密の値より、必要な環境変数名と設定の確認場所を案内する方がよいでしょう。指示変更もコードと同じように差分を読むと、古いコマンドや不要な例外を見つけやすくなります。

6. 実際のコマンドがある架空リポジトリで書く

次はJavaScriptの架空プロジェクトの記述例で、実行結果ではありません。READMEとpackage.jsonから開発サーバー・検証コマンドを探したと仮定します。架空のscriptsにはdev、test、lintがあり、文書で使えます。実際に存在しない名前を入れると指示が逆に実行を妨げます。

{
  "scripts": {
    "dev": "vite",
    "test": "vitest run",
    "lint": "eslint src"
  }
}

このscripts自体をプロジェクトに上書きする意味ではありません。ツールが異なれば既存コマンドを書いてください。lockファイルとREADMEでパッケージマネージャーを定め、テストが特定サービスや環境変数に依存するなら条件も残します。「テスト実行」より「どこで何を実行し、何を準備するか」が作業者に有用です。

# AGENTS.md

## 프로젝트 구조
- src/ui: 사용자 화면, src/data: 데이터 처리
- tests: 기능 검증, public: 정적 파일
- dist는 생성 산출물이므로 소스를 먼저 수정합니다.

## 실행과 검증
- 저장소 루트에서 npm run dev로 개발 서버를 실행합니다.
- 동작을 바꾸면 관련 사례를 npm test로 확인합니다.
- JavaScript 소스를 바꾸면 npm run lint도 확인합니다.
- 실행에 필요한 조건이 없으면 실패 원인을 보고합니다.
  테스트를 건너뛰고 통과했다고 표현하지 않습니다.

## 변경 기준
- 저장된 데이터 형식은 이번 요청에 포함될 때만 변경합니다.
- 기존 사용자의 정상 입력 동작을 유지합니다.
- 다른 작업자의 변경과 생성 산출물을 덮어쓰지 않습니다.

## 보고 형식
- 변경한 동작과 파일, 실제 실행한 검증, 남은 확인을 설명합니다.

こう書くと正常な作業経路が先に見えます。禁止文だけの長い文書より次の実行コマンドを探しやすくなります。検証のない文言修正にも全段階が必要かはプロジェクトの基準で調節してください。目的は手順の増加ではなく反復作業の混乱削減です。

7. ルートと下位フォルダーに何を分けて書くか？

画面とサーバーがあるリポジトリを考えます。以下は経路別指示の配置例です。ルートにはデータ形式の保全や報告方法の共通約束、サーバーフォルダーには固有の実行条件を置きます。同じ規則を三ファイルにコピーするより、適用範囲を一か所で読める構成が保守に有利です。

project/
  AGENTS.md
  frontend/
    AGENTS.md
  services/
    api/
      AGENTS.override.md

公式の探索はルートから現在ディレクトリまでの経路が基準です。ルート開始で全下位指示が一括統合されると理解しないでください。apiから開始するなら経路の指示を確認し、ルートから複数領域を任せるなら必要な下位指示を読むよう明示できます。実セッションのパスと内容による適用確認が正確です。

同じフォルダーにAGENTS.override.mdとAGENTS.mdがあっても両内容が自動統合されると期待してはいけません。公式の優先順位はoverrideを先に確認し、ディレクトリごとに最大一指示を使います。一時例外で元文書が読まれなくなることを避けるには目的と除去時点を記録してください。継続使用するなら通常指示に整理する方がよいでしょう。

# services/api/AGENTS.override.md

## API 영역의 추가 기준
- 저장소 루트의 공통 변경 기준을 유지합니다.
- API 검증은 이 영역의 README에 적힌 절차를 따릅니다.
- 데이터베이스가 필요한 검증은 연결 대상과 준비 상태를 먼저 확인합니다.
- 테스트용 데이터 변경과 운영 데이터 변경을 구분합니다.
- 데이터 형식 변경은 영향과 이전 버전 호환 여부를 보고합니다.

8. 誤読時はパスから調査する

未適用に見えたら文を強める前に実ファイルと開始位置を確認してください。Windowsで拡張子が非表示ならAGENTS.md.txtが画面でAGENTS.mdに見える場合があります。エクスプローラーで拡張子を表示するか下の名前照会で確認できます。次のコマンドは名前と現在位置を読む例です。

Get-Location
Get-ChildItem -Name AGENTS*
Get-Content -LiteralPath .\AGENTS.md

1. 現在ディレクトリが意図したプロジェクトか見ます。別コピーなら該当プロジェクトへ移動します。
2. 名前が正しく内容が空でないか確認します。誤った拡張子はエディターで直します。
3. 同じパスや上位にoverrideがあるか調べ、想定外の規則の出所を探します。
4. 新セッションで適用ファイルパスとコマンドを要約させます。以前の回答だけで新ファイルが適用されたと判断しません。

グローバルとプロジェクトの規則の混在も確認してください。全リポジトリにnpm testを要求するグローバル指示はPythonに合わない場合があります。韓国語の説明や実行・未実行を分ける報告の好みはグローバルに置けても、特定コマンドは該当リポジトリが自然です。Codexのホームを別設定した場合、既定位置を変えても別設定を読む可能性があります。

9. 古い規則を減らす改訂チェックリスト

指示もプロジェクトの変化で更新が必要です。テストツールの変更やソース移動では関連コマンドとパスも直してください。機能変更の際、古いコマンドの迂回方法だけを会話に残すと次回同じ問題が繰り返します。下のプロンプトで文書と現設定の差から調べられます。

AGENTS.md의 경로와 실행 명령을 현재 저장소와 비교해 주세요.
존재하지 않는 파일·스크립트·생성 경로를 찾아 주세요.
항목별로 현재 근거 파일과 수정 제안을 표로 정리해 주세요.
새 규칙을 임의로 늘리지 말고 오래된 규칙의 갱신부터 제안하세요.
이 단계에서는 문서를 수정하거나 의존성을 설치하지 마세요.

結果では三種類を分けてください。実行コマンドが消えたなら実エラーを直す改訂、新ツール導入案は別の選択です。「常に全テスト」を関連テストと必須検査へ分けるのは作業基準の調整です。区別すると単純な更新が突然ツール置換や大規模な構造変更へ広がるのを減らせます。

• パスとコマンドは現リポジトリに存在するか？
• 条件付き作業と毎回の作業が分かれているか？
• 一機能の一時要件を永続規則にしていないか？
• 失敗・未実行時に次の行動が分かるか？
• 秘密の値より環境変数名と準備方法を案内するか？

よいAGENTS.mdは新しい担当者が一ファイルを読んで正常作業を始められる文書です。規則を長く集めるより、よく誤る選択と実行手順を残してください。反復する複雑な業務手順が必要なら、全てルートへ入れるより個別スキルや参考文書への分割も検討できます。

10. よくある質問

AGENTS.mdとREADMEは同じですか？ READMEは人への紹介によく使い、AGENTS.mdはエージェントの作業指示を整理します。同じ説明を長く複製するより必要文書を参照させられます。

規則は多いほどよいですか？ 適用可能で現在必要な規則が重要です。重複・矛盾する文を減らしてください。

指示で実行権限も変わりますか？ 作業方法の案内と実際の権限設定は別です。ファイルに許可と書いただけでツールの境界は自動拡大しません。

公式の出典と確認日： OpenAI公式文書：AGENTS.mdによるカスタム指示。2026年10月3日確認。例のパスとコマンドは自分のプロジェクトに合わせて調整してください。