저장소 규칙을 에이전트에게 매번 자동 전달 (Codex AGENTS.md)
테스트 명령이나 패키지 관리자 같은 저장소 규칙을 작업마다 다시 말하지 않아도, Codex가 작업 전에 먼저 읽고 시작합니다.
모든 저장소에 쓸 공통 규칙은 ~/.codex/AGENTS.md에, 저장소 규칙은 루트의 AGENTS.md에 적습니다. 폴더마다 다른 규칙은 그 폴더에 따로 두고, 마지막으로 Codex가 어떤 규칙을 읽었는지 확인합니다.
내 내용 넣기
1칸
준비
- Codex CLI 설치
- Git 저장소 하나
1. 전역 규칙 파일 만들기
~/.codex 폴더를 만들고 AGENTS.md에 모든 저장소에 공통인 선호를 적습니다. 예를 들면 JavaScript를 고친 뒤 npm test 실행, pnpm 우선, 운영 의존성 추가 전 확인 같은 규칙입니다. 빈 파일은 건너뛰므로 몇 줄이라도 적습니다.
mkdir -p ~/.codex
$EDITOR ~/.codex/AGENTS.md2. 전역 규칙 적용 확인
승인 없이 한 번 실행해 지금 읽힌 지시를 요약하게 합니다.
codex --ask-for-approval never "Summarize the current instructions."방금 적은 규칙이 답에 나오면 됩니다.
3. 저장소 루트에 AGENTS.md 추가
Git 저장소 루트의 AGENTS.md에 이 저장소만의 규칙을 적습니다. 예를 들면 PR 전 npm run lint 실행, 공개 유틸리티는 docs/에 문서화 같은 규칙입니다.
4. 하위 폴더에 덮어쓰기 규칙 추가
명령이 다른 하위 폴더에는 AGENTS.override.md를 만듭니다. 예를 들어 npm test 대신 make test-payments를 쓰게 합니다. 깊은 폴더의 지시가 위쪽 지시보다 우선합니다.
$EDITOR <하위 폴더>/AGENTS.override.md5. 읽힌 규칙 순서 확인
하위 폴더 기준으로 실행해 읽은 지시의 출처를 나열하게 합니다.
codex --cd <하위 폴더> --ask-for-approval never "List the instruction sources you loaded."전역 파일, 루트 AGENTS.md, 하위 폴더의 override 순서로 세 파일이 나오면 됩니다.
6. 다른 파일 이름 쓰기 (선택)
이미 다른 이름의 안내 파일이 있으면 config.toml에 대체 이름을 등록하고 크기 한도도 함께 조정합니다. 저장한 뒤 Codex를 다시 시작합니다.
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536이제 폴더마다 AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md 순서로 찾습니다. 다시 시작한 뒤 출처 목록에 TEAM_GUIDE.md가 보이면 됩니다.
주의
- 합친 크기가
project_doc_max_bytes(기본 32 KiB)에 닿으면 그 뒤 파일은 읽지 않습니다. 한도를 올리거나 하위 폴더로 나눕니다. - 현재 폴더보다 아래는 찾지 않습니다. 덮어쓰기 파일은 해당 작업 폴더 가까이에 둡니다.
- 규칙이 엉뚱하게 적용되면 위쪽 폴더나 Codex 홈의
AGENTS.override.md를 확인합니다. - 지시 목록은 실행(세션)마다 한 번 만들어집니다. 바뀐 내용이 안 보이면 대상 폴더에서 Codex를 다시 시작합니다.
- 프로필이 헷갈리면 실행 전에
echo $CODEX_HOME으로 확인합니다.
댓글