AGENTS.md — Codex에 프로젝트 규칙 알려 주기 · CLI Academy

AGENTS.md는 Codex가 상속받는 프로젝트 안내서야

Codex는 전역 ~/.codex/AGENTS.md와 Git 루트부터 현재 디렉터리까지의 AGENTS.md를 차례로 읽어 합쳐. 작업 위치에 가까운 문서가 더 구체적인 규칙을 덧붙이므로 루트 내용을 하위 문서에 복사할 필요가 없어.

AGENTS.override.md는 같은 위치의 일반 문서보다 우선해. migration 기간이나 이번 sprint처럼 기한이 있는 규칙을 넣었다가 끝나면 파일째 없애기 좋아. 기존 팀 문서 이름을 유지하려면 project_doc_fallback_filenames에 등록하고, 너무 큰 문서가 통째로 문맥을 잡아먹지 않게 최대 크기도 정할 수 있어.

직접 확인할 항목: .agents.md, AI_GUIDE.md, TEAM_GUIDE.md, config.toml, project_doc_max_bytes.

Code

실전 AGENTS.md 예시·markdown

# AGENTS.md — Project Root

## What this is
TypeScript microservices API on Node 22 + Postgres 16, gRPC between
services, JWT RS256 auth.

## Setup
1. npm install
2. docker-compose up -d postgres
3. npm run migrate
4. npm run dev      # port 3000
5. npm test         # vitest

## Code standards
- Strict TS, no `any` (use `unknown`)
- Result<T, E> for error returns where possible
- Functions max 40 lines
- Files max 300 lines

## Important files
- src/config/env.ts — env vars (don't add new ones elsewhere)
- src/types/errors.ts — error types

## Do not
- Commit to main directly
- console.log in app code (use src/lib/logger.ts)
- Hardcode env vars outside config/env.ts

우선 규칙과 하위 디렉토리 계층·markdown

# ~/.codex/AGENTS.override.md
# Sprint override — week of 2026-05-04
All work this week is TEST ONLY. Do not modify production code.
Tests use Vitest. Branch coverage must be 100%.

# services/payments/AGENTS.md (nested, additive)
## Payments — additional rules
PCI-DSS regulated. NEVER log card numbers, CVVs, full PANs.
All encryption: src/lib/crypto.ts (AES-256-GCM).
Stripe calls: src/clients/stripe.ts only.

Exercise

실제 저장소에 계층형 AGENTS.md를 구성해. 루트에는 프로젝트 공통 표준을 적고, auth·payments·infra 같은 민감한 하위 디렉토리 한 곳에는 별도의 AGENTS.md를 둬. 루트와 하위 디렉토리에서 각각 codex --ask-for-approval never "활성 instruction 요약"을 실행해 하위 규칙이 필요한 곳에서만 나타나는지 확인해.

AGENTS.md — Codex에 프로젝트 규칙 알려 주기

AGENTS.md는 Codex가 상속받는 프로젝트 안내서야

Code

Exercise

Progress

댓글 0