이 글에서 다루는 내용: AGENTS.md의 정체와 표준화 경위, 담을 내용, CLAUDE.md·Rules와의 계층 구성, 작성 팁.
왜 생겼나
도구마다 설정 파일이 달랐기 때문입니다 — Claude Code는 CLAUDE.md, Cursor는 .cursor/rules, 다른 도구는 또 제각각. 팀이 도구를 섞어 쓰면 같은 내용을 여러 파일에 복붙하는 문제가 생겼고, "에이전트가 읽는 프로젝트 안내서" 하나를 표준화하자는 답이 AGENTS.md입니다. 상반기의 도구 통합·종료 흐름을 겪은 뒤라(도구는 사라져도 저장소는 남으니) 도구 중립 파일의 가치가 더 커졌습니다.
뭘 적나
형식 제약은 없는 마크다운이고, 실무 표준 구성은 이렇습니다: 빌드·실행·테스트 명령(에이전트가 가장 자주 틀리는 것), 코드 관례(스타일, 네이밍, 선호 패턴), 프로젝트 구조(뭐가 어디 있는지), 금지 사항("마이그레이션 파일 직접 수정 금지" 같은 경계), PR·커밋 규칙. 연구 기준으로 150줄을 넘으면 효과 대비 비용(토큰)이 나빠진다는 결과가 있으니, 위키가 아니라 요약본으로 유지하세요. 내용 작성 원칙은 CLAUDE.md 작성법과 완전히 같습니다 — 파일 이름만 다를 뿐.
CLAUDE.md·Cursor Rules와의 계층 구성
| 파일 | 읽는 도구 | 둘 것 |
|---|---|---|
| AGENTS.md | 30+ 도구 공통 | 빌드·테스트 명령, 관례, 경계 (공통 지식) |
| CLAUDE.md | Claude Code | Claude Code 특화 (스킬·훅 관련 지시 등) |
| .cursor/rules/ | Cursor | globs 기반 영역 규칙 등 Cursor 특화 기능 |
실전 팁: CLAUDE.md에 "AGENTS.md를 먼저 읽어라"라는 한 줄을 두거나 내용을 참조시키면 중복 관리가 사라집니다. Cursor Rules는 globs(파일 타입별 적용) 같은 AGENTS.md에 없는 메커니즘이 있으므로, 그 기능이 필요한 내용만 Rules로 남기면 됩니다. 이미 CLAUDE.md만 있는 프로젝트라면 파일을 AGENTS.md로 복사하는 것부터가 시작입니다 — OpenCode처럼 AGENTS.md를 기본으로 읽는 도구(소개)를 병용할 때 바로 효과를 봅니다.
도입해본 소감
제 프로젝트는 CLAUDE.md 중심이었는데, OpenCode와 Orca를 시험하면서 AGENTS.md로 공통 내용을 옮겼습니다. 재밌는 부수 효과가 있었는데 — 여러 도구가 같은 파일을 읽는다고 생각하니 내용이 자연스럽게 도구 중립적인 "사실"로 정제됐습니다. "이 프로젝트는 이렇게 되어 있다"는 남고, "너는 이렇게 행동해라"류의 도구 종속 지시는 각 파일로 갈라졌죠. 결과적으로 문서 품질이 올라갔고, 새 도구를 시험하는 비용이 눈에 띄게 줄었습니다.
자주 묻는 질문 (FAQ)
Q. Claude Code도 AGENTS.md를 읽나요?
A. CLAUDE.md가 기본이지만 AGENTS.md 생태계와의 호환은 계속 넓어지는 추세입니다. 확실한 방법은 CLAUDE.md에서 AGENTS.md를 참조시키는 것 — 어느 쪽이든 동작합니다.
Q. 하위 폴더에도 둘 수 있나요?
A. 네, 모노레포에서는 루트에 공통 AGENTS.md를, 패키지별 폴더에 각자의 AGENTS.md를 두는 계층 구성이 표준 관례입니다. 에이전트는 작업 위치에 가까운 파일을 우선합니다.
Q. 얼마나 길게 써야 하나요?
A. 150줄 이하를 권합니다. 그 이상은 토큰 비용만 늘고 효과가 정체된다는 실증 결과가 있습니다. 상세 문서는 링크로 참조시키세요.
한눈에 보는 요약
AGENTS.md = 에이전트용 README, Linux Foundation 관할의 도구 중립 표준. 공통 지식은 여기에, 도구 특화만 CLAUDE.md·Rules에. 시작은 기존 CLAUDE.md를 복사하는 것부터.
함께 보면 좋은 글
CLAUDE.md 작성법
Cursor Rules 실전 레시피 5가지
OpenCode란? (AGENTS.md 기본 채택 도구)
참고 자료
'AI 코딩 일반' 카테고리의 다른 글
| 에이전트 관제 도구 3종 비교: Orca vs Cursor Agents Window vs Google Antigravity (1) | 2026.07.21 |
|---|---|
| Orca 설치하고 Claude Code 물려서 시작하기: 10분 세팅기 (0) | 2026.07.21 |
| 에이전트에게 하루를 맡겨본 기록: 오전 9시부터 퇴근까지 (0) | 2026.07.19 |
| AI 도구에 월 얼마 쓰나: 내 구독 내역을 공개합니다 (0) | 2026.07.19 |
| AI 코딩 에이전트에게 API 키를 흘리지 않는 법: 시크릿 보안 실전 체크리스트 (0) | 2026.07.19 |