AGENTS.md는 코딩 에이전트에게 프로젝트 사정을 알려 주는 파일입니다. Codex에서 /init을 입력하면 현재 프로젝트용 AGENTS.md 틀이 만들어집니다. 이 글은 틀을 만든 뒤 무엇을 채워야 하는지, Codex가 파일을 어떤 순서로 읽는지, 용량 한도에 걸리지 않게 나누는 방법을 다룹니다.
AGENTS.md와 /init이 하는 일
AGENTS.md는 agents.md 사이트가 "에이전트를 위한 README"라고 소개하는 열린 형식입니다. 사람이 읽는 README에 넣기엔 번잡한 내용, 예를 들어 빌드 명령이나 테스트 방법, 코드 스타일 규칙을 에이전트용으로 따로 적어 둡니다. 필수 항목은 없습니다.
Codex의 슬래시 명령 문서는 /init을 "현재 프로젝트용 AGENTS.md 틀(scaffold)을 만든다"고 설명합니다. 틀 안에 정확히 무엇이 들어가는지는 해당 문서에 나와 있지 않습니다. 그래서 만들어진 파일은 반드시 직접 열어 보고, 실제 프로젝트와 맞는지 확인해야 합니다.
agents.md가 흔히 넣는 항목으로 드는 것은 다음과 같습니다. 프로젝트 개요, 빌드와 테스트 명령, 코드 스타일, 테스트 방법, 보안 주의점입니다. 커밋과 PR 규칙, 배포 절차를 적어 두는 경우도 있습니다.
Codex가 파일을 읽는 순서
Codex 문서에 따르면 지침 목록은 실행을 시작할 때 한 번 만들어집니다. 파일을 고치면 다음 실행부터 반영되고, 지워야 할 캐시는 없습니다.
먼저 전역 범위를 봅니다. Codex 홈 디렉터리(기본값 ~/.codex, CODEX_HOME으로 바꿀 수 있음)에서 AGENTS.override.md를 먼저 찾고, 없으면 AGENTS.md를 씁니다. 이 단계에서는 비어 있지 않은 첫 파일 하나만 사용합니다.
다음은 프로젝트 범위입니다. 프로젝트 루트(보통 Git 루트)에서 시작해 현재 작업 디렉터리까지 내려오면서, 디렉터리마다 AGENTS.override.md, AGENTS.md, project_doc_fallback_filenames에 적은 이름 순서로 찾습니다. 디렉터리 하나에서 읽는 파일은 최대 하나입니다. 프로젝트 루트를 찾지 못하면 현재 디렉터리만 확인합니다.
찾은 파일은 루트부터 아래 순서로 빈 줄을 사이에 두고 이어 붙입니다. 가까운 폴더의 파일이 뒤에 오기 때문에 앞의 내용보다 우선하는 효과가 있습니다.
- 같은 폴더에 AGENTS.override.md가 있으면 그 폴더의 AGENTS.md는 무시됩니다.
- 합친 크기의 기본 한도(project_doc_max_bytes)는 32 KiB입니다. 한도에 닿으면 이후 파일은 더 추가되지 않습니다.
- 한도에 걸리면 값을 올리거나(문서 예시는 65536) 지침을 하위 폴더로 나눕니다.
- AGENTS.md가 아닌 이름(예: TEAM_GUIDE.md)을 쓰려면 ~/.codex/config.toml의 project_doc_fallback_filenames에 적고 Codex를 다시 시작해야 합니다.
실제로 쓰는 순서
1) 프로젝트 폴더에서 Codex를 실행하고 /init을 입력합니다. 2) 만들어진 AGENTS.md를 열어 틀린 내용을 고칩니다. 3) 에이전트가 자주 틀리는 부분, 예를 들어 "테스트는 이 명령으로 돌린다"처럼 사람이 알려 주지 않으면 모르는 내용을 구체적으로 적습니다. 4) 하위 폴더에서 규칙이 달라지면 그 폴더에 별도 파일을 둡니다.
제대로 읽혔는지는 문서에 나온 방법으로 확인할 수 있습니다. 아래 명령은 Codex가 불러온 지침 출처를 목록으로 보여 달라고 요청합니다. 전역 파일, 루트 파일, 하위 폴더 파일 순서로 나오면 정상입니다.
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
다른 설정과의 차이
Codex의 메모리 기능과는 역할이 다릅니다. 공식 문서는 메모리를 기억을 돕는 장치로 설명하고, 반드시 지켜야 하는 팀 규칙은 AGENTS.md나 저장소에 들어 있는 문서에 두라고 안내합니다. 메모리는 기본으로 꺼져 있고 따로 켜야 하므로, 규칙의 유일한 보관 장소로 삼으면 안 됩니다.
Codex에서 개인 취향의 "사용자 지침(custom instructions)"은 전역 AGENTS.md(~/.codex/AGENTS.md)에 저장된다고 문서에 나옵니다. 개인 취향은 전역 파일에, 프로젝트 규칙은 저장소 파일에 두면 됩니다.
도구마다 지침 파일 이름이 다릅니다. agents.md는 기존 에이전트 파일을 AGENTS.md로 바꾸고 옛 이름으로 심볼릭 링크를 남기는 방법을 안내합니다. 또 Aider나 Gemini CLI처럼 설정을 해야 AGENTS.md를 읽는 도구도 있다고 합니다. 사용하는 도구가 이 파일을 읽는지는 각 도구 문서로 따로 확인하세요. 이 글은 Codex 기준입니다.
실제 예시
결제 서비스만 테스트 명령이 다른 모노레포입니다.
루트 AGENTS.md에 "PR 전에 npm run lint를 실행한다"를 적고, services/payments/AGENTS.override.md에 "npm test 대신 make test-payments를 쓴다"를 적었습니다.
payments 폴더에서 작업하면 두 파일이 모두 읽히고, 더 가까운 override 파일이 뒤에 놓입니다. 다른 폴더에서는 루트 규칙만 적용됩니다. 위 확인 명령으로 읽힌 순서를 볼 수 있습니다. 이 예시는 Codex 공식 문서의 예를 따랐습니다.
새 프로젝트에 처음 Codex를 붙입니다.
/init 입력 후 만들어진 AGENTS.md를 열어 빌드와 테스트 명령, 쓰지 않는 폴더를 직접 고쳐 적음
틀이 생기고, 사람이 채운 부분이 다음 실행부터 Codex의 지침이 됩니다. 이후 같은 설명을 매번 입력하지 않아도 됩니다. 틀의 구체적인 내용은 버전에 따라 다를 수 있어 확인이 필요합니다.
흔한 실수와 쓰지 말아야 할 때
- /init이 만든 틀을 검토 없이 그대로 두면 안 됩니다. 프로젝트와 맞지 않는 명령이 들어 있을 수 있습니다.
- 파일을 길게 쓰면 32 KiB 한도에 걸려 뒤쪽 파일이 읽히지 않을 수 있습니다. 한 파일에 몰아 쓰지 말고 폴더별로 나누세요.
- 같은 폴더에 AGENTS.override.md를 만들어 두면 AGENTS.md가 무시됩니다. 임시로 만든 override 파일을 지우는 것을 잊기 쉽습니다.
- 비밀번호, 토큰, 개인정보를 AGENTS.md에 적지 마세요. 저장소에 올라가면 그대로 공개됩니다.
- 파일 이름을 바꾸거나 fallback 이름을 추가한 뒤에는 Codex를 다시 시작해야 합니다.
자주 묻는 질문
AGENTS.md를 고치면 바로 적용되나요?
실행 시작 때 한 번 읽는 방식이라 다음 실행부터 적용됩니다. 지워야 할 캐시는 따로 없다고 문서에 나옵니다.
AGENTS.md는 몇 개까지 만들 수 있나요?
폴더마다 하나씩 둘 수 있습니다. 한 폴더에서 읽는 파일은 최대 하나이고, 합친 크기는 기본 32 KiB까지입니다.
/init이 만드는 내용은 항상 같나요?
문서는 "틀을 만든다"고만 설명합니다. 구체적인 내용은 확인하지 못했으니 만들어진 파일을 직접 보세요.
2026-10-30 공식 문서와 대조함. 출처: Codex: AGENTS.md가 지침을 불러오는 방식, Codex 슬래시 명령 (/init), Codex 메모리, ChatGPT 개인 맞춤 설정 (Codex 사용자 지침), AGENTS.md 공식 소개. 작성 원칙