Codex AGENTS.md가 안 먹힐 때, 파일 위치부터 확인하세요

AGENTS.md 지침이 적용되지 않을 때 확인할 파일 위치. AI로 생성한 설명용 이미지.

AGENTS.md를 고쳤는데 Codex가 예전 규칙대로 작업하나요? 문장을 더 붙이기 전에 시작한 폴더와 파일 이름부터 확인해 보세요. 터미널에서 Codex CLI를 쓰는 경우를 기준으로 정리했습니다.

지금 어느 폴더에서 시작했나요?

터미널에서 pwd를 입력하면 현재 위치가 나옵니다. Git 저장소라면 git rev-parse --show-toplevel로 저장소 맨 위 폴더도 확인할 수 있어요.

Codex는 보통 저장소 맨 위부터 현재 작업 폴더까지 지침을 찾습니다. 프로젝트 루트를 찾지 못하면 현재 폴더만 확인합니다. 다른 폴더에 파일을 만들어 두었다면 이번 실행의 탐색 경로에 포함되는지 먼저 살펴보세요.

override 파일도 함께 있나요?

같은 폴더에서는 AGENTS.override.md가 AGENTS.md보다 먼저입니다. 폴더마다 최대 한 파일을 읽으므로 두 파일 내용이 모두 합쳐진다고 생각하면 헷갈립니다. 빈 파일은 건너뜁니다.

공통 규칙과 특정 폴더의 규칙이 충돌하면 현재 작업 폴더에 더 가까운 지침이 우선합니다. 예를 들어 공통 규칙은 “테스트 실행”, 화면 폴더의 규칙은 “화면 테스트 먼저 실행”처럼 구체화할 수 있겠죠. 가상 예시입니다.

바꾼 뒤에는 새 실행에서 확인하세요

개인 공통 지침도 확인해 보세요. 기본 위치는 ~/.codex이며, CODEX_HOME을 따로 설정했다면 달라집니다. 지침을 합치는 기본 한도는 32KiB라서 긴 문서에는 제한도 있습니다.

수정 후에는 작업할 폴더에서 Codex를 새로 시작하고 이렇게 요청해 보세요.

“현재 적용한 지침 파일 경로와 핵심 규칙을 짧게 알려줘. 아직 파일은 수정하지 마.”

답변만 보고 끝내지 말고, 다음 작은 작업에서 원하는 규칙이 실제 결과에 반영됐는지도 확인하세요. 오늘은 자주 쓰는 프로젝트 하나에서 시작 폴더와 override 유무만 점검해도 충분합니다.

출처: OpenAI의 AGENTS.md 공식 안내. 2026년 10월 9일 확인. 공식 동작 설명과 가상 예시를 정리한 글이며, 계정별 앱 화면이나 모델의 지침 준수 성능을 시험한 후기는 아닙니다.