만약 여러분이 Claude Code, Cursor, Codex, Aider, Gemini CLI, GitHub Copilot, Grok, goose 또는 유사한 도구들을 사용해 보았다면, 동일한 패턴을 목격했을 것입니다. 에이전트의 최우선 순위는 컨텍스트 (Context)입니다. 이 프로젝트는 무엇인가? 어떻게 빌드하는가? 테스트는 어떻게 실행하는가? 어떤 컨벤션 (Conventions)을 따라야 하는가? 무엇을 망가뜨리면 안 되는가?

AGENTS.md는 이에 대한 공개적인 해답입니다. 이는 저장소의 루트 (Root)에 배치되는 단일 마크다운 (Markdown) 파일로, AI 코딩 에이전트를 위한 전용이며 예측 가능한 브리핑 역할을 합니다. 이를 사람이 아닌 에이전트를 위해 특별히 작성된 README라고 생각하십시오. 형식은 의도적으로 단순하며 도구에 구애받지 않습니다 — 즉, 하나의 파일로 많은 에이전트에서 작동합니다.

AGENTS.md는 OpenAI의 Codex에 의해 개척되었으며 Cursor, Amp, Factory, 그리고 Google의 Jules와 같은 도구들과 함께 형성되었습니다. 2025년 12월, 이 표준은 Linux Foundation 산하의 Agentic AI Foundation에 기부되었으며, 현재는 오픈 표준 (Open Standard)으로서 관리되고 있습니다.

대부분의 AGENTS.md 파일은 두 가지 방식 중 하나로 실패합니다. 유용하기에는 너무 빈약하거나, 에이전트가 대충 훑어보고 대부분 무시해 버리는 길고 장황한 문서인 경우입니다. 좋은 AGENTS.md는 그 중간에 위치합니다 — 짧고, 최신 상태이며, 구체적이고, 실행 가능해야 합니다.

README는 사람을 위한 것입니다. AGENTS.md는 에이전트를 위한 것입니다.

이 차이가 파일에 포함되어야 할 모든 것을 결정합니다.

• README.md는 _무엇인지(what)_와 _왜인지(why)_를 답합니다: 프로젝트가 무엇인지, 왜 존재하는지, 그리고 사람이 어떻게 시작하는지를 다룹니다.
• AGENTS.md는 _여기서 어떻게 일해야 하는지(how to work here)_를 답합니다: 에이전트가 질문 없이 변경 사항을 만들고 검증하는 데 필요한 정확한 명령어, 컨벤션 (Conventions), 그리고 가드레일 (Guardrails)을 다룹니다.

README의 내용을 중복해서 작성하지 마십시오. 에이전트가 효과적으로 행동하는 데 필요하지 않다면 제외하십시오. 필수적이지 않은 모든 줄은 신호 (Signal)를 희석시킵니다.

AGENTS.md에 실제로 포함되어야 할 내용

대략적인 우선순위에 따른 가장 가치 있는 섹션들입니다.

한 줄 오리엔테이션 (One-line orientation). 프로젝트가 무엇인지와 어떤 스택 (Stack)을 사용하는지 에이전트에게 알려주는 단 한 문장 — 예를 들어, “Postgres를 사용하는 Node 20 기반의 TypeScript REST API이며, Fly.io에 배포됨.”과 같은 형태입니다.

설정 및 빌드 명령 (Setup and build commands). 가장 가치 있는 단일 섹션입니다. 실제로 복사해서 붙여넣을 수 있는 명령어를 제공하세요:

npm install
npm run build
npm run dev

테스트 실행 방법 (How to run tests). 빌드 명령보다 훨씬 더 중요합니다. 테스트는 에이전트가 자신의 작업 결과물을 검증하는 방법입니다:

npm test          # 변경 사항이 완료되었다고 간주하기 전에 모든 테스트를 통과해야 함
npm run lint
npm run typecheck

파일 위치 (Where things live). 전체 디렉토리 구조를 쏟아내는 것이 아니라, 주요 디렉토리와 엔트리 포인트 (entry points)에 대한 짧고 집중적인 지도를 제공합니다.

컨벤션 (Conventions). 준수하기를 원하는 구체적인 패턴입니다: 검증 방식, 에러 핸들링 (error handling), 명명 규칙 (naming), 선호하는 라이브러리, 아키텍처 결정 사항 등입니다. “클린 코드를 작성하라”와 같은 모호한 문구는 쓸모가 없습니다. “라우트 경계에서 Zod를 사용하여 모든 입력을 검증하라”와 같은 구체적인 규칙이 유용합니다.

커밋 및 PR 규칙 (Commit and PR rules). 메시지 형식, 브랜치 명명 규칙, 변경 로그 (changelog) 업데이트, 그리고 기타 모든 프로세스 요구 사항입니다.

가드레일 (Guardrails) — 하지 말아야 할 것. 값비싼 실수를 방지하기 위한 지뢰밭입니다: /generated 디렉토리의 파일은 수정하지 말 것, 프로덕션 설정에 대해 마이그레이션 (migrations)을 절대 실행하지 말 것, 그리고 main 브랜치에 직접 커밋하지 말 것 등입니다.

상황을 더 악화시키는 안티 패턴 (The anti-patterns)

잘못 작성된 AGENTS.md는 단순히 도움이 되지 않는 것에 그치지 않고, 에이전트를 적극적으로 오도합니다.

• 소설 (The novel): 너무 깁니다. 에이전트는 훑어 읽게 되고 중요한 지침이 유실됩니다. 핵심적인 내용이 아니라면 모두 삭제하세요.
• 오래된 파일 (The stale file): 업데이트되지 않은 명령어구나 경로는 파일이 아예 없는 것보다 더 나쁩니다. 에이전트는 잘못된 행동을 자신 있게 수행할 것입니다.
• 모호함 (Vagueness): “베스트 프랙티스 (best practices)를 따르라”는 에이전트에게 실행 가능한 정보를 전혀 주지 못합니다.
• 비밀 정보 (Secrets): AGENTS.md에 자격 증명 (credentials), 키 (keys), 또는 토큰 (tokens)을 절대 넣지 마세요. 대신 그것들이 어디에서 오는지 (.env, secrets manager 등)를 가리키세요.
• README 중복 (README duplication): 토큰 낭비와 유지보수 부담을 초래합니다.

생명력을 유지하세요 — AGENTS.md를 코드처럼 취급하세요

AGENTS.md 파일은 관리하는 사람이 없으면 부패합니다. 이 파일을 프로덕션 코드와 동일하게 취급하세요:

• 풀 리퀘스트 (pull requests)에서 해당 파일의 변경 사항을 검토하세요.
• 현실이 변하는 즉시 업데이트하세요 (새로운 테스트 명령, 새로운 디렉토리 구조, 새로운 컨벤션 (convention) 등).
• 에이전트가 실제로 무엇을 하는지 관찰하세요. 에이전트가 추측하거나, 불필요한 질문을 하거나, 건드려서는 안 될 부분을 건드린다면, 그것은 대개 누락되었거나 오래된 지침 때문입니다.

유용한 습관: 채팅 중에 에이전트에게 동일한 지침을 두 번 이상 주게 된다면, 그 지침을 AGENTS.md로 옮기세요.

하나의 파일, 여러 에이전트

AGENTS.md의 강점은 특정 도구에 종속되지 않는다는 점입니다. 대부분의 주요 코딩 에이전트들은 이 파일을 직접 읽거나, 동일한 루트 레벨 지침 패턴으로 수렴합니다. 도구에 구애받지 않는 (tool-agnostic) 지침을 담은 일반적인 마크다운 (Markdown) 형식으로 작성하세요. "만약 X 도구를 사용한다면"과 같은 분기 처리는 피하세요.

모노레포 (monorepos)의 경우, 하위 디렉토리에 추가적인 AGENTS.md 파일을 배치할 수 있습니다. 대부분의 에이전트는 작업 중인 코드와 가장 가까운 파일을 사용합니다.

최소한의 완전한 예시

# AGENTS.md

Node 20, Postgres 기반의 TypeScript REST API이며, Fly.io에 배포됩니다.
...

에이전트(또는 새로운 인간 팀원)는 이를 30초 이내에 읽고 생산적인 작업을 시작할 수 있습니다.

좋은 AGENTS.md를 판가름하는 진짜 시험대

새로운 에이전트가 빌드 방법, 테스트 방법, 또는 어떤 컨벤션을 따라야 하는지 묻지 않고도—그리고 명시적으로 건드리지 말라고 지시한 것을 건드리지 않고도—저장소에 정확하고 테스트된 변경 사항을 반영할 수 있다면, 그 파일이 제대로 작동하고 있다는 것을 알 수 있습니다.

짧게. 최신 상태로. 구체적으로. 실행 가능하게. 이것이 이 파일의 전부입니다.

이것은 필드 가이드(field guide)였습니다 — '왜'와 '무엇'에 대한 내용이었죠.

시리즈의 다음 내용: 단계별 빌드 실습입니다. 실제 저장소를 대상으로 완전한 AGENTS.md를 작성한 다음, 에이전트에게 이를 지정하여 요청 없이도 빌드하고, 테스트하며, 가드레일 (guardrails)을 준수하는 모습을 지켜볼 것입니다. (1~2일 내 공개 예정.)