Cursor Rules vs CLAUDE.md vs AGENTS.md: 하나의 설정을 세 가지 도구로 실행해본 결과 (2026)
Cursor Rules와 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를 표준으로 삼고(공개 표준, 60,000+ 저장소), 도구별 특수 설정만 추가하세요.
어떤 설정 형식을 써야 할까요? 30초 결정법
형식을 선택할 때는 유행이 아니라 팀 구조로 판단하세요. 도구 하나만 쓰면 그 도구의 네이티브 파일을 사용하세요. 둘 이상이면 AGENTS.md를 진실의 근원으로 채택하고, 특정 도구가 다른 도구에는 없는 기능이 필요할 때만 도구별 오버라이드를 추가하세요. 이 한 가지 규칙이 대부분의 혼동을 정리합니다.
어느 AI 코딩 어시스턴트를 쓸지 먼저 결정하지 못했다면 먼저 우리의 AI 코딩 에이전트 선택 가이드를 참고한 후 파일 설정으로 돌아오세요.
가장 중요한 판단 기준은 이식성(portability)입니다. .cursor/rules 파일은 Cursor 내에서 강력하지만 다른 곳에서는 쓸모가 없습니다. AGENTS.md는 옮겨다닐 수 있습니다. 따라서 한 가지 도구에 영원히 묶여있지 않는 한, 도구 중립적인 파일이 더 안전한 선택입니다.
각 형식은 실제로 무엇인가 (각각 30초에)
이 세 파일은 모두 한 가지를 합니다. AI 코딩 도구에 프로젝트의 규칙, 관례, 주의사항을 코드 한 줄을 쓰기 전에 전달합니다. 차이점은 누가 읽는지와 어떻게 범위를 정하느냐입니다. 간단한 버전입니다. 각각에 대한 깊이 있는 가이드는 해당 문서에 있습니다.
Cursor Rules는 .cursor/rules/ 안에 있는 .mdc 파일입니다. Cursor는 네 가지 규칙 유형(항상 켜짐, 에이전트 요청 시, glob 범위, 수동 @-멘션)을 지원하므로, *.tsx 파일에만 또는 마이그레이션에만 규칙을 붙일 수 있습니다. 프론트매터, glob, 토큰 예산에 대해서는 .cursor/rules 파일을 실제로 작성하는 방법 가이드를 읽으세요.
CLAUDE.md는 Claude Code의 메모리 파일입니다. Claude는 작업 폴더에서부터 디렉터리 트리를 올라가면서 찾은 모든 CLAUDE.md를 연결합니다. 순수 마크다운이며 프론트매터는 필요 없습니다. 구조와 Claude가 무시하지 않도록 하는 규칙에 대해서는 Claude가 무시하지 않는 CLAUDE.md가 무엇인지 보세요.
AGENTS.md는 공개 표준입니다. 저장소 루트에 있는 순수 마크다운 파일 하나로, 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를 읽을까요? 도움 없이는 아니오. 그 "도움"이 이 글이 존재하는 이유 전부이며, 다음에 나올 두 개의 짧은 명령입니다.
우선순위와 중첩이 어떻게 작동하는가, 나란히 비교
각 도구는 충돌을 다르게 처리하며, 이를 잘못 이해하는 것이 "왜 내 규칙이 무시되지?"라는 혼동의 주된 원인입니다. Cursor는 소스 우선순위별로 규칙을 병합합니다. Claude Code는 디렉터리 깊이별로 연결합니다. AGENTS.md는 트리에서 가장 가까운 파일을 선택합니다. 좋은 CLAUDE.md 관리는 당신이 어느 정신 모델에 있는지 아는 것으로 시작합니다.
우리 설정에서 실질적인 결과는 간단합니다. 넓은 규칙은 높이(저장소 루트)에, 구체적인 규칙은 낮이(패키지 폴더 내부)에 두세요. Claude Code와 AGENTS.md 모두 작업하는 위치에 가장 가까운 파일이 우선순위를 가지므로, packages/api/AGENTS.md는 그 폴더 내부의 모든 것에 대해 루트 파일을 오버라이드합니다. Cursor는 이상하게도, 폴더 깊이가 아니라 소스 계층으로 해석합니다.
한 가지 설정을 Cursor + Claude Code에서 실행했습니다. 각 도구가 실제로 로드한 것입니다
Cursor 3.7(2026년 6월 17일 빌드)과 Claude Code v2.1.x(2026년 7월 초)를 사용해 라이브 Techsy 클라이언트 저장소(Next.js 15 백엔드)에서 이를 테스트했습니다. AGENTS.md 하나, 세 가지 공유 설정, 두 도구 모두에서 열린 같은 프롬프트. 각각이 실제로 가져온 것입니다.
최소한의 파일로 시작했습니다:
설정 1: AGENTS.md만. Cursor는 즉시 이를 선택했습니다. 파일이 컨텍스트에 표시되었고 npm install을 제안하지 않기를 올바르게 거부했습니다. Claude Code는 이를 무시했습니다. Claude Code에서 /memory를 실행하면 0개의 프로젝트 메모리 파일이 나열됩니다. CLAUDE.md를 찾을 수 없었고, AGENTS.md는 인정받지 못했습니다. 확인됨: 자동 폴백 없음.
설정 2: 심볼릭 링크. CLAUDE.md를 같은 파일로 가리켰습니다:
이제 Claude Code의 /memory는 ./CLAUDE.md를 프로젝트 메모리로 나열했고, 로드된 콘텐츠는 우리 AGENTS.md 그대로였습니다. Cursor는 여전히 AGENTS.md를 직접 읽었습니다. 물리 파일 하나, 두 도구 모두 행복. Windows에서는 관리자나 개발자 모드를 활성화해야 하며, 그렇지 않으면 ln / mklink가 조용히 실패합니다.
설정 3: @import. 심볼릭 링크를 삭제하고 대신 실제 CLAUDE.md의 맨 위에 한 줄을 넣었습니다:
그러면 /memory는 CLAUDE.md를 로드된 파일로 표시했고 AGENTS.md는 그 아래에 임포트된 참조로 가져왔습니다. 이것이 Anthropic이 실제로 문서화한 경로이며, 특수한 OS 권한이 필요 없습니다.
우리 테스트의 판정: 심볼릭 링크는 Claude Code가 AGENTS.md를 그대로 읽게 하며, @AGENTS.md 임포트는 Anthropic이 실제로 권장하는 Windows 안전 버전입니다. 둘 다 하나의 진실 근원을 제공합니다. macOS/Linux에서는 0 간접성을 위해 심볼릭 링크를 선택하거나, 팀의 누구든 Windows를 쓰면 임포트 줄을 선택하세요.
형식 간 마이그레이션: .cursorrules → .cursor/rules → AGENTS.md
대부분의 팀은 여기에 레거시 .cursorrules 파일과 함께 오고 단일 파일 함정에서 벗어나길 원합니다. 마이그레이션은 모든 방향에서 짧으며 이동은 복사-붙여넣기입니다. 사람들을 물어뜯는 한 가지 함정: .cursor/rules 내 프론트매터 없는 .md 파일은 조용히 무시되므로 .mdc여야 합니다.
레거시 .cursorrules를 현대화하려면 두 가지 깔끔한 경로가 있습니다.
...