AGENTS.md 완전 가이드 — Context Engineering

AGENTS.md란?

AGENTS.md는 OpenAI의 Codex CLI에서 시작해 Linux Foundation의 Agentic AI Foundation이 관리하는 개방형 표준이다. 특정 도구에 종속되지 않는 범용 마크다운 파일로, 여러 AI 코딩 도구가 동시에 인식한다.

왜 AGENTS.md인가? 팀에서 Cursor, Claude Code, Copilot을 섞어 쓰는 상황이 늘고 있다. AGENTS.md 하나로 공통 규칙을 정의하고, 도구별 세부 설정만 각 설정 파일에 넣는 전략이 효과적이다.

지원 도구 현황

네이티브 지원 도구와 호환 가능 도구 목록 (2025년 기준)

💻

Codex CLI

🖱

Cursor

💬

Claude Code

🔧

Continue

⌨

Aider

💎

Gemini CLI

🐙

GitHub Copilot

🤖

Devin

🏭

Factory

🛠

Jules

📝

VS Code

🌊

Windsurf

네이티브 지원 호환/fallback 지원

파일 디스커버리 메커니즘

Codex CLI 기준. 파일을 찾는 순서와 우선순위.

1

~/.codex/AGENTS.override.md

최우선

2

~/.codex/AGENTS.md

글로벌

3

{git root}/AGENTS.md

프로젝트

4

{git root}/sub/dir/AGENTS.md

서브디렉토리

5

{현재 디렉토리}/AGENTS.md

최근접 우선

Override 메커니즘: AGENTS.override.md는 같은 디렉토리의 AGENTS.md보다 항상 우선한다. 기존 파일을 삭제하지 않고 임시로 규칙을 교체할 때 유용하다.

# ~/.codex/config.toml — 디스커버리 설정

# 인식할 파일명 패턴 (기본값 외 추가)
project_doc_fallback_filenames = [
  "AGENTS.md",
  "CLAUDE.md",
  "COPILOT.md"
]

# 전체 로드 가능한 최대 크기 (기본 32KB)
project_doc_max_bytes = 32768

디렉토리 구조 예시

# 단일 프로젝트
my-project/
├── AGENTS.md                # 프로젝트 전체 규칙
├── AGENTS.override.md       # 임시 오버라이드 (선택)
├── src/
│   ├── frontend/
│   │   └── AGENTS.md        # 프론트엔드 전용 규칙
│   └── backend/
│       └── AGENTS.md        # 백엔드 전용 규칙
└── ...

# 멀티 도구 환경 (권장 패턴)
my-project/
├── AGENTS.md                # 범용 규칙 (모든 도구가 읽음)
├── CLAUDE.md                # Claude Code 전용 (Skills, hooks)
├── .cursor/rules/           # Cursor 전용 (glob 트리거)
├── .github/copilot-instructions.md  # Copilot 전용
└── ...

# 글로벌 설정
~/.codex/
├── AGENTS.md                # 모든 프로젝트에 적용
├── AGENTS.override.md       # 글로벌 오버라이드
└── config.toml              # Codex CLI 설정

실전 예제

범용 AGENTS.md (멀티 도구 환경)

# AGENTS.md
# 이 파일은 Codex, Cursor, Claude Code, Gemini 등이 읽습니다.

## 프로젝트 개요
Next.js 14 + TypeScript + Prisma를 사용하는 SaaS 플랫폼.
App Router 기반, Server Components 우선.

## 빌드 & 테스트
- dev: pnpm dev
- build: pnpm build
- test: pnpm vitest run
- lint: pnpm eslint . --fix
- db migrate: pnpm prisma migrate dev
- db generate: pnpm prisma generate

## 코드 컨벤션
- Server Component가 기본. 'use client'는 꼭 필요할 때만.
- API Route는 app/api/ 아래에 route.ts로 작성.
- DB 접근은 반드시 lib/db.ts의 prisma 인스턴스를 통해서.
- 에러 처리: try-catch 대신 Result 패턴 (lib/result.ts 참조).
- 환경변수는 env.mjs에서 zod로 검증. process.env 직접 접근 금지.

## 디렉토리 규칙
- app/ — 페이지와 라우트
- components/ — 재사용 UI (shadcn/ui 기반)
- lib/ — 비즈니스 로직, 유틸리티
- prisma/ — 스키마, 마이그레이션

## 절대 하지 말 것
- any 타입 사용 금지
- console.log 커밋 금지 (logger 사용)
- 인라인 스타일 금지 (Tailwind CSS만)

오픈소스 라이브러리용

# AGENTS.md

## 이 프로젝트에 대해
React 상태 관리 라이브러리. API 표면이 작고 번들 크기가 작다.
TypeScript로 작성되며, 100% 테스트 커버리지를 유지한다.

## 개발 가이드
- build: pnpm build (tsup 사용)
- test: pnpm test (vitest)
- benchmark: pnpm bench

## PR 규칙
- 새 기능은 RFC 이슈를 먼저 올린 후 작업
- breaking change는 반드시 마이그레이션 가이드 포함
- 번들 사이즈 증가 시 justification 필수
- examples/ 디렉토리에 사용 예제 추가

AGENTS.md vs CLAUDE.md

둘 다 쓸 수 있다. 어떻게 역할을 나눌까?

관리 주체

Linux Foundation

Anthropic

범용성

10+ 도구 지원

Claude Code 전용

Override 메커니즘

AGENTS.override.md

CLAUDE.local.md

@import 지원

미지원

지원

Skills 시스템

미지원

.claude/skills/ 지원

크기 제한

32KB (설정 가능)

~200줄 권장

권장 용도

팀 공통 규칙, 범용 컨벤션

Claude 전용 기능 활용

멀티 도구 환경 전략

권장 접근법: AGENTS.md를 기반으로, 도구별 확장

AGENTS.md에 공통 규칙을 넣는다 — 빌드 명령어, 코드 컨벤션, 아키텍처 결정
CLAUDE.md에는 Claude 전용 기능만 — Skills, @import, hooks, 메모리 관련 지시
.cursor/rules/에는 Cursor 전용 기능만 — glob 트리거, @mention 규칙
.github/copilot-instructions.md에는 Copilot 전용만 — 조직 레벨 설정
중복을 최소화한다 — AGENTS.md에 있는 내용을 다른 파일에 반복하지 않는다
AGENTS.md를 single source of truth로 삼고, 나머지는 보충 역할

AGENTS.md 공식 가이드 (OpenAI)

developers.openai.com/codex/guides/agents-md

Codex CLI GitHub

github.com/openai/codex

실전 팁: 팀에서 어떤 AI 도구를 쓰는지 아직 정해지지 않았다면, AGENTS.md부터 만들어라. 나중에 특정 도구를 도입할 때 도구별 파일을 추가하면 된다. AGENTS.md는 거의 모든 도구가 읽을 수 있으므로 가장 안전한 출발점이다.