CLAUDE.md vs AGENTS.md vs .cursorrules — AI 에이전트 가이드 파일 3종 비교 2026

CLAUDE.md·AGENTS.md·.cursor/rules 셋 중 어디부터 써야 할지 막막하다면, 셋이 서로 다른 도구 진영에서 나왔다는 점부터 짚어야 합니다. 도구를 한 번에 두 개 이상 같이 쓰는 환경(예: Claude Code + Cursor)에서 룰 파일을 잘못 배치하면, 매 세션마다 한 도구는 가이드를 못 읽고 답변 톤·금지 패턴이 무너집니다.

 

Claude Code를 본업에 매일 붙여 쓰면서 다른 AI CLI 도구도 병행 검토해본 관점에서, 2026년 6월 기준 세 형식의 공식 문서를 직접 확인하고 호환성·환경별 결정 기준을 정리했습니다. 비교 끝나면 환경에서 어느 파일을 어디에 둬야 할지 답이 보입니다.

지난 두 편에서 카파시 CLAUDE.md 65줄 원본 분석과 프로젝트에 맞게 변형하는 5단계를 다뤘다면, 이번 CLAUDE.md vs AGENTS.md vs .cursorrules 비교는 비슷한 역할을 하는 다른 도구들(.cursor/rules·AGENTS.md)과 무엇이 다르고 어떻게 같이 써야 하는지 정리하는 글입니다.

셋이 어떻게 다른가 — 한 줄로

세 파일은 모두 "AI 에이전트한테 프로젝트 룰을 알려주는 파일"이지만 출처와 적용 범위가 다릅니다.

• CLAUDE.md — Anthropic 공식. Claude Code가 자동으로 읽는 전용 메모리 파일. markdown 그대로.
• .cursor/rules/*.mdc — Cursor 공식. .cursorrules 단일 파일은 deprecated, 현재 표준은 디렉토리 + .mdc 확장자. YAML frontmatter로 자동 적용 조건 지정.
• AGENTS.md — Agentic AI Foundation (Linux Foundation 산하) 관리. 단일 회사 표준이 아닌 다중 도구 공통 표준. 2026년 6월 기준 OpenAI Codex·Google Jules·Devin·Aider·Windsurf 등 20개 이상 도구에서 인식.

한눈에 — 3개 가이드 파일 핵심 스펙

발행 시점 기준 공식 문서를 직접 확인한 스펙입니다.

항목	CLAUDE.md	.cursor/rules/*.mdc	AGENTS.md
출처	Anthropic	Cursor	Agentic AI Foundation
형식	Markdown	Markdown + YAML frontmatter	Markdown
위치	5곳 누적 로드 (managed/user/project/local/.claude/rules)	.cursor/rules/ 디렉토리	프로젝트 루트
확장자	.md	.mdc (.md는 무시됨)	.md
권장 길이	200줄 미만	500줄 미만	제한 없음 (간결 권장)
frontmatter	없음 (path-scoped rules는 있음)	description·alwaysApply·globs	없음
자동 파일 매칭	path-scoped rules로 가능	globs 패턴 매칭	없음 (전체 컨텍스트)
호환 도구	Claude Code 전용 (AGENTS.md import 가능)	Cursor 전용	20+ 도구 (Codex, Jules, Devin, Aider, Windsurf 등)
채택 규모	Anthropic 사용자	Cursor 사용자	60,000+ 오픈소스 프로젝트

표를 보면 가장 큰 차이는 "전용이냐 공통이냐"입니다. CLAUDE.md vs AGENTS.md vs .cursorrules 비교에서 CLAUDE.md·.cursor/rules는 각 도구 전용이고, AGENTS.md만 도구를 가리지 않는 공통 표준 위치에 있습니다. 프로젝트가 한 도구만 쓰면 전용 파일, 여러 도구 병행이면 AGENTS.md로 단일화하는 게 룰 동기화 비용을 0으로 만듭니다.

CLAUDE.md — Anthropic 공식 메모리 파일

Claude Code가 자동으로 읽는 markdown 파일입니다. /init 명령으로 자동 생성도 됩니다.

5곳에서 누적 로드 (공식 문서 기준):

1. Managed policy (조직 전체) — macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md
2. User instructions — ~/.claude/CLAUDE.md
3. Project instructions — ./CLAUDE.md 또는 ./.claude/CLAUDE.md
4. Local instructions — ./CLAUDE.local.md (gitignore 권장)
5. Path-scoped rules — .claude/rules/ 디렉토리 (YAML frontmatter 있음)

다섯 위치에서 모두 읽어 누적하기 때문에, 회사 공통 룰은 1번, 개인 룰은 2번, 프로젝트 룰은 3번에 두는 분리가 가능합니다. 권장 길이는 200줄 미만 — 그 이상이면 모델이 다 읽고도 일부를 잊어버리기 시작한다는 게 공식 가이드 입장입니다.

AGENTS.md를 같은 프로젝트에 두면 CLAUDE.md에서 @AGENTS.md 한 줄로 import해 호환됩니다. 이 점이 멀티 도구 환경에서 중요합니다.

# CLAUDE.md

이 프로젝트의 공통 AI 룰은 AGENTS.md에 정의되어 있습니다.

@AGENTS.md

추가로 Claude Code 전용 룰:
- 답변은 한국어로
- 파일 패치는 unified diff 형식

.cursor/rules/ — Cursor 디렉토리 룰

⚠️ 자주 헷갈리는 부분 — .cursorrules 단일 파일은 deprecated입니다. 현재 Cursor 공식 가이드(cursor.com/docs/context/rules)에서 권장하는 표준은 .cursor/rules/ 디렉토리 + .mdc 확장자 파일입니다. .md 파일은 frontmatter가 없어서 무시됩니다.

4가지 룰 유형:

• Project Rules — .cursor/rules/*.mdc (가장 많이 씀)
• User Rules — Cursor 설정 화면에서 입력 (모든 프로젝트 공통)
• Team Rules — 팀 단위 공유 룰
• AGENTS.md — 간단한 대안 (frontmatter 없음, 전체 로드)

.mdc 파일은 YAML frontmatter로 자동 적용 조건을 지정합니다. 권장 길이는 500줄 미만.

---
description: TypeScript 컴포넌트 코딩 룰
alwaysApply: false
globs:
  - "src/**/*.tsx"
  - "src/**/*.ts"
---

# TypeScript Rules

- 함수형 컴포넌트만 사용 (class 금지)
- Props 타입은 interface로 정의
- useState 대신 Context API 우선 검토

globs 필드가 핵심입니다. 파일 패턴이 매칭되면 Cursor가 해당 파일을 편집할 때만 이 룰을 자동 첨부합니다. CLAUDE.md의 5곳 누적 로드와 다르게, 패턴별로 다른 룰 묶음을 다르게 적용할 수 있는 게 .cursor/rules의 차별점입니다.

AGENTS.md — 다중 도구 공통 표준

agents.md 공식 사이트 기준, AGENTS.md는 단일 회사 표준이 아니라 Agentic AI Foundation (Linux Foundation 산하) 가 관리하는 공통 표준입니다. 초기 개발에 OpenAI Codex·Amp·Google Jules·Cursor·Factory가 함께 참여했고, 2026년 6월 기준 20개 이상 도구가 인식합니다.

인식 도구 목록 (공식 사이트 기준):

• OpenAI Codex, Google Jules, Devin, VS Code, Cursor, Windsurf, Aider, goose
• GitHub Copilot Coding Agent, Zed, Warp, UiPath Autopilot
• Amp, RooCode, Gemini CLI, Semgrep 외

채택 규모: 60,000개 이상 오픈소스 프로젝트가 AGENTS.md를 두고 있습니다. OpenAI 자체 레포·Apache Airflow·Temporal 등이 포함됩니다. Claude Code는 기본적으로 CLAUDE.md를 우선 읽지만, @AGENTS.md import 한 줄로 호환됩니다.

형식은 표준 markdown입니다. 필수 필드도 frontmatter도 없습니다. "도구가 한 파일로 합의했다"는 점이 가치이지, 새 문법이 따로 있는 건 아닙니다.

호환성 매트릭스 — 같이 쓰는 법

이게 핵심입니다. 한 프로젝트에서 두 도구 이상 쓰면 어떤 조합이 룰 동기화 비용이 가장 적은가.

사용 도구 조합	권장 파일 배치	비고
Claude Code 단독	CLAUDE.md 1개	가장 단순. 200줄 미만 유지.
Cursor 단독	.cursor/rules/*.mdc	globs로 파일별 룰 분리 가능.
멀티 AI 도구 (Codex·Aider·Jules)	AGENTS.md 1개	단일 파일로 20+ 도구 커버.
Claude Code + Cursor 병행	AGENTS.md 1개 + CLAUDE.md에서 @AGENTS.md import	룰을 AGENTS.md에 모으고 CLAUDE.md는 import만.
Claude Code + 멀티 도구	AGENTS.md + CLAUDE.md(import)	위와 동일 패턴.
대규모 모노레포	.cursor/rules/ 디렉토리 + path-scoped + AGENTS.md	폴더별 룰 다르게, 전체 룰은 AGENTS.md.

가장 자주 쓰는 패턴은 4번 — Claude Code와 Cursor를 둘 다 쓰는 경우입니다. 같은 룰을 두 파일에 복붙하면 한쪽 수정할 때 다른 쪽 잊어버립니다. AGENTS.md에 모으고 CLAUDE.md는 한 줄 import만 두면 동기화 문제가 사라집니다.

Linux/macOS 환경에서는 symlink로 더 간단하게 처리할 수 있습니다.

# AGENTS.md를 단일 진실 소스로 두고 CLAUDE.md를 symlink
ln -s AGENTS.md CLAUDE.md

# 확인
ls -la CLAUDE.md
# lrwxr-xr-x  CLAUDE.md -> AGENTS.md

Windows에서는 symlink가 권한 이슈가 있어 import 한 줄 방식이 더 안정적입니다.

환경별 결정 매트릭스 — 어디에 해당하나

5단계 흐름으로 환경을 판별합니다.

1. Q1. 쓰는 AI 도구가 Claude Code 하나뿐인가? → YES면 CLAUDE.md 단독. 끝.
2. Q2. Cursor만 쓰는가? → YES면 .cursor/rules/ 디렉토리 + .mdc. 끝.
3. Q3. 두 개 이상 도구를 같이 쓰는가? → YES면 AGENTS.md를 단일 진실 소스로.
4. Q4. Claude Code도 같이 쓰는가? → YES면 CLAUDE.md에 @AGENTS.md import 한 줄 추가.
5. Q5. 모노레포에서 폴더별 룰이 다른가? → YES면 .cursor/rules/의 globs + path-scoped 룰 활용.

대부분의 1인 개발자나 소규모 팀은 Q1·Q2에서 끝납니다. Q3 이후는 도구를 의도적으로 분업하거나(예: 기획은 Codex, 코딩은 Claude Code) 회사 차원에서 멀티 도구 정책이 있는 경우입니다.

흔한 함정 3가지

문서를 보고 시작해도 자주 빠지는 함정입니다.

함정 1 — .cursorrules 파일을 그대로 두기. Cursor가 deprecated로 표시했고 신규 기능(globs·alwaysApply)이 안 됩니다. 현재 표준은 .cursor/rules/ 디렉토리 + .mdc. 옛 .cursorrules는 삭제하고 디렉토리로 이전하세요.

함정 2 — AGENTS.md만 두고 Claude Code가 인식 안 됨. Claude Code는 기본적으로 CLAUDE.md를 우선 읽습니다. AGENTS.md만 있으면 무시될 수 있으니, CLAUDE.md를 만들고 @AGENTS.md import 한 줄을 추가하거나 symlink로 연결해야 합니다.

함정 3 — CLAUDE.md를 200줄 넘기기. 공식 권장 길이를 넘어가면 모델이 다 읽고도 일부를 잊어버리기 시작합니다. 길어지면 path-scoped rules(.claude/rules/)로 폴더별·기능별로 쪼개거나, 공통 룰은 AGENTS.md로 빼서 import 받으세요.

트레이드오프 — 어느 쪽도 정답은 아님

CLAUDE.md vs AGENTS.md vs .cursorrules 비교에서 세 형식 다 장단점이 있습니다. 한 쪽만 옳다는 결론은 아닙니다.

• CLAUDE.md만 쓰기 — 장점은 단일 도구 환경에서 가장 단순. 단점은 다른 도구를 추가하면 룰 두 벌 관리.
• .cursor/rules만 쓰기 — 장점은 globs로 파일 패턴별 자동 적용이 강력. 단점은 Cursor 외 도구 인식 안 됨.
• AGENTS.md 위주 — 장점은 멀티 도구 환경에서 동기화 비용 0. 단점은 Cursor의 globs 같은 세밀한 자동 매칭 기능이 없음.

환경에서 "도구 1개 + 룰 1벌"이면 전용 파일, "도구 2개+ 또는 팀 공유"면 AGENTS.md 우선이 일관된 결론입니다.

결정 전 자주 보는 질문

Q. Claude Code만 쓰는데 AGENTS.md도 만들어야 하나요?
A. 안 만들어도 됩니다. CLAUDE.md 하나로 충분합니다. 다만 나중에 Cursor·Codex 같은 도구를 추가할 가능성이 있다면 처음부터 AGENTS.md에 룰을 쓰고 CLAUDE.md는 @AGENTS.md import만 두는 게 이전 비용을 0으로 만듭니다.

Q. .cursorrules 파일 그대로 두면 안 되나요?
A. 단기적으로는 인식되지만 deprecated 상태입니다. Cursor 공식 가이드는 .cursor/rules/ 디렉토리로 이전하라고 명시합니다. 새 기능(globs로 파일 패턴별 자동 적용, alwaysApply 토글)은 디렉토리 방식에서만 동작합니다.

Q. 한 프로젝트에 셋 다 같이 두면 충돌 안 나나요?
A. 충돌은 안 나지만 룰이 중복되면 모델이 헷갈립니다. 권장은 단일 진실 소스(AGENTS.md)에 룰을 모으고, CLAUDE.md·.cursor/rules는 import 또는 짧은 도구 전용 추가만 담는 패턴입니다.

Q. AGENTS.md는 어디에 두는 게 표준인가요?
A. 프로젝트 루트(./AGENTS.md)가 표준 위치입니다. 모든 인식 도구가 루트를 우선 검색합니다. 모노레포라면 각 패키지 루트에 둘 수도 있지만, 일반적으로는 한 레포에 하나로 충분합니다.

Q. 팀에서 도입할 때 어떤 형식이 좋나요?
A. 팀원이 쓰는 AI 도구가 통일돼 있으면 전용 파일(CLAUDE.md 또는 .cursor/rules), 도구가 섞여 있으면 AGENTS.md 단일화가 룰 충돌·동기화 비용을 가장 적게 만듭니다. 신규 입사자가 다른 도구를 들고 와도 AGENTS.md 한 파일이면 즉시 적용됩니다.

📚 Claude Code 시리즈 — 처음 쓰는 사람부터 자동화까지

1. 단 1달러도 내지 않고 Claude Code 사용하는 방법 — 입문
2. Claude Code 창시자·해커톤 우승자 꿀팁 7가지 — 팁
3. Claude Cowork 자동화 — 매일 아침 카톡 AI 브리핑 — 자동화
4. Claude Code 활용법 — 망치는 습관 3개·살리는 습관 7개 — 베스트 프랙티스
5. 카파시 CLAUDE.md — 65줄 파일 정리 — 사례 (시리즈 1편)
6. CLAUDE.md 작성법 — 카파시 65줄을 프로젝트에 맞게 변형하는 5단계 — 실전 작성
7. 👉 현재 글 — CLAUDE.md vs AGENTS.md vs .cursorrules — AI 에이전트 가이드 파일 3종 비교

처음 보시는 분은 단 1달러도 내지 않고 Claude Code 사용하는 방법부터 보세요.

환경에 맞는 쪽을 위 매트릭스에서 고르면 됩니다. CLAUDE.md vs AGENTS.md vs .cursorrules 어느 쪽이 정답인지는 환경에 따라 다르지만, 단일 도구면 전용 파일, 멀티 도구면 AGENTS.md로 모으고 import만 거는 패턴이 룰 동기화 비용을 가장 적게 만듭니다. 블로그 다른 글도 한번 둘러봐 주세요.

설치 환경: Windows 11, Node.js v24, Claude Code, Cursor 검토용