요약 (TL;DR)

AGENTS.md는 프로젝트의 규칙을 한 번만 작성하면 Copilot, Cursor, Kilo Code, Devin Desktop, Aider 및 30개 이상의 대부분의 AI 코딩 도구가 자동으로 읽을 수 있게 해주는 개방형 표준 (open standard)입니다. 이 글에서는 파일에 무엇을 담아야 하는지, 대부분의 가이드가 생략하는 부분은 무엇인지, 그리고 당신이 기대하는 방식대로 이 파일을 읽지 않는 한 가지 인기 있는 도구에 대해 다룹니다.

문제점: 지침 드리프트 (instruction drift)

두 개 이상의 AI 코딩 도구를 사용하고 있다면, 아마 이 문제를 겪어보았을 것입니다.

GitHub Copilot을 위해 copilot-instructions.md를 작성합니다. 팀원이 Cursor를 사용하므로 동일한 규칙이 담긴 .cursorrules/ 파일을 추가합니다. 다른 누군가는 Cline을 사용하므로 .clinerules/를 추가합니다. 그다음 CI에서 Codex CLI를 사용하므로 이를 위한 또 다른 파일을 작성합니다.

6개월 후, 당신은 거의 동일한 5개의 지침 파일들을 갖게 되며, 그중 어느 것도 서로 일치하지 않고, 단 하나의 컨벤션 (convention)을 업데이트하려면 다섯 군데를 모두 수정해야 합니다.

이것이 바로 **지침 드리프트 (instruction drift)**이며, AGENTS.md가 해결하기 위해 만들어진 문제입니다.

AGENTS.md란 무엇인가

AGENTS.md는 저장소 (repository)의 루트에 위치하는 일반 마크다운 (markdown) 파일입니다. YAML 프론트매터 (frontmatter)도, 특별한 구문 (syntax)도, 배워야 할 스키마 (schema)도 없습니다.

이 표준은 2025년 8월 OpenAI에 의해 발표되었으며, Linux Foundation의 Agentic AI Foundation에 관리 권한이 넘겨져 개방형 표준으로 운영되고 있습니다. 2026년 중반까지 60,000개 이상의 오픈 소스 저장소에서 채택되었습니다.

README가 인간에게 프로젝트를 설명한다면, AGENTS.md는 에이전트 (agents)에게 프로젝트를 설명합니다.

실제로 누가 읽는가 (그리고 누가 읽지 않는가)

이 부분은 대부분의 AGENTS.md 가이드가 생략하는 부분이지만, 단 한 줄을 쓰기 전에도 매우 중요합니다.

네이티브로 읽는 도구들 (별도 설정 불필요):

Cursor, Devin Desktop, Aider, Amp, OpenCode, Gemini CLI, Codex CLI, Kilo Code, GitHub Copilot, 그리고 공식 AGENTS.md 사이트에 나열된 30개 이상의 도구들. Copilot은 저장소 루트(repo root)에서 이를 직접 읽습니다. Kilo Code는 AGENTS.md 지원이 기본적으로 활성화되어 있습니다.

유일하고 솔직한 예외: Cline

Cline의 네이티브 규칙 형식은 .clinerules/입니다 — 자체적인 폴더와 자체적인 파일 구조를 가집니다. 프로젝트 루트의 AGENTS.md는 대부분의 다른 도구들처럼 자동으로 감지되지 않습니다. Cline은 글로벌(global) ~/.agents/AGENTS.md를 읽기는 하지만, 이는 프로젝트별 파일과는 별개입니다. 이것은 버그가 아니라 현재 Cline이 작동하는 방식이며, 하나의 파일이 모든 것을 커버한다고 가정하기 전에 알아둘 가치가 있습니다.

AGENTS.md 파일에 실제로 넣어야 할 내용

다음은 Next.js 프로젝트를 위한 실제 예시입니다:

# AGENTS.md

## Project
...

각 섹션이 중요한 이유

**Commands (명령어)**는 가장 가치가 높은 섹션입니다. 이 섹션은 에이전트가 가장 흔히 저지르는 실수, 즉 프로젝트에서 pnpm을 사용하는데 npm을 사용하거나, vitest를 사용 중인데 pytest를 실행하는 실수를 제거해 줍니다. 모든 도구는 프로젝트를 설치(install), 실행(run), 테스트(test), 빌드(build)하는 방법을 알아야 합니다.

**Conventions (컨벤션/관례)**는 모호하지 않고 구체적이어야 합니다. "함수형 컴포넌트를 사용하세요"는 컨벤션이 아닙니다 — 에이전트에게 실행 가능한 정보를 전혀 주지 못합니다. 반면 "컴포넌트 작성 시 기본 내보내기(default exports) 없이 이름 있는 내보내기(named exports)만 사용하세요"는 에이전트가 작성하는 모든 파일을 검사하며 확인할 수 있는 컨벤션입니다.

**Hard constraints (강력한 제약 사항)**에는 "절대 ~하지 마세요(never)"라는 단어를 사용해야 합니다. 이는 섹션 간에 기계적인 차이가 있어서가 아닙니다 — 에이전트는 사용자의 헤더를 파싱하지 않습니다. 에이전트가 하는 일은 명시적인 부정 표현(explicit negatives)에 선호도(preferences)보다 더 높은 가중치를 두는 것입니다. "이름 있는 내보내기만 사용"은 선호도입니다. "절대 기본 내보내기를 사용하지 마세요"는 더 강력한 신호입니다. 같은 아이디어지만 가중치가 다를 뿐입니다.

연구 결과가 실제로 말해주는 것

2026년 2월 ETH Zurich 연구 (Gloaguen et al.)는 138개의 실제 GitHub 태스크를 통해 컨텍스트 파일 (context files)을 테스트했습니다. 연구 결과는 대부분의 가이드가 가정하는 것과는 반대되었습니다. 일반적으로 컨텍스트 파일은 컨텍스트 파일이 아예 없는 경우보다 태스크 성공률을 오히려 _감소_시켰습니다. 직접 작성한 파일(Hand-written files)만이 예외였으며, 평균적으로 4%의 완만한 개선을 보였습니다.

문제는 다음과 같습니다. 해당 개선조차 최대 19% 더 많은 단계와 토큰 비용 (token cost)을 수반했는데, 이는 에이전트 (agent)가 행동하기 전에 더 많은 작업을 수행했기 때문입니다. /init을 통해 자동 생성된 파일 (Auto-generated files)은 테스트된 대부분의 설정에서 아무것도 없는 것보다 성능이 낮았습니다.

여기서 얻을 수 있는 교훈은 "파일을 건너뛰라"는 것이 아닙니다. 핵심은 다음과 같습니다: 적게 작성하고, 에이전트가 이미 코드를 읽어서 발견할 수 없는 내용만 작성하며, 생성하기보다는 직접 작성하십시오.

200행 미만으로 유지하세요

Anthropic의 Claude Code 문서에서도 명시적으로 밝히고 있습니다: CLAUDE.md 파일당 200행 미만을 목표로 하십시오. 파일이 길어지면 더 많은 컨텍스트 (context)를 소비하고 준수율 (adherence)을 떨어뜨립니다. 동일한 원칙이 AGENTS.md에도 적용됩니다. 특정 길이를 넘어서면 하단에 위치한 규칙들의 가중치가 비례하여 감소합니다. 내용이 넘쳐난다면, 해당 내용은 스킬 (skill)이나 범위가 지정된 지침 파일 (scoped instructions file)로 옮겨야 합니다.

공개된 파일처럼 취급하세요

실제 API 키 형식을 붙여넣지 마세요. 진짜처럼 보이는 예시 토큰을 포함하지 마세요. 내부 인증 비밀값 (auth secrets)을 문서화하지 마세요. 비밀값이 저장된 위치를 작성하십시오 — ".env.local, 커밋 금지" — 라고만 적고 멈추십시오. 이 파일이 유출될 수 있다고 가정하고 취급하십시오. 실제로 유출될 수도 있기 때문입니다.

대부분의 AGENTS.md 가이드가 생략하는 세 가지 패턴

1. 중첩된 파일 (Nested files) — 가까운 쪽이 승리한다

대부분의 개발자는 AGENTS.md가 루트 (root)에 있는 단 하나의 파일이라고 생각합니다. 하지만 반드시 그럴 필요는 없습니다.

공식 agents.md 명세에 따르면, 에이전트는 자신이 편집 중인 대상과 가장 가까운 파일을 읽습니다. 즉, 가까운 쪽이 승리하며, 루트 파일은 단지 폴백 (fallback) 역할을 할 뿐입니다. OpenAI의 Codex 리포지토리 (repository)는 디렉토리 트리 전반에 걸쳐 88개의 별도 AGENTS.md 파일을 포함하고 있습니다.

my-project/
├── AGENTS.md                 ← 전역 규칙 (global rules): 스택 (stack), 명령어 (commands), 컨벤션 (conventions)
└── packages/
...

사이드 프로젝트를 위해 88개의 파일이 필요하지는 않습니다. 하지만 코드베이스의 특정 부분(레거시 패키지, 벤더 폴더 등)에 진정으로 다른 규칙이 적용되어야 하는 순간이 오면, 루트(root) 디렉토리에 예외 사항을 억지로 밀어 넣는 대신 그곳에 두 번째 AGENTS.md를 배치하세요.

2. 컨텍스트 예산 (Context Budget) 섹션

에이전트(Agents)는 언제 읽기를 멈춰야 할지 모릅니다. 그대로 두면 schema.prisma 전체, 모든 상수(constants) 파일, 필요하지 않은 파일들까지 모두 열어보며 코드 한 줄을 쓰기도 전에 컨텍스트(context)와 시간을 낭비할 것입니다.

대신 검색하는 방법을 알려주세요:

## Context Budget (컨텍스트 예산)
- 전체 파일을 열기 전에 관련 심볼(symbol)이나 라우트(route)를 먼저 검색할 것
- 해당 요소를 소비하기만 하는 파일보다, 요소를 정의하는 파일을 먼저 읽을 것
...

3. 빠른 라우팅 맵 (Fast Routing Map)

작업 유형을 정확한 파일 경로와 매핑하는 AGENTS.md 내의 직접적인 테이블입니다:

## Fast Routing Map (빠른 라우팅 맵)
| 필요 사항           | 우선적으로 읽을 파일                     |
|--------------------|------------------------------------------|
...

이를 통해 환각(hallucination)된 파일 경로라는 카테고리 전체를 제거할 수 있습니다. 에이전트는 파일이 어디에 있는지 추측하는 것을 멈추고, 먼저 지도를 확인하기 시작합니다.

Codex CLI 전용 기능 (범용적이지 않음)

만약 구체적으로 OpenAI의 Codex CLI를 사용 중이라면, 동일한 디렉토리 수준에서 일반 AGENTS.md보다 우선순위를 갖는 AGENTS.override.md 파일이 있습니다. 이는 실제 규칙 파일을 건드리지 않고 릴리스 프리즈(release freeze)와 같은 일시적인 상황에 대응할 때 유용합니다. 또한 Codex CLI는 기본적으로 컨텍스트 로딩을 32 KiB로 제한하며, 총량이 제한을 초과할 경우 현재 디렉토리에 가장 가까운 파일이 우선권을 갖습니다.

이것들은 Codex CLI 전용 동작이며, Copilot이나 Claude Code가 수행하는 기능이 아닙니다. 존재하지 않는 기능을 찾아 헤매지 않도록 명시적으로 표시합니다.

완료 정의 (Definition of Done) 섹션

## Definition of Done (완료 정의)
모든 작업을 완료되었다고 선언하기 전에, 다음을 순서대로 실행할 것:
1. pnpm tsc --noEmit
...

한 가지 솔직한 주의사항: 이 섹션은 권고 사항입니다. 에이전트 (Agent)는 이를 읽고 일반적으로 따르려고 노력하지만, 이것이 보장되는 것은 아닙니다. 잘 작동하는 에이전트라도 불필요하다고 판단되는 체크 항목은 건너뛸 수 있습니다. 이는 더 큰 주제(훅 (Hooks), 강제 메커니즘 (Enforcement mechanisms))이며, Part 2B에서 다룰 예정입니다.

핵심 요약 (Key takeaways)

• AGENTS.md는 저장소 루트 (Repo root)에 위치합니다. 일반적인 마크다운 (Markdown) 형식이며, 스키마 (Schema)나 프론트매터 (Frontmatter)는 필요하지 않습니다.
• 30개 이상의 AI 코딩 도구들이 이를 기본적으로 읽습니다. Copilot은 이를 직접 읽으며, Kilo Code는 기본적으로 이를 활성화합니다.
• Cline은 솔직한 예외입니다 — Cline의 네이티브 형식은 프로젝트 루트의 AGENTS.md가 아니라 .clinerules/입니다.
• Commands (명령어) 섹션이 가장 가치가 높은 섹션입니다. 이것부터 정확하게 작성하세요.
• ETH Zurich 연구 (2026년 2월, 138개 작업): 직접 작성한 파일은 약간의 도움(+4%)을 주지만, 자동 생성된 파일은 오히려 해가 되는 경향이 있습니다. 직접 작성하고, 짧게 유지하세요.
• 중첩된 AGENTS.md는 실제로 존재하며, 가장 가까운 파일이 우선권을 갖습니다. OpenAI의 Codex 저장소는 88개의 파일을 사용합니다.
• 컨텍스트 예산 (Context Budget)과 빠른 라우팅 맵 (Fast Routing Map)을 추가하세요. 대부분의 가이드에서 이를 생략하지만, 이는 불필요한 단계를 방지하는 데 가장 유용한 섹션입니다.
• 이를 공개적인 것으로 취급하세요. 실제 비밀 정보는 포함하지 마세요.

다음 단계 (What's next)

Part 2B에서는 이를 Claude Code의 CLAUDE.md, Copilot의 전체 툴킷 (프롬프트 파일, 커스텀 에이전트, 두 도구가 모두 읽는 공유 기술 폴더), 그리고 사용 중인 모든 스택의 도구 전반에 걸친 MCP (Model Context Protocol)의 실제 상태와 제대로 연결할 것입니다.

링크가 활성화되는 즉시 여기에 삽입됩니다.

📺 전체 강의: AI Second Brain for Developers