Rules란?

.claude/rules/ 디렉터리에 두는 마크다운 파일로, CLAUDE.md를 여러 주제별 파일로 쪼개서 관리할 수 있게 해주는 기능입니다.

• paths frontmatter가 없으면 .claude/CLAUDE.md와 같은 우선순위로 항상 로드됩니다 (단순히 CLAUDE.md를 주제별 파일로 분리하는 용도)
• paths frontmatter가 있으면 그 glob에 매칭되는 파일을 Claude가 읽을 때만 조건부로 로드됩니다 (수정 여부와 무관하게, 읽는 시점에 트리거)

이 글에서는 실무에서 더 유용한 path-scoped rules(조건부 로드) 위주로 정리합니다.

---

저장 위치 / 우선순위

• 사용자 전역: ~/.claude/rules/*.md — 내 모든 프로젝트에 적용. 프로젝트 rules보다 먼저 로드됨(= 프로젝트 rules가 더 나중에 읽혀서 우선순위가 높음)
• 프로젝트: .claude/rules/*.md — 해당 repo에서만 적용, git으로 공유
• 하위 디렉터리(frontend/, backend/ 등)로 나눠도 .md 파일은 재귀적으로 전부 탐색됨
• symlink 지원 — 회사 공통 규칙 모음을 만들어두고 여러 repo의 .claude/rules/에 symlink로 연결하면 한 곳만 수정해도 전체에 반영됨

---

작성 방법

기본 구조

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

# API 작업 규칙

- 모든 엔드포인트 핸들러는 입력 검증을 거친다
- 에러 응답 포맷은 공통 포맷을 따른다

파일명은 code-style.md, testing.md처럼 다루는 주제를 그대로 드러내는 이름으로 짓고, 한 파일에는 한 주제만 담습니다. 여러 주제를 한 파일에 섞으면 그중 일부 경로에만 해당되는 내용도 같이 로드돼서 노이즈가 늘어납니다.

frontmatter 필드

• paths: 적용 대상 glob 목록 (YAML 리스트). glob은 *, ** 같은 와일드카드로 파일 경로를 패턴 매칭하는 표기법(.gitignore에서 쓰는 그 방식). 비워두면(필드 자체를 안 쓰면) 무조건 로드되는 일반 규칙이 됨
• 패턴 예시: **/*.ts(전체 TS 파일), src/**/*(특정 디렉터리 전체), *.md(루트의 md 파일만), src/**/*.{ts,tsx}(중괄호로 여러 확장자 한 번에)

좋은 rule 작성 팁

• glob은 실제로 "예외"인 영역에만 좁게: 매칭 범위가 프로젝트 대부분을 덮으면 굳이 조건부로 둘 이유가 없음 — 그럴 거면 CLAUDE.md에 적는 게 나음
• 진입점이 되는 파일을 포함하도록 패턴 짜기: Claude가 그 패턴에 걸리는 파일을 한 번도 안 읽으면 규칙 자체가 안 보이므로, 작업 시 반드시 거치게 되는 파일(컴포넌트, API 함수 등)을 패턴에 포함시킬 것
• "왜"를 같이 적기: 단순히 "이렇게 해라"보다 "포팅된 코드라 컨벤션이 다르다", "공통 타입이 기준이다" 같은 배경을 한 줄 적어두면 Claude가 애매한 케이스에서 더 일관되게 판단함
• 체크리스트/불릿 형태: CLAUDE.md와 마찬가지로 산문보다 구조화된 목록이 더 잘 지켜짐

---

Skill / CLAUDE.md와의 차이

	CLAUDE.md	Rules (paths 있는 경우)	Skill
로드 조건	항상 전체 컨텍스트	매칭되는 파일을 Claude가 읽을 때	작업 의도(description)로 트리거
단위	프로젝트 전체	폴더/파일 패턴 단위	작업 절차 단위
트리거 방식	자동(항시)	자동(경로 매칭)	자동(의도 매칭) 또는 /스킬명
적합한 용도	전역 컨벤션	특정 폴더/파일 타입에만 적용되는 예외 규칙	반복되는 다단계 작업 절차

Rules(paths 있는 경우)의 가장 큰 차이점은 트리거가 "무슨 말을 했는가"가 아니라 "어떤 파일을 읽고 있는가" 라는 것입니다. Skill처럼 description으로 의도를 추론할 필요가 없고, CLAUDE.md처럼 매번 전체에 끼얹을 필요도 없습니다.

---

paths를 쓰는 이유 / 장점

• 전역 CLAUDE.md를 오염시키지 않음: "이 폴더만의 예외 규칙"을 CLAUDE.md에 적으면 다른 영역 작업할 때도 불필요하게 컨텍스트를 차지함. paths로 묶으면 해당 파일을 안 읽는 대화에서는 토큰 비용이 0
• 레거시/포팅 코드처럼 "이 영역만 다른 기준" 케이스에 정확히 맞음: 외부에서 포팅해온 코드, 마이그레이션 중인 모듈처럼 나머지 코드베이스와 컨벤션이 다른 영역을 격리해서 규칙을 줄 수 있음
• description 튜닝이 필요 없음: Skill은 "언제 트리거될지"를 description 문장으로 추론시켜야 해서 오작동 여지가 있는데, Rules는 파일 경로라는 명확한 기준이라 트리거가 항상 정확함
• 여러 글롭으로 한 도메인의 흩어진 폴더를 한 번에 묶을 수 있음: 컴포넌트, API 함수, 훅처럼 실제로는 디렉토리가 분산되어 있어도 하나의 규칙 파일로 다 포괄 가능
• 자동 적용이라 까먹을 일이 없음: Skill처럼 트리거 문구를 말해야 하는 게 아니라, 해당 경로 파일을 Claude가 읽는 순간 자동으로 컨텍스트에 들어가므로 "이 규칙 적용해야 하는데 깜빡했다"가 구조적으로 방지됨
• 여러 repo에 규칙 재사용: symlink로 공통 규칙을 여러 프로젝트에 연결 가능

---

실제 쓰는 예시: 포팅된 레거시 도메인 규칙

특정 서비스 안의 한 도메인 폴더(컴포넌트/API 함수/쿼리 훅이 흩어진 영역)를 glob 여러 개로 묶어 적용한 사례입니다.

배경: 이 영역은 외부 프로젝트에서 포팅된 코드라 현재 프로젝트 컨벤션과 어긋나는 부분이 있어, 아래 기준으로 점검 후 수정합니다.

• 타입 불일치: any 금지, 공통 패키지에 정의된 지정 타입(API 요청/응답 타입) 사용. 지정 타입과 실제 요청/응답이 다르면 공통 타입을 고치지 말고 포팅된 쪽 코드를 공통 타입 기준으로 수정
• 사용처 데이터 불일치: 컴포넌트가 받는 데이터 형태가 공통 타입과 다르면 컴포넌트 쪽을 맞춤 (타입을 깎아서 끼워 맞추지 않음)
• 토스트/알림: 프로젝트 표준 알림 훅만 사용. 포팅된 코드에 남은, 존재하지 않거나 다른 프로젝트의 알림 함수는 표준 훅으로 교체
• 경로: 옛 프로젝트 구조를 가리키는 import는 현재 alias 기준으로 수정

→ "공통 타입이 기준, 나머지가 거기에 맞춘다"처럼 방향이 헷갈리기 쉬운 규칙을 경로에 고정해두면, 이 영역을 만질 때마다 매번 설명할 필요가 없어집니다.

---

주의할 점

• glob 범위를 너무 넓게 잡으면(예: apps/**/*.ts) 사실상 CLAUDE.md와 다를 게 없어지고 조건부로 두는 의미가 사라짐 — 정말 예외적인 영역에만 좁게 적용
• 트리거는 "Claude가 매칭되는 파일을 읽는 시점"이라, 그 파일을 한 번도 안 읽으면 규칙이 안 보임 — 너무 좁게 잡거나 진입점이 아닌 파일만 노리면 막상 필요할 때 안 불려올 수 있음
• 포팅/마이그레이션이 끝나서 코드가 일반 컨벤션으로 정리되면 해당 rules 파일은 삭제하거나 갱신할 것 (안 그러면 이미 끝난 마이그레이션 규칙이 계속 컨텍스트를 차지함)
• CLAUDE.md, Rules, Skill 세 가지를 동시에 운영할 때는 "전역 규칙 / 특정 폴더 예외 규칙 / 특정 작업 절차"로 역할을 명확히 나눠서 같은 내용이 중복 적히지 않게 관리