ChatGPT 문서
한국어
문의 goolvyouyou@gmail.com

AGENTS.md를 사용한 사용자 지정 지침

프로젝트에 관한 추가 지침과 컨텍스트를 Codex에 제공하세요

Codex는 작업을 시작하기 전에 AGENTS.md 파일을 읽습니다. 전역 지침 위에 프로젝트별 재정의를 계층화하면 어떤 리포지토리를 열더라도 일관된 기준으로 각 작업을 시작할 수 있습니다.

Codex가 지침을 검색하는 방식

Codex는 시작할 때 지침 체인을 구성합니다(실행당 한 번이며, TUI에서는 일반적으로 세션을 시작할 때마다 한 번입니다). 검색에는 다음 우선순위가 적용됩니다.

  1. 전역 범위: Codex 홈 디렉터리(CODEX_HOME을 설정하지 않은 경우 기본값은 ~/.codex)에서 AGENTS.override.md이 있으면 Codex가 이를 읽습니다. 그렇지 않으면 Codex는 AGENTS.md을 읽습니다. Codex는 이 수준에서 비어 있지 않은 첫 번째 파일만 사용합니다.
  2. 프로젝트 범위: Codex는 프로젝트 루트(일반적으로 Git 루트)에서 시작해 현재 작업 디렉터리까지 내려갑니다. 프로젝트 루트를 찾을 수 없으면 현재 디렉터리만 확인합니다. 경로에 있는 각 디렉터리에서 AGENTS.override.md, AGENTS.md, project_doc_fallback_filenames에 지정된 대체 이름 순으로 확인합니다. Codex는 디렉터리마다 최대 하나의 파일만 포함합니다.
  3. 병합 순서: Codex는 루트부터 아래로 파일을 이어 붙이고 파일 사이에 빈 줄을 삽입합니다. 현재 디렉터리에 가까운 파일은 결합된 프롬프트에서 나중에 나오므로 앞선 지침을 재정의합니다.

Codex는 빈 파일을 건너뛰며, 결합된 크기가 project_doc_max_bytes에 정의된 제한(기본값 32 KiB)에 도달하면 파일 추가를 중단합니다. 이러한 설정에 관한 자세한 내용은 프로젝트 지침 검색을 참조하세요. 제한에 도달하면 제한을 늘리거나 중첩된 디렉터리에 지침을 나누어 배치하세요.

전역 지침 만들기

모든 리포지토리가 작업 규칙을 상속하도록 Codex 홈 디렉터리에 영구 기본값을 만드세요.

  1. 디렉터리가 있는지 확인합니다.

    mkdir -p ~/.codex

  2. 재사용할 기본 설정을 담은 ~/.codex/AGENTS.md을 만듭니다.

    # ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

  3. 아무 위치에서나 Codex를 실행하여 파일이 로드되는지 확인합니다.

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

    예상 결과: Codex가 작업을 제안하기 전에 ~/.codex/AGENTS.md의 항목을 인용합니다.

기본 파일을 삭제하지 않고 전역 설정을 일시적으로 재정의해야 할 때는 ~/.codex/AGENTS.override.md을 사용하세요. 공유 지침을 복원하려면 재정의 파일을 제거하세요.

프로젝트 지침 계층화하기

리포지토리 수준 파일을 사용하면 Codex가 전역 기본값을 계속 상속하면서도 프로젝트 규칙을 파악할 수 있습니다.

  1. 리포지토리 루트에 기본 설정을 다루는 AGENTS.md을 추가합니다.

    # AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

  2. 특정 팀에 다른 규칙이 필요하면 중첩된 디렉터리에 재정의를 추가합니다. 예를 들어 services/payments/ 안에 AGENTS.override.md을 만듭니다.

    # services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

  3. payments 디렉터리에서 Codex를 시작합니다.

    codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

    예상 결과: Codex가 전역 파일을 첫 번째로, 리포지토리 루트의 AGENTS.md을 두 번째로, payments 재정의를 마지막으로 표시합니다.

Codex는 현재 디렉터리에 도달하면 검색을 중단하므로, 재정의는 전문 작업이 이루어지는 위치에 최대한 가깝게 배치하세요.

다음은 전역 파일과 payments 전용 재정의를 추가한 후의 리포지토리 예시입니다.

<FileTree class="mt-4" tree={[ { name: "AGENTS.md", comment: "리포지토리 작업 기준", highlight: true, }, { name: "services/", open: true, children: [ { name: "payments/", open: true, children: [ { name: "AGENTS.md", comment: "재정의가 있으므로 무시됨", }, { name: "AGENTS.override.md", comment: "Payments 서비스 규칙", highlight: true, }, { name: "README.md" }, ], }, { name: "search/", children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }], }, ], }, ]} />

코드 리뷰 규칙 추가하기

GitHub의 Codex 코드 리뷰를 사용하려면 규칙이 적용되는 코드와 가장 가까운 AGENTS.md에 ## Code Review Rules 섹션을 추가하세요. 리포지토리 전체에 적용되는 검사는 루트에 배치하고 서비스별 검사는 중첩된 파일에 배치하세요.

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

규칙은 간결하게 유지하고, 지적할 동작과 안전한 처리 방법 또는 예외를 설명하세요. 형식 지정 및 린트 검사는 CI에서 처리하세요. 설정 및 규칙 작성 지침은 Codex의 리뷰 대상 사용자 지정을 참조하세요.

대체 파일 이름 사용자 지정하기

리포지토리에서 이미 다른 파일 이름(예: TEAM_GUIDE.md)을 사용하고 있다면 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 순으로 확인합니다. 이 목록에 없는 파일 이름은 지침 검색에서 무시됩니다. 바이트 제한이 커졌으므로 잘리기 전에 더 많은 지침을 결합할 수 있습니다.

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

<FileTree class="mt-4" tree={[ { name: "TEAM_GUIDE.md", comment: "대체 목록을 통해 감지됨", highlight: true, }, { name: ".agents.md", comment: "루트의 대체 파일", }, { name: "support/", open: true, children: [ { name: "AGENTS.override.md", comment: "대체 지침을 재정의함", highlight: true, }, { name: "playbooks/", children: [{ name: "…", placeholder: true }], }, ], }, ]} />

프로젝트별 자동화 사용자처럼 다른 프로필을 사용하려면 CODEX_HOME 환경 변수를 설정하세요.

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

예상 결과: 출력에 사용자 지정 .codex 디렉터리를 기준으로 한 상대 경로의 파일 목록이 표시됩니다.

설정 확인하기

  • 리포지토리 루트에서 codex --ask-for-approval never "Summarize the current instructions."을 실행합니다. Codex가 전역 및 프로젝트 파일의 지침을 우선순위에 따라 출력해야 합니다.
  • codex --cd subdir --ask-for-approval never "Show which instruction files are active."을 사용하여 중첩된 재정의가 더 광범위한 규칙을 대체하는지 확인합니다.
  • Codex가 로드한 지침 파일을 확인하려면 codex -c log_dir=./.codex-log을 사용하여 일반 텍스트 TUI 로그를 활성화하고 ./.codex-log/codex-tui.log을 확인하세요. 세션 로깅을 활성화했다면 가장 최근의 session-*.jsonl 파일을 확인해도 됩니다.
  • 지침이 오래된 것처럼 보이면 대상 디렉터리에서 Codex를 다시 시작하세요. Codex는 실행할 때마다(TUI 세션을 시작할 때도) 지침 체인을 다시 구성하므로 수동으로 지울 캐시는 없습니다.

지침 검색 문제 해결하기

  • 아무것도 로드되지 않음: 의도한 리포지토리에 있는지, 그리고 codex status이 예상한 워크스페이스 루트를 표시하는지 확인하세요. 지침 파일에 내용이 있는지도 확인하세요. Codex는 빈 파일을 무시합니다.
  • 잘못된 지침이 표시됨: 디렉터리 트리의 상위 위치나 Codex 홈 아래에 AGENTS.override.md이 있는지 확인하세요. 일반 파일로 되돌아가려면 재정의 파일의 이름을 바꾸거나 제거하세요.
  • Codex가 대체 이름을 무시함: project_doc_fallback_filenames에 이름을 오타 없이 나열했는지 확인한 다음, 업데이트된 구성이 적용되도록 Codex를 다시 시작하세요.
  • 지침이 잘림: project_doc_max_bytes을 늘리거나 큰 파일을 중첩된 디렉터리에 나누어 배치하여 중요한 지침이 온전히 유지되도록 하세요.
  • 프로필 혼동: Codex를 시작하기 전에 echo $CODEX_HOME을 실행하세요. 기본값이 아닌 값이 표시되면 Codex는 편집한 홈 디렉터리와 다른 홈 디렉터리를 사용합니다.

다음 단계

  • 자세한 내용은 공식 AGENTS.md 웹사이트를 참조하세요.
  • 영구 지침과 함께 사용하기 좋은 대화 패턴은 Codex 프롬프팅에서 확인하세요.