AGENTS.md란? 모든 AI 코딩 도구가 읽는 '에이전트용 README' (2026)

 

AI 코딩 도구마다 "이 프로젝트는 이렇게 빌드하고, 이 폴더는 건드리지 마"를 매번 설명하기 지치셨나요? AGENTS.md 하나면 됩니다. 에이전트를 위한 README라고 보면 돼요 — 프로젝트 루트에 이 파일 하나만 써두면 Codex·Cursor·Copilot 등 30개가 넘는 도구가 알아서 읽습니다. 이 글에서 AGENTS.md가 뭐고, 뭘 적고, 어떻게 쓰는지 정리합니다.

📌 이 글에서 얻어갈 것

✓ AGENTS.md가 무엇인가 (오픈 표준)
✓ 무엇을 적나 (빌드·테스트·규칙·금지)
✓ 형식과 작성 예시
✓ CLAUDE.md·.cursorrules와의 관계

AGENTS.md란?

AGENTS.md는 AI 코딩 에이전트에게 프로젝트 맥락을 알려주는 오픈 표준입니다. 저장소 루트에 두는 마크다운 파일 하나로, 에이전트가 효과적으로 일하는 데 필요한 정보를 담죠. 거버넌스는 Linux Foundation 산하 AAIF(MCP를 관리하는 그 조직)가 맡고 있고, 2026년 중반 기준 6만 개가 넘는 저장소가 씁니다.

무엇을 적나

🔧 빌드·실행 명령 — 정확한 플래그까지 (예: npm run build)

🧪 테스트 방법 — 어떻게 검증하는지

🎨 코드 스타일 — 기본값과 다른 우리 팀 규칙

🚫 건드리지 말 것 — 수정 금지 파일·아키텍처 제약(중요!)

형식 — 그냥 마크다운

형식이 아주 단순합니다. 필수 필드도, YAML 프론트매터도, 특수 문법도 없어요. 그냥 제목과 불릿으로 쓰면 됩니다.

# AGENTS.md

## 빌드 & 테스트
- 설치: `npm install`
- 빌드: `npm run build`
- 테스트: `npm test` (통과해야 완료)

## 코드 스타일
- 들여쓰기 2칸, 세미콜론 사용
- 함수형 컴포넌트만 사용

## 건드리지 말 것
- `/legacy` 폴더는 수정 금지
- `.env` 등 시크릿은 절대 커밋 금지

어떤 도구가 읽나

호환성이 가장 넓습니다 — 30개가 넘는 에이전트가 읽어요:

OpenAI Codex · Cursor · GitHub Copilot · Claude Code(import) · Gemini CLI

Google Jules · Factory · Aider · Zed · VS Code · Windsurf · Devin …

"한 번 쓰면, 모든 AI 도구가 읽는다"
도구마다 규칙 파일을 따로 만들 필요가 없어진다

CLAUDE.md·.cursorrules와의 관계

AGENTS.md 크로스툴 오픈 표준. 도구를 안 가림. 여기에 공통 규칙을 몰아넣는 게 정석.

CLAUDE.md · .cursorrules 특정 도구(Claude·Cursor) 전용. 대개 AGENTS.md를 import하고 도구별 추가만.

※ 실전 팁: 공통 규칙은 AGENTS.md 하나에 쓰고, Claude Code용 CLAUDE.md에서는 @AGENTS.md로 불러오면 중복 없이 깔끔합니다.

자주 묻는 질문 (FAQ)

Q. README랑 뭐가 다른가요?

README는 사람을 위한 문서, AGENTS.md는 AI 에이전트를 위한 문서입니다. 빌드 명령·금지 규칙처럼 "에이전트가 실수하지 않도록" 하는 내용에 집중해요.

Q. 길게 써야 하나요?

아니요. 핵심만 간결하게가 좋습니다. 너무 길면 에이전트가 컨텍스트를 낭비해요. 빌드·테스트·금지사항부터 시작하세요.

Q. 하위 폴더에도 둘 수 있나요?

네, 모노레포라면 하위 디렉터리마다 AGENTS.md를 둘 수 있습니다. 가까운 파일이 더 구체적 규칙으로 우선 적용돼요.

마치며

AGENTS.md는 "AI 도구 파편화를 끝내는 하나의 표준"입니다. 도구마다 다른 규칙 파일을 만들 필요 없이, 이 파일 하나면 30+ 도구가 우리 프로젝트 규칙을 이해하죠. 빌드·테스트·금지사항부터 간결하게 써두면, 어떤 AI로 갈아타도 일관되게 일합니다.

여러분의 AGENTS.md엔 어떤 규칙을 넣으시나요? 댓글로 공유해주세요 🙌

---

※ 본 글은 2026년 7월 기준 자료를 확인해 작성했습니다. 주요 출처: agents.md(공식), Agentic AI Foundation(Linux Foundation), Codex·Cursor 문서. 표준·채택 도구는 계속 늘어나니 공식 사이트에서 현행 정보를 확인하세요.