Claude Code CLAUDE.md 설정 베스트 프랙티스: 프로젝트별 AI 코딩 워크플로우 구축 가이드
Claude Code CLAUDE.md란 무엇인가?
CLAUDE.md는 Claude Code가 프로젝트 컨텍스트에서 자동으로 읽어들이는 설정 파일입니다. 이 파일을 통해 코딩 컨벤션, 금지 패턴, 워크플로우 규칙을 정의하면, AI 어시스턴트가 매번 같은 지시를 반복하지 않아도 일관된 코드를 생성합니다. 프로젝트 루트, 사용자 홈 디렉토리, 또는 하위 폴더에 배치할 수 있어 계층적 설정 관리가 가능합니다.
CLAUDE.md 파일 구조와 배치 전략
1단계: 글로벌 설정 파일 생성
모든 프로젝트에 공통 적용할 규칙은 사용자 홈 디렉토리에 배치합니다.
# 글로벌 CLAUDE.md 생성 (모든 프로젝트 적용)
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << ‘EOF’
글로벌 코딩 규칙
언어 설정
- 코드 주석: 영어
- 커밋 메시지: Conventional Commits 형식
- 응답 언어: 한국어
공통 금지 패턴
- console.log 디버깅 코드 커밋 금지
- any 타입 사용 금지 (TypeScript)
하드코딩된 시크릿 금지 EOF
2단계: 프로젝트별 설정 파일 생성
각 프로젝트 루트에 해당 프로젝트만의 규칙을 정의합니다.
# 프로젝트 루트에 CLAUDE.md 생성
cat > ./CLAUDE.md << 'EOF'
# 프로젝트: my-saas-app
기술 스택
- Frontend: Next.js 14 (App Router)
- Backend: FastAPI + SQLAlchemy
- DB: PostgreSQL 16
- 패키지 매니저: pnpm
코딩 컨벤션
- React 컴포넌트: 함수형 + Arrow Function
- 상태 관리: Zustand (Redux 사용 금지)
- CSS: Tailwind CSS만 사용 (styled-components 금지)
- API 호출: fetch 대신 반드시 @tanstack/react-query 사용
파일 구조 규칙
- 컴포넌트: src/components/{도메인}/{ComponentName}.tsx
- 훅: src/hooks/use{Name}.ts
- API 라우트: src/app/api/{resource}/route.ts
테스트 규칙
- 단위 테스트: Vitest
- E2E: Playwright
- 테스트 파일 위치: tests/ 폴더 (*.test.ts)
- DB 테스트는 실제 DB 연결 사용 (mock 금지)
Git 규칙
- 브랜치: feature/{ticket-id}-{설명}
PR 생성 전 반드시 lint + test 통과 확인 EOF
3단계: 하위 디렉토리별 오버라이드
특정 폴더에 추가 규칙이 필요하면 해당 경로에 CLAUDE.md를 배치합니다.
# 백엔드 전용 규칙
cat > ./backend/CLAUDE.md << 'EOF'
## Python 컨벤션
- 포매터: Black (line-length=88)
- 타입 힌트 필수
- Pydantic v2 모델 사용
- SQLAlchemy 2.0 스타일 쿼리만 사용
- raw SQL 쿼리 금지
EOF
## 금지 패턴 정의 베스트 프랙티스
단순히 "하지 마세요"가 아닌, 이유와 대안을 함께 명시하면 Claude가 더 정확하게 규칙을 따릅니다.
## 금지 패턴 (이유 + 대안 포함)
❌ 금지: moment.js 사용
- 이유: 번들 크기 과다, 유지보수 중단
- 대안: date-fns 또는 dayjs 사용
❌ 금지: enum 키워드 (TypeScript)
- 이유: 트리 쉐이킹 불가, 런타임 오버헤드
- 대안: as const + 유니온 타입 사용
❌ 금지: useEffect 내 데이터 페칭
- 이유: 경쟁 조건, 로딩/에러 상태 수동 관리 필요
- 대안: @tanstack/react-query의 useQuery 사용
❌ 금지: index.ts 배럴 파일
- 이유: 순환 의존성 유발, 빌드 속도 저하
대안: 직접 임포트 경로 사용
자동 메모리 시스템 활용법
Claude Code의 자동 메모리는 대화 간 컨텍스트를 유지합니다. CLAUDE.md와 함께 사용하면 프로젝트 지식이 축적됩니다.
메모리 저장 트리거
| 메모리 타입 | 저장 시점 | 예시 |
|---|---|---|
| user | 사용자 역할/선호도 파악 시 | "백엔드 시니어 개발자, Python 전문" |
| feedback | 사용자가 수정 요청 시 | "테스트에서 DB mock 사용하지 말 것" |
| project | 프로젝트 맥락 파악 시 | "3/20까지 머지 프리즈, 모바일 릴리즈" |
| reference | 외부 리소스 언급 시 | "버그 트래킹은 Linear BACKEND 프로젝트" |
# CLAUDE.md에 넣을 것 (정적, 팀 공유)
- 코딩 컨벤션, 기술 스택, 파일 구조
- 금지 패턴과 대안
- 빌드/테스트 명령어
메모리에 저장할 것 (동적, 개인용)
- 사용자 선호도와 피드백
- 진행 중인 이슈 컨텍스트
외부 시스템 참조 정보
실전 워크플로우 예시
CLAUDE.md가 올바르게 설정된 프로젝트에서의 워크플로우입니다.
# 1. 새 기능 개발 시작
$ claude
> 사용자 프로필 편집 API를 만들어줘
Claude가 CLAUDE.md를 읽고 자동으로:
- FastAPI + SQLAlchemy 2.0 스타일로 작성
- Pydantic v2 모델 사용
- src/app/api/users/route.ts 경로에 생성
- Vitest 테스트 파일 함께 생성
- Conventional Commits 형식 커밋 메시지 제안
Pro Tips
- 조건부 규칙 활용: “PR 리뷰 모드일 때는 보안 취약점과 성능 이슈만 집중 검토” 같은 상황별 지시를 추가하세요.- 명령어 단축키 등록: 자주 쓰는 빌드/테스트 명령어를 CLAUDE.md에 명시하면 Claude가 정확한 명령어를 사용합니다.- 팀 공유는 프로젝트 CLAUDE.md, 개인 설정은 ~/.claude/CLAUDE.md: Git에 커밋되는 프로젝트 파일과 개인 파일을 분리해 관리하세요.- 규칙 우선순위 이해: 하위 디렉토리 CLAUDE.md가 상위를 오버라이드합니다. 충돌 시 가장 가까운 파일이 우선합니다.- 메모리에 “기억해” 명령 활용:
이 프로젝트에서는 항상 pnpm을 사용해. 기억해.라고 하면 자동 메모리에 저장됩니다.
Troubleshooting
CLAUDE.md가 인식되지 않는 경우
- 파일 이름이 정확히
CLAUDE.md인지 확인 (대소문자 구분)- 파일이 작업 디렉토리 또는 상위 경로에 있는지 확인-.gitignore에 CLAUDE.md가 포함되어 있어도 Claude Code는 읽을 수 있지만, 팀 공유가 안 됩니다
규칙이 무시되는 경우
- 규칙이 너무 모호하면 무시될 수 있습니다. “깔끔하게 작성” 대신 “함수당 최대 20줄” 같은 구체적 기준을 사용하세요- 상충되는 규칙이 있는지 확인하세요. 글로벌과 프로젝트 설정이 충돌하면 예측 불가한 동작이 발생할 수 있습니다
메모리가 저장되지 않는 경우
- “기억해” 또는 “remember this” 같은 명시적 표현을 사용하세요- 메모리 디렉토리 (
~/.claude/projects/)의 쓰기 권한을 확인하세요
자주 묻는 질문 (FAQ)
Q1: CLAUDE.md 파일 크기에 제한이 있나요?
공식적인 파일 크기 제한은 없지만, 컨텍스트 윈도우를 효율적으로 사용하기 위해 핵심 규칙 위주로 간결하게 유지하는 것이 좋습니다. 일반적으로 200줄 이내를 권장하며, 상세한 문서는 별도 파일로 분리하고 CLAUDE.md에서 참조하는 방식이 효과적입니다. 불필요하게 긴 설정은 오히려 중요한 규칙의 우선순위를 낮출 수 있습니다.
Q2: CLAUDE.md와 .cursorrules 같은 다른 AI 설정 파일을 동시에 사용할 수 있나요?
CLAUDE.md는 Claude Code 전용 설정 파일로, 다른 AI 코딩 도구의 설정 파일과 독립적으로 동작합니다. 같은 프로젝트에 .cursorrules, .github/copilot-instructions.md 등이 있어도 충돌하지 않습니다. 다만, 팀에서 여러 AI 도구를 사용한다면 각 설정 파일의 규칙을 일관되게 유지하는 것이 코드 품질 관리에 유리합니다.
Q3: 자동 메모리와 CLAUDE.md 중 어떤 것이 우선순위가 높나요?
CLAUDE.md는 프로젝트 시작 시 항상 로드되는 정적 규칙이고, 자동 메모리는 대화를 통해 축적되는 동적 컨텍스트입니다. 두 가지가 충돌할 경우 CLAUDE.md의 명시적 규칙이 우선합니다. 따라서 팀 전체가 따라야 할 핵심 컨벤션은 반드시 CLAUDE.md에 명시하고, 개인 선호도나 임시 프로젝트 상태는 메모리에 저장하는 것이 올바른 사용 방법입니다.