5
Codex 사용법 5강. AGENTS.md와 팀 규칙
Lesson 05

반복 설명을 줄이려면
AGENTS.md와 팀 규칙을 먼저 문서화하는 편이 좋습니다.

개인 요청만으로도 시작은 할 수 있지만, 같은 로그인 버그 수정 설명을 팀이 계속 반복하면 금방 피로가 생깁니다. 이때부터는 AGENTS.md처럼 반복 규칙을 모아두는 문서가 필요합니다.

기준 날짜 2026-04-13

이 가이드는 OpenAI Codex 제품, 정책, 표준 변경에 따라 이후 달라질 수 있습니다.

공통 예시 — 로그인 에러 메시지 사라지는 문제 (펼치기)
문제: 로그인 실패 시 에러 메시지가 화면에서 사라집니다.
범위: auth/LoginForm.tsx, auth/useLogin.ts, auth/LoginForm.test.tsx
제약: UI 문구 유지, API 스펙 유지, auth 범위 안에서만 수정, npm test -- auth로 검증합니다.
Bad Team Rule

팀 규칙이 약하면 생기는 일

  • 누가 요청하느냐에 따라 검증 방식이 달라집니다.
  • build, lint, test 명령이 사람마다 다르게 적힙니다.
  • auth 범위만 수정하라는 제약이 매번 빠지거나 달라집니다.
  • 새 팀원이 팀 기대치를 파악하는 데 시간이 오래 걸립니다.
Good Team Rule

AGENTS.md가 있으면 좋아지는 점

  • 반복 설명이 줄어듭니다.
  • 결과 일관성이 올라갑니다.
  • 새 팀원이 빠르게 따라올 수 있습니다.
  • 리뷰 기준과 금지사항을 팀 단위로 맞출 수 있습니다.
What To Include

AGENTS.md에 먼저 넣으면 좋은 항목

작업 범위auth 관련 이슈는 auth 폴더 범위에서 먼저 해결합니다.
검증 명령npm test -- auth, 필요 시 lint/build 명령을 함께 적습니다.
금지사항UI 문구와 API 스펙은 별도 승인 없이 변경하지 않습니다.
리뷰 기준범위 초과 수정, 테스트 누락, 회귀 위험을 먼저 봅니다.
문서 규칙중요한 요청 템플릿과 예시를 함께 남깁니다.
권한 원칙기본은 제한된 권한에서 작업하고 위험한 실행은 approval을 거칩니다.
Template Example

로그인/auth 사례 기준 AGENTS.md 예시

# AGENTS.md

## Scope
- auth 관련 이슈는 auth 폴더 범위에서 먼저 해결합니다.
- UI 문구와 API 스펙은 별도 승인 없이 변경하지 않습니다.

## Validation
- auth 변경 후에는 npm test -- auth 를 실행합니다.
- 테스트가 없으면 관련 테스트 초안을 함께 제안합니다.

## Review
- 범위 초과 수정이 없는지 먼저 확인합니다.
- 로그인 실패 시 에러 메시지가 유지되는지 확인합니다.
- 테스트 누락이나 회귀 위험을 리뷰 코멘트에 남깁니다.

## Safety
- 민감정보는 입력하지 않습니다.
- 네트워크 사용이나 범위 밖 수정은 approval 이후에만 진행합니다.
Per-Directory Split

AGENTS.md가 커지면 디렉터리별로 나눠야 합니다

AGENTS.md 하나에 모든 규칙을 넣으면 관리는 쉽지만, 파일이 길어질수록 Codex가 요청마다 전체를 읽어야 해서 토큰 비용이 올라갑니다. 해결책은 디렉터리별로 파일을 나눠두는 것입니다. Codex는 현재 작업 중인 파일의 위치를 기준으로 디렉터리 트리를 위쪽으로 탐색하면서 AGENTS.md를 찾아 로드합니다. auth 파일만 건드리는 요청이라면 루트의 AGENTS.md와 auth/AGENTS.md만 로드되고, api 규칙은 읽지 않습니다.

Before — 단일 파일

하나로 모은 경우

project/
└── AGENTS.md   ← 모든 규칙이 여기에
    (Scope, Validation, Review,
     Safety, auth 규칙, api 규칙,
     UI 규칙, CI 규칙 ...)

파일이 길어질수록 관련 없는 규칙도 매번 토큰으로 소모됩니다.

After — 디렉터리별 분리

나눈 경우

project/
├── AGENTS.md         ← 전체 공통 규칙만
├── auth/
│   └── AGENTS.md    ← auth 전용 규칙
└── api/
    └── AGENTS.md    ← api 전용 규칙

auth 파일 작업 시 루트 + auth/AGENTS.md만 로드됩니다.

루트 AGENTS.md전체 공통 규칙 — 검증 명령 형식, 금지사항 원칙, 권한 정책 등 어느 디렉터리에서도 항상 적용될 내용만 남깁니다.
auth/AGENTS.mdauth 전용 규칙 — UI 문구 유지, npm test -- auth, auth 범위 제한처럼 auth 작업에서만 의미 있는 내용을 넣습니다.
언제 나눌까AGENTS.md가 50~100줄을 넘거나, 서로 다른 도메인(auth/api/ui)의 규칙이 섞이기 시작할 때 분리를 고려합니다.
Load Order
1
project/AGENTS.md 전체 공통 규칙 — 항상 먼저 로드됩니다. 검증 명령 형식, 금지사항 원칙 등 모든 디렉터리에 적용될 내용만 남깁니다.
2
auth/AGENTS.md auth 전용 규칙 — 나중에 로드되어 공통 규칙을 좁힙니다. UI 문구 유지, npm test -- auth, auth 범위 제한처럼 auth 작업에서만 의미 있는 내용을 넣습니다.
로드 순서 원칙 Codex는 작업 파일 위치에서 시작해 루트 방향으로 올라가며 AGENTS.md를 탐색합니다. 하위 디렉터리 규칙이 루트 규칙보다 나중에 로드되므로, 하위에서 상위 규칙을 좁혀 쓰는 방식으로 설계하면 자연스럽습니다.
Why It Helps

결국 무엇이 좋아질까요

반복 설명 감소같은 로그인 버그 수정 조건을 여러 번 다시 쓰지 않아도 됩니다.
결과 일관성 증가테스트와 금지사항이 공통으로 적용돼 결과 편차가 줄어듭니다.
온보딩 속도 개선새 팀원도 무엇을 기준으로 요청하고 리뷰해야 하는지 빠르게 알 수 있습니다.
Workshop

실습

실습 1

팀이 자주 반복하는 Codex 요청 3개를 적고, 어떤 항목을 AGENTS.md로 올릴지 골라보세요.

실습 2

위의 예시를 바탕으로 auth 관련 AGENTS.md 초안을 직접 작성해보세요.

References

공식 문서

Custom instructions with AGENTS.md Codex best practices Codex approvals & security