Codex 프로젝트 지침의 계층과 충돌 해결법

Codex가 지침을 찾는 순서를 읽습니다

Codex 홈은 기본적으로 `~/.codex`입니다. 여기서는 비어 있지 않은 `AGENTS.override.md`가 있으면 그것만 읽고, 없으면 `AGENTS.md`를 읽습니다.

프로젝트에서는 Git 루트부터 현재 작업 디렉터리까지 내려오며 각 폴더에서 `AGENTS.override.md`, `AGENTS.md`, 설정한 대체 이름 순으로 하나만 고릅니다. 루트 지침이 먼저, 가까운 폴더 지침이 나중에 결합됩니다.

공통 원칙과 지역 예외를 분리합니다

루트에는 전 저장소에 해당하는 검증과 금지 사항을 둡니다. 서비스 전용 명령은 서비스 폴더 가까이에 둡니다.

repo/AGENTS.md
- 변경 뒤 npm test를 실행한다.
- 커밋과 푸시는 사람이 승인한다.

repo/services/payments/AGENTS.override.md
- 이 폴더에서는 npm test 대신 make test-payments를 실행한다.
- 운영 키는 읽거나 교체하지 않는다.

우선 파일은 추가가 아니라 같은 폴더의 교체입니다

같은 디렉터리에 `AGENTS.md`와 `AGENTS.override.md`가 있으면 둘을 합치지 않습니다. 우선 파일만 선택됩니다. 임시 예외를 끝낸 뒤 파일을 남겨두면 기본 지침은 계속 무시됩니다.

하위 우선 파일에 필요한 공통 규칙이 상위 파일에 있다면 상위 규칙은 이미 체인에 들어옵니다. 하지만 같은 폴더의 기본 지침 파일에만 있던 문장은 사라지므로 우선 파일 자체가 무엇을 대체하는지 검토합니다.

최소 저장소에서 충돌을 재현합니다

실제 프로젝트를 고치기 전에 임시 저장소에 루트와 하위 지침을 만들고 하위 폴더에서 다음처럼 묻습니다. 승인 질문을 끄는 것만으로는 파일 쓰기를 막지 못하므로 읽기 전용 샌드박스를 함께 지정합니다.

cd services/payments
codex --sandbox read-only --ask-for-approval never "로드한 지침 파일을 적용 순서대로 적고, 이 폴더에서 사용할 테스트 명령만 말해줘. 실행하거나 파일을 바꾸지 마."

길이 한도와 모호한 문장을 관리합니다

공식 문서의 기본 합산 한도는 32KiB입니다. 지침이 길어지면 뒤쪽 파일이 모두 들어오지 않을 수 있습니다. 코드 스타일 설명 전체를 붙이기보다 실제 명령, 변경 금지 대상과 승인 조건을 짧게 적습니다.

“조심해서 배포한다”보다 “배포 명령은 실행하지 않고 명령과 예상 영향만 보고한다”가 검증 가능합니다. 충돌한 두 규칙을 모두 만족할 수 없으면 가까운 지침을 따르더라도 먼저 충돌을 보고하도록 씁니다.

새 세션에서 실제 행동까지 검증합니다

지침 체인은 실행 시작 때 만들어집니다. 파일을 수정한 뒤 기존 세션의 답만 보고 성공으로 판단하지 말고 새 세션에서 로드 출처와 테스트 명령을 다시 묻습니다.

예상 파일이 보이지 않거나 전역 우선 파일의 존재를 설명할 수 없으면 작업을 멈춥니다. `project_doc_max_bytes`를 무작정 늘리기 전에 중복 지침을 줄이고 폴더별 규칙을 가까운 위치로 나눕니다.