.claude/rules로 규칙 체계화하기: CLAUDE.md를 주제별로 쪼개는 법

클로드 코드에 프로젝트 규칙을 알려주는 가장 기본적인 방법은 CLAUDE.md입니다. 그런데 프로젝트가 커지면 이 파일 하나가 점점 비대해지죠. 프론트엔드 규칙, 백엔드 규칙, 테스트 컨벤션, 보안 요구사항… 온갖 내용이 한 파일에 뒤섞이면 읽기도 어렵고, 매 세션 전부 로드되니 컨텍스트도 부담스러워집니다.

.claude/rules/ 디렉토리는 이 문제를 푸는 방법입니다. 규칙을 주제별로 여러 파일에 나눠 담고, 필요한 순간에만 로드되도록 만들 수 있어요. 이 글에서는 .claude/rules/를 어떻게 구성하는지, 그리고 CLAUDE.md나 에이전트 스킬과는 무엇이 다른지 정리해보겠습니다.

.claude/rules/ 시작하기

.claude/rules/ 디렉토리에 마크다운 파일을 넣기만 하면 됩니다. 각 파일은 하나의 주제를 다루도록 testing.md, api-design.md처럼 이름만 봐도 내용을 알 수 있게 짓는 게 좋아요.

my-project/
├── .claude/
│   ├── CLAUDE.md           # 늘 적용되는 핵심 지시
│   └── rules/
│       ├── code-style.md   # 코드 스타일 가이드
│       ├── testing.md      # 테스트 컨벤션
│       └── security.md     # 보안 요구사항

.md 파일은 재귀적으로 탐색되기 때문에 frontend/, backend/ 같은 하위 디렉토리로 더 잘게 분류할 수도 있습니다. 규칙이 수십 개로 늘어나도 디렉토리로 정리할 수 있는 거죠.

이렇게 paths 설정 없이 그냥 둔 규칙 파일은 매 세션 시작 시 모두 로드됩니다. 우선순위는 .claude/CLAUDE.md와 동일하게 취급돼요. 즉 내용은 여러 파일로 쪼갰지만 효과는 CLAUDE.md에 다 적은 것과 같은 상태가 됩니다. 정리정돈에는 좋지만, 이것만으로는 컨텍스트를 아끼지는 못합니다.

경로 기반 규칙으로 필요할 때만 로드하기

.claude/rules/의 진짜 힘은 경로 기반 규칙에서 나옵니다. 규칙 파일 맨 위 YAML 프론트매터에 paths 필드를 넣으면, Claude가 그 패턴에 맞는 파일을 건드릴 때만 규칙이 컨텍스트에 로드됩니다.

---
paths:
  - "src/api/**/*.ts"
---

# API 개발 규칙

- 모든 엔드포인트에 입력 유효성 검사를 넣을 것
- 표준 에러 응답 형식을 사용할 것
- OpenAPI 문서화 주석을 추가할 것

이제 이 규칙은 Claude가 src/api/ 아래 TypeScript 파일을 읽을 때만 등장합니다. CSS를 만지거나 문서를 고칠 때는 컨텍스트에 들어오지 않으니, 그만큼 토큰을 아끼고 노이즈도 줄어들죠. 한 가지 짚어둘 점은 이 트리거가 매 도구 호출이 아니라 매칭되는 파일을 읽는 시점이라는 겁니다.

paths에는 글로브 패턴을 쓸 수 있습니다. 자주 쓰는 패턴은 다음과 같아요.

• **/*.ts — 모든 디렉토리의 TypeScript 파일
• src/**/* — src/ 아래 모든 파일
• *.md — 프로젝트 루트의 마크다운 파일
• src/components/*.tsx — 특정 디렉토리의 React 컴포넌트

여러 패턴을 나열하거나 중괄호 확장으로 확장자를 묶을 수도 있습니다.

---
paths:
  - "src/**/*.{ts,tsx}"
  - "tests/**/*.test.ts"
---

반대로 paths 필드가 아예 없으면 앞서 말한 대로 모든 세션에 무조건 로드됩니다. 그래서 규칙을 만들 때는 이게 늘 필요한지, 특정 영역에서만 필요한지를 먼저 판단하는 게 좋습니다.

CLAUDE.md, 규칙, 스킬은 어떻게 다를까

여기까지 보면 “그래서 CLAUDE.md랑 뭐가 다르지? 스킬이랑은 또 어떻게 다르고?”라는 의문이 들 텐데요. 세 가지를 가르는 핵심 축은 하나입니다. 언제 컨텍스트에 들어오는가.

CLAUDE.md는 매 세션 통째로 로드되는 상시 메모리입니다. 빌드 명령어처럼 프로젝트 전반에 늘 적용되는 규칙에 어울려요.

.claude/rules/는 그 상시 메모리를 주제별로 쪼갠 것에 가깝습니다. paths를 붙이지 않으면 CLAUDE.md와 거의 같지만(모듈화만 된 셈), paths를 붙이는 순간 해당 영역을 만질 때만 켜지는 규칙이 됩니다. CLAUDE.md와 스킬의 중간 지점인 셈이죠.

에이전트 스킬은 한 발 더 나아갑니다. 평소에는 컨텍스트에 전혀 없다가, 사용자가 직접 호출하거나 Claude가 지금 이 작업에 이 스킬이 필요하겠다고 판단할 때만 로드됩니다. 그래서 여러 단계를 거치는 절차나, 가끔만 쓰는 워크플로우, 스크립트가 딸린 작업에 적합합니다. 매번 컨텍스트에 들고 있을 필요가 없는 것들이죠.

정리하면 이렇게 고르면 됩니다. 프로젝트 어디서나 늘 지켜야 하는 규칙은 CLAUDE.md, 특정 디렉토리나 파일 타입에만 해당하는 규칙은 경로 기반 .claude/rules/, 평소엔 필요 없지만 특정 작업에서 꺼내 쓰는 절차는 스킬입니다.

사용자 레벨 규칙과 공유

규칙은 프로젝트 안에만 두는 게 아닙니다. ~/.claude/rules/에 두면 모든 프로젝트에 적용되는 개인 규칙이 됩니다. “주석은 한국어로 달아줘”처럼 프로젝트와 무관한 내 취향을 여기에 넣어두면 편해요. 사용자 레벨 규칙은 프로젝트 규칙보다 먼저 로드되므로, 충돌이 나면 프로젝트 규칙이 우선합니다.

여러 프로젝트에서 같은 규칙 세트를 공유하고 싶다면 심볼릭 링크를 활용할 수 있습니다. .claude/rules/는 심볼릭 링크를 정상적으로 따라가고, 순환 링크도 알아서 처리합니다.

# 공유 규칙 디렉토리 통째로 연결
ln -s ~/shared-claude-rules .claude/rules/shared

# 회사 표준 규칙 파일 하나만 연결
ln -s ~/company-standards/security.md .claude/rules/security.md

이렇게 하면 규칙을 한 곳에서 관리하면서 여러 저장소에 뿌릴 수 있습니다. 회사 전체가 공유하는 보안 규칙 같은 걸 두기에 좋죠.

CLAUDE.md에서 규칙으로 분리하기

이미 비대해진 CLAUDE.md가 있다면, 다음 순서로 규칙을 떼어내면 깔끔합니다.

먼저 CLAUDE.md에서 특정 영역에만 해당하는 덩어리를 찾습니다. “API는 이렇게”, “테스트는 저렇게” 같은 섹션이 후보예요. 반대로 프로젝트 전반에 늘 적용되는 내용(빌드 명령어, 전역 코딩 스타일)은 그대로 CLAUDE.md에 둡니다.

그다음 떼어낸 덩어리를 주제별 파일로 옮기고, 적용 범위에 맞는 paths를 붙입니다. 예를 들어 테스트 컨벤션은 tests/**/* 패턴으로 스코프하면 테스트 파일을 만질 때만 로드됩니다.

마지막으로 CLAUDE.md가 200줄 안쪽으로 가벼워졌는지 확인합니다. 규칙으로 잘 분리하면 CLAUDE.md에는 이 프로젝트의 핵심 요약만 남고, 세부 규칙은 필요할 때만 등장하게 됩니다.

한 가지 팁을 더하자면, 한 파일에 한 주제만 담는 원칙을 지키세요. code-style.md에 보안 규칙까지 섞으면 나중에 어떤 규칙이 어디 있는지 찾기 어려워집니다. 파일 이름만 봐도 내용을 짐작할 수 있어야 관리가 쉽습니다.

마치며

.claude/rules/는 CLAUDE.md가 감당하기 버거워지는 시점에 빛을 발합니다. 규칙을 주제별로 쪼개 정리하고, 경로 기반 규칙으로 필요할 때만 로드해서 컨텍스트를 아낄 수 있죠. 핵심은 세 가지 도구를 로딩 시점으로 구분하는 감각입니다. 늘 필요하면 CLAUDE.md, 특정 영역이면 경로 기반 규칙, 가끔 꺼내 쓰는 절차면 스킬이에요.

CLAUDE.md 자체의 작성법이 궁금하다면 CLAUDE.md 작성 가이드를, Claude가 스스로 규칙을 학습하는 방식이 궁금하다면 자동 메모리를 함께 읽어보시길 권합니다.

더 자세한 내용은 클로드 코드 메모리 공식 문서를 참고하세요.