컨텍스트 엔지니어링 실패모드 위키

OpenAI Codex — AGENTS.md 설정과 컨텍스트 관리

8 min read

상위: 08_00_MOC

OpenAI Codex — AGENTS.md 설정과 컨텍스트 관리

AGENTS.md: 다단계 우선순위 시스템

Codex는 CLAUDE.md에 대응하는 AGENTS.md를 사용한다. 계층 구조:

  1. ~/.codex/AGENTS.override.md — 전역 최우선
  2. ~/.codex/AGENTS.md — 전역 기본값
  3. Git 루트에서 현재 디렉터리까지 위계를 따라 탐색하며, 가까운 파일이 나중에 배치되어 우선 적용된다

“Codex builds an instruction chain when it starts (once per run; in the TUI this usually means once per launched session). Files concatenate from root downward, with closer directories overriding earlier guidance because they appear later.” — Custom instructions with AGENTS.md, OpenAI

크기 한도

기본 한도는 32KiB(project_doc_max_bytes)이며, 설정으로 최대 65,536바이트(64KiB)까지 조정할 수 있다.

“Codex skips empty files and stops adding files once the combined size reaches the limit.” — 동일 문서

빈 파일은 자동으로 건너뛰며, project_doc_fallback_filenames로 대체 파일명을 지정할 수 있다.

매 실행 재구성 — 캐시 부패 없음

CLAUDE.md와 가장 중요한 설계 차이:

“Codex rebuilds the instruction chain on every run (and at the start of each TUI session), so there is no cache to clear manually.” — Custom instructions with AGENTS.md, OpenAI

CLAUDE.md에서는 세션 도중의 편집이 즉시 반영되지 않는 점이 가장 흔한 함정이다. 반면 Codex AGENTS.md는 매 실행마다 새로 읽기 때문에 05 부패 부패가 구조적으로 덜 발생한다.

graph LR
  subgraph claude["Claude Code CLAUDE.md"]
    C1["세션 시작에 1회 로드"]
    C2["편집해도 현재 세션 미반영"]
    C3["/clear·/compact·재시작 필요"]
  end
  subgraph codex["Codex AGENTS.md"]
    D1["매 실행마다 재구성"]
    D2["편집 즉시 다음 실행에 반영"]
    D3["수동 캐시 클리어 불필요"]
  end
  C1 --> C2 --> C3
  D1 --> D2 --> D3
  style C2 fill:#fff3cd
  style D2 fill:#d4edda

Claude Code와 상호운용

Claude Code는 AGENTS.md를 직접 읽지 않는다. 병행 사용 시 공식 권장 방법:

# CLAUDE.md
@AGENTS.md
 
## Claude Code
Use plan mode for changes under `src/billing/`.

또는 심링크:

ln -s AGENTS.md CLAUDE.md

Windows에서는 심링크에 관리자 권한 또는 개발자 모드가 필요하므로 @AGENTS.md import 방식 권장.

/init을 실행하면 기존 AGENTS.md를 감지해 관련 부분을 CLAUDE.md에 통합한다.

피드백 루프 패턴

“When the agent makes incorrect assumptions about your codebase, correct them in AGENTS.md to establish a feedback loop that persists across sessions.” — Custom instructions with AGENTS.md, OpenAI

에이전트가 같은 가정을 반복해서 틀리면 AGENTS.md에 교정을 명시해 둔다. 이것이 03 혼란 실패모드를 해결하는 Codex의 표준 방법이다.

Codex Memories

“Memories are off by default. In the European Economic Area, the United Kingdom, and Switzerland, Codex uses or generates memories only after you enable them.” — Memories, OpenAI

저장 위치는 Codex 홈 디렉터리인 ~/.codex다.

보안 처리:

“Codex skips active or short-lived sessions, redacts secrets from generated memory fields, and updates memories in the background.” — 동일 문서

업데이트는 비동기로 이뤄진다. 스레드가 충분히 idle 상태가 된 뒤 백그라운드에서 반영하는데, 진행 중인 작업을 섣불리 요약하지 않으려는 안전장치다. rate-limit 잔여 비율이 임계값 아래로 떨어지면 백그라운드 패스를 건너뛸 수 있다.

Chronicle — 화면 컨텍스트 기반 메모리

⚠️ 가용성 주의: Chronicle은 ChatGPT Pro 구독자를 대상으로 한 macOS 전용 opt-in 연구 프리뷰(research preview)다. Codex CLI 일반 사용자나 API 사용자에게는 해당되지 않을 수 있다.

“Chronicle augments Codex memories with context from your screen. When you prompt Codex, those memories can help it understand what you’ve been working on with less need for you to restate context.” “Chronicle is in an opt-in research preview. It is only available for ChatGPT Pro subscribers on macOS.” — Chronicle, OpenAI

작동 방식은 이렇다. 백그라운드의 샌드박스 에이전트가 화면 이미지를 캡처해 메모리를 만든다. 캡처한 화면은 기기에 임시 저장한 뒤 서버에서 처리하고, 생성한 메모리는 기기에 로컬로 저장하며, 6시간이 지난 스크린샷은 자동으로 삭제한다.

공식 보안 경고:

“Chronicle uses rate limits quickly, increases risk of prompt injection, and stores memories unencrypted on your device.” — 동일 문서

회의나 기밀 화면이 노출될 때는 “Pause Chronicle”을 쓰는 편이 좋다. 화면 캡처를 통해 01 오염 오염과 프롬프트 인젝션 리스크가 확장되는 사례다.

OpenAI Responses API 서버사이드 컴팩션

Codex와 ChatGPT API 수준에서는 서버사이드 컴팩션을 제공한다.

response = client.responses.create(
  model="gpt-5.3-codex",
  input=conversation,
  store=False,
  context_management=[{"type": "compaction", "compact_threshold": 200000}],)

토큰 수가 compact_threshold를 넘으면 서버가 자동으로 컴팩션을 실행한다.

불투명성 문제도 있다.

“It is opaque and not intended to be human-interpretable.” — Compaction — OpenAI Responses API, OpenAI

반환된 compaction item은 암호화된 불투명 객체라 개발자가 무엇이 보존되고 무엇이 사라졌는지 검증할 수 없다. 05 부패 블랙박스 문제의 실제 사례다.

항목 제거 전략은 두 갈래다.

  • stateless 체이닝: compaction item 이전 항목을 제거할 수 있어 요청 크기와 지연을 줄인다
  • previous_response_id 체이닝: 수동 제거가 불가능하며 시스템이 관리한다

스탠드얼론 엔드포인트 client.responses.compact(...)는 ZDR(Zero Data Retention)을 지원하고 완전히 stateless하다.

Claude Code vs Codex 비교

항목Claude CodeCodex
지시 파일CLAUDE.mdAGENTS.md
로드 시점세션 시작 1회매 실행 재구성
편집 반영/clear·/compact·재시작 필요다음 실행 즉시 반영
크기 한도200줄 권장 (준수율)32KiB 기본 (설정 최대 64KiB)
지속 메모리Auto Memory (MEMORY.md)Memories (기본 비활성)
컴팩션/compact (클라이언트사이드)서버사이드 자동 또는 standalone
캐시 부패 리스크세션 중 편집 미반영매 실행 재구성으로 구조적 방지

참고문헌

관련 노트

그래프 뷰

백링크