같은 파일, 다른 종(種)
처음에는 모두 비슷해 보인다. 마크다운 파일 하나, 규칙 몇 줄, 그리고 AI가 그걸 따른다는 믿음. 하지만 Cursor Rules와 CLAUDE.md를 같은 프로젝트에 나란히 써보면 금방 이상한 점을 발견한다. 한쪽은 잘 따르는데, 다른 쪽은 점점 잊어버린다. 16개 iOS 앱과 SaaS를 혼자 운영하는 한 인디 개발자가 dev.to에 공유한 경험담이 정확히 이 지점을 짚는다—"한 달간 혼란 끝에 내린 결론은, 이 둘은 컨텍스트 주입 방식이 근본적으로 다른 종이라는 것"이었다.
주입 타이밍이 전부다
두 도구의 가장 결정적인 차이는 언제 규칙을 읽느냐다.
Cursor는 인라인 에디트 요청마다 시스템 프롬프트를 새로 구성한다. 규칙이 매 요청마다 주입되고, 토큰 비용도 매번 발생한다. 덕분에 새 규칙을 추가하면 다음 요청부터 바로 반영된다. 반면 Claude Code는 세션 시작 시점에 CLAUDE.md를 한 번만 읽고, 세션이 끝날 때까지 동일한 시스템 프롬프트를 유지한다. 프롬프트 캐시 덕분에 토큰 비용은 작지만, 규칙을 바꾸고 싶다면 /clear로 세션을 리셋하거나 새 대화를 열어야 한다. "왜 새 규칙을 안 따르지?"라며 30분을 허비할 수 있다.
이 차이가 규칙을 쓰는 톤까지 바꿔야 한다는 뜻이다. Cursor는 매 요청마다 다시 읽히므로 "Tailwind only", "App Router only" 같은 짧고 강한 명령형이 효과적이다. Claude Code는 세션 내내 참조되는 배경 컨텍스트이므로, 왜 이 코드베이스가 이렇게 구조화됐는지, 건드리면 안 되는 위험 구역이 어디인지를 서술형으로 풀어야 모델이 판단할 때 제대로 참조한다. 같은 규칙을 양쪽에 복붙했더니 Claude는 명령형 톤을 거슬러 하며 규칙을 우회하기 시작했고, Cursor는 파일이 너무 길어서 처음 30줄만 읽고 나머지는 흘려보냈다는 게 실제 경험담이다.
Cursor Rules의 4가지 모드—알고 쓰면 토큰이 절약된다
Cursor의 .cursor/rules/*.mdc 파일은 프론트매터 조합으로 네 가지 모드로 동작한다.
- Always:
alwaysApply: true. 모든 요청에 강제 주입. 프로덕션 직접 수정 금지, force push 금지처럼 잊으면 사고가 나는 규칙만 여기에. - Auto:
alwaysApply: false+globs지정..swift파일을 건드릴 때만 iOS 규칙이 들어오고,.tsx를 건드릴 때만 Next.js 규칙이 들어온다. 불필요한 노이즈 없이 스택별 컨벤션을 분리할 수 있는 핵심 모드. - Agent-requested:
description만 작성,globs와alwaysApply비워두기. 모델이 description을 보고 관련성을 판단해 스스로 가져온다. 코드 리뷰 체크리스트나 마이그레이션 절차처럼 간헐적으로 필요한 것에 적합. - Manual: 자동 트리거 없이
@rulename으로 직접 호출. 강제하고 싶지 않지만 필요할 때 불러오고 싶은 템플릿에 사용.
1년간 운영하며 정착한 비율은 Always 20%, Auto 60%, Agent 15%, Manual 5%라고 한다. Always에 너무 많이 몰아넣으면 요청당 토큰 비용이 불어나고 오히려 모델의 주의력이 분산된다.
CLAUDE.md의 3개 레이어와 @import 시스템
CLAUDE.md에는 모드가 없는 대신 레이어가 있다. 세션 시작 시 세 곳에서 읽어 시스템 프롬프트 앞에 통째로 붙인다.
~/.claude/CLAUDE.md(전역): 개인 정체성, 톤, 사용하는 스택, 절대 금지 행동. 약 50~80줄이 적정선.<project-root>/CLAUDE.md(프로젝트): 해당 코드베이스의 폴더 구조, 컨벤션, 위험 구역. 전역 설정과 충돌하는 경우 여기서 명시적으로 오버라이드.- 하위 디렉토리
CLAUDE.md:apps/ios/CLAUDE.md에는 SwiftUI 컨벤션,apps/web/CLAUDE.md에는 Next.js 컨벤션. 모노레포에 특히 유용.
@import 구문으로 파일을 체이닝할 수도 있다. 프로젝트 루트 CLAUDE.md를 50줄 엔트리포인트로 유지하고 @docs/stack.md, @docs/danger.md를 임포트하는 구조가 관리하기 좋다. 다만 Cursor의 globs와 달리 @import는 조건 없이 항상 전체를 읽는다—모든 임포트가 사실상 alwaysApply: true처럼 동작한다는 점을 감안해야 한다.
Andrej Karpathy의 공개 CLAUDE.md가 65줄이라는 사실, HumanLayer가 전역 파일은 60줄 미만을 권장한다는 점은 시사하는 바가 크다. 200줄을 넘어가자 모델이 우선순위를 잃기 시작했고, 80줄로 줄이자 규칙 준수율이 다시 올라갔다는 경험담이 이를 뒷받침한다.
규칙이 안 지켜질 때—실전에서 발견한 함정들
규칙이 무시되는 원인은 거의 항상 둘 중 하나다. "파일이 실제로 읽히지 않았거나", "두 규칙이 서로 충돌하고 있거나."
쓰는 방식의 함정: "App Router를 써라"는 약하다. 학습 데이터에 Pages Router 예시가 훨씬 많기 때문에 모델은 압박 상황에서 다수 클래스인 Pages Router로 회귀한다. "No Pages Router → App Router"처럼 금지와 대안을 한 줄에 묶어야 효과가 있다. Anthropic 공식 가이드도 "순수한 부정 규칙보다 건설적인 규칙"을 일관성 있게 권장한다.
범위 혼합의 함정: Web 컨벤션과 iOS 컨벤션을 전역 파일에 함께 넣으면, Web 작업 중에 iOS 규칙이 컨텍스트에 끼어들어 모델을 혼란스럽게 만든다. 전역은 사람에 따라 변하지 않는 것(정체성, 톤, 안전 규칙), 프로젝트는 코드베이스에 따라 변하는 것으로 분리해야 한다.
커밋 관리의 함정: 프로젝트 CLAUDE.md는 git에 커밋하되, 개인 로컬 설정인 CLAUDE.local.md는 반드시 .gitignore에 추가해야 한다. 전역 설정(~/.claude/CLAUDE.md)을 절대 git에 올리지 말 것.
코드 스타일 위임의 함정: 들여쓰기, 세미콜론, 쿼트 스타일은 ESLint와 Prettier 영역이지 CLAUDE.md 영역이 아니다. LLM에 린터 규칙을 강제하면 토큰만 낭비하고 결과는 불안정하다.
에이전트가 실제로 깨뜨리는 것—비용의 진실
규칙 설계의 중요성은 에이전트를 실제 코드베이스에 풀어봤을 때 비로소 체감된다. dev.to에 올라온 한 경험담은 솔직하다. 에이전트는 반복 편집, 테스트 스캐폴딩, 유틸리티 함수 정리에서 분명히 시간을 아껴줬다. 하지만 다중 파일 리팩토링 중 내부 인증 플로우와 연결된 네이밍 패턴을 조용히 바꿨고, 피처 플래그에 묶여 있던 코드를 "안 쓰는 것처럼 보인다"는 이유로 지워버렸다.
숨겨진 비용도 세 가지였다. 첫째, 리뷰 시간—에이전트가 초안을 빠르게 쏟아내도 사람이 검증하는 시간이 그 절약분을 일부 잡아먹는다. 둘째, 실제 비용—Anthropic 추산 기준 엔터프라이즈 개발자 1인당 하루 평균 약 13달러, 90%는 하루 30달러 미만이지만 월 150~250달러는 실제 예산에 잡힌다. 셋째, 컨텍스트 부채—못생긴 워크어라운드가 왜 존재하는지 에이전트는 모른다. 패턴만 보고 제거하면 그게 사고가 된다.
이것이 규칙 설계가 단순한 편의 기능이 아닌 이유다. 위험 구역을 명시하고, 금지 행동을 명확히 하고, 왜 이 코드가 이렇게 생겼는지를 사전에 컨텍스트로 주입해두지 않으면, 에이전트는 패턴 매칭 속도로 실수를 증폭시킨다.
시사점—규칙 파일은 팀의 제도다
결국 Cursor Rules와 CLAUDE.md는 단순한 설정 파일이 아니다. 에이전트가 판단해야 할 때 참조하는 팀의 암묵지를 문서화한 제도다. 이 관점에서 몇 가지 원칙이 선명해진다.
규칙은 '있으면 좋은 것'이 아니라 '없으면 사고가 나는 것'에서 출발해야 한다. Always 모드와 전역 파일에는 잊으면 프로덕션이 흔들리는 규칙만 담아야 한다. 나머지는 Auto와 프로젝트 레이어로 분산한다.
길이는 적의 편이다. 전역 CLAUDE.md 200줄은 80줄보다 규칙을 덜 따른다. Cursor의 Always 규칙이 많아질수록 모델의 주의력 예산이 얇아진다. 짧고 구체적인 것이 길고 포괄적인 것을 이긴다.
그리고 2026년을 향한 트렌드가 하나 더 있다. AGENTS.md를 단일 진실의 원천으로 두고 Cursor·Claude·Codex·Copilot이 모두 여기서 임포트하는 방식이 업계 표준으로 자리잡는 흐름이다. 도구마다 파일을 따로 관리하는 시대가 지나고, 규칙 자체를 하나의 소스로 버전 관리하는 시대가 온다.
전망—'규칙 설계'가 프론트엔드 역량이 되는 시대
에이전트가 코드를 짜는 속도는 이미 사람을 앞선다. 하지만 에이전트가 무엇을 건드리지 말아야 하는지를 아는 건 여전히 사람이 설계해줘야 한다. Cursor Rules의 4가지 모드를 이해하고, CLAUDE.md의 레이어를 적절히 분리하고, 금지와 대안을 한 줄에 묶어 쓰는 것—이게 이제 프론트엔드 개발자의 실질적인 역량 중 하나가 됐다.
빠른 프로토타이핑 → 사용자 검증 → 고도화라는 흐름에서 에이전트는 첫 번째 단계를 비약적으로 가속한다. 하지만 그 속도가 두 번째, 세 번째 단계에서 독이 되지 않으려면, 규칙 설계라는 '컨텍스트 인프라'가 먼저 갖춰져 있어야 한다. 코드를 잘 짜는 것만큼, 에이전트에게 잘 가르치는 것이 중요한 시대다.