필요한 곳에서만 켜지는 규칙 | Rules | Claude Code, 제대로 배우기

매뉴얼이 두꺼워질 때 규칙을 주제별 파일로 쪼개고, paths 로 경로별로 켜고 끄는 구조를 익힙니다

Overview

프로젝트가 자라면서 CLAUDE.md 에 적힌 규칙이 늘어나면, 매 대화마다 컴포넌트·테스트·백엔드 규칙이 한꺼번에 로드됩니다. 지침의 저주가 매번 발동하는 구조입니다.

이번 레슨은 규칙을 주제별 파일로 쪼개고, 작업 경로에 맞는 규칙만 켜지게 하는 .claude/rules/ 사용법을 익힙니다.

학습 목표

CLAUDE.md와 .claude/rules/ 의 차이를 설명할 수 있습니다
paths frontmatter와 glob 패턴으로 규칙의 적용 범위를 지정할 수 있습니다
어떤 내용을 CLAUDE.md에 두고 어떤 내용을 Rules로 옮길지 판단할 수 있습니다

시작하기 전 확인사항

실습 프로젝트의 시작 브랜치로 전환합니다 (git checkout ch06-01)

ch06-01 브랜치는 이 레슨의 시작점입니다. CLAUDE.md에 여러 규칙이 한꺼번에 쌓여 있는 상태입니다.

Claude Code 문법은 claude-code-guide에게

이번 챕터부터 .claude/rules/, .claude/commands/, .claude/skills/ 같은 Claude Code 고유 설정이 등장합니다. 옵션이나 문법이 궁금하면 외부 검색 대신 Claude Code 안에서 "rules 파일에 쓸 수 있는 옵션이 뭐야?"처럼 물어보면, claude-code-guide 서브에이전트가 자동 호출해 정확하게 답변합니다. 자동 호출이 안 될 때는 "claude-code-guide 사용해서 알려줘"라고 명시하면 됩니다.

매뉴얼이 두꺼워질수록 약해지는 규칙들

CLAUDE.md 에 "NEVER .env 파일 커밋" 같은 핵심 제약사항을 적어두는 것을 다뤘습니다. 규칙이 다섯 줄일 때는 문제가 없습니다. 하지만 프로젝트가 자라면서 규칙도 같이 늘어납니다.

## Rules
- **NEVER** .env 파일 커밋
- 컴포넌트는 components/ 아래에만 생성
- Shadcn UI 컴포넌트를 우선 사용
- 테스트에서 실제 API 호출 금지, mock 사용
- API 응답은 표준 에러 형식 사용
- 데이터베이스 쿼리는 ORM 만 사용
- Plan Mode 에서 계획은 간결하게 작성
- ...

API 파일 하나를 수정하는 동안 "Shadcn UI 컴포넌트 우선 사용" 규칙도 같이 로드됩니다. 테스트 코드를 작성할 때 "API 응답 표준 에러 형식" 규칙도 함께 들어옵니다. 지침의 저주(지침이 많아질수록 각 지침의 준수율이 떨어지는 현상)가 매 대화마다 발동합니다.

핵심 문제는 단순합니다. CLAUDE.md의 규칙은 작업 경로와 무관하게 항상 전부 로드됩니다. 매뉴얼 두께를 줄이거나, 규칙이 켜지는 조건을 따로 둬야 합니다.

Rules: 매뉴얼을 주제별 파일로 쪼개기

해답은 매뉴얼을 더 잘 쓰는 것이 아니라 매뉴얼을 쪼개는 것입니다. 한 두꺼운 매뉴얼 대신, 주제별로 얇은 책자를 두고 필요할 때만 펼치는 방식입니다.

.claude/rules/ 폴더 안에 마크다운 파일을 만들면, 각 파일이 독립된 규칙 묶음으로 인식됩니다.

.claude/
  rules/
    components.md     # 컴포넌트 작성 규칙
    testing.md        # 테스트 작성 규칙
    shadcn.md         # Shadcn UI 사용 규칙

파일 하나가 한 주제를 책임집니다. 파일명이 곧 그 책자의 표지입니다.

paths: 규칙이 켜지는 경로를 지정하기

쪼개는 것만으로는 부족합니다. 파일 하나를 수정하는데 모든 Rules 파일이 같이 로드되면, 매뉴얼이 두꺼워진 결과와 같습니다. 쪼갠 다음 필요한 것만 켜는 장치가 필요합니다. 그 역할을 paths frontmatter가 합니다.

규칙 파일 상단에 paths 를 적으면, 해당 경로의 파일을 작업할 때만 그 규칙이 켜집니다.

---
paths:
  - "components/**"
---

# Component Rules

- Shadcn UI 컴포넌트를 우선 사용
- 새 컴포넌트는 components/ 아래에만 생성

components/ 아래 파일을 만지는 동안에만 이 규칙이 활성화됩니다. API 파일이나 테스트 파일을 수정하는 동안에는 로드되지 않습니다.

paths 는 glob 패턴을 따릅니다.

패턴	매칭 대상
`*/.ts`	모든 디렉토리의 TypeScript 파일
`components/**`	components/ 아래 모든 파일
`*/.test.ts`	모든 테스트 파일
`*/.{ts,tsx}`	.ts와 .tsx 파일 모두

paths 가 빠진 규칙 파일은 모든 작업에 전역으로 적용됩니다. CLAUDE.md와 같은 동작입니다. 경로와 무관하게 항상 지켜야 하는 규칙은 paths 없이 둡니다.

CLAUDE.md vs Rules 구분하기

공식 문서가 둘을 가르는 규칙을 정해두진 않지만, 두 메커니즘의 동작을 보면 다음 기준으로 나누는 것이 자연스럽습니다.

	CLAUDE.md	`.claude/rules/`
역할	프로젝트 맥락 (아키텍처 결정, 워크플로우)	제약사항 / 규칙 (NEVER, MUST)
로드 시점	항상 전체	`paths` 매칭 시, 또는 paths 없으면 전역
적합한 내용	아키텍처 결정 이유, 팀 워크플로우	코딩 규칙, 테스트 규칙, 린트 규칙

판단 기준은 단순합니다. 맥락 정보("이 프로젝트는 Server Components를 우선 쓴다")는 CLAUDE.md에, 제약사항("NEVER Shadcn 컴포넌트 원본 수정")은 Rules에 둡니다. 매뉴얼 본문에 들어갈 설명인지, 매뉴얼 뒤에 붙은 체크리스트에 들어갈 줄인지로 가릅니다.

[실습] CLAUDE.md의 한 규칙을 Rules로 옮기기

CLAUDE.md에 있는 Shadcn UI 규칙을 .claude/rules/ 로 분리하고, paths가 실제로 켜지고 꺼지는지 같은 세션에서 확인합니다.

Step 1: rules 폴더 생성

프로젝트 루트에 .claude/rules/ 폴더를 만듭니다. .claude/ 가 이미 있다면 rules/ 만 추가합니다.

mkdir -p .claude/rules

Step 2: Shadcn UI 규칙 파일 작성

.claude/rules/shadcn.md 를 다음과 같이 작성합니다.

---
paths:
  - "components/ui/**"
---

# Shadcn UI

- Shadcn UI 컴포넌트(`components/ui/`) 는 직접 수정하지 않는다
- 스타일이나 동작을 변경하려면 래퍼 컴포넌트를 만들어 사용한다

paths 가 components/ui/** 이므로, 이 규칙은 components/ui/ 아래 파일을 만지는 동안에만 활성화됩니다.

Step 3: CLAUDE.md에서 옮긴 규칙 삭제

.claude/rules/shadcn.md 로 옮긴 내용을 CLAUDE.md 에서 지웁니다.

중복하면 의미가 없습니다

같은 내용이 CLAUDE.md와 Rules에 동시에 있으면 둘 다 로드되어 Context만 두 번 차지합니다. 분리한 규칙은 반드시 원본에서 지웁니다.

Step 4: 두 경로에서 켜짐과 꺼짐 확인

같은 세션에서 두 가지 작업을 순서대로 요청합니다.

먼저 components/ui/ 안의 파일을 수정합니다.

components/ui/button.tsx 의 padding 을 수정해줘

Claude가 "원본을 직접 수정하지 말고 래퍼를 만들자" 같은 제안을 하면, Shadcn 규칙이 켜진 것입니다.

이어서 같은 세션에서 다른 경로의 파일을 만집니다.

lib/todo-store.ts 에 정렬 함수를 추가해줘

이번에는 Shadcn 관련 언급 없이 곧장 수정합니다. 같은 세션, 같은 프로젝트인데도 작업 파일의 경로만 달라지면 적용되는 규칙이 달라집니다. 이것이 paths의 핵심 동작입니다.

핵심 포인트 정리

Rules = 주제별 매뉴얼: CLAUDE.md 한 곳에 다 적는 대신 .claude/rules/ 에 주제별 파일을 두면, 파일명이 곧 그 책자의 표지가 됩니다.
paths = 경로별 스위치: paths frontmatter가 있으면 해당 경로 작업 시에만 켜지고, 없으면 전역으로 로드됩니다. 지침의 저주를 구조로 푸는 장치입니다.
CLAUDE.md = 맥락, Rules = 제약: "이 프로젝트는 뭐 하는 곳"은 CLAUDE.md에, "이건 하지 마"는 Rules에 둡니다.

FAQ

Q: CLAUDE.md와 .claude/rules/ 에 같은 내용이 있으면요?
- A: 둘 다 로드되어 Context만 두 번 차지합니다. CLAUDE.md에는 경로 무관하게 항상 지켜야 할 핵심만 남기고, 나머지는 .claude/rules/ 로 분리합니다.
Q: 규칙 파일을 몇 개까지 만들 수 있나요?
- A: 개수 제한은 없지만, paths 없는 파일이 많으면 전부 상시 로드되어 결국 CLAUDE.md에 다 넣은 것과 같아집니다. 전역 규칙은 최소화하고 가능하면 paths로 범위를 좁히는 편을 권장합니다.
Q: 한 파일에 여러 paths 규칙이 매칭되면요?
- A: 매칭되는 모든 규칙이 같이 켜집니다. 한 파일에 두 규칙이 동시에 적용될 수 있고, 그 자체로 문제는 아닙니다. 각 규칙이 자기 주제 안에서 일관되면 됩니다.

이어서 배울 내용

Rules로 규칙을 주제별·경로별로 나눌 수 있습니다. 그런데 규칙 외에도 반복되는 게 있습니다. 코드 리뷰를 요청할 때마다 같은 형식의 프롬프트를 매번 타이핑하고, 커밋할 때마다 같은 안내를 반복 입력하고 있다면, 그 시간이 쌓입니다. 다음 레슨에서는 반복 프롬프트를 한 단어로 호출하는 Custom Commands를 배웁니다.

마크다운 파일 한 개로 슬래시 명령어 만들기
$ARGUMENTS 와 frontmatter로 재사용 가능한 프롬프트 설계하기

필요한 곳에서만 켜지는 규칙 | Rules

On this page