Codex에게 같은 설명을 반복한다면 먼저 프롬프트를 늘리기보다 AGENTS.md를 점검할 차례다. 이 파일은 저장소와 함께 관리되는 작업 지침이다. 하지만 규칙이 많다고 결과가 안정되는 것은 아니다. 좋은 시작점은 다음 작업에서 실제 선택을 바꿀 6줄이다. 테스트 명령, 수정 금지 경로, 완료 조건처럼 관찰 가능한 행동을 적고 작은 작업으로 효과를 확인해야 한다.
전역·루트·하위 폴더의 역할부터 나눈다
OpenAI 공식 문서에 따르면 Codex는 실행을 시작할 때 지침 체인을 만든다. 전역 범위에서는 Codex 홈의 AGENTS.override.md 또는 AGENTS.md 중 첫 번째 비어 있지 않은 파일을 읽는다. 프로젝트에서는 저장소 루트부터 현재 작업 폴더까지 내려가며 디렉터리마다 하나를 포함한다. 더 가까운 폴더의 지침이 뒤에 합쳐져 앞의 공통 지침보다 우선한다.
이 원리를 파일 배치 기준으로 바꾸면 단순하다.
| 위치 | 넣을 내용 | 넣지 않을 내용 |
|---|---|---|
| 전역 | 개인 응답 방식, 모든 프로젝트의 공통 습관 | 특정 저장소의 빌드 명령 |
| 저장소 루트 | 설치·테스트·리뷰·완료 기준 | 한 폴더에서만 쓰는 예외 |
| 하위 폴더 | 결제·모바일 등 해당 영역의 명령과 경계 | 이미 루트에 있는 공통 규칙 |
합쳐진 프로젝트 지침은 기본 32KiB 한도에 도달하면 이후 파일이 포함되지 않을 수 있다. 중요한 규칙을 위에 몰아넣는 임시방편보다, 공통 규칙은 루트에 두고 전문 규칙은 실제 작업 폴더 가까이에 나누는 편이 낫다.
첫 파일은 이 6줄로 시작한다
아래 예시는 제품 설명이 아니라 작업 결정을 바꾸는 최소 지침이다.
- 패키지 설치와 테스트는 저장소 루트에서 실행한다.
- TypeScript 수정 뒤 `pnpm test --filter api`를 실행한다.
- `generated/`와 `vendor/`는 직접 수정하지 않는다.
- 마이그레이션 파일을 만들기 전 승인을 요청한다.
- 완료 보고에는 변경 파일과 실행한 검사를 적는다.
- 검사를 실행하지 못했다면 이유를 밝히고 중단한다.“고품질 코드를 작성하라”처럼 판정할 수 없는 문장은 빼는 것이 좋다. README의 제품 소개, 일반 코딩 상식, 긴 스타일 가이드도 그대로 복사하지 않는다. 필요하면 원문 문서를 별도로 두고 AGENTS.md에는 언제 무엇을 읽어야 하는지만 남긴다.
문장마다 실패 사례와 안전한 경로를 붙인다
규칙을 추가하기 전 질문은 하나다. “어떤 반복 실수를 막으려는가?” 예를 들어 문서만 고치는 작업에서 배포 파일이 함께 변경됐다면 “배포 파일을 조심한다”가 아니라 대상 경로와 다음 행동을 적는다.
- 문서 작업에서는 `.github/workflows/`를 수정하지 않는다.
변경이 필요하면 별도 작업으로 분리해 승인을 요청한다.이렇게 쓰면 금지와 대안이 한 쌍이 된다. 같은 문제가 다시 생기지 않으면 규칙을 유지하고, 행동이 달라지지 않으면 표현을 구체화하거나 CI로 옮긴다. 포맷, 타입 검사, 테스트처럼 자동 판정 가능한 항목은 지침만 믿지 말고 린터와 CI가 강제하게 해야 한다.
새 세션에서 세 가지로 검증한다
파일 저장이 끝이 아니다. 지침 체인은 실행 시작 시 만들어지므로 새 실행에서 확인한다. 첫째, Codex에게 읽은 지침 출처와 적용 순서만 요약하게 한다. 둘째, 금지 경로가 포함된 가상 작업을 주고 수정 계획에서 제외하는지 본다. 셋째, 작은 실제 수정 한 건을 맡겨 올바른 테스트를 고르고 완료 보고를 남기는지 확인한다.
여기서 AGENTS.md는 보안 장치가 아니라 행동 지침이라는 경계를 지켜야 한다. 파일 접근과 네트워크 권한은 샌드박스·승인 정책으로 제한한다. 반복 셸 명령은 Codex Rules 공식 문서의 prefix_rule로 허용·질문·차단을 정할 수 있으며, 겹치는 규칙에서는 더 제한적인 결정이 적용된다. 규칙 파일은 codex execpolicy check로 예상 명령과 위험 명령을 각각 시험한다.
결론은 간단하다. 긴 규칙집을 먼저 만들지 말고, 최근 실패를 막는 6줄을 배치하고 새 세션에서 행동 변화부터 확인한다. 통과한 규칙만 남기고, 자동 검사로 옮길 수 있는 항목은 CI에 맡기면 AGENTS.md가 설명서가 아니라 재현 가능한 팀 운영 장치가 된다.
확인한 공식 자료
- OpenAI: Custom instructions with AGENTS.md
- OpenAI: Codex Rules
- 확인일: 2026-08-31