포스팅 개요
본 포스팅은 Claude Code의 Rules 기능에 대해 다루는 글입니다. Claude Code로 작업하다 보면, 매 세션마다 같은 지시를 반복하게 되는 경우가 있습니다. "이모지 쓰지 마", "로그는 이 형식으로 작성해", "테스트는 pytest로 돌려" 같은 것들이죠. 한두 번이면 괜찮지만, 프로젝트가 커지고 팀원이 늘어나면 이런 반복 지시는 꽤 번거로워집니다.
Claude Code의 Rules는 이런 문제를 해결합니다. CLAUDE.md 파일이나 .claude/rules/ 디렉토리에 규칙을 작성해두면, Claude가 매 세션 시작 시 자동으로 읽고 따르려 합니다. 다만 이것은 강제 설정이 아니라 컨텍스트로 취급되기 때문에, 지침이 구체적이고 간결할수록 더 일관되게 따릅니다. 한 번 써두면 다시 말할 필요가 없는, 일종의 "Claude를 위한 팀 컨벤션 문서"인 셈입니다.
이 글에서는 Rules의 기본 개념, 구성 방법, 예제(example)를 단계별로 살펴보겠습니다.
본 포스팅은 2026년 3월 기준 Anthropic 공식 문서를 바탕으로 작성되었습니다.
- Anthropic 공식 문서 (Memory): https://docs.anthropic.com/ko/docs/claude-code/memory
Claude가 프로젝트를 기억하는 방법 - Claude Code Docs
CLAUDE.md 파일로 Claude에 지속적인 지침을 제공하고, 자동 메모리를 통해 Claude가 자동으로 학습을 축적하도록 합니다.
code.claude.com
포스팅 본문
그러면 지금부터 Claude Code의 Rules에 대해 하나씩 살펴보겠습니다.
[1]. Rules 기본 개념
Claude Code에서 "Rules"라고 하면, Claude에게 지속적인 지침을 제공하는 두 가지 메커니즘을 말합니다.
1) CLAUDE.md 파일
프로젝트 루트나 홈 디렉토리에 놓는 마크다운 파일입니다. Claude가 모든 세션의 시작 시 이 파일을 읽고, 그 안의 지침을 따릅니다. 프로젝트의 빌드 명령, 코딩 규칙, 아키텍처 결정 같은 내용을 담기에 좋습니다.
2) .claude/rules/ 디렉토리
CLAUDE.md 하나에 모든 규칙을 넣으면 파일이 길어지고 관리가 어려워집니다. .claude/rules/ 디렉토리를 사용하면 규칙을 주제별 파일로 나눌 수 있습니다. 예를 들어 code-style.md, testing.md, security.md처럼 분리하는 것이죠. 또한 특정 파일 경로에만 적용되는 조건부 규칙도 설정할 수 있습니다.
이 외에도 Claude Code에는 자동 메모리(Auto Memory)라는 기능이 있습니다. 이것은 사용자가 작성하는 게 아니라, Claude가 작업하면서 스스로 학습한 내용을 기록하는 시스템입니다. 빌드 명령, 디버깅 팁, 코드 스타일 선호도 같은 것들을 Claude가 알아서 기록하고 다음 세션에서 활용합니다.
CLAUDE.md와 자동 메모리의 차이를 표로 정리하면 다음과 같습니다.
| 구분 | CLAUDE.md | 자동 메모리 |
|---|---|---|
| 작성자 | 사용자 | Claude |
| 포함 내용 | 지침 및 규칙 | 학습 및 패턴 |
| 범위 | 프로젝트, 사용자, 조직 | 워크트리당 |
| 로드 대상 | 모든 세션 | 모든 세션 (처음 200줄) |
| 용도 | 코딩 표준, 워크플로우, 프로젝트 아키텍처 |
빌드 명령, 디버깅 팁, Claude가 파악한 선호도 |
정리하면, Claude의 동작을 직접 안내하려면 CLAUDE.md와 .claude/rules/를 쓰고, Claude가 자연스럽게 학습하도록 두려면 자동 메모리를 활용하면 됩니다.
[2]. Rules가 필요한 이유
Rules를 왜 써야 하는지, 실무적인 관점에서 정리해보겠습니다.
첫째, 일관성을 유지할 수 있습니다.
CLAUDE.md에 "들여쓰기는 2칸", "함수명은 camelCase"라고 적어두면, Claude가 매번 동일한 스타일로 코드를 작성합니다. 팀원 각자가 다른 지시를 내리는 바람에 코드 스타일이 뒤죽박죽이 되는 일을 방지할 수 있죠.
둘째, 반복 지시를 없앨 수 있습니다.
매 세션마다 "테스트는 pytest로 돌려", "커밋 메시지는 한국어로 작성해"라고 말하지 않아도 됩니다. 한 번 규칙 파일에 적어두면 Claude가 알아서 따릅니다.
셋째, 팀과 공유할 수 있습니다.
프로젝트 루트의 CLAUDE.md나 .claude/rules/ 디렉토리를 git에 커밋하면, 팀원 모두가 동일한 규칙 하에서 Claude를 사용하게 됩니다. 새 팀원이 합류해도 별도의 온보딩 없이 프로젝트 규칙이 바로 적용됩니다.
넷째, 컨텍스트를 효율적으로 관리할 수 있습니다.
.claude/rules/의 경로별 규칙(paths frontmatter)을 사용하면, 특정 파일을 다룰 때만 해당 규칙이 로드됩니다. TypeScript 파일을 편집할 때만 TypeScript 규칙이 로드되고, Python 파일을 편집할 때만 Python 규칙이 로드되는 식이죠. 불필요한 컨텍스트 소비를 줄일 수 있습니다.
[3]. Rules 구성 방법
이제 실제로 Rules를 구성하는 방법을 알아보겠습니다.
[3-1]. CLAUDE.md 파일 위치와 범위
CLAUDE.md 파일은 놓는 위치에 따라 적용 범위가 달라집니다.
| 범위 | 위치 | 목적 | 공유 대상 |
|---|---|---|---|
| 관리 정책 | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux/WSL: /etc/claude-code/CLAUDE.md Windows: C:\Program Files\ClaudeCode\CLAUDE.md |
조직 전체 지침 | 조직 모든 사용자 |
| 프로젝트 | ./CLAUDE.md 또는 ./.claude/CLAUDE.md | 팀 공유 지침 | git으로 팀 공유 |
| 사용자 | ~/.claude/CLAUDE.md | 개인 선호도 | 본인만 |
Claude Code는 현재 작업 디렉토리에서 시작해서 상위 디렉토리까지 올라가며 CLAUDE.md 파일을 찾습니다. 예를 들어 foo/bar/에서 Claude Code를 실행하면, foo/bar/CLAUDE.md와 foo/CLAUDE.md 모두 로드됩니다. 하위 디렉토리의 CLAUDE.md는 Claude가 해당 디렉토리의 파일을 읽을 때 로드됩니다.
더 구체적인 위치의 지침이 더 넓은 범위의 지침보다 우선합니다.
[3-2]. /init으로 CLAUDE.md 자동 생성
CLAUDE.md를 처음부터 직접 작성하기 귀찮다면, /init 명령을 사용하면 됩니다. Claude가 코드베이스를 분석하고, 빌드 명령, 테스트 지침, 프로젝트 규칙이 포함된 CLAUDE.md를 자동으로 생성해줍니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선 사항을 제안합니다.
/init
자동 생성된 파일을 기반으로, Claude가 스스로는 발견하지 못할 규칙이나 워크플로우를 추가해 나가는 것을 권장합니다!
[3-3]. .claude/rules/ 디렉토리 구조
프로젝트가 커지면 CLAUDE.md 하나로는 관리가 어렵습니다.
이에, .claude/rules/ 디렉토리를 사용하면 규칙을 주제별 파일로 나눌 수 있습니다.
your-project/
├── .claude/
│ ├── CLAUDE.md # 메인 프로젝트 지침
│ └── rules/
│ ├── code-style.md # 코드 스타일 가이드라인
│ ├── testing.md # 테스트 규칙
│ └── security.md # 보안 요구사항
각 .md 파일은 한 가지 주제를 다루는 것이 좋습니다. 그리고 하위 디렉토리로 더 세분화할 수도 있습니다.
예를 들어 rules/frontend/react.md, rules/backend/api.md처럼 구성하는 것도 가능합니다.
참고로 paths frontmatter가 없는 규칙 파일은 세션 시작 시 모두 로드됩니다. ( CLAUDE.md와 같은 우선순위입니다! )
[3-4]. 경로별 규칙 (paths frontmatter)
규칙 파일에 YAML frontmatter로 paths를 지정하면, Claude가 해당 패턴에 맞는 파일을 읽을 때만 규칙이 로드됩니다.
모든 세션에 항상 로드되는 것이 아니라 조건부로 적용되는 것이죠!
---
paths:
- "src/api/**/*.ts"
---
# API 개발 규칙
- 모든 API 엔드포인트는 입력 검증을 포함해야 합니다
- 표준 오류 응답 형식을 사용합니다
- OpenAPI 문서 주석을 포함합니다
위 규칙은 src/api/ 디렉토리 아래의 TypeScript 파일을 읽을 때 적용됩니다. 만약, Python 파일을 다루고 있다면 이 규칙은 로드되지 않습니다. 이렇게 상황에 맞게 로드를 시킬 수 있는 것입니다.
자주 사용하는 glob 패턴을 정리하면 다음과 같습니다.
| 패턴 | 매칭 대상 |
|---|---|
| **/*.ts | 모든 디렉토리의 TypeScript 파일 |
| src/**/* | src/ 디렉토리 아래의 모든 파일 |
| *.md | 프로젝트 루트의 마크다운 파일 |
| src/**/*.{ts,tsx} | src/ 아래의 .ts와 .tsx 파일 모두 |
| tests/**/*.test.ts | tests/ 아래의 테스트 파일 |
[3-5]. 사용자 수준 규칙
앞서 CLAUDE.md를 생성할 때 언급드렸듯, 범위를 확장할수도 있는데요.
~/.claude/rules/ 에 넣는 규칙은 모든 프로젝트에 적용되는 개인 규칙입니다.
프로젝트와 무관하게 항상 적용하고 싶은 개인 코딩 선호도를 여기에 작성합니다.
~/.claude/rules/
├── preferences.md # 개인 코딩 선호도
└── workflows.md # 선호하는 워크플로우
사용자 수준 규칙은 프로젝트 규칙보다 먼저 로드되며, 프로젝트 규칙이 더 높은 우선순위를 가집니다.
[3-6]. @path 가져오기
CLAUDE.md 파일 안에서 @path 구문을 사용하면 다른 파일을 가져올 수 있습니다.
가져온 파일은 CLAUDE.md와 함께 세션 시작 시 로드됩니다. 이렇게 성격별로 파일을 나누어서 지침을 지시할 수 있죠.
프로젝트 개요는 @README.md를 참조하세요.
사용 가능한 npm 명령은 @package.json을 참조하세요.
# 추가 지침
- git 워크플로우: @docs/git-instructions.md
상대 경로는 가져오기를 포함하는 파일을 기준으로 해석됩니다. 가져온 파일이 또 다른 파일을 가져올 수도 있는데, 최대 5단계 깊이까지 재귀적으로 가져올 수 있습니다. 홈 디렉토리의 개인 파일도 가져올 수 있어서, 공유 CLAUDE.md에서 개인 설정 파일을 참조하는 것도 가능합니다.
# 개인 선호도
- @~/.claude/my-project-instructions.md
[4]. 예제(Example)
이제 직접 규칙을 만들어보겠습니다.
간단하게 만들어 볼 것인데요. 2개의 rules을 만들어 보려고 합니다.
첫 번째는 "불필요한 이모지 사용 금지" 규칙이고, 두 번째는 "이수진 yyyy-mm-dd hhmmss" 형식으로 로그를 찍도록 하는 규칙입니다.
[4-1]. 규칙 파일 생성
프로젝트의 .claude/rules/ 디렉토리에 clean-code.md 파일과 logging-format.md 파일을 생성합니다.
파일 경로: .claude/rules/clean-code.md
# 클린 코드 규칙
## 이모지 사용 금지
- 코드 주석, 로그 메시지, 커밋 메시지, 변수명에 이모지를 사용하지 마세요
- 콘솔 출력이나 사용자 대면 메시지에도 이모지를 포함하지 마세요
- 이모지 대신 명확한 텍스트 레이블을 사용하세요
## 좋은 예와 나쁜 예
나쁜 예:
- console.log("✅ 배포 성공!")
- // 🔥 핫픽스: 긴급 수정
- const status = "⚠️ 경고"
좋은 예:
- console.log("[SUCCESS] 배포가 완료되었습니다.")
- // HOTFIX: 긴급 수정
- const status = "[WARNING] 경고"
## 주석 작성 규칙
- 주석은 한국어 또는 영어로 간결하게 작성합니다
- 불필요한 특수문자나 장식용 기호를 사용하지 않습니다
- 코드의 의도를 설명하는 주석만 작성합니다
파일 경로: .claude/rules/logging-format.md
# 로그 형식 규칙
## 로그 메시지 형식
모든 로그 메시지는 아래 형식을 따라야 합니다:
```
이수진 yyyy-mm-dd hhmmss [LOG_LEVEL] 메시지
```
## 세부 규칙
- 로그의 맨 앞에 "이수진"을 반드시 포함합니다
- 날짜는 yyyy-mm-dd 형식으로 작성합니다
- 시간은 hhmmss 형식(24시간제, 콜론 없이)으로 작성합니다
- LOG_LEVEL은 INFO, WARN, ERROR, DEBUG 중 하나를 사용합니다
- 날짜/시간과 로그 레벨 사이에 공백을 둡니다
## 출력 예시
```
이수진 2026-03-22 153042 [INFO] 서버가 시작되었습니다.
이수진 2026-03-22 153045 [ERROR] 데이터베이스 연결에 실패했습니다.
이수진 2026-03-22 153100 [DEBUG] 요청 파라미터: {id: 42}
```
## 언어별 구현 가이드
### Python
```python
import datetime
def log(level, message):
now = datetime.datetime.now()
timestamp = now.strftime("%Y-%m-%d %H%M%S")
print(f"이수진 {timestamp} [{level}] {message}")
```
### JavaScript / TypeScript
```javascript
function log(level, message) {
const now = new Date();
const y = now.getFullYear();
const mon = String(now.getMonth() + 1).padStart(2, '0');
const d = String(now.getDate()).padStart(2, '0');
const h = String(now.getHours()).padStart(2, '0');
const m = String(now.getMinutes()).padStart(2, '0');
const s = String(now.getSeconds()).padStart(2, '0');
console.log(`이수진 ${y}-${mon}-${d} ${h}${m}${s} [${level}] ${message}`);
}
```
## 적용 범위
- 새로 작성하는 모든 로그 관련 코드에 이 형식을 적용합니다
- 기존 코드에 로그를 추가할 때도 이 형식을 사용합니다
- 디버깅용 임시 로그도 같은 형식을 따릅니다
[4-2]. 특정 파일에만 적용하기
만약 프론트엔드 코드에만 이 규칙을 적용하고 싶다면, paths frontmatter를 추가하면 됩니다.
파일 경로: .claude/rules/frontend-clean.md
---
paths:
- "src/frontend/**/*.{ts,tsx,js,jsx}"
---
# 프론트엔드 클린 코드 규칙
- 이모지를 UI 텍스트에 직접 사용하지 마세요
- 아이콘은 아이콘 라이브러리의 컴포넌트를 사용하세요
- 문자열 리터럴에 특수문자를 직접 넣지 마세요
이렇게 하면 src/frontend/ 아래의 TypeScript와 JavaScript 파일을 편집할 때만 이 규칙이 적용됩니다.
[4-3]. 동작 확인
규칙이 제대로 로드되는지 확인하려면 Claude Code에서 /memory 명령을 실행합니다. 현재 세션에 로드된 모든 CLAUDE.md 파일과 규칙 파일 목록이 표시됩니다. clean-code.md가 목록에 있으면 정상입니다.
그리고 실제로 동작 되는지 봐볼까요?
claude code를 실행시켜서, 아래 사진과 같이 작업을 수행시켜 보겠습니다.
간단한 예제입니다. game.py를 하나 만들어서, 사용자가 python game.py를 실행하면 사칙연산을 수행하고 그 결과를 보여달라는 것이죠. 단, 로깅 기능도 만들어 달라고 했습니다.
Claude code가 제대로 제가 작성한 logging 지시를 따르는 지 확인해보면요!
중간에, Claude code 작업하는 결과가 보여지는데, 제가 원하는 "이수진 yyyy-mm-dd hhmmss [LOG_LEVEL] 메시지" 형식으로 만든 것을 확인할 수 있습니다.
그리고 실제 완성된 파이썬 파일을 봐도, 로그를 제가 지시한 rules대로 만든 것을 확인할 수 있습니다.
그리고 clean-code 가이드에 맞게 이모지를 사용하지도 않았습니다.
[5]. Rules 효과적으로 작성하기
마지막으로, Rules를 효과적으로 작성하기 위한 팁을 정리하겠습니다.
1) CLAUDE.md는 200줄 이하로 유지하세요
CLAUDE.md가 길어지면 더 많은 컨텍스트를 소비하고, Claude가 규칙을 놓칠 확률이 올라갑니다. 내용이 많아지면 .claude/rules/로 분할하거나, @path 가져오기로 별도 파일을 참조하세요.
2) 구체적으로 작성하세요
모호한 지침은 Claude가 따르기 어렵습니다. 검증할 수 있을 정도로 구체적으로 작성하는 게 좋습니다.
- "코드를 제대로 포맷하세요" 대신 "2칸 들여쓰기를 사용하세요"
- "변경 사항을 테스트하세요" 대신 "커밋하기 전에 npm test를 실행하세요"
- "파일을 정리하세요" 대신 "API 핸들러는 src/api/handlers/에 위치시키세요"
3) 충돌하는 규칙이 없는지 확인하세요
두 규칙이 서로 모순되면 Claude가 하나를 임의로 선택할 수 있습니다. CLAUDE.md, .claude/rules/, 하위 디렉토리의 CLAUDE.md를 주기적으로 검토해서 오래되었거나 충돌하는 지침을 정리하세요.
4) /memory 명령으로 확인하세요
현재 세션에 어떤 규칙 파일이 로드되어 있는지 확인하려면 /memory 명령을 실행하면 됩니다. 규칙이 로드되지 않았다면 파일 위치를 확인해보세요.
5) /compact 후에도 규칙은 유지됩니다
Claude Code에서 /compact를 실행해서 대화를 압축해도, CLAUDE.md는 디스크에서 다시 읽어 새로 주입됩니다. 다만 대화 중에 말로만 전달한 지시는 압축 과정에서 사라질 수 있으니, 중요한 규칙은 반드시 CLAUDE.md나 규칙 파일에 기록해두세요.
6) 마크다운 구조를 활용하세요
Claude는 사람이 문서를 읽는 것과 비슷한 방식으로 구조를 스캔합니다. 헤더와 글머리 기호로 관련 지침을 그룹화하면, 긴 문단보다 훨씬 잘 따릅니다.
마무리
이번 포스팅에서는 Claude Code의 Rules 기능에 대해 살펴보았습니다.
부족한 글이지만, Claude Code를 더 효과적으로 활용하는 데 도움이 되셨으면 합니다.
궁금한 점이나 피드백이 있으시면 댓글이나 연락해주세요!