Cursor Rules vs CLAUDE.md vs AGENTS.md: 설정 하나로 세 도구 모두 돌려봤다 (2026)

Cursor Rules vs CLAUDE.md vs AGENTS.md: 설정 하나로 세 도구 모두 돌려봤다 (2026)

cursor rules vs claude md라는 질문에는 함정이 하나 있다. 둘 중 하나를 고르는 선택지가 아니라는 점이다. 이건 두 개의 파일이고, 두 개의 서로 다른 도구가 읽으며, 우연히 같은 일을 한다. CLAUDE.md를 Cursor 프로젝트에 넣으면 Cursor는 무시한다. AGENTS.md를 Claude Code에 넣어도 아무 일도 일어나지 않는다. 우리도 놀랐다. AGENTS.md는 현재 60,000개 이상의 리포지토리에서 오픈 표준으로 자리 잡았고, Linux Foundation 산하 Agentic AI Foundation이 관리하고 있지만, Claude Code는 여전히 자체적으로 이 파일을 읽지 않는다. 아래는 우리 리포지토리에서 직접 테스트한 호환성 맵이다.

핵심 요약

• Cursor는 .cursor/rules/*.mdc와 AGENTS.md를 읽지, CLAUDE.md는 읽지 않는다.
• Claude Code는 CLAUDE.md만 읽고, AGENTS.md는 네이티브로 읽지 않는다.
• 파일 하나를 공유하려면: AGENTS.md를 CLAUDE.md에 심볼릭 링크하거나, @AGENTS.md로 임포트하면 된다.
• AGENTS.md(오픈 표준, 60k+ 리포지토리)로 표준화한 뒤, 도구별 오버라이드를 추가하라.

어떤 설정 포맷을 써야 할까? 30초 의사결정

포맷은 팀 구성에 따라 고르되, 유행에 따라 고르지 마라. 도구 하나만 쓴다면 그 도구의 네이티브 파일을 써라. 두 개 이상 쓴다면 AGENTS.md를 단일 진실 공급원(source of truth)으로 삼고, 다른 도구에는 없는 무언가가 필요한 도구에만 도구별 오버라이드를 추가하라. 이 규칙 하나면 대부분의 혼란이 정리된다.

어떤 어시스턴트를 돌릴지 아직 결정 중이라면? 먼저 어떤 AI 코딩 에이전트를 쓸지 고르는 가이드부터 읽고, 파일 세팅은 그 다음으로 돌아와라.

여기서 진짜 중요한 판단 축은 **이식성(portability)**이다. .cursor/rules 파일은 Cursor 안에서는 강력하지만 그 밖에서는 쓸모가 없다. AGENTS.md는 어디든 따라간다. 그러니 하나의 도구에 영원히 묶일 게 아니라면, 도구 무관 파일이 더 안전한 선택이다.

각 포맷이 실제로 뭔지 (각각 30초 버전)

이 세 파일은 모두 한 가지를 한다. AI 코딩 도구가 코드를 한 줄 쓰기 전에 프로젝트의 규칙, 컨벤션, 주의사항을 넘겨주는 것이다. 차이는 누가 읽고, 어떻게 스코프를 정하느냐다. 아래는 짧은 버전이고, 각각의 상세 how-to는 개별 가이드에 있다.

Cursor Rules는 .cursor/rules/ 안에 있는 .mdc 파일이다. Cursor는 4가지 규칙 타입(항상 적용, 에이전트 요청, glob 스코프, 수동 @ 멘션)을 지원해서, *.tsx 파일에만 또는 마이그레이션에만 규칙을 붙일 수 있다. frontmatter, glob, 토큰 예산에 대해서는 실제로 .cursor/rules 파일을 작성하는 법 가이드를 읽어라.

CLAUDE.md는 Claude Code의 메모리 파일이다. Claude는 작업 폴더에서 디렉터리 트리를 위로 올라가면서 만나는 모든 CLAUDE.md를 이어 붙인다. 순수 Markdown이고, frontmatter는 필요 없다. 구조와 Claude가 무시하지 않게 만드는 규칙은 Claude가 무시하지 않는 CLAUDE.md를 만드는 법을 참고하라.

AGENTS.md는 오픈 표준이다. 리포지토리 루트에 순수 Markdown 파일 하나를 두면 Cursor, Codex, Copilot, Windsurf, Zed, Aider 등 수십 개 도구가 네이티브로 읽는다. Agentic AI Foundation이 관리하며, 이미 60,000개 이상의 프로젝트에 존재한다.

기억할 만한 관점 전환: AGENTS.md, CLAUDE.md, .cursor/rules는 경쟁자가 아니라, 같은 지시문을 다른 수신자에게 보내는 것이다.

Cursor Rules vs CLAUDE.md vs AGENTS.md: 마스터 비교표

차이를 가장 빠르게 보는 방법은 나란히 놓고 보는 것이다. 결정적인 열은 이식성이다. 어떤 도구가 추가 세팅 없이 이 파일을 읽느냐. AGENTS.md는 도달 범위에서 이기고, Cursor Rules는 스코프 정밀도에서 이기며, CLAUDE.md는 Claude Code에 올인한 사람에게 이긴다.

.cursorrules 행을 주목하라. 그 단일 루트 파일은 아직 Cursor에서 작동하지만, 문서에서 빠졌다. 레거시로 취급하라. 새 프로젝트는 .cursor/rules/*.mdc나 AGENTS.md를 써야 한다.

어떤 도구가 어떤 파일을 읽나? (AGENTS.md 미신 깨기)

인터넷의 절반이 틀리는 사실: Claude Code는 AGENTS.md를 네이티브로 읽지 않고, Cursor는 CLAUDE.md를 읽지 않는다. Cursor는 .cursor/rules/*.mdc와 AGENTS.md를 읽는다. Claude Code는 CLAUDE.md만 읽고 그 외에는 아무것도 읽지 않는다. 어느 방향으로도 자동 폴백은 없고, 표준 파일 하나로 모든 게 커버된다고 가정하는 팀들이 여기서 걸린다.

이 질문이 너무 자주 나오니 직설적으로 말하겠다. AGENTS.md를 Claude Code 프로젝트에 넣는 것만으로는 아무 일도 일어나지 않는다. Claude Code는 CLAUDE.md만, 오직 CLAUDE.md만 읽는다. Anthropic의 Claude Code 메모리 문서는 파일 로드 동작을 설명하면서 AGENTS.md를 언급하지 않고, AGENTS.md 스펙은 네이티브 리더로 Cursor와 Codex를 나열하지만 Claude Code는 빼고, Cursor 자체 규칙 문서도 이 분리를 확인하며, Claude Code GitHub 이슈에는 정확히 이 벽에 부딪힌 개발자들로 가득하다.

그럼 Cursor는 claude.md를 읽나? 아니다. Claude Code는 agents.md를 읽나? 도움 없이는 안 된다. 그 "도움"이 이 글이 존재하는 이유 전체이고, 다음에 나올 짧은 명령어 두 개다.

우선순위와 중첩은 어떻게 작동하나, 나란히 비교

각 도구는 충돌을 다르게 해결하고, 이걸 잘못 이해하는 것이 "왜 내 규칙이 무시되지?" 혼란의 1위 원인이다. Cursor는 소스 우선순위로 규칙을 병합한다. Claude Code는 디렉터리 깊이로 이어 붙인다. AGENTS.md는 트리에서 가장 가까운 파일을 고른다. 좋은 claude md management는 지금 어떤 멘탈 모델 안에 있는지 아는 것에서 시작한다.

우리 세팅에서 실질적 결론은 간단하다. 넓은 규칙은 위(리포지토리 루트)에, 구체적인 규칙은 아래(패키지 폴더 안)에 둬라. Claude Code와 AGENTS.md 둘 다, 작업 위치에 가장 가까운 파일이 우선순위를 가지므로, packages/api/AGENTS.md는 그 폴더 안의 모든 것에 대해 루트 파일을 오버라이드한다. Cursor는 예외로, 폴더 깊이가 아니라 소스 티어로 해결한다.

Cursor + Claude Code에 하나의 설정을 돌려봤다, 각 도구가 실제로 불러온 것

우리는 실제 Techsy 클라이언트 리포지토리(Next.js 15 백엔드)에서 Cursor 3.7(2026년 6월 17일 빌드)과 Claude Code v2.1.x(2026년 7월 초)로 테스트했다. AGENTS.md 하나, 3가지 공유 세팅, 같은 프롬프트를 두 도구에서 열었다. 아래가 각 도구가 실제로 가져온 것이다.

최소 파일로 시작했다:

# AGENTS.md
- Package manager: pnpm, never npm.
- Tests: Vitest. Run `pnpm test` before any commit.
- DB access goes through `lib/db.ts` only, no inline SQL.

세팅 1: AGENTS.md만. Cursor는 즉시 인식했다. 파일이 컨텍스트에 표시됐고, npm install을 제안하지 않는 것도 정확했다. Claude Code는 아무것도 하지 않았다. Claude Code에서 /memory를 실행하니 프로젝트 메모리 파일이 0개로 나왔다. CLAUDE.md를 찾지 못했고, AGENTS.md는 인식조차 되지 않았다. 확인: 네이티브 폴백 없음.

세팅 2: 심볼릭 링크. CLAUDE.md를 같은 파일로 연결했다:

ln -s AGENTS.md CLAUDE.md

이제 Claude Code에서 /memory가 ./CLAUDE.md를 Project memory로 나열했고, 로드된 내용은 우리 AGENTS.md와 바이트 단위로 동일했다. Cursor는 여전히 AGENTS.md를 직접 읽었다. 물리적 파일 하나, 두 도구 모두 만족. Windows에서는 관리자 권한 또는 개발자 모드를 활성화해야 하며, 그렇지 않으면 ln/mklink가 조용히 실패한다.

세팅 3: @import. 심볼릭 링크를 삭제하고, 실제 CLAUDE.md 맨 위에 한 줄을 넣었다:

@AGENTS.md

/memory는 CLAUDE.md를 로드된 파일로 표시하고, 그 아래에 AGENTS.md가 임포트된 참조로 끌려온 것을 보여줬다. 이건 Anthropic이 실제로 문서화한 경로이고, 특별한 OS 권한이 필요 없다.

우리 테스트의 결론: 심볼릭 링크는 Claude Code가 AGENTS.md를 바이트 단위로 그대로 읽게 만들고, @AGENTS.md 임포트는 Anthropic이 실제로 권장하는 Windows 안전 버전이다. 둘 다 단일 진실 공급원을 제공한다. macOS/Linux에서는 간접 참조 제로의 심볼릭 링크를, 팀에 Windows 사용자가 있으면 임포트 한 줄을 선택하라.

포맷 간 마이그레이션: .cursorrules → .cursor/rules → AGENTS.md

대부분의 팀은 레거시 .cursorrules 파일을 들고 여기에 도착해서 단일 파일 함정에서 벗어나고 싶어 한다. 마이그레이션은 어느 방향이든 짧고, 복붙이면 된다. 사람들이 걸리는 함정 하나: .cursor/rules 안의 .md 파일은 frontmatter 없이 조용히 무시되므로, 반드시 .mdc여야 한다.

오래된 .cursorrules를 현대화하는 깔끔한 경로는 두 가지다:

• .cursor/rules/*.mdc로: .cursor/rules/general.mdc를 만들고, frontmatter를 추가하고(전역 규칙이면 alwaysApply: true), 기존 내용을 그 아래에 붙여넣어라. 확인 후 .cursorrules를 삭제하라.
• AGENTS.md로 (다중 도구 팀에 권장): cursorrules를 agents.md로 변환하려면, .cursorrules의 본문을 리포지토리 루트의 새 AGENTS.md에 복사하라. frontmatter 불필요; 순수 Markdown이다. 그런 다음 심볼릭 링크나 @AGENTS.md 임포트를 추가해서 Claude Code도 읽게 하라.

Cursor 안에 머물면서 더 뽑아내고 싶다면, Cursor를 일상에서 더 효율적으로 쓰는 법 가이드가 실무에서의 규칙 스코핑을 다룬다.

반대 방향(AGENTS.md → CLAUDE.md)은 지난 섹션의 심볼릭 링크나 임포트 그대로다. 세 가지 모두 내부적으로 Markdown이므로 손실 변환은 없다.

SKILL.md와 Copilot Instructions는 어디에 해당하나?

이 대화에 두 개의 포맷이 더 등장하고, skills md는 지금 급상승 검색어이므로 빠르게 위치를 짚을 가치가 있다. 둘 다 세 가지 메인 파일을 대체하지 않고, 그 옆에 자리한다.

SKILL.md는 Anthropic의 Skills 포맷이다. .claude/skills/*/SKILL.md에 번들된 태스크별 지시문으로, CLAUDE.md처럼 항상 켜져 있는 게 아니라 태스크가 매칭될 때 Claude가 온디맨드로 로드한다. Claude가 꺼내 드는 전문 플레이북이지, 프로젝트 전체 메모리 파일이 아니다. 스코프는 아직 진화 중이므로, 아직 과하게 투자하지 마라. 실제 워크플로우에서 어떻게 맞는지 보려면 실제 Claude Code 워크플로우에서 CLAUDE.md의 위치를 참고하라.

Copilot instructions는 GitHub Copilot용 .github/copilot-instructions.md에 있다. 좋은 소식: Copilot도 AGENTS.md를 읽으므로, 오픈 표준으로 표준화했다면 별도 파일 없이 Copilot은 이미 커버된다.

뭘 써야 하나? (팀 구성별)

포맷을 팀의 실제 작업 방식에 맞춰라:

• 1인 Claude Code 사용자: 그냥 CLAUDE.md를 써라. 나중에 Cursor나 Codex를 들일 계획이 없다면 AGENTS.md를 추가할 이유가 없다.
• 1인 Cursor 사용자: glob 스코프를 위해 .cursor/rules/*.mdc, 또는 첫날부터 이식성을 원하면 단일 AGENTS.md.
• 혼합 도구 팀: AGENTS.md 하나를 단일 진실 공급원으로, CLAUDE.md에 심볼릭 링크 또는 임포트. Cursor 전용 동작에만 작은 .cursor/rules 파일을 추가하라.
• 모노레포: 루트에 AGENTS.md + 패키지별 중첩 파일, 각 서브프로젝트가 스스로를 설명하고 가장 가까운 파일이 이긴다.

Techsy에서는 혼합 도구 팀 전체에 AI 코딩 설정을 표준화한다. 보통 AGENTS.md 하나를 단일 진실 공급원으로 두고, 도구가 필요로 하는 곳에 도구별 오버라이드를 둔다. 팀이 세 개의 설정 파일을 수동으로 돌리고 있다면, 무료 상담을 받아라. 우리가 구조를 잡아준다.

마지막 포인터: 이 글은 설정 파일을 비교한다. 도구 자체를 비교하려는 거라면, 설정 파일이 아닌 어시스턴트 자체 비교를 읽어라.

저자 소개

Mert Batur Gurbuz는 Techsy.io의 공동 창업자로, 팀은 B2B 클라이언트를 위한 AI 에이전트, 자동화 시스템, 음성/SDR 파이프라인을 구축한다. University of Birmingham에서 공부하며, Techsy 팀이 실제 프로덕션에서 사용하는 LLM 도구 스택에 대해 쓴다.

공동 창업자, Techsy.io · University of Birmingham · LinkedIn

자주 묻는 질문

Cursor는 CLAUDE.md를 읽나?

아니다. Cursor는 .cursor/rules/*.mdc와 AGENTS.md를 네이티브로 읽지만, CLAUDE.md는 Cursor 문서에 언급되지 않으며 로드되지 않는다. Cursor를 쓰면서 Claude Code 사용자와 설정을 공유하고 싶다면, 규칙을 CLAUDE.md가 아닌 AGENTS.md(Cursor가 실제로 읽는 파일)에 넣어라.

Claude Code는 AGENTS.md를 읽나?

네이티브로는 아니다. Claude Code는 CLAUDE.md만 읽고, AGENTS.md로의 자동 폴백은 없다. 작동시키려면, 파일을 심볼릭 링크(ln -s AGENTS.md CLAUDE.md)해서 Claude가 AGENTS.md를 바이트 단위로 읽게 하거나, CLAUDE.md 1행에 @AGENTS.md를 추가해서 임포트하라. 임포트가 Anthropic이 권장하는 Windows 안전 옵션이다.

세 도구 모두에 파일 하나만 쓸 수 있나?

가능하다. AGENTS.md를 단일 진실 공급원으로 삼으면 Cursor와 Codex는 직접 읽는다. Claude Code에는 브릿지 하나를 추가하라. AGENTS.md를 CLAUDE.md에 심볼릭 링크하거나, CLAUDE.md 맨 위에 @AGENTS.md를 넣으면 된다. 파일 하나만 유지하면, 모든 도구가 같은 규칙을 로드한다. 그게 설정 하나 공유 레시피의 전부다.

.cursorrules는 디프리케이티드인가?

소프트 디프리케이티드다. 리포지토리 루트의 단일 파일 .cursorrules는 아직 Cursor에서 작동하지만, 더 이상 공식 문서에 없다. 이는 포맷이 퇴출 수순이라는 일반적 신호다. 새 프로젝트는 스코프 규칙에는 .cursor/rules/*.mdc, 이식성에는 AGENTS.md를 써야 한다.

.cursorrules를 AGENTS.md로 어떻게 변환하나?

.cursorrules 파일의 본문을 리포지토리 루트의 새 AGENTS.md에 복사하라. 순수 Markdown이므로 frontmatter나 재포맷이 필요 없다. 그런 다음 심볼릭 링크나 @AGENTS.md 임포트를 추가해서 Claude Code도 읽게 하고, Cursor가 새 파일을 인식하는지 확인한 후 기존 .cursorrules를 삭제하라.

CLAUDE.md와 AGENTS.md의 차이는?

CLAUDE.md는 Claude Code의 독자적 메모리 파일로, Claude Code만 읽는다. AGENTS.md는 Cursor, Codex, Copilot 외 20개 이상의 도구가 읽는 오픈 표준이지만, Claude Code는 네이티브로 읽지 않는다. 같은 Markdown 포맷, 같은 역할. 차이는 도달 범위다. AGENTS.md는 도구를 넘나들고, CLAUDE.md는 Claude Code 안에 머문다.

여러 AI 도구를 쓰는 팀은 어떤 포맷으로 표준화해야 하나?

AGENTS.md. 오픈 표준이고, 대부분의 도구가 네이티브로 읽으며, 이미 60,000개 이상의 리포지토리에 있다. 공유 규칙을 여기서 표준화하고, 심볼릭 링크나 임포트로 Claude Code에 브릿지하고, 하나의 도구만 다른 동작이 필요한 곳에 작은 도구별 파일(.cursor/rules 같은)을 추가하라.

중첩된 설정 파일이 있을 때 우선순위는 어떻게 되나?

Claude Code와 AGENTS.md 둘 다, 작업 디렉터리에 가장 가까운 파일이 이기므로, packages/api/AGENTS.md의 규칙은 그 폴더 안의 모든 것에 대해 리포지토리 루트 파일을 오버라이드한다. Cursor는 다르다. 폴더 깊이가 아니라 소스 티어로 Team, Project, User 규칙을 병합하며, 앞선 소스가 충돌에서 이긴다.

SKILL.md는 어디에 해당하나?

SKILL.md는 Anthropic의 신흥 Skills 포맷이다. .claude/skills/*/SKILL.md에 있는 태스크별 지시문으로, CLAUDE.md처럼 항상 켜져 있는 게 아니라 태스크가 매칭될 때 Claude가 온디맨드로 로드한다. CLAUDE.md를 대체하는 게 아니라 보완한다. 2026년 현재 스코프는 아직 진화 중이므로, 모든 프로젝트에 필요한 네 번째 파일이 아니라 전문 애드온으로 취급하라.