AGENTS.md

AGENTS.md는 Codex가 작업을 시작하기 전에 읽는 지속적인 지침 파일입니다. 전역 지침에 프로젝트별 지침을 계층적으로 얹으면 어떤 저장소에서든 기본 합의를 유지하면서 저장소 고유의 규칙도 적용할 수 있습니다.

가능한 한 작고 명확하게 유지하십시오. 모든 규칙을 문서만으로 보장하려 하기보다 pre-commit hook, linter, type checker처럼 자동으로 검증할 수 있는 도구와 함께 쓰는 것이 좋습니다.

무엇을 적어야 하나

AGENTS.md에는 저장소에서 항상 지켜야 하는 규칙을 넣습니다.

• 빌드, 테스트, 린트 명령
• 코드 리뷰에서 기대하는 기준
• 저장소 고유의 코드 작성 규칙
• 특정 디렉터리에만 적용되는 작업 방식
• 반복해서 잘못 이해되는 코드베이스 맥락

한 번만 필요한 지시는 프롬프트에 직접 쓰고, 여러 작업에서 반복될 규칙만 AGENTS.md로 옮깁니다. Codex가 같은 실수를 반복한다면 그 내용을 규칙으로 정리해 AGENTS.md에 추가하도록 요청할 수 있습니다. 이렇게 하면 리뷰 피드백과 프로젝트 지식이 다음 작업에도 이어집니다.

지침 파일 배치와 우선순위

Codex는 실행마다 지침 체인을 만듭니다. TUI에서는 일반적으로 새 세션을 시작할 때 한 번 만들어집니다.

Codex 홈 디렉터리의 기본값은 ~/.codex이며 CODEX_HOME을 설정하면 달라집니다. 전역 범위에서는 AGENTS.override.md가 있으면 이를 읽고, 없으면 AGENTS.md를 읽습니다. 이 수준에서는 첫 번째 비어 있지 않은 파일만 사용합니다.

프로젝트 범위에서는 프로젝트 루트, 일반적으로 Git root에서 현재 작업 디렉터리까지 내려가며 지침을 찾습니다. 각 디렉터리에서는 AGENTS.override.md, AGENTS.md, project_doc_fallback_filenames에 있는 대체 파일 이름 순서로 확인하고, 디렉터리당 최대 하나의 파일만 포함합니다.

병합은 루트에서 현재 디렉터리 방향으로 이루어집니다. 현재 디렉터리에 가까운 파일일수록 결합된 프롬프트에서 뒤에 나타나므로 앞선 지침을 덮어쓸 수 있습니다. Codex는 빈 파일을 건너뛰고, 결합된 크기가 project_doc_max_bytes 한도에 도달하면 파일 추가를 중단합니다. 기본값은 32 KiB입니다. 자세한 옵션은 프로젝트 지침 발견을 참고하십시오.

repo-root/
├── AGENTS.md                  # 저장소 전체 규칙
└── services/
    ├── payments/
    │   ├── AGENTS.md          # override가 있으므로 무시됨
    │   ├── AGENTS.override.md # 결제 서비스 규칙
    │   └── README.md
    └── search/
        └── AGENTS.md

기본 파일 만들기

개인 선호는 전역 파일에, 저장소 규칙은 저장소 안의 파일에 둡니다. 특정 영역에만 다른 규칙이 필요할 때만 하위 디렉터리에 별도 파일을 추가합니다.

mkdir -p ~/.codex

# ~/.codex/AGENTS.md

## 작업 합의

- JavaScript 파일을 수정한 뒤에는 항상 `npm test`를 실행합니다.
- 의존성을 설치할 때는 `pnpm`을 우선 사용합니다.
- 새 production 의존성을 추가하기 전에는 확인을 요청합니다.

# repo-root/AGENTS.md

## 저장소 기대 사항

- pull request를 열기 전에 `npm run lint`를 실행합니다.
- public utility의 동작을 바꾸면 `docs/`에 문서화합니다.

# repo-root/services/payments/AGENTS.override.md

## 결제 서비스 규칙

- `npm test` 대신 `make test-payments`를 사용합니다.
- 보안 채널에 알리지 않고 API key를 교체하지 않습니다.

파일이 의도대로 로드되는지 확인하려면 대상 디렉터리에서 다음 명령을 실행합니다.

codex --ask-for-approval never "Summarize the current instructions."

업데이트할 때

AGENTS.md는 처음부터 길게 만들기보다 실제 작업에서 반복되는 피드백을 반영하며 키우는 것이 좋습니다. 특히 다음 상황에서는 지침을 추가하거나 다듬습니다.

• 반복되는 실수: Codex가 같은 실수를 반복한다면 규칙을 추가합니다.
• 불필요하게 많은 파일 읽기: Codex가 올바른 파일을 찾기는 하지만 너무 많은 문서를 읽는다면, 먼저 확인해야 할 디렉터리나 파일을 안내합니다.
• 반복되는 PR 피드백: 같은 리뷰 코멘트를 두 번 이상 남기게 된다면 규칙으로 정리합니다.
• GitHub에서의 요청: pull request 댓글에서 @codex를 태그하고, 예를 들어 @codex add this to AGENTS.md처럼 요청하면 클라우드 작업으로 업데이트를 위임할 수 있습니다.
• 지침 누락 점검 자동화: 자동화를 사용해 정기적으로 지침의 빈틈을 확인하고, AGENTS.md에 추가할 내용을 제안하게 할 수 있습니다.

규칙을 추가할 때는 그 지침이 적용되는 가장 가까운 디렉터리에 파일을 둡니다. 팀 전체가 따라야 하는 내용은 저장소 루트에 두고, 한 패키지나 서비스에만 필요한 내용은 해당 하위 디렉터리에 둡니다.

대체 파일 이름 사용자화

저장소가 이미 다른 파일 이름, 예를 들어 TEAM_GUIDE.md를 사용한다면 fallback 목록에 추가해 Codex가 지침 파일처럼 취급하게 합니다.

1. Codex 구성을 편집합니다.

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536
   

2. Codex를 다시 시작하거나 새 명령을 실행해 업데이트된 구성이 로드되게 합니다.

이제 Codex는 각 디렉터리에서 AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md 순서로 확인합니다. 이 목록에 없는 파일 이름은 지침 발견 과정에서 무시됩니다. 더 큰 byte 제한은 잘림 전에 더 많은 결합 지침을 허용합니다.

fallback 목록을 설정하면 Codex는 대체 파일도 지침으로 취급합니다.

repo-root/
├── TEAM_GUIDE.md       # fallback 목록으로 감지됨
├── .agents.md          # 루트 fallback 파일
└── support/
    ├── AGENTS.override.md # fallback 지침을 override함
    └── playbooks/

프로젝트별 자동화 사용자처럼 다른 profile을 원할 때는 CODEX_HOME 환경 변수를 설정합니다.

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

예상 결과: 출력이 사용자 지정 .codex 디렉터리를 기준으로 파일을 나열합니다.

설정 확인

• 저장소 루트에서 codex --ask-for-approval never "Summarize the current instructions."를 실행합니다. Codex는 전역과 프로젝트 파일의 지침을 우선순위 순서로 요약해야 합니다.
• 중첩 override가 넓은 규칙을 대체하는지 확인하려면 codex --cd subdir --ask-for-approval never "Show which instruction files are active."를 사용합니다.
• 어떤 지침 파일이 로드되었는지 감사해야 한다면 세션 후 ~/.codex/log/codex-tui.log 또는 세션 logging을 켠 경우 가장 최근 session-*.jsonl 파일을 확인합니다.
• 지침이 오래된 것처럼 보이면 대상 디렉터리에서 Codex를 다시 시작합니다. Codex는 모든 실행과 각 TUI 세션 시작 때 지침 체인을 다시 만들므로 수동으로 지울 cache는 없습니다.

발견 문제 해결

• 아무것도 로드되지 않음: 의도한 저장소에 있는지, codex status가 예상한 workspace root를 보고하는지 확인합니다. 지침 파일에 내용이 있는지도 확인합니다. Codex는 빈 파일을 무시합니다.
• 잘못된 지침이 나타남: 디렉터리 트리 위쪽이나 Codex 홈 아래에 AGENTS.override.md가 있는지 찾습니다. 일반 파일로 fallback하려면 override 파일의 이름을 바꾸거나 제거합니다.
• Codex가 fallback 이름을 무시함: project_doc_fallback_filenames에 오타 없이 이름을 나열했는지 확인한 뒤 Codex를 다시 시작해 업데이트된 구성이 적용되게 합니다.
• 지침이 잘림: project_doc_max_bytes를 높이거나 큰 파일을 중첩 디렉터리로 나눠 중요한 지침이 유지되게 합니다.
• profile 혼동: Codex를 시작하기 전에 echo $CODEX_HOME을 실행합니다. 기본값이 아닌 값은 Codex가 편집한 홈 디렉터리와 다른 홈 디렉터리를 가리킨다는 뜻입니다.

다음 단계

• 자세한 내용은 공식 AGENTS.md 웹사이트를 참고하십시오.
• 지속 지침과 함께 쓰기 좋은 대화 패턴은 Codex 프롬프트 작성을 검토하십시오.