이 페이지의 목차
확인 2026-10-16근거 자료 4건갱신 2026-10-26언급 10곳
이 페이지의 목차

OpenAI의 LLM 에이전트다. 이 페이지는 활용법을 모은다. Karpathy LLM Wiki

확인 날짜 안내

확인 날짜가 섞인 페이지다. Karpathy 원본은 날짜 미상이라 수집일(2026-10-16)을, Codex 공식 문서 Codex AGENTS.md 가이드와 Claude Code 메모리 문서 부분은 각각 수집일(2026-10-18)을 확인 날짜로 둔다(둘 다 원본 날짜 미상).

지시 파일 AGENTS.md (2026-10-18 기준)#

Codex는 작업을 하기 전에 AGENTS.md(용어 사전) 파일을 읽는다. 전역 지시에 프로젝트별 override를 겹쳐 두면 어느 저장소를 열든 같은 기대치로 작업을 시작한다. Codex AGENTS.md 가이드

탐색 순서#

Codex는 시작할 때 지시 체인을 만든다. 실행마다 한 번이고, TUI에서는 보통 띄운 세션마다 한 번이다. 우선순위는 다음 순서다. Codex AGENTS.md 가이드

  1. 전역: Codex 홈 디렉터리(기본 ~/.codex, CODEX_HOME을 설정하면 그 위치)에서 AGENTS.override.md가 있으면 그것을, 없으면 AGENTS.md를 읽는다. 이 층에서는 비어 있지 않은 첫 파일 하나만 쓴다.
  2. 프로젝트: 프로젝트 루트(보통 Git 루트)에서 시작해 현재 작업 디렉터리까지 내려간다. 프로젝트 루트를 못 찾으면 현재 디렉터리만 확인한다. 경로의 디렉터리마다 AGENTS.override.md, AGENTS.md, project_doc_fallback_filenames에 적은 이름 순으로 확인하고, 디렉터리당 최대 한 파일만 넣는다.
  3. 합치기: 루트에서 아래로 빈 줄을 끼워 이어 붙인다. 현재 디렉터리에 가까운 파일이 합친 프롬프트에서 뒤에 오므로 앞선 지시를 override한다.

근거: Codex AGENTS.md 가이드

크기 한도#

합친 크기가 project_doc_max_bytes(기본 32 KiB)에 닿으면 파일을 더 넣지 않는다. 한도에 걸리면 한도를 올리거나 지시를 하위 디렉터리로 나눈다. Codex AGENTS.md 가이드

toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

원본 설정 예다. 이렇게 두면 디렉터리마다 AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md 순으로 확인하고, 목록에 없는 파일 이름은 지시 탐색에서 무시한다. 한도를 키우면 잘리기 전에 더 많은 지시를 합칠 수 있다. 설정을 바꾼 뒤에는 Codex를 다시 시작하거나 새 명령을 실행해야 적용된다. Codex AGENTS.md 가이드

override 파일 쓰는 법#

  • 전역: 기본 파일을 지우지 않고 잠시 다른 전역 지시를 쓰고 싶으면 ~/.codex/AGENTS.override.md를 만든다. 지우면 공유 지시로 돌아간다. Codex AGENTS.md 가이드
  • 하위 디렉터리: 특정 팀에 다른 규칙이 필요하면 그 디렉터리에 AGENTS.override.md를 둔다. 원본 예는 services/payments/AGENTS.override.md에 "npm test 대신 make test-payments를 써라", "보안 채널에 알리지 않고 API 키를 교체하지 마라"를 적는 것이다. 같은 디렉터리에 AGENTS.md가 있어도 override가 있으면 무시된다. Codex AGENTS.md 가이드
  • 이 상태로 codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."를 실행하면 원본이 기대하는 출력은 전역 파일, 저장소 루트 AGENTS.md, payments override 순이다. Codex AGENTS.md 가이드

전역·프로젝트 지시 만들기#

bash
mkdir -p ~/.codex
md
# ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

전역 파일은 모든 저장소가 물려받는 기본 작업 약속이다. 저장소 루트에는 기본 설정을 다루는 AGENTS.md를 두고(원본 예: PR 전에 npm run lint, 동작을 바꾸면 docs/에 공개 유틸리티 문서화), 특정 팀이 다른 규칙을 쓰는 하위 디렉터리에 override를 더한다. Codex AGENTS.md 가이드

코드 리뷰 규칙#

GitHub에서 Codex 코드 리뷰를 쓸 때는 규칙이 적용될 코드에 가장 가까운 AGENTS.md에 ## Code Review Rules 절을 둔다. 저장소 전체 점검은 루트에, 서비스별 점검은 하위 파일에 둔다. 원본은 규칙을 짧게 쓰고, 잡아낼 동작과 안전한 경로·예외를 설명하며, 포맷·린트 점검은 CI에 맡기라고 한다. Codex AGENTS.md 가이드

다른 프로필로 실행하기#

자동화 전용 사용자처럼 다른 프로필이 필요하면 CODEX_HOME을 설정한다. CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"를 실행하면 원본이 기대하는 출력은 그 .codex 디렉터리 기준 파일 목록이다. Codex AGENTS.md 가이드

확인하기#

  • 저장소 루트에서 codex --ask-for-approval never "Summarize the current instructions."를 실행한다. 원본은 Codex가 전역·프로젝트 파일의 지시를 우선순위 순으로 되풀이해야 한다고 한다. Codex AGENTS.md 가이드
  • codex --cd subdir --ask-for-approval never "Show which instruction files are active."로 하위 override가 넓은 규칙을 대체하는지 본다. Codex AGENTS.md 가이드
  • 어떤 파일이 로드됐는지 감사하려면 codex -c log_dir=./.codex-log로 평문 TUI 로그를 켜고 ./.codex-log/codex-tui.log를 보거나, 세션 로깅을 켰다면 가장 최근 session-*.jsonl을 본다. Codex AGENTS.md 가이드
  • 지시가 낡아 보이면 대상 디렉터리에서 Codex를 다시 시작한다. 체인은 실행마다(TUI는 세션 시작마다) 다시 만들므로 손으로 지울 캐시는 없다. Codex AGENTS.md 가이드

문제 해결#

증상확인할 것
아무것도 로드되지 않는다의도한 저장소인지, codex status가 기대한 워크스페이스 루트를 보고하는지 본다. 지시 파일에 내용이 있는지 확인한다(빈 파일은 무시)
엉뚱한 지시가 나온다디렉터리 트리 위쪽이나 Codex 홈에 AGENTS.override.md가 있는지 찾는다. 이름을 바꾸거나 지우면 일반 파일로 돌아간다
대체 파일 이름을 무시한다project_doc_fallback_filenames에 오타 없이 적었는지 확인하고 Codex를 다시 시작한다
지시가 잘린다project_doc_max_bytes를 올리거나 큰 파일을 하위 디렉터리로 나눠 중요한 지시를 지킨다
프로필이 헷갈린다실행 전에 echo $CODEX_HOME을 본다. 기본값이 아니면 편집한 곳과 다른 홈 디렉터리를 가리킨다

근거: Codex AGENTS.md 가이드

Claude Code와 함께 쓰기#

  • (2026-10-18 기준) Claude Code 공식 문서에 따르면 Claude Code는 AGENTS.md를 프로젝트 지시로 읽을 수 있어서, 다른 코딩 에이전트용으로 세팅된 저장소가 CLAUDE.md 없이도 동작한다. Claude Code 메모리
  • (2026-10-18 기준) 다만 Claude Code는 AGENTS.override.md를 읽지 않는다. Claude Code 메모리 Codex에서는 이 파일이 같은 디렉터리의 AGENTS.md보다 먼저 쓰인다. Codex AGENTS.md 가이드
  • 두 도구의 탐색 순서·override·크기 한도 비교와 한 파일을 공유하는 방법: AGENTS.md와 CLAUDE.md 함께 쓰기

코딩이 아닌 일과 ChatGPT Work (2026-10-18 기준)#

OpenAI의 ChatGPT Work 시작 문서는 코딩이 아닌 일에 Codex를 써 왔다면 Codex에 머물러도 되고 ChatGPT Work를 써도 된다고 말한다. ChatGPT Work는 같은 핵심 기능을 일상 업무용으로 설계한 경험으로 제공한다는 것이 그 문서의 설명이다. 일반 사용과 제공 범위는 Help Center "ChatGPT Work and Codex" 문서로 넘긴다. ChatGPT Work 시작하기

LLM Wiki 운영 에이전트로 쓰기#