AI·개발자 도구 · Codex 프로젝트 설정 가이드
매번 같은 테스트 명령과 금지 범위를 프롬프트에 붙여 넣고 있다면, 반복되는 규칙부터 Codex AGENTS.md로 옮길 수 있어요. AGENTS.md는 Codex가 작업 전에 읽는 지속적인 프로젝트 지침 파일로, 테스트 명령·코딩 규칙·수정 금지 범위·완료 조건을 저장할 때 사용해요.
Codex AGENTS.md 작성법 핵심 요약
- 여러 작업에서 반복할 규칙은
AGENTS.md에, 이번 작업의 목표는 현재 프롬프트에 적어요. - 루트에는 공통 규칙을, 하위 폴더에는 해당 영역의 명령과 예외를 두고 같은 위치의
AGENTS.override.md를 함께 확인해요. - 강제로 지켜야 하는 검사는 CI와 테스트에도 두고, 작성 후에는 Codex가 읽은 지침과 실행 위치·길이 제한을 검증하세요.
Codex AGENTS.md란?
AGENTS.md가 필요한 시점은 같은 명령과 제약을 여러 Codex 작업에서 반복할 때예요. OpenAI의 AGENTS.md 공식 문서에 따르면 Codex는 작업 전에 전역 지침과 프로젝트별 지침을 읽어 지침 체인을 구성해요.
“설정 화면의 버튼 간격만 8px 줄여줘”처럼 한 번만 수행할 목표는 현재 프롬프트에 남기면 돼요. 반면 “프런트엔드를 바꾼 뒤에는 모바일 화면과 npm test를 확인한다”처럼 계속 반복할 규칙은 파일로 옮기는 편이 관리하기 쉬워요.
Codex로 기존 프로젝트를 수정하고 검증한 전체 과정에서는 첫 요청에 목표·맥락·제약·완료 조건을 넣는 방법을 다뤘어요. 이번 글은 그중 반복되는 내용을 프로젝트 규칙으로 남기는 다음 단계예요.
AGENTS.md 작성법: 무엇을 넣어야 할까
좋은 AGENTS.md는 프로젝트 설명서 전체가 아니라 Codex가 작업 중 판단할 때 필요한 실행 규칙의 목록에 가까워요. 프로젝트 목적, 시작 방법, 금지 범위, 검증 명령과 완료 조건을 짧고 구체적으로 적으면 돼요.
| 내용 | 권장 위치 | 이유 |
|---|---|---|
| 모든 작업에 반복되는 명령·제약·완료 조건 | AGENTS.md |
Codex가 작업 전에 반복해서 참고해야 함 |
| 이번 작업의 목표·대상 파일·세부 요구 | 현재 프롬프트 | 다음 작업에는 적용되지 않을 수 있음 |
| 설치 방법·아키텍처·사용자 안내 | README.md 또는 docs/ |
사람도 읽어야 하고 설명이 길어질 수 있음 |
| 반드시 실패로 막아야 하는 형식·테스트 | CI, 린터, 테스트 | 자동 검사가 실제 결과를 판정함 |
| API 키·비밀번호·고객 정보 | 평문으로 저장하지 않음 | 지침 파일도 프로젝트 파일이므로 노출 위험이 있음 |
처음 작성할 때는 다음 다섯 묶음이면 충분해요.
- 프로젝트 목적과 기술 환경: 무엇을 만들고 어떤 패키지 관리자와 프레임워크를 쓰는지 적어요.
- 작업 순서: 수정 전에 읽을 문서, 기존 패턴을 찾는 방법과 계획이 필요한 조건을 적어요.
- 검증 명령: 실제로 실행 가능한 테스트·린트·빌드 명령을 정확히 적어요.
- 금지 범위와 승인 조건: 운영 배포, 의존성 추가와 데이터 삭제처럼 별도 확인이 필요한 행동을 구분해요.
- 완료 조건: 어떤 테스트·화면·문서가 확인돼야 끝인지 적어요.
항상 최선의 코드를 작성한다보다 변경한 기능의 관련 테스트를 먼저 실행한다, 모바일 390px에서 가로 넘침을 확인한다처럼 행동과 결과가 보이는 문장이 유용해요.
바로 쓰는 AGENTS.md 예시
처음부터 긴 규칙집을 만들 필요는 없어요. 아래 템플릿에서 실제로 반복되는 항목만 남기고, 존재하지 않는 명령이나 팀 규칙은 삭제하세요.
# Project instructions
## Purpose
이 프로젝트는 고객 문의를 관리하는 웹 애플리케이션이다.
## Working agreements
- 수정 전에 관련 코드와 기존 테스트를 먼저 확인한다.
- 기존 공개 API와 데이터 형식은 요청 없이 바꾸지 않는다.
- 새 의존성을 추가하기 전에는 필요성과 대안을 설명한다.
## Verification
- 관련 테스트를 실행한다: `npm test -- --runInBand`
- 프런트엔드를 수정했다면 `npm run build`를 실행한다.
- 화면 변경은 데스크톱과 모바일에서 확인한다.
## Safety
- 비밀번호, 토큰과 고객 데이터를 출력하거나 커밋하지 않는다.
- 운영 배포와 데이터 삭제는 사용자 승인 없이 실행하지 않는다.
## Completion
- 변경 파일과 이유를 요약한다.
- 실행한 검증 명령과 결과를 보고한다.
- 확인하지 못한 항목은 숨기지 않고 남긴다.템플릿의 명령은 사람이 터미널에서 먼저 실행해 보세요. Python 프로젝트라면 pytest, PHP 프로젝트라면 composer test, 앱 프로젝트라면 실제 빌드 명령으로 바꿔야 완료 조건을 검증할 수 있어요.
루트와 하위 폴더 AGENTS.md 사용 예시
현재 프로젝트에는 루트 AGENTS.md와 프런트엔드 프로토타입 폴더의 AGENTS.md가 따로 있어요. 공통 규칙과 작업 영역별 규칙을 실제로 분리한 구조예요.
직접 확인한 환경과 결과
아래 값은 2026년 8월 11일에 macOS의 실제 작업공간에서 find, wc -c, codex --version으로 확인한 과거 증거예요. 이 리프레시에서는 같은 명령을 다시 실행해 2026년 9월 11일 현재 CLI가 codex-cli 0.153.2임을 확인했어요. 로컬 경로는 공개용 이름으로 줄였고, 파일 내용은 민감정보를 제외한 축약본만 사용했어요.
| 확인 항목 | 결과 |
|---|---|
| Codex 환경 | 데스크톱 앱, Codex CLI 0.145.0 |
| 프로젝트 지침 | 루트 AGENTS.md 4,112바이트 |
| 폴더 전용 지침 | 하위 AGENTS.md 1,507바이트 |
| 확인한 범위 | 파일 존재, 크기, 규칙의 역할 분리 |
| 비교하지 않은 항목 | 적용 전후 시간·토큰·성능 차이 |
이 수치는 AGENTS.md가 성능을 높인다는 증거가 아니에요. 두 파일을 서로 다른 범위의 규칙으로 관리한다는 구조 확인값이에요.
AGENTS.md 4,112바이트를 보여줘요. 개인정보와 관련 없는 행만 잘라냈고 명령·버전·파일 크기는 원본 값을 유지했어요.두 번째 캡처에는 루트 파일만 보여요. 하위 AGENTS.md는 루트 바로 아래가 아니라 프런트엔드 프로토타입 작업 폴더 안에 있어서, 루트에서 실행한 ls -al 목록에는 나타나지 않아요.
project/
├── AGENTS.md # 사이트 전체 운영 규칙
└── frontend-prototype/
└── AGENTS.md # 프로토타입에만 필요한 규칙루트 파일에는 사이트 목적, 증거 우선 원칙, 공개 발행 승인과 품질 확인처럼 프로젝트 전체에 필요한 규칙을 뒀어요.
## Project rules
- 기존 공개 URL과 검색 메타를 임의로 바꾸지 않는다.
- 확인하지 않은 경험, 수치와 링크를 만들지 않는다.
- 공개 발행 전에는 사용자 승인을 확인한다.
- 변경 뒤 테스트, 실제 화면과 운영 응답을 검증한다.
- 작업 결과와 다음 점검일을 문서에 기록한다.하위 파일에는 프로토타입에서 수정할 폴더, 실행할 명령과 운영 WordPress 쓰기 금지처럼 그 영역에만 필요한 내용을 뒀어요.
## Frontend prototype rules
- 애플리케이션 UI는 `src/`에서 수정한다.
- 운영 WordPress에는 직접 쓰지 않는다.
- 변경 후 `npm run build`와 관련 테스트를 실행한다.
- 로컬 미리보기에서 데스크톱과 모바일 화면을 확인한다.공통 내용은 루트 한 곳에 남기고 차이만 하위 파일에 적어야 복사본이 서로 달라지는 일을 줄일 수 있어요.
AGENTS.md 적용 순서와 우선순위
Codex는 전역 지침을 확인한 뒤 프로젝트 루트에서 현재 작업 폴더까지 내려오며 지침을 결합해요. 전역에서는 $CODEX_HOME/AGENTS.override.md가 있으면 그것만, 없으면 $CODEX_HOME/AGENTS.md 중 비어 있지 않은 첫 파일을 사용해요. 프로젝트의 각 디렉터리에서는 AGENTS.override.md, AGENTS.md, project_doc_fallback_filenames에 등록한 대체 파일명 순서로 확인하고 디렉터리마다 최대 하나만 포함해요. 충돌하는 항목은 현재 폴더에 가까운 지침이 뒤에 놓이므로 더 구체적으로 적용될 수 있어요.
| 위치 | 적용 범위 | 적합한 내용 |
|---|---|---|
Codex 홈의 AGENTS.md |
여러 프로젝트에 쓰는 개인 기본값 | 선호하는 작업 방식, 공통 보고 형식 |
프로젝트 루트 AGENTS.md |
프로젝트 전체 | 공통 명령, 코드 규칙, 안전 조건 |
하위 폴더 AGENTS.md |
해당 폴더까지 내려간 작업 | 서비스·앱·패키지별 명령과 예외 |
AGENTS.override.md |
같은 위치의 기본 파일 대신 적용 | 임시 전환 또는 더 강한 범위별 규칙 |
| 현재 프롬프트 | 이번 작업 | 구체적인 목표, 대상과 일회성 완료 조건 |
다만 Codex가 프로젝트 루트를 찾지 못하면 현재 디렉터리만 확인해요. 공식 문서가 말하는 프로젝트 루트는 보통 Git 루트예요. 이 Sinabro 작업공간은 실제로 .git이 없어 Git 루트를 찾을 수 없으므로, 문서 작업을 시작한 폴더의 AGENTS.md만 자동 발견된다고 이해해야 해요. Git 저장소가 아니거나 별도 작업공간을 열었다면 Codex를 시작한 폴더와 인식된 작업공간 루트부터 확인하세요.
프로젝트 지침에는 읽는 양의 제한도 있어요. 공식 AGENTS.md 가이드가 안내하는 project_doc_max_bytes 기본값은 32 KiB예요. 여러 파일을 루트부터 합치다가 이 한도에 닿으면 뒤쪽 지침이 잘릴 수 있으니, 핵심 명령·제약을 앞에 두고 긴 설명은 docs/로 옮기거나 디렉터리별로 나누세요.
AGENTS.override.md를 사용했다면 현재 폴더뿐 아니라 상위 폴더와 Codex 홈에도 남아 있는 파일이 없는지 확인하세요.
Codex가 AGENTS.md를 읽었는지 확인하는 방법
파일을 저장한 뒤에는 Codex가 어떤 지침을 읽었는지 직접 물어보세요. OpenAI 공식 문서는 루트와 하위 폴더에서 각각 지침 요약을 요청해 적용 순서를 확인하는 예를 제공해요.
codex -s read-only --ask-for-approval never exec \
--skip-git-repo-check --ephemeral -C . \
"List the instruction sources you loaded and summarize the current instructions."하위 폴더 규칙까지 확인하려면 대상 폴더를 작업 위치로 지정해요.
codex -s read-only --ask-for-approval never exec \
--skip-git-repo-check --ephemeral -C frontend-prototype \
"Show which instruction files are active."주의:
--ask-for-approval never는 코드를 바꾸지 않고 지침만 요약하게 하는 위 확인 예시에 사용했어요. 파일 수정·배포·삭제 작업에 그대로 붙이지 말고, 작업 전에 현재 승인 정책과 샌드박스 범위를 확인하세요.
출력에서는 파일명보다 다음 세 가지를 비교하세요.
- 루트의 공통 테스트와 금지 범위가 포함됐는가?
- 현재 폴더의 전용 명령과 예외가 뒤에 적용됐는가?
- 예상하지 못한
AGENTS.override.md나 대체 파일이 끼어 있지 않은가?
현재 CLI에는 공식 가이드에 등장하는 대화형 예시와 별도로 비대화형 exec 명령이 있어요. 이 작업공간에서 codex --help를 확인했을 때 status 하위 명령은 보이지 않았으므로, codex status를 전제로 하지 말고 exec 출력이나 로그로 적용 여부를 확인하세요. 답이 파일 내용과 다르면 코드를 바꾸기 전에 실행 위치와 지침 체인부터 바로잡는 편이 안전해요.
AGENTS.md가 적용되지 않을 때 확인할 것
규칙 파일이 적용되지 않는 것처럼 보일 때는 문장을 계속 추가하기보다 발견 조건부터 확인하세요.
- 파일이 비어 있지 않은지 확인해요. Codex는 빈 지침 파일을 건너뛰어요.
- 파일명을 확인해요. 기본 파일명은
AGENTS.md와AGENTS.override.md예요. 다른 이름은project_doc_fallback_filenames에 등록해야 해요. - 현재 작업 폴더와 프로젝트 루트를 확인해요. 다른 폴더에서 실행하면 예상한 상위 파일을 찾지 못할 수 있어요.
- 상위 폴더와 Codex 홈의 override를 확인해요. 같은 위치에서는 override가 기본 파일 대신 선택돼요.
- 파일을 줄여요. 핵심 명령·제약·완료 조건을 앞에 두고 긴 배경 설명은
docs/로 옮겨요. - fallback 설정을 확인해요. 다른 파일명을 쓰려면
config.toml에project_doc_fallback_filenames를 정확히 등록해야 해요. 등록하지 않은 이름은 지침 파일로 읽히지 않아요. - 새 세션에서 다시 확인해요. Codex는 실행 또는 TUI 세션을 시작할 때 지침 체인을 구성하므로 별도 캐시를 지우기보다 대상 폴더에서 다시 시작하세요.
테스트를 철저히 한다처럼 모호한 문장은 TypeScript 파일을 바꾼 뒤 npm test를 실행하고 실패 수를 보고한다처럼 실행 조건과 결과로 바꾸는 편이 좋아요.
AGENTS.md 작성 전 체크리스트
프로젝트의 명령, 폴더 구조와 공개 절차가 바뀌면 AGENTS.md도 함께 고쳐야 해요. 첫 버전은 다음 일곱 가지만 확인해도 충분해요.
- 프로젝트 목적과 여러 작업에서 반복할 규칙만 적었는가?
- 실제로 실행되는 테스트·린트·빌드 명령을 확인했는가?
- 수정 금지 범위와 별도 승인이 필요한 행동을 구분했는가?
- 완료 여부를 테스트·화면·출력으로 검증할 수 있는가?
- 비밀번호, 토큰, 고객 정보와 내부 주소를 제외했는가?
- 공통 규칙과 하위 폴더 규칙의 중복을 줄였는가?
- 실제 작업 폴더에서 활성 지침을 확인하고 갱신 책임을 정했는가?
테스트와 CI는 코드의 실제 동작을 판정하고, AGENTS.md는 Codex가 그 검증을 빠뜨리지 않도록 작업 방향을 알려줘요.
자주 묻는 질문
AGENTS.md가 없으면 Codex를 사용할 수 없나요?
아니요. AGENTS.md가 없어도 Codex를 사용할 수 있어요. 한 번의 작은 작업은 현재 프롬프트에 목표, 제약과 검증 방법을 적으면 돼요.
README와 AGENTS.md에는 같은 내용을 적어야 하나요?
아니요. 같은 내용을 통째로 복사할 필요는 없어요. README에는 사람을 위한 설치·구조·사용법을, AGENTS.md에는 Codex가 따를 명령·제약·완료 조건을 간결하게 적으세요.
규칙을 바꾸면 현재 세션에 바로 반영되나요?
아니요. 바로 반영된다고 가정하지 않는 편이 안전해요. Codex는 실행 또는 TUI 세션을 시작할 때 지침 체인을 구성하므로 대상 폴더에서 새 세션을 시작한 뒤 활성 지침을 다시 요약하게 하세요.
출처 및 확인한 공식 자료
- OpenAI Codex AGENTS.md 공식 문서: 파일 발견 순서, 전역·프로젝트 범위, override, 확인과 문제 해결
다음으로 확인할 글
지금 할 일 하나. 최근 세 번의 Codex 요청에서 반복한 문장을 찾아보세요. 프로젝트 전체에 계속 적용할 명령·금지 범위·완료 조건만 위 템플릿에 넣고, 새 세션에서 활성 지침을 요약하게 하면 돼요.