CLAUDE.md 작성 가이드: 프로젝트 규칙을 AI에게 알려주는 법

클로드 코드로 작업하다 보면 새 세션을 시작할 때마다 AI가 프로젝트에 대해 아무것도 모른다는 걸 느끼게 됩니다. “테스트는 bun run test로 돌려”, “커밋 메시지는 영어로 써줘”, “이 프로젝트는 Prettier를 쓰고 있어”… 매번 같은 말을 반복하는 건 꽤 피곤한 일이죠.

CLAUDE.md는 이 문제를 해결하는 가장 직접적인 방법입니다. 프로젝트의 빌드 명령어, 코딩 스타일, 아키텍처 결정 같은 규칙을 마크다운으로 적어두면 Claude가 매 세션 시작 시 읽어들이거든요. Git에 커밋하면 팀 전체가 공유할 수 있고, 개인 설정으로만 쓸 수도 있습니다.

CLAUDE.md 파일의 위치와 스코프

CLAUDE.md 파일을 어디에 놓느냐에 따라 적용 범위가 달라집니다. 여러 위치에 동시에 둘 수 있고, 구체적인 위치가 더 높은 우선순위를 갖습니다.

가장 많이 쓰는 건 프로젝트 지시 파일입니다. ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 두면 팀원 모두가 공유하는 프로젝트 규칙이 됩니다. 빌드 명령어, 테스트 방법, 코딩 컨벤션 같은 내용을 여기에 적고 Git에 커밋하면 돼요.

사용자 지시 파일(~/.claude/CLAUDE.md)은 모든 프로젝트에 적용되는 개인 설정입니다. “응답은 한국어로 해줘”, “커밋 메시지는 Conventional Commits 형식으로” 같은 선호를 담기에 좋죠.

로컬 지시 파일(./CLAUDE.local.md)은 프로젝트 안에서 나만 쓰는 설정입니다. 샌드박스 URL이나 테스트 데이터 같은 걸 넣어두면 돼요. .gitignore에 자동으로 추가되어 Git에 커밋되지 않습니다.

조직 관리자라면 관리 정책 파일도 있습니다. macOS는 /Library/Application Support/ClaudeCode/CLAUDE.md, Linux는 /etc/claude-code/CLAUDE.md에 두면 해당 기기의 모든 사용자에게 적용돼요. 회사 보안 정책이나 코딩 표준을 강제할 때 쓰이며, 개별 설정으로 비활성화할 수 없습니다.

/init으로 시작하기

처음 CLAUDE.md를 만들 때 빈 파일에서 뭘 써야 할지 막막하죠? 클로드 코드의 /init 커맨드를 쓰면 코드베이스를 분석해서 CLAUDE.md를 자동으로 만들어줍니다.

$ claude
> /init

Claude가 package.json, README.md, 기존 설정 파일들을 참고해서 프로젝트 구조, 빌드 명령어, 테스트 방법, 코딩 컨벤션 등을 파악하고 적절한 내용으로 채워줍니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선 사항을 제안합니다.

자동 생성된 내용에서 시작해서, Claude가 알아서 못 찾는 프로젝트 고유의 규칙이나 주의사항을 직접 추가하면 됩니다.

효과적인 지시문 작성법

CLAUDE.md는 매 세션마다 컨텍스트 윈도우에 로드되기 때문에 토큰을 잡아먹습니다. 너무 길면 오히려 지시 준수율이 떨어져요. 몇 가지 원칙만 지키면 효과가 확 달라집니다.

우선 분량은 200줄 이내로 유지하는 게 좋습니다. 파일이 길어지면 핵심이 묻혀요. 꼭 필요한 정보만 담고 상세한 내용은 별도 파일로 분리하세요.

마크다운 헤딩과 불릿으로 구조를 잡아주는 것도 중요합니다. 빽빽한 문단보다 정리된 섹션이 Claude 입장에서 파악하기 훨씬 쉬워요.

무엇보다 구체적으로 작성해야 합니다. “코드를 잘 포맷해줘”보다 “들여쓰기는 2칸 스페이스를 써”가 훨씬 효과적이에요. 검증 가능한 수준으로 구체적이어야 Claude가 일관되게 따라갑니다.

## 빌드와 테스트

- 개발 서버: `bun run dev`
- 빌드: `bun run build`
- 테스트: `bun run test`

## 코드 스타일

- 들여쓰기: 2칸 스페이스
- 세미콜론 사용하지 않음
- 문자열은 작은따옴표 사용
- 커밋 전 `bun run format` 실행

## 프로젝트 구조

- API 핸들러: `src/api/handlers/`
- 공유 유틸리티: `src/utils/`
- 테스트 파일: `__tests__/` 디렉토리에 작성

여러 CLAUDE.md 파일에 서로 충돌하는 규칙이 있으면 Claude가 임의로 하나를 골라버릴 수 있으니 주의하세요. 가끔 검토해서 오래된 지시를 정리하는 습관이 필요합니다.

다른 파일 임포트하기

CLAUDE.md가 길어지면 파일을 나눠서 관리할 수 있습니다. @경로 문법으로 다른 파일을 임포트하면 세션 시작 시 함께 로드됩니다.

프로젝트 개요는 @README.md를 참고하세요.
사용 가능한 명령어는 @package.json을 참고하세요.

# 추가 지시사항
- Git 워크플로우는 @docs/git-instructions.md를 따르세요.

상대 경로와 절대 경로 모두 쓸 수 있어요. 상대 경로는 임포트하는 파일이 있는 디렉토리 기준입니다. 임포트된 파일이 또 다른 파일을 임포트할 수도 있는데, 최대 5단계까지 허용됩니다.

여러 워크트리에서 작업하는 경우, CLAUDE.local.md는 한 워크트리에만 존재합니다. 모든 워크트리에서 공유할 개인 설정이 있다면 홈 디렉토리의 파일을 임포트하는 방식이 좋습니다.

# 개인 설정
- @~/.claude/my-project-instructions.md

프로젝트에서 처음 외부 임포트를 발견하면 승인 대화상자가 나타납니다. 거부하면 해당 임포트는 비활성화되고 대화상자는 다시 나타나지 않습니다.

.claude/rules/로 규칙 체계화하기

프로젝트가 커지면 모든 규칙을 하나의 CLAUDE.md에 담기 어려워집니다. .claude/rules/ 디렉토리를 활용하면 주제별로 규칙을 나눠서 관리할 수 있어요.

my-project/
├── .claude/
│   ├── CLAUDE.md           # 메인 프로젝트 지시문
│   └── rules/
│       ├── code-style.md   # 코드 스타일 가이드
│       ├── testing.md      # 테스트 컨벤션
│       └── security.md     # 보안 요구사항

각 파일은 하나의 주제를 다루도록 testing.md, api-design.md 같이 서술적인 이름을 붙입니다. .md 파일은 재귀적으로 탐색되므로 frontend/, backend/ 같은 하위 디렉토리로 분류할 수도 있습니다.

여기서 특히 쓸만한 게 경로 기반 규칙입니다. YAML 프론트매터에 paths 필드를 넣으면 특정 파일에만 적용되는 규칙을 만들 수 있거든요.

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

# API 개발 규칙

- 모든 API 엔드포인트에 입력 유효성 검사를 포함할 것
- 표준 에러 응답 형식을 사용할 것
- OpenAPI 문서화 주석을 추가할 것

이렇게 하면 Claude가 src/api/ 하위의 TypeScript 파일을 읽을 때만 이 규칙이 컨텍스트에 로드됩니다. 관련 없는 파일에서 작업할 때는 불필요한 토큰을 소비하지 않으니 효율적이죠.

여러 글로브 패턴을 조합할 수도 있습니다.

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

paths 필드가 없는 규칙 파일은 모든 세션에서 무조건 로드됩니다. .claude/CLAUDE.md와 같은 우선순위로 취급돼요.

개인 규칙은 ~/.claude/rules/에 둘 수 있습니다. 모든 프로젝트에 적용되는 개인 선호사항을 넣어두기 좋습니다. 사용자 레벨 규칙은 프로젝트 규칙보다 먼저 로드되므로 프로젝트 규칙이 더 높은 우선순위를 갖습니다.

심볼릭 링크도 지원하기 때문에, 여러 프로젝트에서 공유하는 규칙 세트가 있다면 링크를 걸어서 사용할 수 있습니다.

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

CLAUDE.md가 로드되는 방식

클로드 코드는 현재 작업 디렉토리에서 디렉토리 트리를 위로 올라가면서 CLAUDE.md와 CLAUDE.local.md 파일을 찾습니다. 예를 들어 foo/bar/에서 실행하면 foo/bar/CLAUDE.md와 foo/CLAUDE.md가 모두 로드됩니다.

하위 디렉토리의 CLAUDE.md는 좀 다르게 동작합니다. 세션 시작 시 바로 로드되지 않고, Claude가 해당 디렉토리의 파일을 읽을 때 함께 포함됩니다. 필요한 순간에 로드되는 것이죠.

대규모 모노레포에서 다른 팀의 CLAUDE.md가 함께 로드되는 게 신경 쓰인다면 설정 파일의 claudeMdExcludes 옵션으로 특정 파일을 제외할 수 있습니다.

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

패턴은 절대 파일 경로에 대해 글로브 매칭됩니다. 관리 정책 CLAUDE.md는 제외할 수 없도록 되어 있어서, 조직 전체의 규칙은 항상 적용됩니다.

--add-dir 플래그로 추가 디렉토리를 지정한 경우, 기본적으로는 해당 디렉토리의 CLAUDE.md가 로드되지 않습니다. 로드하려면 환경 변수를 설정해야 합니다.

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

/compact와 CLAUDE.md

긴 세션에서 컨텍스트 윈도우가 가득 차면 /compact 커맨드로 대화를 압축할 수 있는데요. 이때 CLAUDE.md는 압축의 영향을 받지 않습니다. 압축 후 Claude가 디스크에서 CLAUDE.md를 다시 읽어서 새롭게 주입하기 때문이죠.

다만 대화 중에 말로만 전달한 지시는 압축 과정에서 사라질 수 있습니다. “앞으로 이렇게 해줘”라고 구두로 말한 것이 /compact 후에 안 지켜진다면, 그 내용을 CLAUDE.md에 적어두는 것이 좋습니다.

트러블슈팅

실제 사용하다 보면 몇 가지 문제에 부딪힐 수 있습니다.

“Claude가 CLAUDE.md를 안 따라요.” 이건 가장 흔한 불만인데요. CLAUDE.md는 강제 설정이 아니라 컨텍스트라서 100% 보장은 안 됩니다. 먼저 /memory를 실행해서 파일이 제대로 로드되고 있는지 확인해보세요. 목록에 없으면 Claude가 아예 못 보고 있는 겁니다. 지시가 모호하거나 규칙끼리 충돌하고 있진 않은지도 점검해보세요.

“CLAUDE.md가 너무 길어졌어요.” 200줄이 넘으면 컨텍스트를 많이 잡아먹고 준수율도 떨어집니다. @경로 임포트로 별도 파일을 참조하거나 .claude/rules/로 분리하세요.

마치며

CLAUDE.md는 프로젝트의 규칙과 지식을 Claude에게 전달하는 가장 직접적인 방법입니다. 시작이 막막하다면 /init으로 기본 파일을 만들고, Claude가 자꾸 틀리는 부분을 하나씩 추가해나가면 됩니다.

여러 AI 코딩 에이전트를 사용하는 팀이라면 AGENTS.md와 CLAUDE.md에서 다룬 심볼릭 링크 방식도 참고해보세요. CLAUDE.md와 함께 Claude가 스스로 학습하는 자동 메모리를 활용하면 세션을 거듭할수록 Claude와의 협업이 더 매끄러워집니다. 설정 파일까지 함께 다루면 권한 관리, 모델 선택 등 클로드 코드 환경을 더 세밀하게 제어할 수 있습니다.