Codex AGENTS.md 작성법: 프로젝트 규칙 설정하는 방법

Codex AGENTS.md는 프로젝트를 열 때마다 반복해서 설명하던 빌드 명령, 코드 스타일, 수정 금지 영역과 완료 기준을 저장소에 남기는 지침 파일입니다. 잘 작성하면 Codex가 엉뚱한 패키지 관리자를 사용하거나 테스트를 빠뜨리는 일을 줄일 수 있지만, 너무 길거나 모호한 규칙은 오히려 충돌을 만듭니다. 프로젝트 루트에서 시작해 하위 디렉터리 규칙을 나누고 실제로 로드됐는지 확인하는 방법까지 설명합니다.

AGENTS.md란 무엇인가

AGENTS.md는 Codex가 작업을 시작하기 전에 읽는 지속적인 프로젝트 지침입니다. 개발자가 매번 프롬프트에 붙여 넣지 않아도 저장소의 작업 방식, 검증 명령과 주의사항을 알려줄 수 있습니다. 코드와 함께 버전 관리하면 팀원이 같은 기본 규칙을 공유하고 변경 이유도 검토할 수 있습니다.

정보	AGENTS.md에 적합한가	이유
패키지 관리자·빌드 명령	적합	모든 작업에서 반복되는 실행 기준
테스트·린트 완료 조건	적합	결과를 명령으로 검증 가능
디렉터리별 아키텍처 규칙	적합	변경 범위와 의존 방향을 안내
API 키·비밀번호	부적합	저장소와 프롬프트에 비밀값 노출
한 번만 필요한 작업 요구사항	대체로 부적합	이슈·현재 프롬프트에 두는 편이 명확
실행 권한 자체	부적합	샌드박스·승인 설정으로 통제해야 함

Codex가 AGENTS.md를 찾는 순서

OpenAI Docs에 따르면 Codex는 세션을 시작할 때 지침 체인을 한 번 구성합니다. 먼저 Codex 홈의 전역 지침을 확인하고, 프로젝트 루트부터 현재 작업 디렉터리까지 내려오면서 각 디렉터리의 지침을 연결합니다. 현재 작업 위치에 가까운 파일이 나중에 추가되므로 더 구체적인 규칙으로 앞선 지침을 재정의할 수 있습니다.

1. 전역: 기본적으로 ~/.codex/AGENTS.override.md가 있으면 이를 읽고, 없으면 ~/.codex/AGENTS.md를 읽습니다.
2. 프로젝트: 일반적으로 Git 루트에서 현재 디렉터리까지 경로를 따라 확인합니다.
3. 디렉터리별: AGENTS.override.md, AGENTS.md, 설정된 대체 파일 이름 순으로 비어 있지 않은 파일 하나를 선택합니다.
4. 병합: 루트 규칙부터 가까운 디렉터리 규칙까지 순서대로 합칩니다.

가장 빠르게 시작하는 방법

Codex CLI에서 프로젝트를 열고 /init을 사용하면 시작용 AGENTS.md를 만들 수 있습니다. 자동 생성된 내용은 완성본이 아니므로 실제 스크립트와 저장소 정책을 대조해 불필요한 문장을 지우고 완료 조건을 보강하세요. 직접 만든다면 저장소 루트에 AGENTS.md 파일을 추가하면 됩니다.

# AGENTS.md

## Project overview
- This repository is a Next.js application using TypeScript.
- Use pnpm. Do not create npm or yarn lockfiles.

## Working rules
- Keep changes limited to the requested feature.
- Follow existing patterns before adding abstractions.
- Do not change public APIs without explaining compatibility impact.

## Validation
- Run `pnpm run lint` after code changes.
- Run `pnpm build` before marking the task complete.
- Report commands run, results, and any checks not run.

프로젝트가 한국어 문서와 팀 커뮤니케이션을 사용한다면 지침도 한국어로 작성할 수 있습니다. 중요한 것은 언어보다 명령과 기대 결과가 실제 저장소와 정확히 일치하는지입니다.

15분 안에 프로젝트용 AGENTS.md 작성하는 순서

프로젝트용 AGENTS.md 템플릿 내려받기

1. 저장소 루트를 확인합니다. git rev-parse --show-toplevel로 Codex가 기준으로 삼을 루트가 맞는지 확인합니다.
2. 실제 명령을 찾습니다. README, package.json, Gradle·Maven 파일과 CI 설정에서 설치·lint·test·build 명령을 확인합니다.
3. 변경 경계를 적습니다. 생성하면 안 되는 lockfile, 수정 금지 디렉터리, 공개 API와 데이터베이스 변경 조건을 명시합니다.
4. 검증 조건을 적습니다. “테스트한다”가 아니라 실행할 명령과 실패 시 보고 방식을 적습니다.
5. 보안 규칙을 분리합니다. 비밀값, 개인정보, 운영 명령과 외부 네트워크 사용 기준을 짧게 작성합니다.
6. 로드 결과를 확인합니다. 새 세션에서 활성 지침을 요약하게 하고 원본 파일과 대조합니다.

AGENTS.md 품질을 점검하는 6가지 기준

기준	통과 질문	실패할 때 수정
정확성	명령과 경로가 현재 저장소에 실제로 존재하는가	README·CI·빌드 파일과 대조
판정 가능성	준수 여부를 diff나 명령 결과로 확인할 수 있는가	추상 표현을 구체적인 결과로 변경
적용 범위	저장소 전체 규칙과 서비스 전용 규칙이 분리됐는가	가장 가까운 하위 디렉터리로 이동
충돌 방지	상위 규칙과 다를 때 무엇이 우선인지 명확한가	override 이유와 예외 범위 기록
안전성	비밀값·운영 명령·외부 전송의 경계가 있는가	금지 항목과 승인 조건 추가
유지보수	도구나 구조 변경 시 함께 고칠 담당 지점이 있는가	관련 PR 체크리스트에 포함

각 기준을 단순히 “있음”으로 표시하지 말고 대표 작업 하나로 시험하세요. 예를 들어 패키지 관리자를 pnpm으로 제한했다면 Codex가 npm 명령을 제안하지 않는지, 하위 서비스에서는 지정된 테스트 명령을 우선하는지 확인해야 합니다.

좋은 프로젝트 규칙의 7가지 구성

1. 프로젝트 개요: 프레임워크, 런타임과 주요 디렉터리를 두세 문장으로 설명합니다.
2. 도구: 패키지 관리자, 포맷터와 빌드 도구를 명시합니다.
3. 변경 범위: 수정 가능한 영역과 생성하면 안 되는 파일을 구분합니다.
4. 코드 규칙: 기존 패턴, 타입, 오류 처리와 호환성 기준을 적습니다.
5. 검증: lint, typecheck, 단위·통합 테스트 명령을 적습니다.
6. 보안: 비밀값, 개인정보, 네트워크와 배포 시 주의사항을 설명합니다.
7. 완료 보고: 변경 파일, 실행한 검사와 남은 위험을 보고하게 합니다.

모호한 문장을 검증 가능한 규칙으로 바꾸기

피할 문장	개선한 문장
코드를 깔끔하게 작성한다	기존 모듈 경계를 유지하고 새 공개 API에는 타입을 작성한다
테스트를 충분히 한다	변경된 패키지의 unit test와 루트의 pnpm run lint를 실행한다
보안에 주의한다	.env 파일을 읽거나 출력하지 않고 새 네트워크 호출은 사전 승인을 받는다
최신 방식을 사용한다	현재 lockfile 버전을 유지하며 새 의존성은 승인 없이 추가하지 않는다
UI를 예쁘게 만든다	기존 디자인 토큰을 사용하고 375px와 1280px 레이아웃을 확인한다

React·Next.js 프로젝트 예시

# AGENTS.md

## Frontend conventions
- Use existing components in `components/` before creating a new primitive.
- Keep server and client components separated; add `use client` only when required.
- Preserve keyboard navigation and visible focus states.
- Prevent horizontal overflow at a 375px viewport.

## Validation
- Run `pnpm run lint`.
- Run `pnpm build`.
- For UI changes, verify loading, empty, error, and mobile states.

## Dependencies
- Use pnpm only.
- Ask before adding a production dependency.

“React 모범 사례를 사용한다”보다 현재 프로젝트에서 실제로 지켜야 하는 서버·클라이언트 경계, 모바일 너비와 검증 명령을 적는 편이 결과를 평가하기 쉽습니다.

Java·Spring 백엔드 예시

# AGENTS.md

## Backend conventions
- Target the Java version declared in the build file.
- Keep controller, service, and repository responsibilities separate.
- Do not change response fields or database schemas without a migration note.
- Never log credentials, tokens, or personal data.

## Validation
- Run `./gradlew test` for code changes.
- Run the configured static analysis task when available.
- Add a regression test for every bug fix.

## Operations
- Do not run production migrations or deployment commands.
- Ask before changing infrastructure or external service configuration.

Java 버전을 숫자로 고정해서 적기 전에 실제 빌드 파일과 CI 버전을 확인하세요. 저장소가 업그레이드되면 AGENTS.md도 같은 풀 리퀘스트에서 갱신해야 오래된 지침이 남지 않습니다.

모노레포에서 하위 규칙 나누기

프론트엔드와 서버가 함께 있는 모노레포에 모든 규칙을 루트 파일 하나로 넣으면 서로 관련 없는 지침까지 매 작업에 포함됩니다. 루트에는 공통 규칙을 두고 패키지 가까이에 전용 규칙을 배치하세요.

repository/
├── AGENTS.md
├── apps/
│   └── web/
│       └── AGENTS.md
└── services/
    └── payments/
        └── AGENTS.override.md

루트 AGENTS.md에는 브랜치, 패키지 관리자와 공통 보안 정책을 둡니다. apps/web/AGENTS.md에는 UI·접근성·브라우저 테스트를, services/payments/AGENTS.override.md에는 결제 서비스 전용 테스트와 절대 수행하면 안 되는 운영 작업을 둡니다.

AGENTS.md와 AGENTS.override.md 차이

같은 디렉터리에 두 파일이 모두 있으면 Codex는 AGENTS.override.md를 먼저 확인합니다. override는 기본 파일을 잠시 또는 특정 영역에서 대체해야 할 때 유용하지만, 존재 사실을 놓치면 “AGENTS.md를 수정했는데 반영되지 않는다”는 혼란이 생길 수 있습니다.

• 일상적인 공유 규칙은 AGENTS.md에 둡니다.
• 일시적인 전역 대체나 명확한 서비스별 예외에만 AGENTS.override.md를 사용합니다.
• 왜 대체하는지와 제거 조건을 파일 안에 기록합니다.
• 중복 규칙을 두 파일에 복사하지 않습니다.

전역 AGENTS.md는 무엇을 적을까

~/.codex/AGENTS.md는 모든 저장소에서 반복하는 개인 작업 선호에 적합합니다. 특정 회사의 빌드 명령이나 한 프로젝트의 아키텍처는 전역 파일에 넣지 마세요.

# ~/.codex/AGENTS.md

## Working agreements
- Inspect the repository instructions before editing files.
- Prefer the package manager selected by the existing lockfile.
- Ask before adding production dependencies.
- Preserve unrelated user changes in a dirty worktree.
- Summarize validation results and remaining risks.

코드 리뷰 규칙 작성하기

Codex 코드 리뷰에서 반드시 확인할 도메인 규칙은 적용 대상 코드와 가장 가까운 AGENTS.md의 ## Code Review Rules 섹션에 둘 수 있습니다. 일반적인 포맷 검사까지 길게 복사하기보다 CI가 찾기 어려운 비즈니스 위험과 안전한 대안을 작성하세요.

## Code Review Rules

### Authentication
- Flag routes that read user data without the existing authorization helper.
- Safe path: reuse `requireUser()` and add a forbidden-access test.

### Database changes
- Flag destructive schema changes without a staged migration plan.
- Safe path: use an additive migration before removing old fields.

AGENTS.md에 넣지 말아야 할 것

• API 키, 토큰, 비밀번호와 실제 고객 데이터
• 실행할 수 없거나 현재 저장소에 존재하지 않는 명령
• “항상 완벽하게”, “최대한 좋게”처럼 판정할 수 없는 표현
• README와 개발 문서를 그대로 복사한 긴 설명
• 서로 충돌하면서 우선순위를 설명하지 않은 규칙
• 도구의 샌드박스와 승인을 대신한다고 오해할 수 있는 권한 문장
• 이번 작업에서만 필요한 이슈 세부 요구사항

AGENTS.md는 신뢰할 수 있는 프로젝트 지침이지 보안 경계가 아닙니다. 파일에 “배포하지 말 것”이라고 적는 것과 별개로 배포 자격증명, 네트워크와 명령 권한을 기술적으로 제한해야 합니다.

Codex가 지침을 읽었는지 확인하기

파일을 만들었으면 예상대로 로드되는지 확인해야 합니다. 공식 문서는 저장소 루트와 하위 디렉터리에서 다음과 같은 확인 명령을 제시합니다.

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

codex --cd services/payments --ask-for-approval never \
  "Show which instruction files are active."

1. 전역 지침과 루트 지침이 예상 순서로 표시되는지 확인합니다.
2. 하위 디렉터리에서 실행했을 때 가까운 규칙이 추가되는지 확인합니다.
3. override 파일이 일반 파일을 대체하는지 확인합니다.
4. 실제 코드 변경 없이 검증 명령과 금지 영역을 다시 말하게 합니다.
5. 파일을 수정했다면 새 세션을 시작해 지침 체인을 다시 구성합니다.

AGENTS.md가 적용되지 않을 때

증상	확인할 원인	해결 방법
아무 지침도 표시되지 않음	잘못된 작업 위치·빈 파일	워크스페이스 루트와 파일 내용을 확인
수정한 내용이 반영되지 않음	세션 시작 후 파일 수정	대상 디렉터리에서 Codex를 다시 시작
다른 규칙이 적용됨	상위 경로의 override 파일	전역부터 현재 경로까지 파일을 감사
하위 AGENTS.md가 무시됨	같은 위치에 override 존재	override 내용과 필요 여부 확인
뒤쪽 규칙이 잘림	결합 문서 크기 한도	규칙을 줄이거나 디렉터리별로 분리
다른 홈 지침을 읽음	CODEX_HOME 변경	현재 환경 변수와 실제 설정 위치 확인

대체 파일 이름과 크기 설정

팀이 이미 TEAM_GUIDE.md 같은 문서를 사용한다면 ~/.codex/config.toml의 대체 이름 목록에 추가할 수 있습니다. 기본 크기가 부족한 경우 한도를 조정할 수도 있지만, 먼저 불필요한 설명을 줄이는 편이 좋습니다.

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

이 설정을 바꾸면 새 세션을 시작해 로드 결과를 다시 확인하세요. 대체 이름은 각 디렉터리에서 override와 기본 AGENTS.md 다음 순서로 검사됩니다.

AGENTS.md, 스킬, MCP는 어떻게 다른가

기능	주요 역할	예시
AGENTS.md	프로젝트에 지속 적용할 규칙과 맥락	빌드·테스트·코드 리뷰 기준
스킬	특정 작업을 수행하는 재사용 절차	릴리스 노트 작성·보안 검토 절차
MCP	외부 도구와 데이터 연결	문서 검색·브라우저·이슈·디자인
현재 프롬프트	이번 작업의 목표와 완료 조건	특정 버그 수정·기능 구현

AGENTS.md에 외부 서비스 연결법을 모두 넣기보다 Codex MCP 서버 연결 가이드처럼 연결 설정은 MCP 구성에서 관리하고, AGENTS.md에는 언제 어떤 도구를 사용하거나 사용하지 말아야 하는지 적는 편이 명확합니다.

팀에서 유지하는 방법

1. 처음에는 반복적으로 지적되는 규칙 5~10개만 작성합니다.
2. 코드 리뷰에서 같은 문제가 반복되면 검증 가능한 문장으로 추가합니다.
3. 빌드·CI·디렉터리 구조를 바꾸는 PR에서 AGENTS.md도 함께 검토합니다.
4. 규칙마다 담당 영역과 실제 확인 명령이 있는지 점검합니다.
5. 분기마다 사용하지 않는 규칙과 중복 설명을 삭제합니다.
6. 새 팀원이 읽어도 명령과 금지 범위를 이해할 수 있는지 확인합니다.

편집부 결론

좋은 Codex AGENTS.md는 길고 정교한 프롬프트가 아니라 프로젝트의 실제 작업 계약에 가깝습니다. 저장소 전체 규칙은 루트에, 서비스별 차이는 가까운 디렉터리에 두고 빌드·테스트·보안·보고 기준을 확인 가능한 문장으로 작성하세요.

이 글은 2026년 9월 9일 OpenAI Docs를 다시 대조해 갱신했으며 특정 저장소에서 모든 규칙의 효과를 장기간 측정한 사용 후기는 아닙니다. Codex 버전과 프로젝트 구조가 달라지면 탐색 결과도 확인해야 하므로 새 규칙을 추가할 때마다 로드 순서와 대표 작업을 다시 시험하세요.

공식 문서와 함께 읽을 글

OpenAI Codex AGENTS.md 공식 문서 확인하기

Codex CLI 공식 사용법 확인하기

Codex CLI 설치부터 프로젝트 실행까지 따라하기

Claude Code CLAUDE.md 프로젝트 규칙과 비교하기

Codex CLI 오류와 설정 문제 해결하기

Windows에 Codex 앱과 CLI 설치하기

Codex로 PR을 검토하고 버그 찾기

Codex Skills로 반복 개발 업무 자동화하기

Codex MCP 서버로 외부 개발 도구 연결하기

Codex와 Claude Code의 프로젝트 지침 비교하기

AI 코딩 에이전트 4종 비교하기

자주 묻는 질문

AGENTS.md 파일은 어디에 만들어야 하나요?

저장소 전체 규칙은 일반적으로 Git 루트의 AGENTS.md에 만듭니다. 특정 앱이나 서비스에만 적용할 규칙은 해당 디렉터리에 더 가까운 AGENTS.md로 나누세요.

Codex가 AGENTS.md를 자동으로 읽나요?

Codex는 작업 시작 시 전역 위치와 프로젝트 루트부터 현재 디렉터리까지 지침 파일을 탐색합니다. 빈 파일은 무시되므로 로드 확인 명령으로 실제 적용 여부를 검사하세요.

AGENTS.md와 AGENTS.override.md의 차이는 무엇인가요?

같은 디렉터리에서는 AGENTS.override.md가 우선합니다. 기본 지침을 일시적으로 또는 명확한 하위 영역에서 대체할 때 사용하고 불필요해지면 제거하세요.

AGENTS.md는 한국어로 작성해도 되나요?

가능합니다. 언어보다 실제 파일 경로, 명령과 완료 조건이 정확하고 모호하지 않은지가 중요합니다.

AGENTS.md에 API 키를 넣어도 되나요?

넣으면 안 됩니다. 저장소에 커밋되거나 모델 컨텍스트에 포함될 수 있으므로 비밀값은 환경 변수와 전용 시크릿 관리 도구에서 관리하세요.

파일을 수정했는데 Codex가 이전 규칙을 따르는 이유는 무엇인가요?

지침 체인은 일반적으로 세션을 시작할 때 구성됩니다. 대상 디렉터리에서 새 Codex 세션을 시작하고 상위 경로의 override 파일도 확인하세요.

AGENTS.md가 길수록 결과가 좋아지나요?

그렇지 않습니다. 충돌과 오래된 정보가 늘 수 있고 결합 크기 한도에 도달할 수 있습니다. 반복되는 핵심 규칙만 남기고 디렉터리별로 나누는 편이 좋습니다.

AGENTS.md가 샌드박스나 권한 설정을 대신하나요?

아닙니다. AGENTS.md는 행동 지침이며 기술적인 보안 경계가 아닙니다. 파일 쓰기, 명령, 네트워크와 외부 시스템 권한은 별도 설정과 승인 절차로 제한해야 합니다.