Codex AGENTS

• AGENTS.md는 OpenAI Codex CLI가 작업 수행 전 읽는 영속적 지시(instruction) 파일
• 글로벌 가이드라인과 프로젝트별 오버라이드를 **계층적으로 병합(merge)**하는 구조
• ~/.codex/AGENTS.md(글로벌)부터 프로젝트 하위 디렉토리까지 **루트→리프 순서로 연결(concatenate)**되는 메커니즘
• Claude Code의 CLAUDE.md에 대응하는 OpenAI Codex의 프로젝트 컨텍스트 시스템

해당 개념이 필요한 이유

• 여러 레포지토리에서 일관된 코딩 규칙을 유지해야 할 때
• 프로젝트/디렉토리별로 다른 규칙을 계층적으로 적용해야 할 때
• Codex SDK를 서비스에 통합할 때 instruction 주입 방식을 이해해야 할 때

AS-IS

sequenceDiagram
    autonumber
    participant Dev as 개발자
    participant Codex as Codex CLI
    Dev->>Codex: 작업 요청
    Note over Codex: 지시사항 없음
    Codex->>Codex: 기본 동작만 수행
    Codex-->>Dev: 일관성 없는 결과

TO-BE

sequenceDiagram
    autonumber
    participant Dev as 개발자
    participant Codex as Codex CLI
    participant Global as ~/.codex/AGENTS.md
    participant Project as {cwd}/AGENTS.md
    participant Sub as {cwd}/sub/AGENTS.md
    Dev->>Codex: 작업 요청
    Codex->>Global: 1) 글로벌 지시 로드
    Codex->>Project: 2) 프로젝트 지시 로드
    Codex->>Sub: 3) 하위 디렉토리 지시 로드
    Note over Codex: 1+2+3 연결(concatenate)
    Codex-->>Dev: 일관된 규칙 기반 결과

파일 탐색(Discovery) 순서

디렉토리별 탐색 우선순위

각 디렉토리에서 최대 1개 파일만 선택된다:

우선순위	파일명	설명
1	AGENTS.override.md	임시 오버라이드용
2	AGENTS.md	기본 지시 파일
3	project_doc_fallback_filenames에 등록된 파일	커스텀 대체 파일

전체 병합 순서

flowchart LR
    A("1 글로벌: ~/.codex/AGENTS.md") -->|concat| B("2 프로젝트: root/AGENTS.md") -->|concat| C("3 하위: subdir/AGENTS.md")

“Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt.”

핵심: 나중에 등장하는 파일이 더 높은 우선도를 가진다. 이는 LLM의 프롬프트 특성상 나중에 나오는 지시가 앞선 지시를 덮어쓰기 때문이다.

병합(Merge) 메커니즘 상세

동작 방식

1. .git이 있는 디렉토리를 프로젝트 루트로 인식
2. 글로벌(~/.codex/) → 프로젝트 루트 → 현재 디렉토리까지 트리를 내려가며 수집
3. 수집된 파일을 빈 줄로 구분하여 연결(concatenate)
4. 합산 크기가 project_doc_max_bytes(기본 32 KiB)에 도달하면 중단

글로벌 AGENTS.md 로드 원리

글로벌 ~/.codex/AGENTS.md는 환경변수나 CWD와 무관하게, Codex의 빌트인 config_loader가 자동 로드한다.

// codex-rs/core/src/config_loader — Codex 내부 초기화
let layers = load_config_layers_state(
    &codex_home,    // ← ~/.codex/ (항상 고정, 환경변수와 무관)
    Some(cwd),      // ← thread/start에서 전달한 cwd
    &cli_overrides,
    LoaderOverrides::default(),
    None,
).await?;

• codex_home은 항상 ~/.codex/로 고정 — 스폰 시 설정한 커스텀 환경변수와 별개 메커니즘
• CWD가 git repo가 아니어도 글로벌 AGENTS.md는 로드됨 (~/.codex/ 자체가 git repo가 아닌 것이 그 증거)
• model_instructions_file 설정과 무관하게 글로벌/프로젝트 AGENTS.md는 항상 로드됨 (아래 소스 코드 기반 분석 참조)

예시: 3개 레벨 병합

# 실제 Codex가 받는 combined prompt:

[~/.codex/AGENTS.md 내용]       ← 글로벌 규칙

[{root}/AGENTS.md 내용]         ← 프로젝트 규칙 (글로벌 규칙 덮어쓰기 가능)

[{root}/services/AGENTS.md 내용] ← 서비스 규칙 (프로젝트 규칙 덮어쓰기 가능)

AGENTS.override.md

• 어느 디렉토리에든 AGENTS.override.md를 두면 같은 디렉토리의 AGENTS.md보다 우선 적용
• 용도: 임시 오버라이드 — 기존 AGENTS.md를 삭제하지 않고 규칙을 바꿀 때
• 오버라이드 파일을 삭제하면 원래 AGENTS.md로 자동 복원

# services/payments/AGENTS.override.md
 
## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

Codex 내부 Instruction 구조 (소스 코드 기반)

Codex 소스 코드(codex-rs) 분석 결과, 내부에는 3개의 독립적인 instruction 경로가 존재한다.

내부 Instruction 전체 맵

내부 값	의미	기본값 (default)	model_instructions_file 영향	로드 출처	적용 방법 (코드)	API role	소스 코드 근거
base_instructions	모델의 핵심 행동 규칙 — “너는 Codex라는 AI야”. AGENTS.md 스펙, 도구 사용법, 샌드박스 규칙 등 모델의 최상위 지시	OpenAI 서버에서 모델별 빌트인 프롬프트 (instructions_template)	이 값만 대체됨 — 파일 내용이 빌트인 대신 사용	model_info.get_model_instructions()	파일: config.toml에 model_instructions_file = "경로", 코드: config에 model_instructions_file 키 추가	instructions (system)	config/mod.rs:2433-2442, codex.rs:553-562, openai_models.rs:316
developer_instructions	서비스 운영자의 비공개 지시 — API 호출 서비스가 설정. 사용자에게 노출 안 됨, override 불가. 런타임에 sandbox policy·skills·plugins 등이 developer_sections로 함께 합산	None. sandbox policy·skills·plugins 등은 Codex가 자동 추가	영향 없음	config.toml의 developer_instructions 필드 (string, 파일경로 아님)	코드로 설정: config에 developer_instructions: "내용" 키 추가 → --config developer_instructions="..." 전달	developer role msg	config/mod.rs:1179-1181, config/mod.rs:2443, codex.rs:3494-3497, updates.rs:161-162
user_instructions	최종 사용자의 커스텀 지시 — 사용자가 AGENTS.md에 직접 작성. 프로젝트 규칙, 코딩 컨벤션, 선호 기술 스택. 사용자가 직접 제어 가능	~/.codex/AGENTS.md(글로벌) + {cwd}/AGENTS.md(프로젝트) 자동 병합, --- project-doc --- 구분자로 연결	영향 없음	① load_instructions(codex_home) → 글로벌 ② read_project_docs() → 프로젝트	파일 배치만으로 자동: ~/.codex/AGENTS.md 또는 {cwd}/AGENTS.md 생성	user role msg	config/mod.rs:2033, config/mod.rs:2769-2782, project_doc.rs:79-119, project_doc.rs:128-178, updates.rs:165-166

최종 프롬프트 구조 (API 호출 기준)

 ┌─ instructions (system) ──────────────────────────────────┐
 │  base_instructions                                       │
 │  ← model_instructions_file 설정 시 대체                     │
 │  ← 미설정 시: 서버 빌트인 프롬프트 (모델별)                       │
 └──────────────────────────────────────────────────────────┘
                            ↓
 ┌─ developer role message ─────────────────────────────────┐
 │  sandbox policy + approval policy                        │
 │  developer_instructions (config 설정 값)                   │
 │  memory tool instructions                                │
 │  personality, skills, plugins ...                        │
 └──────────────────────────────────────────────────────────┘
                            ↓
 ┌─ user role message (contextual) ─────────────────────────┐
 │  user_instructions:                                      │
 │    ├─ ~/.codex/AGENTS.md (글로벌)                          │
 │    ├─ --- project-doc ---                                │
 │    └─ {cwd}/AGENTS.md (프로젝트 병합)                       │
 │  environment context (cwd, os, shell ...)                │
 └──────────────────────────────────────────────────────────┘

model_instructions_file의 정확한 역할 (공식문서 vs 소스코드)

공식 문서 정의:

“Replacement for built-in instructions instead of AGENTS.md.” — Configuration Reference, model_instructions_file 항목

이 문장의 올바른 해석 (소스 코드 기반):

• “AGENTS.md를 대체한다” (X)
• “AGENTS.md가 아닌, 빌트인 지시사항을 대체하는 파일” (O)

소스 코드 근거 — model_instructions_file은 base_instructions에만 매핑:

// config/mod.rs:2433-2442
// Load base instructions override from a file if specified.
let model_instructions_path = config_profile
    .model_instructions_file.as_ref()
    .or(cfg.model_instructions_file.as_ref());
let file_base_instructions =
    Self::try_read_non_empty_file(model_instructions_path, ...)?;
let base_instructions = base_instructions.or(file_base_instructions);
//  ^^^^^^^^^^^^^^^^     ← base_instructions에만 매핑

AGENTS.md를 로드하는 get_user_instructions() (project_doc.rs:79-119)에는 model_instructions_file에 대한 참조가 전혀 없음.

FAQ

Q. developer_instructions에 설정하면 사용자가 물어봐도 내용을 답하지 않는가?

맞다. OpenAI API의 developer role 스펙에 의해 모델은 developer 메시지 내용을 사용자에게 공개하지 않도록 훈련되어 있다. “시스템 프롬프트 보여줘”라고 물어도 모델이 거부한다. 단, 이것은 모델 행동 레벨의 보호이지 암호화 같은 하드 보안은 아님.

코드 근거 — developer role로 전송:

// updates.rs:161-162
pub fn build_developer_update_item(text_sections: Vec<String>) -> Option<ResponseItem> {
    build_text_message("developer", text_sections)  // ← developer role
}

반면 user_instructions(AGENTS.md)는 user role로 전송되므로 사용자가 내용을 물어보면 답할 수 있다:

// updates.rs:165-166
pub fn build_contextual_user_message(text_sections: Vec<String>) -> Option<ResponseItem> {
    build_text_message("user", text_sections)  // ← user role
}

Q. developer_instructions는 파일이 아닌 코드로 설정하는 것인가?

맞다. developer_instructions는 string 타입이며 파일 경로가 아니다.

// config.schema.json
"developer_instructions": {
  "default": null,
  "description": "Developer instructions inserted as a `developer` role message.",
  "type": "string"    // ← 파일 경로가 아닌 문자열
}

SDK/app-server 통합 시 config override로 설정:

// Codex SDK 또는 app-server config override
const config = {
  sandbox_mode: "workspace-write",
  developer_instructions: "서비스 비공개 지시사항 내용...",
  // → --config developer_instructions="..." 로 전달됨
};

Q. developer_instructions vs user_instructions의 차이는?

OpenAI API의 message role 스펙 기반:

우선순위: system(base) > developer > user

developer = "서비스를 만든 개발자"의 지시
 → 사용자가 볼 수 없고, override 불가
 → e.g. 서비스가 "항상 한국어로 답변" 설정

user = "서비스를 사용하는 최종 사용자"의 지시
 → 사용자가 AGENTS.md로 직접 제어
 → e.g. 사용자가 "TypeScript 선호, 커밋 한글" 설정

서비스의 지시사항은 developer_instructions에, 사용자 커스텀은 AGENTS.md(user_instructions)에 넣는 것이 의미적으로 정확하다.

config.toml 주요 설정

# AGENTS.md 관련 설정
project_doc_max_bytes = 32768                              # 기본 32 KiB
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]  # 대체 파일명
model_instructions_file = "/path/to/instructions.md"       # AGENTS.md 전면 대체
 
# 기타 주요 설정
model = "gpt-5-codex"
sandbox_mode = "workspace-write"     # read-only | workspace-write | danger-full-access
approval_policy = "on-request"       # untrusted | on-request | never

Claude Code의 CLAUDE.md와 비교

항목	Codex AGENTS.md	Claude Code CLAUDE.md
글로벌 경로	~/.codex/AGENTS.md	~/.claude/CLAUDE.md
프로젝트 경로	{cwd}/AGENTS.md	{cwd}/CLAUDE.md
병합 방식	루트→리프 concatenate	루트→리프 concatenate
오버라이드 파일	AGENTS.override.md	없음 (단일 파일)
대체 설정	model_instructions_file	없음
크기 제한	project_doc_max_bytes (32 KiB)	자동 관리
fallback 파일	project_doc_fallback_filenames	없음

참고 문서

• Custom instructions with AGENTS.md – Codex (OpenAI)
• Configuration Reference – Codex (OpenAI)
• Command line options – Codex CLI (OpenAI)