CLAUDE.md와 AGENTS.md는 무엇이 다른가: 역할별로 나누어 작성하는 실전 설계

「CLAUDE.md는 작성했는데, AGENTS.md는 뭐야? 같은 거 아니야?」

이 Qiita에 「CLAUDE.md를 팀 헌법으로 만든다면」이라는 기사를 올린 이후로 자주 받는 질문입니다. 저 자신도 처음에는 같은 것이라고 생각했습니다. 하지만 AGENTS.md는 2026년에 들어서면서 채택이 폭발적으로 늘어났으며, agents.md 규격은 Linux Foundation의 Agentic AI Foundation 산하에서 관리되는 오픈 표준(Open Standard)이 되었습니다.

GitHub에서 AGENTS.md를 포함하는 리포지토리는 6만 개를 넘어섰고, AGENTS.md가 정비된 프로젝트에서는 에이전트 생성 버그가 35-55% 감소했다는 벤치마크 결과도 나오고 있습니다.

본 기사에서는 CLAUDE.md와 AGENTS.md의 차이를 정리하고, 두 파일을 역할별로 나누는 실전 설계를 공유합니다.

먼저 결론입니다.

파일	주요 독자	1 리포지토리당 개수	역할
CLAUDE.md	Claude Code	1	Claude Code 고유의 설정 및 습관
AGENTS.md	임의의 AI 에이전트	1	프로젝트 공통 인덱스

CLAUDE.md는 Claude Code 전용입니다. AGENTS.md는 도구에 의존하지 않는 오픈 표준으로, Codex CLI, GitHub Copilot, Cursor, Windsurf, Amp, Devin 등이 2026년 시점에서 네이티브(Native)로 대응하고 있습니다.

즉, CLAUDE.md를 작성해도 Cursor는 읽지 않습니다. AGENTS.md를 작성해도 (2026년 5월 시점에서는) Claude Code는 네이티브로 읽지 않습니다. 역할이 다르기 때문에 양쪽 모두 작성하는 것이 현실적인 해답입니다.

「양쪽 다 작성하는 것은 이중 관리 아닌가?」라고 생각하실지도 모릅니다. 저도 그렇게 생각했습니다. 하지만 한 달간 운용해 본 결과, 명확하게 역할을 나누는 편이 유지보수하기 쉽다는 것을 실감하고 있습니다.

처음의 제 운용 방식입니다. CLAUDE.md에 무엇이든 적었습니다.

# CLAUDE.md (구 버전)
- EC 사이트 백엔드, FastAPI + PostgreSQL
- 디렉토리 구성: app/, tests/, scripts/...
...

3,000행을 넘어섰습니다. Claude Code는 매번 이것을 읽습니다. 이는 컨텍스트(Context)를 압박하여 정작 중요한 지시 사항을 희석시킵니다. Cursor와 Claude Code를 병용했을 때, Cursor 측에서 동일한 정보를 참조하고 싶어도 Cursor는 .cursor/rules/만 확인합니다.

# AGENTS.md (프로젝트 공통, 500자 이하)
## Overview
EC 사이트 백엔드. FastAPI + PostgreSQL.
...

# CLAUDE.md (Claude Code 고유 사항만, 200자 정도)
## Tools
- Read/Edit/Write 우선, Bash는 최후의 수단
...

CLAUDE.md는 「Claude Code 고유의 습관과 도구 사용법」만 작성합니다. 프로젝트 공통 정보는 AGENTS.md로 집약합니다. 이를 통해 Cursor/Codex/Windsurf/Devin과도 공통된 지시를 전달할 수 있게 되었습니다.

AGENTS.md 설계에서 가장 중요한 것은 거대한 문서로 만들지 않는 것입니다. Anthropic의 공식 가이드도, agents.md의 공식 사양도 입을 모아 이렇게 말합니다.

「AGENTS.md는 목차다. 상세 내용은 스킬 파일(Skill file)로」

저의 운용 방식은 다음과 같습니다.

프로젝트 루트/
├── AGENTS.md # 500자 이하의 인덱스
├── CLAUDE.md # Claude Code 고유의 200자
...

AGENTS.md에 쓰는 것은 "무엇이 어디에 있는가"뿐입니다. 상세 절차는 각 스킬 파일로 나눕니다. 에이전트는 필요할 때만 스킬 파일을 읽습니다 (Lazy load).

파일	권장 사이즈	역할
AGENTS.md	500자 이하	인덱스 · 헌법
...

사이즈 상한을 의식적으로 설정하고 있습니다. 이를 초과하면 스킬 파일로의 분할을 검토합니다.

스킬 파일은 「언제 · 어떻게 사용하는가」가 명확할수록 에이전트의 판단 정밀도가 높아집니다. 저의 템플릿은 다음과 같은 구조입니다.

# harness/skills/add-api-endpoint.md
## When to use
새로운 API 엔드포인트를 추가할 때
...

When to use가 서두에 있는 것이 중요합니다. 에이전트는 「이 스킬을 지금 읽어야 하는가」를 여기서 판단합니다. 모호하면 불필요하게 읽게 되어 컨텍스트 (Context)를 낭비합니다.

CLAUDE.md에 남기는 것은 Claude Code 특유의 설정뿐입니다. 제가 지금 작성하고 있는 내용은 다음과 같습니다.

# CLAUDE.md
## Tool Priority
- Read/Edit/Write 우선, Bash는 최후의 수단
...

200자 정도로 압축하여 작성합니다. 「Claude Code를 사용하는 우리만의 고유한 합의 사항」뿐입니다. 그 외의 내용은 AGENTS.md와 스킬 파일에 두는 것이 원칙입니다.

두 파일에 공통되는 설계 원칙으로서, 금지 사항에는 반드시 이유를 적는 것이 효과적입니다.

## Forbidden
- `any` 타입 사용 금지
→ 타입 안정성 (Type Safety)을 보장하기 위함. 타입을 알 수 없는 곳은 unknown + 타입 가드 (Type Guard)로 대응
...

이유 없는 금지는 인간도 지키고 싶지 않으며, 에이전트도 미지의 케이스에서 판단을 그르칩니다. 「왜 안 되는가」를 적음으로써, 에이전트가 엣지 케이스 (Edge Case)에서도 올바른 방향으로 판단할 수 있습니다.

AGENTS.md는 한 번 쓰고 끝내는 것이 아닙니다. 저의 운용 사이클은 다음과 같습니다.

1. AGENTS.md / 스킬 파일 작성
2. 에이전트에게 작업 지시
3. 틀린 부분 특정
...

에이전트가 「어라? 이 프로젝트에서는 import 에일리어스 (Alias)를 @/로 설정했는데, 상대 경로를 사용했네」라고 실수하면, 스킬 파일에 「Use @/ alias for imports, never relative paths」라고 한 줄 추가합니다.

Louis Bouchard의 말을 빌리자면, 「모델이 멍청하다」라고 말하는 것을 그만둡시다. 「내 시스템이 이 실패를 허용했다」라고 말합시다. 실수는 AGENTS.md 개선의 시그널입니다.

각 에이전트 도구의 AGENTS.md 대응 현황을 정리합니다.

도구	AGENTS.md	고유 파일
Codex CLI	◎ 네이티브	-
...	.windsurfrules (구형)
Amp	◎ 네이티브	-
Devin	◎ 네이티브	-
Claude Code	△ pending	CLAUDE.md
Gemini CLI	×	GEMINI.md

주요 도구의 대부분이 AGENTS.md를 지원합니다. Cursor/Windsurf의 구형 고유 파일 ( .cursorrules 등)은 AGENTS.md 대응 이후에는 옵션 사항으로 바뀌고 있습니다.

저의 운용 방침은 다음과 같습니다.

## 2026년 5월 시점의 나의 방침
1. AGENTS.md를 「정본 (Source of Truth)」으로 관리 (프로젝트 공통)
2. CLAUDE.md는 Claude Code 전용으로만 사용, AGENTS.md를 참조
...

Claude Code의 AGENTS.md 대응이 출시되면, CLAUDE.md는 고유 설정으로만 축소하고, AGENTS.md가 정본으로서 일원화되는 미래를 내다보고 있습니다.

제가 고객에게 권장하는 3단계 도입 플랜입니다. 팀 성숙도가 L1 (개인 에이전트 운용) 단계라 하더라도, 하루 만에 착수할 수 있습니다.

## Day 1: 자산 정리
1. 기존의 CLAUDE.md / .cursorrules / README에서 「프로젝트 공통 정보」를 추출
2. AGENTS.md (500자 이하) 신규 생성
...

3일이면 AGENTS.md 운용 체계가 잡힙니다. 중요한 것은 「완벽을 목표로 하지 않는 것」입니다. 투박하더라도 AGENTS.md를 두고, 사이클을 돌리면서 개선하는 것이 효율적입니다.

CLAUDE.md와 AGENTS.md는 역할이 다르므로 나누어 작성하는 것이 2026년 시점의 현실적인 해답입니다.

CLAUDE.md: Claude Code 고유의 습관, 200자 이하 -
AGENTS.md: 프로젝트 공통 인덱스, 500자 이하, 도구 비의존적 -
스킬 파일: 상세 절차, 각 300-500자, 레이지 로드 (Lazy Load)

AGENTS.md는 6만 개 이상의 리포지토리(Repository)로 확산되었으며, 에이전트 생성 버그를 35-55% 감소시키는 효과가 보고되었습니다. Claude Code의 AGENTS.md 대응이 출시되면, CLAUDE.md의 역할은 더욱 축소되고 AGENTS.md가 사실상의 표준(De facto standard)이 될 것입니다.

당신의 프로젝트의 CLAUDE.md는 몇 줄이나 되나요? 만약 3,000줄을 넘는다면, 이번 주에 AGENTS.md로 분리하는 작업을 시작할 가치가 있습니다.

• agents.md (공식 사양) (Linux Foundation Agentic AI Foundation)
• AGENTS.md Guide (2026): Copilot, Cursor & More
• CLAUDE.md, AGENTS.md & Copilot Instructions (DeployHQ)
• Keep your AGENTS.md in sync (Kaushik Gopal)
• Anthropic 「Claude Code Best Practices」 공식 가이드