AGENTS.md로 프로젝트 규칙 전달하기
매번 "pnpm만 사용하고 기존 변경을 보존해줘"라고 설명한다면 프로젝트 지침으로 정리할 수 있습니다. Codex는 작업 전에 AGENTS.md 계열 파일에서 지침을 읽습니다. 다만 파일 이름만 만들면 저장소의 모든 하위 지침이 언제나 적용된다고 가정해서는 안 됩니다.
이 글은 공식 발견 규칙을 한국어로 설명하는 비공식 가이드입니다. 아래 파일 내용은 자체 예제이며 실제 세션에서 로딩을 시험하지 않았습니다.
시작 위치가 중요합니다
공식 문서가 설명하는 기본 순서는 다음과 같습니다.
- Codex 홈 디렉터리의 전역 지침을 찾습니다. 기본 경로는
~/.codex이며CODEX_HOME으로 바뀔 수 있습니다. - 프로젝트 루트에서 현재 작업 디렉터리까지 경로를 따라 지침을 찾습니다. 프로젝트 루트를 찾지 못하면 현재 디렉터리만 확인합니다.
- 넓은 범위에서 가까운 디렉터리 순으로 합치며, 더 가까운 지침이 뒤에 놓입니다.
각 디렉터리에서는 비어 있지 않은 AGENTS.override.md를 우선하고, 없으면 AGENTS.md, 이어 설정된 fallback 이름을 확인합니다. 한 디렉터리에서 여러 파일을 전부 합치는 방식이 아닙니다.
작은 예제로 보면
practice-project/
AGENTS.md
packages/
web/
AGENTS.override.md
README.md
packages/web에서 세션을 시작한다면 프로젝트 루트의 규칙과 web 쪽 override가 발견 경로에 포함됩니다. 루트에서 시작했다고 이 발견 단계가 모든 하위 폴더를 재귀적으로 읽는다고 가정하지 마세요. 실제 작업 디렉터리를 먼저 확인하고, 적용 범위가 중요한 하위 작업은 그 위치와 지침을 명시합니다.
무엇을 적으면 좋은가
규칙은 실행 가능한 명령과 승인 경계를 중심으로 짧게 씁니다. 다음은 pnpm을 사용하는 합성 프로젝트의 예제입니다. 본인 프로젝트에 해당 명령이 있는지 먼저 확인하세요.
# Project agreements
- 의존성 설치와 스크립트 실행은 pnpm만 사용한다.
- 변경 전 git status로 기존 수정 파일을 확인하고 보존한다.
- 동작 변경에는 실패 재현 테스트를 먼저 추가한다.
- pnpm test와 pnpm build의 실제 결과를 보고한다.
- 의존성 추가, 외부 게시, push, 데이터 삭제는 먼저 승인받는다.
- 실행하지 못한 검증은 완료라고 표시하지 않는다.
비밀번호·API 키·내부 고객 자료는 넣지 않습니다. 이 파일은 모델이 읽을 지침이지 비밀값 저장소가 아닙니다. 관리자 정책이나 샌드박스를 해제할 수 있는 권한 파일도 아닙니다.
규칙이 적용되지 않는다면
현재 디렉터리, 프로젝트 루트, CODEX_HOME 설정을 확인합니다. 예상하지 못한 override가 일반 파일보다 먼저 선택되는지도 살펴보세요. 조직의 관리 정책이 더 강한 제한을 적용할 수 있습니다.
공식 문서는 지침 전체 크기에 project_doc_max_bytes 한도가 있다고 설명합니다. 긴 문서를 통째로 넣기보다 꼭 지켜야 하는 규칙과 상세 문서 경로를 남기는 편이 읽기 쉽습니다. 이 글에서는 기본값 숫자에 맞춰 규칙을 늘리기보다 필요한 내용만 유지할 것을 권합니다.
Codex는 실행 시작 시 지침 체인을 구성합니다. 파일을 수정한 뒤 같은 세션에 즉시 반영되었다고 단정하지 말고 새 세션에서 적용 경로를 확인하세요. 모델에게 읽은 지침을 설명해 달라고 요청하는 것 역시 AI 작업이며, 그 응답만으로 접근 통제가 증명되는 것은 아닙니다.
지침과 권한은 별개
"절대 삭제하지 마"라는 지침은 의도를 전달하지만 OS 수준의 차단을 보장하지 않습니다. 실제 제한은 권한과 샌드박스에서 확인합니다. 팀 규칙을 바꿀 때는 지침 파일 자체의 diff도 리뷰하고, 기존 승인 없이 자동으로 외부 작업을 허용하는 문구가 추가되지 않았는지 확인하세요.
공식 한국어 도움말: ChatGPT 플랜과 Codex에서 계정별 이용 안내를 확인할 수 있습니다. 이 글은 해당 도움말의 공식 번역이 아니며, 계정 조건과 요금은 공식 안내를 우선합니다.