Claude Code CLAUDE.md 작성법: 프로젝트 규칙 제대로 설정하기

Claude Code의 CLAUDE.md는 프로젝트를 열 때마다 반복해서 설명하던 구조, 명령어와 개발 규칙을 팀 공통 문맥으로 전달하는 파일입니다. 잘 작성하면 Claude가 올바른 패키지 관리자와 테스트 명령을 선택하고 수정 범위를 지키는 데 도움이 됩니다. 반대로 모호한 문장, 오래된 명령과 상충하는 규칙을 한 파일에 쌓으면 문맥만 늘고 행동은 불안정해질 수 있습니다.

CLAUDE.md는 어떤 파일인가

CLAUDE.md는 Claude Code가 세션에서 참고하는 지속적인 프로젝트 지침입니다. 소스코드처럼 저장소에 커밋하면 팀원이 같은 아키텍처 설명, 코딩 표준과 작업 절차를 공유할 수 있습니다. 운영체제와 계정에만 필요한 개인 설정은 별도 범위에 두는 것이 좋습니다.

이 파일은 Claude의 행동을 안내하지만 권한 시스템처럼 동작을 강제로 차단하는 보안 경계는 아닙니다. 반드시 막아야 하는 명령은 permissions, 정해진 시점에 실행해야 하는 검사는 Hooks, 특정 업무에만 필요한 긴 절차는 Skills로 분리해야 합니다.

CLAUDE.md 저장 위치와 적용 범위

프로젝트 규칙은 저장소 루트의 두 위치 중 하나를 선택해 일관되게 관리하세요. CLAUDE.local.md에는 비밀값을 넣지 말고 Git에서 제외합니다. 개인 파일이라는 이유만으로 토큰이나 고객 데이터를 평문으로 저장해서는 안 됩니다.

CLAUDE.md는 어떻게 불러와지나

Claude Code는 현재 작업 디렉터리에서 상위 디렉터리 방향으로 관련 지침 파일을 찾습니다. 시작 위치의 상위 계층에 있는 파일은 세션 시작 시 읽고, 하위 디렉터리의 중첩된 CLAUDE.md는 Claude가 그 경로의 파일을 다룰 때 필요에 따라 불러옵니다.

모노레포에서 루트 규칙은 전체 공통 원칙만 담고, 프론트엔드·백엔드처럼 영역이 다른 규칙은 해당 디렉터리 또는 경로별 rules로 좁히는 편이 좋습니다. 여러 위치에 같은 주제의 상반된 지침을 쓰면 어느 규칙을 따라야 할지 불명확해집니다.

1단계: /init으로 초안 만들기

cd your-project
claude
/init

/init은 저장소의 빌드 도구, 테스트 프레임워크와 코드 패턴을 분석해 시작용 CLAUDE.md를 제안합니다. 기존 파일이 있다면 덮어쓰기보다 개선점을 제시하도록 설계돼 있습니다. 자동 생성 결과는 출발점일 뿐이므로 package scripts, CI 설정과 실제 팀 규칙을 사람이 대조해야 합니다.

2단계: 프로젝트 사실부터 적기

좋은 규칙은 취향보다 Claude가 저장소에서 바로 확인하기 어려운 사실을 우선합니다.

• 서비스 목적과 변경 시 지켜야 할 경계
• 주요 앱·패키지·공유 라이브러리의 위치
• 패키지 관리자와 지원 런타임 버전
• 개발, lint, 타입 검사, 단위·통합 테스트 명령
• 데이터베이스 마이그레이션과 생성 파일 처리 방식
• 변경 완료 전에 확인할 최소 검증 항목

README를 그대로 복사하지 말고 Claude의 구현 선택에 영향을 주는 내용만 남기세요. 이미 코드만 읽어도 자명한 설명은 지속적인 문맥 비용만 늘릴 수 있습니다.

3단계: 검증 가능한 문장으로 바꾸기

“항상”, “절대” 같은 표현을 늘리는 것보다 대상 경로, 조건, 명령과 완료 기준을 명시하는 편이 효과적입니다. 예외가 있다면 예외 조건과 승인 주체까지 적으세요.

바로 수정해서 쓰는 CLAUDE.md 예시

# Project overview

이 저장소는 pnpm workspace 기반 TypeScript 모노레포다.
- apps/web: Next.js 사용자 화면
- apps/api: API 서버
- packages/ui: 공유 UI 컴포넌트

## Commands

- 의존성 설치: `pnpm install`
- 전체 lint: `pnpm lint`
- 전체 타입 검사: `pnpm typecheck`
- 변경 패키지 테스트: `pnpm --filter <package> test`
- 프로덕션 빌드: `pnpm build`

## Code rules

- 기존 공개 API를 변경하기 전에 영향받는 호출부를 찾는다.
- 새 TypeScript 코드에 `any`를 추가하지 않는다.
- UI는 packages/ui의 기존 컴포넌트를 우선 사용한다.
- 생성 파일은 직접 수정하지 말고 생성 명령을 실행한다.

## Safety

- 비밀값, .env 내용과 고객 데이터를 출력하거나 커밋하지 않는다.
- 배포, 데이터 삭제와 마이그레이션은 사용자 승인 없이 실행하지 않는다.
- 요청 범위 밖 파일은 수정하지 않는다.

## Done

- 변경한 기능의 정상·오류 경로를 확인한다.
- 관련 lint, 타입 검사와 테스트 결과를 보고한다.
- 실행하지 못한 검증은 이유와 함께 명시한다.

명령은 예시이므로 자신의 package.json, Makefile과 CI에서 실제 작동하는 값으로 교체해야 합니다. 존재하지 않는 명령을 넣으면 자동화보다 재작업이 늘어납니다.

무엇을 CLAUDE.md에 넣지 말아야 하나

• API 키, 비밀번호, 개인 식별 정보와 실제 고객 데이터
• 한 번만 수행할 작업의 긴 프롬프트
• 이미 끝난 마이그레이션이나 폐기된 명령
• 코드와 맞지 않는 이상적인 아키텍처 설명
• 동일한 의미를 반복하는 여러 문장
• 검증할 수 없는 “최고 품질”, “완벽하게” 같은 표현
• 권한 설정 대신 사용하는 금지 요청 문구

CLAUDE.md와 다른 기능 구분하기

긴 규칙은 .claude/rules로 분리하기

.claude/
├── CLAUDE.md
└── rules/
    ├── testing.md
    ├── security.md
    └── frontend/
        └── react.md

.claude/rules/ 아래 Markdown 파일은 주제별로 규칙을 나누는 데 적합합니다. 경로 조건이 없는 rules는 공통 지침처럼 불러오므로 파일을 나눴다는 이유만으로 문맥이 줄어드는 것은 아닙니다. 특정 영역에만 필요한 규칙은 paths frontmatter를 사용합니다.

경로별 규칙 설정 예시

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

# API rules

- 모든 외부 입력을 handler 경계에서 검증한다.
- 표준 오류 응답 형식을 사용한다.
- 인증이 필요한 endpoint에는 권한 테스트를 추가한다.

경로별 규칙은 Claude가 일치하는 파일을 읽을 때 적용됩니다. src/**/*.{ts,tsx}처럼 여러 확장자를 지정할 수 있지만 지나치게 넓은 glob은 다시 모든 작업의 문맥이 될 수 있습니다.

@ import로 기존 문서 재사용하기

See @README.md for the project overview.

# Development workflow
- Git workflow: @docs/git-workflow.md
- Available scripts: @package.json

상대 경로는 import를 선언한 파일을 기준으로 해석됩니다. 공식 문서 기준으로 import는 재귀적으로 사용할 수 있지만 깊이 제한이 있으며, 외부 파일을 처음 불러올 때 승인을 요구할 수 있습니다. 큰 문서를 import하면 내용이 함께 문맥에 들어오므로 링크를 나눈다고 토큰 사용량이 자동으로 줄지는 않습니다.

문서 전체가 항상 필요하지 않다면 핵심 규칙만 CLAUDE.md에 적고 자세한 절차는 Skill로 전환하는 편이 낫습니다.

기존 AGENTS.md를 함께 사용하는 방법

Anthropic 공식 문서는 Claude Code가 기본적으로 CLAUDE.md를 읽으며, 기존 AGENTS.md를 재사용하려면 import할 수 있다고 설명합니다.

@AGENTS.md

## Claude Code only

- 결제 영역 변경은 구현 전에 영향 범위를 먼저 요약한다.

공통 규칙은 한 파일에서 관리하고 도구별 차이만 아래에 추가하면 중복과 충돌을 줄일 수 있습니다. 다른 코딩 에이전트의 구조가 궁금하다면 Codex AGENTS.md 작성법과 비교해보세요.

개인 규칙은 CLAUDE.local.md로 분리하기

# .gitignore
CLAUDE.local.md

개발 서버 주소, 개인 테스트 선호처럼 팀에 공유할 필요가 없는 지침은 프로젝트 루트의 CLAUDE.local.md에 둡니다. 여러 Git worktree에서는 gitignore된 파일이 각 worktree에 자동 복제되지 않을 수 있으므로 필요한 범위를 확인하세요.

로드 여부를 /memory에서 확인하기

/memory

/memory는 현재 세션에 불러온 CLAUDE.md, CLAUDE.local.md와 rules 파일을 확인하는 출발점입니다. 파일을 수정한 뒤 새 세션에서 다시 열고, 예상 위치의 파일이 목록에 있는지 봅니다.

CLAUDE.md가 있는데도 따르지 않는다면 먼저 로드 여부, 정확한 경로, 상위·하위 파일의 충돌, 문장의 구체성과 실제 명령 유효성을 차례로 확인하세요.

규칙이 실제로 작동하는지 테스트하기

1. 새 Claude Code 세션을 프로젝트 루트에서 시작합니다.
2. /memory로 지침 파일과 적용 범위를 확인합니다.
3. “이 프로젝트의 lint와 테스트 명령을 알려줘”처럼 읽기 전용 질문을 합니다.
4. 작은 테스트 파일 변경을 요청하고 디렉터리·스타일 규칙 준수를 봅니다.
5. 검증 명령을 실행하게 하고 결과 보고 형식을 확인합니다.
6. 의도적으로 범위 밖 작업을 제안해 안전 규칙이 작동하는지 확인합니다.
7. 실패한 규칙은 문장을 구체화하고 중복·충돌 항목을 제거합니다.

CLAUDE.md가 무시되는 것처럼 보일 때

• 세션을 저장소 루트 또는 올바른 하위 경로에서 시작했는지 확인합니다.
• 파일명이 정확히 CLAUDE.md인지 대소문자를 점검합니다.
• /memory 목록에 예상 파일이 표시되는지 봅니다.
• 사용자·프로젝트·로컬·중첩 규칙에서 같은 주제의 충돌을 찾습니다.
• “잘”, “적절히” 같은 표현을 명령·경로·조건으로 바꿉니다.
• 필수 자동 검사는 지침이 아니라 Hook으로 옮깁니다.

CLAUDE.md가 너무 길 때

공식 문서는 짧은 파일이 지침 준수에 유리하며, 매우 긴 파일은 문맥을 소비하고 준수율을 낮출 수 있다고 안내합니다. 오래된 설명, 코드로 자명한 정보와 중복 문장을 먼저 삭제하세요. 특정 경로 규칙은 paths가 있는 rules로, 특정 작업의 긴 절차는 Skills로 옮깁니다.

@ import는 유지보수 구조를 개선하지만 가져온 내용이 세션에 포함되므로 단순 분리만으로 문맥을 절약하지는 않습니다. 실제로 항상 필요한 정보인지가 판단 기준입니다.

컴팩션 이후에도 유지되나

프로젝트 루트의 CLAUDE.md는 대화 컴팩션 뒤 다시 주입될 수 있지만, 하위 디렉터리의 중첩 규칙은 Claude가 해당 경로를 다시 읽을 때 재로드됩니다. 중요한 전역 규칙을 대화에서만 말하거나 깊은 하위 파일에만 두지 마세요.

팀 운영 체크리스트

• CLAUDE.md 변경도 일반 코드처럼 리뷰하는가
• 명령이 CI와 현재 package scripts에서 실제 작동하는가
• 루트·사용자·하위 규칙 사이에 충돌이 없는가
• 개인 환경과 비밀정보가 커밋되지 않는가
• 필수 제약이 permissions와 Hooks로 집행되는가
• 경로별 규칙의 glob이 필요한 범위로 제한됐는가
• 분기 또는 주요 구조 변경 때 오래된 항목을 정리하는가

CLAUDE.md 개선 전후를 평가하는 방법

“Claude가 더 똑똑해졌다”는 인상 대신 재작업 횟수, 잘못 선택한 명령, 범위 밖 수정, 테스트 누락과 사람이 다시 설명한 규칙을 기록하세요. 같은 유형의 작은 작업을 기준으로 변경 전후를 비교하면 어떤 문장이 실제로 도움이 됐는지 판단하기 쉽습니다.

저장소와 작업 성격이 다르므로 특정 길이, 규칙 수나 생산성 향상률을 보편적인 정답으로 제시하기는 어렵습니다. 팀의 실패 기록을 바탕으로 짧게 고치는 과정이 중요합니다.

규칙별 효과 기록표

CLAUDE.md를 한꺼번에 길게 만들지 말고 반복 실패 한 가지를 고친 뒤 행동 변화를 기록하세요.

행동이 바뀌지 않으면 파일 로드 여부와 충돌을 확인하고, 이미 잘 지켜지는 장황한 규칙은 삭제해 문맥을 줄입니다.

편집부 결론

Claude Code CLAUDE.md의 핵심은 많은 규칙을 넣는 것이 아니라 프로젝트에서 반복되는 중요한 판단을 짧고 검증 가능한 형태로 유지하는 것입니다. 루트 파일에는 공통 구조와 명령, 안전 기준을 두고 경로별 규칙은 .claude/rules/, 반복 절차는 Skills, 강제 검사는 Hooks로 분리하세요. 마지막으로 /memory와 대표 작업으로 실제 로드와 준수 여부를 확인해야 합니다.

이 글은 2026년 9월 6일 Anthropic 공식 문서를 분석해 작성했으며 특정 개발팀에서 CLAUDE.md 도입 효과를 장기간 측정한 후기는 아닙니다. 파일 로딩과 기능은 업데이트될 수 있으므로 적용 전 현재 Claude Code 버전과 공식 문서를 확인하세요.

공식 문서와 함께 읽을 글

Claude Code CLAUDE.md 공식 문서 보기

Claude Code 프로젝트 설정 모범 사례 확인하기

Claude Code 설정 범위 공식 문서 보기

CLAUDE.md 규칙으로 Agent Teams 협업 기준 통일하기

긴 반복 절차를 Claude Code Skills로 분리하기

필수 검사를 Claude Code Hooks로 자동화하기

팀 규칙과 자동화를 Claude Code Plugin으로 배포하기

Codex AGENTS.md 프로젝트 규칙과 비교하기

자주 묻는 질문

Claude Code CLAUDE.md는 어디에 만들어야 하나요?

팀 프로젝트 규칙은 저장소 루트의 CLAUDE.md 또는 .claude/CLAUDE.md에 만듭니다. 모든 프로젝트에 적용할 개인 지침은 ~/.claude/CLAUDE.md를 사용합니다.

CLAUDE.md를 자동으로 만들 수 있나요?

Claude Code에서 /init을 실행하면 저장소를 분석해 초안을 제안합니다. 생성 결과의 명령, 구조와 규칙이 실제 프로젝트와 일치하는지는 사람이 검토해야 합니다.

CLAUDE.md가 로드됐는지 어떻게 확인하나요?

/memory 명령에서 현재 세션에 불러온 CLAUDE.md, 로컬 지침과 rules 파일을 확인할 수 있습니다.

CLAUDE.md와 CLAUDE.local.md의 차이는 무엇인가요?

CLAUDE.md는 Git으로 공유할 팀 규칙이고 CLAUDE.local.md는 현재 사용자의 프로젝트별 선호를 위한 파일입니다. 로컬 파일은 Git에서 제외하고 두 파일 모두 비밀 저장소로 사용하지 마세요.

CLAUDE.md에서 다른 문서를 가져올 수 있나요?

@README.md 또는 @docs/workflow.md 형식으로 import할 수 있습니다. 가져온 내용도 문맥을 사용하므로 항상 필요한 문서만 연결해야 합니다.

프론트엔드와 백엔드 규칙을 다르게 적용하려면 어떻게 하나요?

.claude/rules/에 주제별 파일을 만들고 paths frontmatter로 대상 디렉터리와 확장자를 제한할 수 있습니다.

CLAUDE.md에 금지 명령을 쓰면 실행이 완전히 차단되나요?

아닙니다. CLAUDE.md는 행동 지침이지 강제 보안 경계가 아닙니다. 반드시 차단할 도구와 명령은 permissions와 관리 설정을 사용해야 합니다.

CLAUDE.md와 AGENTS.md를 함께 사용할 수 있나요?

CLAUDE.md에서 @AGENTS.md를 import하고 Claude Code 전용 규칙만 추가하면 공통 지침의 중복을 줄일 수 있습니다.