규칙 (Rules)
규칙이란?
규칙(Rules)은 Claude Code가 매 세션 시작 시 자동으로 읽는 지속적인 지침입니다. 매번 같은 설명을 반복할 필요 없이, 한 번 작성해두면 Claude가 항상 참고합니다.
예를 들어 "TypeScript로 작성해줘", "커밋 메시지는 한국어로 해줘"와 같은 지침을 매번 입력하는 대신, 규칙에 한 번만 적어두면 됩니다.
규칙 적용 우선순위
CLAUDE.md 파일
규칙을 설정하는 가장 기본적인 방법은 CLAUDE.md 파일을 만드는 것입니다.
자동 생성 (권장)
Claude Code에서 다음 명령어를 실행하면 프로젝트에 맞는 CLAUDE.md를 자동 생성합니다:
claude /init
환경변수 CLAUDE_CODE_NEW_INIT=1을 설정하면 대화형(interactive) 초기화 플로우를 사용할 수 있습니다. 프로젝트 구조를 분석하고 더 상세한 CLAUDE.md를 생성합니다:
CLAUDE_CODE_NEW_INIT=1 claude /init
수동 생성
프로젝트 루트에 직접 CLAUDE.md 파일을 만들 수도 있습니다:
# 프로젝트 가이드
## 기술 스택
- Next.js 14 (App Router)
- TypeScript (strict 모드)
- Prisma + PostgreSQL
- Tailwind CSS
## 빌드 및 테스트
- 빌드: `npm run build`
- 테스트: `npm test`
- 린트: `npm run lint`
## 코딩 컨벤션
- 함수형 컴포넌트만 사용
- 커밋 메시지는 Conventional Commits 형식
- 변수명은 camelCase, 컴포넌트명은 PascalCase
CLAUDE.md의 적용 범위
CLAUDE.md 파일은 여러 위치에 둘 수 있고, 위치에 따라 적용 범위가 달라집니다:
| 범위 | 파일 위치 | 누가 사용하나 | Git에 커밋 |
|---|---|---|---|
| 프로젝트 | ./CLAUDE.md 또는 ./.claude/CLAUDE.md | 팀 전체 | O (팀 공유) |
| 개인 (프로젝트) | ./CLAUDE.local.md | 나만 | X (.gitignore에 추가) |
| 사용자 전역 | ~/.claude/CLAUDE.md | 나만, 모든 프로젝트 | 해당 없음 |
| 조직 | 시스템 경로 (관리자 설정) | 조직 전체 | 해당 없음 |
로드 순서 및 우선순위: 더 구체적인 위치가 더 광범위한 위치보다 우선합니다 — 개인(프로젝트) > 프로젝트 > 개인(전역) > 조직. 모든 파일은 컨텍스트에 연결(concatenate)되며 서로를 완전히 재정의하지 않습니다.
로딩 방식
Claude Code는 현재 작업 디렉토리에서 상위 디렉토리까지 올라가면서 모든 CLAUDE.md와 CLAUDE.local.md 파일을 찾아서 읽습니다. 하위 디렉토리의 파일은 Claude가 해당 디렉토리의 파일을 읽을 때 필요에 따라 로딩됩니다.
CLAUDE.md 파일의 처음 200줄 또는 25KB가 세션 시작 시 로딩됩니다. 너무 큰 파일은 잘릴 수 있으므로 핵심 내용을 상단에 배치하세요.
/compact 명령어로 컨텍스트를 압축한 후에는 루트 CLAUDE.md 파일이 자동으로 재로딩됩니다. 이를 통해 컴팩트 이후에도 프로젝트 규칙이 항상 컨텍스트에 유지됩니다.
단, 중첩된 하위 디렉토리의 CLAUDE.md(예: src/CLAUDE.md)는 /compact 후 자동으로 재주입되지 않습니다. 해당 파일의 내용이 필요하다면 /compact 후 직접 @src/CLAUDE.md로 참조하거나, 내용을 루트 CLAUDE.md로 통합하는 것을 권장합니다.
HTML 주석 자동 제거
CLAUDE.md 로딩 시 블록 수준 HTML 주석(<!-- maintainer notes -->)이 자동으로 제거됩니다. 이를 활용하여 개발자 메모를 남기면서 토큰을 절약할 수 있습니다:
<!-- 이 내용은 Claude에게 전달되지 않습니다 -->
<!-- 개발자 전용 메모: 2024년 3월 기준 작성 -->
## 기술 스택
<!-- 이 섹션은 팀 전체용이므로 수정 시 모두에게 알릴 것 -->
- Next.js 14 (App Router)
- TypeScript strict 모드
## Claude가 실제로 받는 내용 (주석 제거 후)
- 기술 스택 정보만 전달됨
조직 전체 CLAUDE.md 배포
조직 관리자는 모든 사용자에게 적용되는 CLAUDE.md를 시스템 경로에 배포할 수 있습니다:
| OS | 경로 |
|---|---|
| macOS | /Library/Application Support/ClaudeCode/CLAUDE.md |
| Linux 및 WSL | /etc/claude-code/CLAUDE.md |
| Windows | C:\Program Files\ClaudeCode\CLAUDE.md |
이 위치의 CLAUDE.md는 해당 시스템의 모든 사용자에게 자동으로 적용됩니다.
추가 디렉토리 CLAUDE.md 로딩
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 환경변수를 1로 설정하고 --add-dir 플래그로 추가 디렉토리를 지정하면, 해당 디렉토리의 CLAUDE.md를 자동으로 로딩합니다:
# 추가 디렉토리의 CLAUDE.md 로딩 (env var는 1로 설정)
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config
모노레포나 여러 프로젝트에서 공통 설정을 공유할 때 유용합니다.
Auto Memory 시스템
Claude Code는 작업 중 중요한 정보를 자동으로 기억하는 Auto Memory 기능을 제공합니다.
Auto Memory는 Claude Code v2.1.59 이상에서 사용 가능합니다.
작동 방식
- Claude가 프로젝트에서 학습한 내용을
~/.claude/projects/<project>/memory/디렉토리에 자동 저장합니다 MEMORY.md파일이 진입점(entrypoint)으로 사용됩니다- 세션 시작 시 처음 200줄 또는 25KB가 자동 로딩됩니다
설정
# 세션 중 메모리 토글
/memory
// settings.json에서 비활성화
{
"autoMemoryEnabled": false
}
// 커스텀 메모리 디렉토리 지정
{
"autoMemoryDirectory": "path/to/custom/memory"
}
/memory 명령어 기능
/memory 슬래시 명령어는 세션 중 다음 기능을 제공합니다:
| 기능 | 설명 |
|---|---|
| 로드된 파일 목록 표시 | 현재 세션에 로드된 CLAUDE.md, CLAUDE.local.md, 규칙 파일 목록 확인 |
| Auto Memory 토글 | Auto Memory 기능 켜기/끄기 |
| 메모리 폴더 열기 | 메모리 파일이 저장된 폴더를 파일 탐색기에서 열기 |
CLAUDE.md 파일이 예상대로 로딩되지 않을 때 /memory로 실제 로드된 파일을 확인할 수 있습니다.
Auto Memory 비활성화
환경변수로 전체 비활성화할 수도 있습니다:
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude
- CLAUDE.md: 팀이 공유하는 명시적 규칙 (Git에 커밋)
- Auto Memory: Claude가 자동으로 학습한 개인별 컨텍스트 (로컬 저장)
둘은 보완적입니다. CLAUDE.md에는 팀 규칙을, Auto Memory에는 개인 선호도와 프로젝트별 학습 내용이 저장됩니다.
규칙 파일 분리하기 (.claude/rules/)
프로젝트가 커지면 규칙을 주제별로 분리할 수 있습니다:
프로젝트/
├── .claude/
│ ├── CLAUDE.md # 메인 지침
│ └── rules/
│ ├── code-style.md # 코드 스타일 규칙
│ ├── api-design.md # API 설계 패턴
│ ├── testing.md # 테스트 작성 규칙
│ └── security.md # 보안 요구사항
경로별 규칙 적용
특정 파일 경로에만 적용되는 규칙을 만들 수 있습니다. YAML 프론트매터(frontmatter)에 paths를 지정합니다:
---
paths: ["src/api/**/*.ts"]
---
API 엔드포인트는 반드시 인증 미들웨어를 사용할 것
모든 엔드포인트에 입력 유효성 검사를 포함할 것
표준 에러 응답 형식을 사용할 것
OpenAPI 문서를 포함할 것
paths가 없는 규칙은 세션 시작 시 항상 로딩되고, paths가 있는 규칙은 Claude가 해당 경로의 파일을 읽을 때만 로딩됩니다.
사용자 전역 규칙 (~/.claude/rules/)
프로젝트별이 아닌 모든 프로젝트에 적용되는 개인 규칙을 설정할 수 있습니다:
~/.claude/
├── CLAUDE.md # 전역 지침
└── rules/
├── my-style.md # 개인 코딩 스타일
└── language.md # 언어 선호도 (예: 한국어로 응답)
다른 파일 참조하기 (Import)
CLAUDE.md에서 @경로 문법으로 다른 파일을 참조할 수 있습니다:
# 프로젝트 개요
설정 방법은 @README 를 참고하세요.
사용 가능한 npm 명령어는 @package.json 을 확인하세요.
## 추가 지침
- Git 워크플로우: @docs/git-instructions.md
Import 제한
- 최대 **5홉(hop)**까지 참조를 따라갑니다 (A → B → C → D → E → F에서 F는 로딩되지 않음)
- 순환 참조는 자동으로 감지되어 무시됩니다
워크트리 간 규칙 공유
@~/.claude/ 절대 경로로 임포트하면 여러 Git 워크트리에서 동일한 규칙 파일을 공유할 수 있습니다:
# 워크트리 간 공유 규칙 참조
공통 코딩 스타일: @~/.claude/shared/code-style.md
보안 정책: @~/.claude/shared/security.md
이 방식은 git worktree 환경에서 각 워크트리의 .claude/ 경로가 달라도 항상 같은 전역 규칙을 참조할 때 유용합니다.
AGENTS.md 호환성
Claude Code는 CLAUDE.md를 읽으며 AGENTS.md를 직접 읽지 않습니다. 저장소가 이미 다른 코딩 에이전트에 AGENTS.md를 사용하는 경우, CLAUDE.md를 만들어 가져오면 됩니다:
@AGENTS.md
## Claude Code 전용 설정
- `src/billing/` 아래 변경 시 Plan Mode 사용
모노레포 관리
claudeMdExcludes로 불필요한 CLAUDE.md 제외
모노레포에서 특정 패키지의 CLAUDE.md를 세션에서 제외할 수 있습니다. .claude/settings.json에서 설정합니다:
{
"claudeMdExcludes": [
"packages/deprecated-*",
"vendor/**"
]
}
심링크(Symlink)로 규칙 공유
여러 프로젝트에서 동일한 규칙을 사용하려면 심링크를 활용합니다:
# 공통 규칙 파일을 하나의 위치에 관리
ln -s ~/shared-rules/code-style.md .claude/rules/code-style.md
ln -s ~/shared-rules/security.md .claude/rules/security.md
효과적인 CLAUDE.md 작성 팁
분량
200줄 이내로 유지하세요. 너무 길면 컨텍스트 윈도우를 차지하여 실제 작업에 사용할 공간이 줄어듭니다.
구체적으로 작성
| 나쁜 예 | 좋은 예 |
|---|---|
| "테스트를 잘 작성해" | "npm test로 Vitest 테스트를 실행하고, 커버리지 80% 이상 유지" |
| "코드를 깔끔하게" | "2칸 들여쓰기, const 우선 사용, 함수당 30줄 이내" |
| "변경 후 확인해" | "커밋 전에 반드시 npm run lint && npm test 실행" |
마크다운 구조 활용
헤더, 목록, 코드 블록으로 명확하게 구조화하면 Claude가 더 잘 이해합니다.
실전 예제: 모노레포에서 CLAUDE.md 구성하기
monorepo/
├── CLAUDE.md # 루트 공통 규칙
├── .claude/
│ ├── settings.json # claudeMdExcludes 설정
│ └── rules/
│ ├── git-workflow.md # Git 워크플로우 규칙
│ └── code-review.md # 코드 리뷰 규칙
├── packages/
│ ├── frontend/
│ │ └── CLAUDE.md # 프론트엔드 전용 규칙
│ ├── backend/
│ │ └── CLAUDE.md # 백엔드 전용 규칙
│ └── shared/
│ └── CLAUDE.md # 공통 라이브러리 규칙
루트 CLAUDE.md:
# 모노레포 공통 규칙
## 기술 스택
- pnpm workspace 사용
- 빌드: `pnpm run build`
- 전체 테스트: `pnpm run test`
## 규칙
- 커밋 메시지는 Conventional Commits + scope 포함: `feat(frontend): 로그인 폼 추가`
- PR은 반드시 하나의 패키지만 변경 (크로스 패키지 변경은 별도 PR)
- 공통 타입은 `packages/shared`에 정의
패키지별 지침은 각 패키지의 CLAUDE.md를 참고: @packages/frontend/CLAUDE.md
packages/backend/CLAUDE.md:
# Backend 패키지
## 기술 스택
- NestJS + TypeScript
- Prisma ORM
- PostgreSQL
## 테스트
- 단위 테스트: `pnpm test`
- E2E 테스트: `pnpm test:e2e`
- 테스트 DB: `DATABASE_URL` 환경변수 사용
## API 규칙
- 모든 엔드포인트에 DTO validation 필수
- 에러 응답은 `HttpException` 사용
- Swagger 데코레이터 필수
실전 예제: 팀 프로젝트 CLAUDE.md 템플릿
다음은 팀 프로젝트에서 바로 사용할 수 있는 CLAUDE.md 템플릿입니다:
# 프로젝트명
## 기술 스택
- [프레임워크/언어 목록]
## 빌드 및 실행
- 설치: `npm install`
- 개발: `npm run dev`
- 빌드: `npm run build`
- 테스트: `npm test`
- 린트: `npm run lint`
## 코딩 컨벤션
- [들여쓰기, 네이밍 규칙 등]
- 커밋: Conventional Commits 형식
- 브랜치: `feature/`, `fix/`, `chore/` 접두사
## 아키텍처
- [디렉토리 구조 설명]
- [주요 패턴: Repository, Service 등]
## 주의사항
- [절대 하지 말아야 할 것]
- [보안 관련 규칙]
- [성능 관련 규칙]
## 참고 문서
- @README.md
- @docs/architecture.md
CLAUDE.md vs settings.json
| 구분 | CLAUDE.md | .claude/settings.json |
|---|---|---|
| 목적 | 행동 지침 (가이드라인) | 기술 설정 (강제 적용) |
| 작성자 | 사람이 작성 | 설정 도구로 생성 |
| 예시 | 코드 스타일, 워크플로우 | 권한, 샌드박싱, 환경변수 |
| 적용 방식 | Claude가 참고 (가이드) | 시스템이 강제 (설정) |
문제 해결
CLAUDE.md가 로딩되지 않는 경우
- 파일 위치 확인: 프로젝트 루트 또는
.claude/디렉토리에 있는지 확인 - 파일명 확인:
CLAUDE.md(대문자)인지 확인 - 크기 확인: 200줄 / 25KB를 초과하면 잘릴 수 있음
- 제외 설정 확인:
claudeMdExcludes에 해당 경로가 포함되어 있지 않은지 확인
규칙이 무시되는 경우
# 현재 로딩된 규칙 확인
> 현재 적용된 CLAUDE.md와 규칙 파일들을 보여줘
InstructionsLoaded 훅으로 로딩 디버깅
InstructionsLoaded 훅은 CLAUDE.md 파일이 로딩된 직후 실행됩니다. 어떤 파일이 로드되었는지 디버깅할 때 활용할 수 있습니다:
{
"hooks": {
"InstructionsLoaded": [
{
"type": "command",
"command": "echo '로드된 지침 파일 목록:' && cat $CLAUDE_ENV_FILE"
}
]
}
}
이 훅은 CLAUDE.md, .claude/rules/ 파일, 임포트된 파일 등 모든 지침이 로딩된 후 한 번 실행됩니다. 예상한 규칙 파일이 로딩되지 않는 경우 디버깅에 유용합니다.
CLAUDE.md의 내용은 강제 사항이 아닌 가이드라인입니다. Claude가 100% 따르지 않을 수 있으며, 중요한 규칙은 후크(Hook)로 강제하는 것이 더 확실합니다.
연계 기능
settings.json으로 권한·환경변수를 강제 설정하고, claudeMdExcludes로 특정 경로의 CLAUDE.md를 제외할 수 있습니다. 규칙(가이드라인)과 설정(강제 적용)을 조합하면 더 견고한 환경을 구성할 수 있습니다.장점, 단점과 한계점
장점
- 세션 간 일관성 보장: CLAUDE.md에 한 번 작성하면 매 세션마다 동일한 지침이 적용되어, 반복 설명 없이 일관된 코드 스타일과 워크플로우를 유지할 수 있습니다.
- 프로젝트/팀/사용자 수준 계층화: 프로젝트(Git 공유), 개인(로컬), 사용자 전역, 조직 수준으로 규칙을 분리하여 팀 규칙과 개인 선호도를 깔끔하게 관리할 수 있습니다.
- Auto Memory로 자동 학습: Claude가 작업 중 학습한 내용을 자동으로 기억하여, 명시적으로 규칙을 작성하지 않아도 점진적으로 프로젝트에 적응합니다.
- 경로별 세밀한 규칙 적용:
.claude/rules/디렉토리에서 YAML 프론트매터의paths필드를 통해 특정 파일 경로에만 적용되는 규칙을 설정할 수 있습니다. - Import로 규칙 모듈화:
@경로문법으로 README, package.json 등 기존 문서를 참조하여 규칙을 중복 없이 모듈화할 수 있습니다.
단점과 한계점
- 200줄/25KB 크기 제한: 대규모 프로젝트에서 모든 규칙을 담기에 부족할 수 있으며, 초과 시 잘려서 중요한 규칙이 누락될 위험이 있습니다.
- Auto Memory 정확도 한계: 자동으로 학습된 내용이 항상 정확하지 않을 수 있으며, 잘못된 기억이 저장되면 수동으로 수정해야 합니다.
- 규칙 충돌 시 디버깅 어려움: 여러 계층(프로젝트, 개인, 전역, 조직)의 규칙이 충돌할 때 어떤 규칙이 우선 적용되는지 파악하기 어렵습니다.
.claude/rules/경로 제한: 규칙 파일은 반드시.claude/rules/디렉토리에 위치해야 하며, 자유로운 경로 구성이 불가능합니다.- CLAUDE.md 변경이 모든 세션에 영향: 프로젝트 CLAUDE.md를 수정하면 팀 전체 세션에 즉시 반영되므로, 신중하게 변경해야 합니다.
크기 제한을 극복하려면 규칙을 .claude/rules/로 분리하고, @경로 import를 활용하세요. 규칙 충돌이 의심되면 Claude에게 "현재 적용된 CLAUDE.md와 규칙 파일들을 보여줘"라고 요청하면 디버깅에 도움이 됩니다.