.claude/rules/로 규칙 모듈화하기

.claude/rules/는 CLAUDE.md의 규칙을 주제별 파일로 나누고, paths 프론트매터로 특정 파일을 다룰 때만 동적으로 읽히게 하는 모듈러 룰 기능입니다. CLAUDE.md가 길어져 매 세션 컨텍스트를 크게 차지하기 시작했다면 이 기능이 답입니다. "필요할 때만 필요한 규칙을 읽는다"는 한 문장이 전부입니다.

핵심 요약

• .claude/rules/ 아래 .md 파일은 자동으로 프로젝트 메모리로 인식됩니다
• paths 없는 규칙은 세션 시작 시 로드, paths 있는 규칙은 대상 파일을 다룰 때 동적 로드됩니다
• 한 번 로드된 규칙은 같은 세션에서 중복 로드되지 않습니다
• 파일 하나에 여러 규칙이 매칭되면 전부 적용됩니다(TypeScript 규칙 + API 규칙 등)
• 1파일 1주제, 서브디렉터리로 정리하는 것이 기본입니다

CLAUDE.md는 왜 비대해지는가

CLAUDE.md는 프로젝트 규칙을 적어 두면 Claude가 알아서 따라 주는 편리한 파일입니다. 그래서 코딩 규약, 테스트 작성법, API 설계 규칙, 보안 요건을 하나씩 추가하다 보면 어느새 수백 줄이 됩니다.

문제는 CLAUDE.md의 내용이 세션 시작 시 전부 컨텍스트에 올라간다는 점입니다. README 한 줄만 고치려는 세션에서도 TypeScript 규칙과 API 규칙이 컨텍스트를 차지합니다. 작업과 무관한 규칙에 매번 토큰을 쓰는 셈입니다.

사양서처럼 "늘 필요한 문서"는 @참조로 분리해도 되지만, @참조 역시 항상 로드됩니다. "이 파일을 건드릴 때만 읽어라"가 필요하다면 .claude/rules/가 맞습니다.

.claude/rules/의 기본 구성

프로젝트 루트의 .claude/ 아래에 rules/ 디렉터리를 만들고 주제별 .md 파일을 둡니다.

your-project/
├── .claude/
│   ├── CLAUDE.md           # 메인 지시 (최소한으로 유지)
│   └── rules/
│       ├── code-style.md   # 코드 스타일
│       ├── testing.md      # 테스트 규약
│       └── security.md     # 보안 요건

.claude/rules/ 아래의 .md 파일은 자동으로 프로젝트 메모리로 인식됩니다. CLAUDE.md에 따로 적어 줄 필요가 없습니다. 서브디렉터리도 재귀적으로 찾아 주므로 frontend/, backend/ 같은 폴더로 묶어도 됩니다.

paths로 조건부 로드하기

규칙 파일 맨 위에 YAML 프론트매터로 paths를 적으면, 그 패턴에 맞는 파일을 다룰 때만 규칙이 읽힙니다.

---
paths: src/api/**/*.ts
---
# API 개발 규칙

- 모든 API 엔드포인트는 입력 검증 필수
- 표준 에러 응답 형식을 사용한다

이렇게 적으면 src/api/ 아래 TypeScript 파일을 읽거나 편집할 때만 이 규칙이 컨텍스트에 추가됩니다.

paths가 없는 규칙은 기존 CLAUDE.md와 똑같이 처음부터 로드됩니다. 모든 작업에 해당하는 규칙이라면 그래도 괜찮지만, 큰 규칙 파일에서 paths를 생략하면 분리한 의미가 없어집니다.

동적 로드가 일어나는 모습

실제로 대상 파일을 읽으면 도구 실행 결과 아래에 규칙 파일이 로드됐다는 줄이 붙습니다.

⏺ Read(src/components/Button.tsx)
  ⎿  Read 15 lines
  ⎿  Loaded .claude/rules/frontend.md

한 번 로드된 규칙은 같은 세션 안에서 다시 로드되지 않습니다. 같은 폴더의 파일을 열 번 열어도 규칙은 한 번만 컨텍스트에 들어갑니다.

Glob 패턴은 어떻게 쓰나

paths에는 Glob 패턴을 씁니다.

여러 패턴을 한 규칙에 걸기

두 가지 방법이 있습니다. 하나는 브레이스 전개입니다. {ts,tsx}처럼 중괄호 안에 확장자를 나열하면 둘 다 매치됩니다.

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

다른 하나는 YAML 리스트입니다. 서로 다른 디렉터리를 묶을 때 읽기 쉽습니다.

---
paths:
  - "{src,lib}/**/*.ts"
  - "tests/**/*.test.ts"
---
# TypeScript 파일용 규칙

- any 타입은 사용 금지
- 타입 정의는 명시적으로 기술한다

이 규칙은 src/와 lib/ 아래의 TypeScript 파일, 그리고 tests/ 아래의 테스트 파일을 다룰 때 읽힙니다. 한 파일이 여러 규칙에 동시에 매칭되면 그 규칙들이 모두 적용됩니다. src/api/users.ts를 열면 TypeScript 규칙과 API 규칙이 함께 들어오는 식입니다.

실전 구성 예 3가지

예 1: 프론트엔드와 백엔드 규칙 분리

풀스택 프로젝트에서 가장 흔한 형태입니다. 폴더별로 규칙을 나누고 paths로 경계를 긋습니다.

.claude/rules/
├── frontend.md     # paths: src/frontend/**
└── backend.md      # paths: src/backend/**

frontend.md

---
paths: src/frontend/**
---
# 프론트엔드 규칙

- React + TypeScript
- Tailwind CSS로 스타일링
- 컴포넌트는 functional component만

backend.md

---
paths: src/backend/**
---
# 백엔드 규칙

- Express.js + TypeScript
- RESTful API 설계를 따른다
- 에러 핸들링은 반드시 구현

백엔드 파일만 고치는 세션에서는 프론트엔드 규칙이 한 토큰도 쓰이지 않습니다.

예 2: 테스트 파일 전용 규칙

테스트에는 고유한 작성 규칙이 있는 경우가 많습니다. 테스트 파일을 건드릴 때만 적용되게 합니다.

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---
# 테스트 규칙

- describe와 it으로 구조화한다
- AAA(Arrange-Act-Assert) 패턴을 쓴다
- 목(mock)은 최소한으로 억제한다

예 3: 문서 작성 규칙

기술 문서를 쓸 때만 필요한 스타일 가이드도 같은 방식입니다.

---
paths: docs/**/*.md
---
# 문서 작성 규칙

- 제목은 명사구로 시작한다
- 코드 예에는 반드시 설명을 덧붙인다
- 이미지에는 alt 속성을 붙인다

규칙이 로드됐는지 확인하려면

앞서 본 ⎿ Loaded ... 표시가 확인 수단입니다. 대상 파일을 읽게 하면 도구 결과에 다음 같은 줄이 나옵니다.

  Read 1 file (ctrl+o to expand)
  ⎿  Loaded .claude/rules/single.md

이 줄이 보이면 그 규칙 파일이 실제로 컨텍스트에 들어간 것입니다. 규칙을 새로 만들었는데 이 줄이 안 나온다면 paths 패턴이 대상 파일과 맞지 않는 경우가 대부분입니다.

한 가지 주의할 점은 /memory 명령입니다. /memory는 CLAUDE.md 같은 메모리 파일을 편집하기 위한 명령이지 "현재 읽힌 규칙 확인"용이 아닙니다.

  Memory
    Auto-memory: off
  ❯ 1. User instructions     Saved in ~/.claude/CLAUDE.md
    2. Project instructions  Saved in ./CLAUDE.md
  Learn more: https://code.claude.com/docs/en/memory
  Enter to confirm · Esc to cancel

.claude/rules/ 아래 파일은 이 목록에 나오지 않습니다. rules가 동작하는지 보고 싶다면 /memory가 아니라 Loaded 줄을 보세요. CLAUDE.md 파일 자체의 배치와 읽기 순서는 CLAUDE.md 배치 장소와 우선순위에서 다룹니다.

@참조·Skills와는 언제 가르나

비슷한 목적의 기능이 셋 있어 헷갈리기 쉽습니다.

"항상 알아야 하는 것"은 @참조, "이 폴더를 건드릴 때 지켜야 하는 것"은 rules, "이 작업을 할 때 따르는 절차"는 Skills로 가르면 대부분 정리됩니다.

정리

• CLAUDE.md가 비대해지는 문제는 .claude/rules/로 주제별 분할해 풉니다
• paths 프론트매터를 붙이면 대상 파일을 다룰 때만 동적으로 로드되어 컨텍스트를 절약합니다
• paths를 생략한 규칙은 늘 로드되므로 큰 파일에는 반드시 붙입니다
• 로드 여부는 ⎿ Loaded ... 표시로 확인하며 /memory에는 나오지 않습니다
• 1파일 1주제, 서브디렉터리로 정리하는 것이 기본입니다

"CLAUDE.md가 너무 길다"고 느끼는 시점이 분할을 시작할 때입니다. 본체는 실전 템플릿의 네 블록으로 줄이고, 영역별 규칙은 rules로 내려보내면 필요한 규칙만 필요한 순간에 읽히는 구조가 됩니다.