CLAUDE.md vs AGENTS.md, Cursor에선 어떻게 읽히나

CLAUDE.md와 AGENTS.md를 한 레포에 같이 두면, Cursor Agent(Chat)가 둘을 어떻게 집어 올지가 궁금합니다. 이 글은 Rules·Rules help 기준으로 읽기·적용 방식만 다룹니다. 가격·플랜 이야기는 없습니다.

이전 AGENTS.md·CLAUDE.md 글은 파일을 어떻게 쓰고 맞출지(역할·임포트·도구 간 동기화)였습니다. 이번엔 Cursor가 무엇을 항상 싣고, 조건부 규범은 어디에 두는지입니다.

Cursor는 둘을 어떻게 읽나?

한 줄 답: Cursor는 루트 AGENTS.md와 CLAUDE.md를 모두 자동으로 읽습니다. CLAUDE.md는 매 대화에 항상 적용되고, AGENTS.md는 평문 마크다운 지침으로 루트·하위 폴더에 둘 수 있습니다.

파일	Cursor에서의 성격	적용
`AGENTS.md`	`.cursor/rules`의 평문 대안 (메타데이터 없음)	루트·하위 디렉터리. 하위는 해당 경로·자식 작업 시 결합, 더 구체적 경로가 우선
`CLAUDE.md`	Claude Code 호환용으로 Cursor도 읽음	항상 매 대화에 포함. frontmatter의 `alwaysApply`와 무관
`.cursor/rules/*.mdc`	Project Rules (조건부 가능)	Always / globs / Intelligent / `@` 수동
`.cursorrules`	레거시	곧 deprecate 예정 → Always Apply `.mdc`로 이전

공식 help의 How does CLAUDE.md work in Cursor? 문구가 핵심입니다. Cursor는 CLAUDE.md를 AGENTS.md와 같은 방식으로 집어 올리되, 적용은 무조건 always입니다. Claude Code용으로만 쓴 문장(“커밋 전 항상 pnpm test” 등)도 Cursor 세션에 새어 들어갑니다.

AGENTS.md는 frontmatter가 없습니다. 경로별로 나누려면 **중첩 AGENTS.md**를 두거나, 조건부 규범은 .mdc로 빼는 편이 맞습니다.

project/
  AGENTS.md                 # 공통 기준
  CLAUDE.md                 # Cursor에선 항상 실림 — 짧게·양쪽 공통만
  frontend/
    AGENTS.md               # frontend 작업 시 결합
  .cursor/rules/
    api-routes.mdc          # globs로 조건부

always-apply와 조건부 rule 차이는?

한 줄 답: CLAUDE.md(그리고 plain AGENTS.md)는 조건 없이 컨텍스트에 실리는 쪽에 가깝고, 언제 실릴지를 고르려면 .cursor/rules/*.mdc의 alwaysApply·globs·description을 씁니다.

Project Rule 네 유형(공식 Rules 문서):

유형	frontmatter 신호	동작
Always Apply	`alwaysApply: true`	매 채팅에 포함 (globs·description 무시)
Apply to Specific Files	`alwaysApply: false` + `globs`	매칭 파일이 컨텍스트에 있을 때 첨부
Apply Intelligently	`alwaysApply: false` + `description`	Agent가 관련 시 끌어옴
Apply Manually	둘 다 없음	`@rule`로만

실무로 나누면:

매 세션 공통·짧게 — 응답 언어, 시크릿 금지, 생성물 디렉터리 금지 → 짧은 Always .mdc 또는 얇은 AGENTS.md / (양쪽 도구가 같이 따를) 얇은 CLAUDE.md.
경로 한정 — src/api/** 스키마 → globs Rule. CLAUDE.md frontmatter로는 조건부 불가.
가끔만 — description Intelligent 또는 @ 수동.
.cursor/rules에 plain .md만 두면 무시됩니다. 확장자는 .mdc여야 합니다. 평문만 쓰려면 AGENTS.md를 쓰세요.

---
globs: src/routes/api/**/*.ts
alwaysApply: false
---

- Validate inputs at the route boundary.
- Return the existing typed error shape.

Team/Enterprise Team Rules는 대시보드 텍스트(+ 선택 glob)이며, 충돌 시 우선순위는 공식 기준 Team → Project → User입니다. 요금·플랜 한도는 다루지 않습니다.

팀 혼용 시 어디에 무엇을 두나?

한 줄 답: 공유 사실·코딩 규범은 AGENTS.md, Cursor만의 경로 스코프는 .cursor/rules/*.mdc, Claude Code와 맞춰야 하는 공통 문장은 **얇은 CLAUDE.md(또는 @AGENTS.md 브리지)**에 두고, Cursor에만 해가 되는 Claude-only 절차는 CLAUDE.md에 넣지 않습니다.

팀 상황	어디에	이유
Cursor + Claude Code 혼용	`AGENTS.md` = 공유 베이스, `CLAUDE.md` = 얇은 브리지/공통만	Cursor가 `CLAUDE.md`를 항상 읽음 → Claude-only 긴 절차는 누수
Cursor 중심, 경로별 규범	`AGENTS.md` 공통 + `.mdc` globs	조건부 적용은 `.mdc`만
모노레포 영역별	하위 `AGENTS.md`	해당 트리 작업 시 결합, 구체 경로 우선
조직 전역 강제	Team Rules (대시보드)	Project/User보다 앞섬. Enforce 옵션은 팀 설정
옛 `.cursorrules`	Always Apply `.mdc`로 이전 후 삭제	공식: legacy, deprecate 예정

체크리스트:

질문	예 →	아니오 →
Claude Code와 Cursor가 같이 따라야 하나?	얇은 공통을 `AGENTS.md` (+ 필요 시 `CLAUDE.md` 브리지)	Claude-only는 Claude 쪽 설정에만
경로·파일 타입에만 실려야 하나?	`.cursor/rules` + `globs`	plain `AGENTS.md` / Always
매 채팅에 짧게 항상?	Always `.mdc` 또는 짧은 root md	Intelligent / `@` / Skill

마무리

CLAUDE.md AGENTS.md Cursor 축의 핵심은 읽기·적용입니다. Cursor는 둘 다 자동으로 읽고, CLAUDE.md는 항상 실립니다. 조건부 규범은 .mdc의 alwaysApply·globs·description에 두고, 팀 공유 베이스는 AGENTS.md에 모으는 편이 안전합니다. 자세한 내용은 Rules, Rules help를 참고하시기 바랍니다.

출처

Cursor Rules — Project Rules, AGENTS.md 중첩, Team Rules 우선순위
Rules help — CLAUDE.md always-apply, .cursorrules 마이그레이션