책에 포함된 노트OpenAI Codex 활용법: IDE·CLI·클라우드에서 코딩 에이전트로 일하기

AGENTS.md로 '지속되는 지시사항' 만들기

2026-03-22Views 12약 8분

Codex를 쓰다 보면, 매번 같은 설명을 반복하게 됩니다. "테스트는 Vitest야", "이 폴더는 건드리지 마", "PR은 작은 diff로", "로그는 logger로"… 이런 규칙은 대화의 일부가 아니라 프로젝트의 상시 규약에 가깝습니다.

AGENTS.md는 그 규약을 한 장으로 고정해, Codex가 세션을 시작할 때부터 같은 전제를 공유하게 만드는 파일입니다. AGENTS.md를 잘 써두면 '설명 → 오해 → 수정'의 왕복이 줄어들고, 자동화(exec)와 비동기 작업(클라우드 태스크/PR 생성)에서도 결과가 안정적으로 맞아떨어집니다.¹²

AGENTS.md가 해결하는 문제: "설명 비용"을 0에 가깝게

README는 사람을 위한 문서라서 개요·사용법·기여 가이드 중심으로 쓰입니다. 반면 에이전트는 작업을 하려면 훨씬 기계적인 정보가 필요합니다. 설치/빌드/테스트 명령, 코드 스타일, 금지 구역, PR 규칙 같은 것들입니다.²

AGENTS.md의 핵심 가치는 단순합니다.

같은 레포에서 같은 작업을 반복할수록, 사람은 점점 "당연한 것"을 말하지 않게 됩니다. 하지만 에이전트는 매 세션이 새 출발이므로, 그 '당연함'을 문서로 고정하지 않으면 계속 틀립니다. AGENTS.md는 이 프로젝트에서의 "당연함"을 영구 컨텍스트로 바꾸는 장치입니다.¹

Codex의 AGENTS.md 탐색(Discovery)과 병합 규칙

여기서 가장 중요한 건 "어느 파일이 적용되느냐"입니다. Codex는 보통 다음 레이어를 조합해 현재 작업에 필요한 지시사항 체인을 구성합니다.

1) 전역(Global) 레이어: 내 기본 작업 규칙

Codex는 사용자 홈 디렉터리(Codex home, 기본값 ~/.codex)에서 전역 지시사항을 찾습니다. 이때 AGENTS.override.md가 있으면 그것을 우선 사용하고, 없으면 AGENTS.md를 사용합니다. 전역 레벨에서는 비어 있지 않은 첫 파일 하나만 사용합니다.³

이 전역 파일은 "어느 프로젝트에서도 지키고 싶은 개인 기본값"을 담기에 좋습니다. 예를 들면 "항상 작은 diff", "의존성 추가는 먼저 물어보기", "명령 실행 전 승인 요구" 같은 규칙입니다.

2) 레포(Repository) 레이어: 프로젝트의 기본 계약

레포 루트(보통 Git root)에는 AGENTS.md를 두고, 이 파일이 프로젝트의 기본 규칙이 됩니다.²

여기에는 프로젝트의 기술 스택/폴더 구조/기본 명령/PR 규칙처럼 '팀이 공유하는 표준'을 넣습니다.

3) 하위 폴더(Subdirectory) 레이어: 모듈별 예외와 로컬 규칙

모노레포이거나, 프론트/백/인프라가 섞인 레포라면 하위 폴더에 AGENTS.md를 추가로 둘 수 있습니다. 에이전트는 수정하려는 파일과 가장 가까운(가장 깊은) AGENTS.md가 우선이며, 상위 폴더의 규칙은 fallback으로 취급됩니다.⁴¹

즉, 충돌이 날 때의 직관은 이렇습니다.

루트 AGENTS.md: "전사 공통 규칙"
apps/web/AGENTS.md: "웹 앱에만 적용되는 규칙"
apps/web/components/AGENTS.md: "컴포넌트 디렉터리에만 적용되는 더 구체적인 규칙"

Codex 구현/도구에 따라 내부적으로는 루트→리프 순으로 내용을 이어 붙이고(뒤에 나온 지시가 더 강하게 작동), 결과적으로 "가까운 파일이 이긴다"는 효과가 납니다.⁴

4) 프롬프트가 최종 우선권을 가진다

아무리 AGENTS.md를 잘 써도, 사용자가 채팅에서 명시적으로 지시하면 그게 우선입니다. "이번만 예외로 전체 테스트를 돌려라" 같은 지시는 AGENTS.md보다 강합니다.⁴

5) (선택) AGENTS.override.md 패턴: '일시적 규칙'을 안전하게 얹기

대규모 마이그레이션, 특정 분기 동안의 임시 금지 규칙처럼 "나중에 반드시 지워야 하는 지시사항"은 AGENTS.override.md로 분리하는 방식이 유용합니다. 도구 체계에 따라 해당 디렉터리 레벨에서 AGENTS.md 대신 AGENTS.override.md를 사용하도록 설계되어 있어, 임시 룰을 깔끔하게 롤백할 수 있습니다.⁴

무엇을 AGENTS.md에 쓰고, 무엇을 프롬프트에 남길까

AGENTS.md는 반복 가능한 규칙/워크플로를 담고, 프롬프트에는 이번 작업의 목표/범위/증거(완료 조건)를 담는 것이 안정적입니다.¹

AGENTS.md에 적합한 내용은 이런 유형입니다.

항상 같은 답이 나와야 하는 것: 코딩 규칙, 폴더별 책임, 금지 구역
실행 가능한 것: 설치·빌드·테스트·린트 명령
팀 합의: 브랜치/커밋/PR 규칙, 리뷰 준비 체크리스트
안전장치: "이 작업은 먼저 물어봐라" 같은 권한 경계

반대로, "이번 이슈 #123을 고쳐라" 같은 일회성 지시는 AGENTS.md에 넣지 않는 편이 좋습니다. 다음 세션에서 그 문장이 남아 오히려 오작동의 원인이 됩니다.¹

AGENTS.md에 반드시 들어가야 할 6가지(실전 기준)

많은 레포 사례를 보면, 잘 작동하는 파일은 대체로 다음 영역을 빠짐없이 다룹니다: 명령, 테스트, 구조, 스타일, Git/PR 워크플로, 경계(금지/승인).⁵

이 책의 목표("반복 설명 제거")에 맞춰, Codex 관점에서 더 실용적으로 재구성해보겠습니다.

1) 핵심 명령(Commands): '가장 먼저'

에이전트가 가장 자주 참조하는 건 "무엇을 실행해야 검증이 되는가"입니다. 그래서 명령 섹션을 문서 앞부분에 둡니다.⁵

중요한 포인트는 두 가지입니다.

첫째, 정확한 커맨드 라인을 적습니다. npm test 수준이 아니라, 필요하면 옵션/필터까지 포함합니다(예: pnpm vitest run -t "...").⁵

둘째, 가능하면 파일 단위(빠른) 검증 명령을 함께 적습니다. 큰 레포에서 매번 전체 빌드를 돌리면 비용이 커지고, 자동화에서도 불필요한 승인/시간이 늘어납니다.⁶

2) 테스트 전략(Testing): "무엇이 green이면 완료인가"

테스트 프레임워크, 테스트 위치, 최소 요구사항(예: 버그 수정 시 재현 테스트 먼저), 느린 E2E의 실행 조건 같은 걸 적습니다. 이렇게 하면 Codex가 '수정했으니 끝'이 아니라 '검증하고 끝'으로 움직입니다.

3) 프로젝트 구조(Project structure): 길찾기 비용을 줄이는 지도

처음 들어온 사람은 파일을 뒤지며 "어디를 고쳐야 하지?"를 찾습니다. 에이전트도 동일합니다. 그래서 AGENTS.md에는 다음을 짧게 적습니다.

주요 디렉터리의 책임(예: src/는 앱 로직, packages/api/는 서버)
"정답 파일"의 위치(예: 라우팅은 App.tsx, HTTP 클라이언트는 src/api/client.ts)
레거시/금지/주의 폴더(예: vendor/, generated/, migrations/)

4) 코딩 규칙(Conventions): Do/Don't + 예시

규칙은 문장으로 길게 쓰기보다, Do/Don't로 촘촘히 쓰는 편이 잘 먹힙니다.⁶

가능하면 "왜"보다 "무엇을"에 집중하고, 한 번의 예시 코드로 스타일을 못 박습니다.⁵

예를 들면 "로그는 console.log 금지, 반드시 logger.info 사용" 같은 식으로 구체적으로 씁니다.

5) PR/커밋 워크플로(PR workflow): 리뷰 가능한 산출물 정의

Codex가 PR을 만들거나, 사람이 PR을 만들 때든, '리뷰 준비 상태' 기준이 문서화되어 있으면 훨씬 빠릅니다. PR은 작고 집중되어야 하고, 자동 테스트/린트/빌드가 통과되어야 하며, 설명에는 목적과 검증 방법이 들어가야 합니다.⁷

또한 PR이 커지는 걸 막기 위해 "한 PR은 한 목적" 같은 규칙을 적어두면 좋습니다.⁷

6) 경계와 권한(Boundaries/Approvals): "자동으로 해도 되는 것 vs 먼저 물어볼 것"

AGENTS.md는 보안 문서이기도 합니다. 에이전트가 할 수 있는 행동을 세 단계로 나누면 운영이 안정적입니다.⁵

항상 가능(읽기/단일 테스트/단일 린트 등)
먼저 물어보기(새 의존성 추가, 파일 삭제, 전체 E2E 등)
절대 금지(시크릿 커밋, 프로덕션 설정 변경, DB destroy 등)

이 경계는 이미 5장(Approvals)에서 다룬 "승인 흐름"과 연결됩니다. 5장이 '승인의 메커니즘'이라면, AGENTS.md는 '승인 기준의 문서화'입니다.

(템플릿) Codex용 AGENTS.md 한 장 예시

아래는 "루트 AGENTS.md"의 실전 템플릿입니다. 그대로 복사해 시작하고, 레포에 맞게 채우면 됩니다.

# AGENTS.md

## 핵심 명령(먼저 읽기)
- Install: `pnpm install`
- Dev: `pnpm dev`
- Lint(빠름): `pnpm lint --filter <pkg>`
- Typecheck(빠름): `pnpm -C <pkg> typecheck`
- Unit tests(빠름): `pnpm -C <pkg> test -- --run <path>`
- Full suite(요청 시에만): `pnpm turbo run test lint typecheck`

## 프로젝트 구조
- `apps/web/`: 프론트엔드(React + TS)
- `apps/api/`: 백엔드(Node)
- `packages/shared/`: 공유 타입/유틸
- 레거시: `apps/web/src/legacy/`는 수정 전에 먼저 물어보기

## 코딩 규칙(Do / Don't)
### Do
- 기존 패턴을 우선 복사: 에러 처리 예시는 `packages/shared/src/errors.ts`
- 로그는 `packages/shared/src/logger.ts`의 logger만 사용
- 변경한 코드에는 테스트를 추가/수정하고, 로컬에서 최소 1회 실행

### Don't
- 새 런타임 의존성 추가는 승인 없이 하지 말 것
- `generated/`, `dist/` 결과물을 커밋하지 말 것
- 대규모 리네이밍/전역 리포맷 등 repo-wide 변경을 제안만 하고 바로 실행하지 말 것

## 테스트 규칙
- 버그 수정: 재현 테스트를 먼저 추가(실패 확인) → 수정 → green
- UI 변경: 가능한 경우 스냅샷/스크린샷 또는 재현 절차를 PR에 포함

## PR 규칙
- PR은 한 목적만(범위가 커지면 쪼개기)
- PR 본문에 포함:
  - 무엇을/왜 바꿨는지
  - 어떻게 검증했는지(실행한 커맨드)
  - 리스크/롤백 포인트
- 머지 전 필수: lint + unit tests green

## 권한 경계
- 자동으로 해도 됨: 파일 읽기/검색, 단일 파일 포맷, 단일 테스트 실행
- 먼저 물어보기: 의존성 추가, 파일 삭제/이동 대규모, 전체 테스트/빌드, 마이그레이션 생성
- 절대 금지: 시크릿/토큰 커밋, 프로덕션 설정 변경, 데이터 파괴(destroy)

이 템플릿이 좋은 이유는 "명령이 앞에 있고", "경계가 명확하고", "규칙이 구체적"이기 때문입니다.⁵⁶

모노레포 운영법: '루트는 얇게, 하위는 날카롭게'

모노레포에서 루트 AGENTS.md가 길어지면, 정작 작업에 필요한 규칙이 묻히고 컨텍스트도 낭비됩니다. 이때는 루트를 공통 규칙만 남기고, 패키지별로 하위 AGENTS.md를 두는 방식이 잘 맞습니다.²⁴

예시 구조는 다음처럼 가져가면 됩니다.

/AGENTS.md
/apps/web/AGENTS.md
/apps/api/AGENTS.md
/packages/shared/AGENTS.md

루트: PR 규칙, 보안 경계, 공통 명령(가능하면 최소)
apps/web: 프론트 전용(컴포넌트 규칙, 스토리북, UI 테스트)
apps/api: API 규칙(라우팅, 인증/권한, DB 접근 패턴)

그리고 기억할 것은 단 하나입니다. "가까운 파일이 이긴다." 웹 파일을 고칠 때는 apps/web/AGENTS.md가 더 중요합니다.⁴

다른 도구와 함께 쓸 때의 주의사항(짧게)

AGENTS.md는 여러 에이전트 생태계가 공유하는 표준으로 자리 잡았고, 한 레포에서 여러 도구를 바꿔가며 써도 '기본 규칙'은 재사용할 수 있습니다.²

다만 도구마다 읽는 방식/제한이 다를 수 있습니다. 예를 들어 GitHub Copilot의 코드 리뷰는 커스텀 인스트럭션 파일당 앞부분 4,000자만 읽는 제한이 있어, 중요한 규칙을 앞쪽에 배치하는 습관이 도움이 됩니다.⁸

유지보수 원칙: AGENTS.md는 '살아있는 계약서'다

AGENTS.md는 한 번 써놓고 끝내는 문서가 아니라, 레포가 바뀔 때 같이 바뀌어야 합니다.²

운영에서 특히 효과가 큰 루틴은 다음 두 가지입니다.

첫째, 문제가 생겼을 때만 한 줄 추가합니다. "에이전트가 Jest로 테스트를 썼다" 같은 사고가 났다면 "테스트는 Vitest만"을 Do/Don't에 한 줄 추가합니다. '사고 기반으로 규칙을 강화'하면, 파일이 필요 이상으로 비대해지지 않습니다.

둘째, 임시 규칙은 override로 처리합니다. 마이그레이션 기간에만 필요한 금지/권장 사항을 루트 AGENTS.md에 넣으면 나중에 제거를 잊기 쉽습니다. 대신 AGENTS.override.md로 분리하고, 작업이 끝나면 파일을 삭제해 원상복구합니다.⁴

참고

¹Instruction Files for AI Coding Assistants: An Overview

²AGENTS.md (공식 소개)

³Custom instructions with AGENTS.md (OpenAI Codex 가이드)

⁴AGENTS.md, Cascading Rules, and the Optional AGENTS.override.md

⁵How to write a great agents.md: Lessons from over 2,500 repositories

⁶AGENTS.md markdown File Best Practices

⁷Pull Requests - Engineering Fundamentals Playbook

⁸Using custom instructions to unlock the power of Copilot code review

책 목록

OpenAI Codex 활용법: IDE·CLI·클라우드에서 코딩 에이전트로 일하기

전체 목차 보기