CLAUDE.md, 이게 뭐고 왜 중요한가요?
Claude Code를 쓰다 보면 “매번 프로젝트 설명을 반복해야 하나?” 싶은 순간이 오는데, 그 해답이 CLAUDE.md 파일이에요. CLAUDE.md는 프로젝트 루트 디렉토리에 놓는 특수한 마크다운 파일로, Claude Code가 실행될 때 자동으로 읽어서 컨텍스트를 파악하는 데 활용해요. 마치 새 팀원에게 주는 온보딩 가이드처럼, Claude에게 “이 프로젝트는 이런 거야”를 한 번만 설명해두면 그 이후로는 매번 설명할 필요가 없어요.
이 글에서는 CLAUDE.md를 효과적으로 작성하는 방법을 실전 예시와 함께 정리할게요. 어떤 내용을 넣어야 하는지, 어떻게 구조화해야 하는지, 그리고 CLAUDE.md를 통해 어떤 생산성 향상을 기대할 수 있는지 알아볼게요.
CLAUDE.md에 꼭 들어가야 할 핵심 내용
프로젝트 개요와 목적
CLAUDE.md의 첫 섹션에는 이 프로젝트가 무엇인지, 어떤 문제를 해결하려는지를 간결하게 설명해요. 기술적인 세부 사항보다 “이 서비스는 무엇이고, 누구를 위한 것인지”를 명확히 해두면 Claude가 모든 작업에서 프로젝트의 목적을 고려하며 도움을 줄 수 있어요.
기술 스택 명시
사용하는 언어, 프레임워크, 라이브러리, 데이터베이스, 클라우드 서비스 등을 명확하게 나열해요. 예를 들어 “Backend: Python 3.11 + FastAPI + PostgreSQL 15, Frontend: TypeScript + Next.js 14 + Tailwind CSS, Infra: AWS ECS + RDS + S3″처럼 버전까지 포함해서 작성하면 Claude가 더 정확한 코드를 생성할 수 있어요.
코딩 컨벤션과 스타일 가이드
코딩 컨벤션을 CLAUDE.md에 적어두면 Claude가 생성하는 코드가 기존 코드베이스와 일관된 스타일을 유지해요. 예를 들어 “변수명은 snake_case, 클래스명은 PascalCase, 주석은 한국어로 작성” 같은 규칙을 적어두면 매번 지시하지 않아도 그 스타일을 따라줘요.
프로젝트 유형별 CLAUDE.md 예시
웹 서비스 프로젝트 예시
웹 서비스 프로젝트의 CLAUDE.md는 API 구조, 인증 방식, 데이터베이스 스키마 요약, 핵심 비즈니스 로직 등을 포함해요. 예를 들어 “이 서비스는 다중 테넌트 SaaS 서비스예요. 모든 DB 쿼리는 tenant_id 필터를 반드시 포함해야 해요. 인증은 JWT로 처리하며 access token 유효시간은 1시간이에요”처럼 핵심 아키텍처 결정 사항을 기록해두는 거예요.
데이터 분석 프로젝트 예시
데이터 분석 프로젝트라면 데이터 소스, 데이터 구조, 분석 방법론, 자주 쓰는 쿼리 패턴 등을 담아요. “메인 데이터소스는 PostgreSQL의 analytics 스키마예요. 이벤트 테이블은 daily partition이고, 쿼리할 때 항상 date 범위를 지정해서 풀 스캔을 방지해야 해요”처럼 데이터 관련 주의사항을 명확히 적어두면 Claude가 올바른 쿼리 패턴을 따라요.
모바일 앱 프로젝트 예시
React Native나 Flutter 프로젝트라면 앱 아키텍처(MVVM, Redux 등), 상태 관리 방식, 네비게이션 구조, 플랫폼별 주의사항 등을 담아요. “iOS와 Android를 동시 지원해요. Platform.select()를 통해 플랫폼별 처리를 해야 하는 부분을 명확히 표시해줘요”처럼 크로스 플랫폼 개발의 특수성을 기록해두면 Claude가 양쪽 플랫폼을 고려한 코드를 작성해줘요.
CLAUDE.md 작성 시 잘 쓰는 패턴
금지 사항과 주의사항 섹션 만들기
“절대 하지 말아야 할 것들”을 별도 섹션으로 구분해서 적어두는 게 효과적이에요. 예를 들어 “절대 raw SQL 직접 작성 금지 — ORM 사용 필수”, “npm install 시 –legacy-peer-deps 금지”, “console.log를 프로덕션 코드에 남기지 말 것” 같은 금지 사항들을 명시해두면 Claude가 그 규칙을 지켜가면서 코드를 작성해줘요.
자주 쓰는 명령어 모음
프로젝트에서 자주 실행하는 명령어들을 CLAUDE.md에 정리해두면 Claude가 필요한 명령을 정확하게 실행해요. 예를 들어 “테스트 실행: pytest tests/ -v –cov=src”, “스타일 검사: flake8 . –max-line-length 120”, “마이그레이션: alembic upgrade head” 같은 명령어 레퍼런스가 있으면 Claude가 정확한 명령을 써줘요.
환경 변수 목록과 역할 설명
프로젝트에서 사용하는 환경 변수 목록과 각 역할을 CLAUDE.md에 담아두면, Claude가 환경 변수와 관련된 코드를 작성할 때 정확한 변수명을 사용해요. 실제 값은 절대 CLAUDE.md에 넣지 말고, 변수명과 역할만 적어야 해요.
CLAUDE.md 길이와 구조 가이드
적정 길이
CLAUDE.md는 너무 길면 오히려 역효과예요. Claude가 파일을 읽는 데 토큰을 소비하기 때문에, 핵심만 담은 간결한 CLAUDE.md가 더 효율적이에요. 일반적으로 100~300줄 정도가 적당해요. 더 긴 내용이 필요하다면 `docs/` 폴더에 별도 문서를 만들고 CLAUDE.md에서 참조하는 방식이 좋아요.
계층적 구조 활용
- H2 헤더로 큰 카테고리(프로젝트 개요, 기술 스택, 컨벤션)를 구분해요
- H3 헤더로 세부 항목을 나눠요
- 리스트와 코드 블록을 적절히 활용해서 가독성을 높여요
- 중요한 주의사항은 볼드체나 강조 표시로 눈에 띄게 만들어요
정기적인 업데이트
CLAUDE.md는 프로젝트와 함께 살아있는 문서예요. 아키텍처가 변경되거나, 새 의존성이 추가되거나, 코딩 컨벤션이 바뀌면 CLAUDE.md도 함께 업데이트해야 해요. 오래된 CLAUDE.md는 Claude에게 잘못된 정보를 줄 수 있어서 오히려 방해가 될 수 있어요.
팀 프로젝트에서 CLAUDE.md 활용하기
온보딩 문서로도 활용
잘 작성된 CLAUDE.md는 새 팀원의 온보딩 문서로도 활용할 수 있어요. Claude를 위한 설명이지만, 동시에 새로 합류한 개발자가 프로젝트를 빠르게 파악하는 데도 도움이 돼요. CLAUDE.md를 작성하면서 자연스럽게 프로젝트 문서화도 이루어지는 셈이에요.
팀 공통 컨벤션 유지
팀원 모두가 같은 CLAUDE.md를 공유하면 Claude Code를 쓰는 모든 팀원이 동일한 컨텍스트에서 작업할 수 있어요. 한 팀원이 만든 코드와 다른 팀원이 만든 코드가 일관된 스타일을 유지하는 데 도움이 돼요.
마무리 — CLAUDE.md 추천, 오늘 바로 시작해요
CLAUDE.md는 Claude Code를 사용하는 모든 개발자에게 꼭 필요한 설정이에요. 처음엔 빈 파일에 프로젝트 이름과 기술 스택만 적어서 시작해도 충분해요. 사용하면서 추가가 필요한 정보가 생길 때마다 업데이트해나가면 자연스럽게 풍부한 CLAUDE.md가 완성돼요.
한 번 잘 작성된 CLAUDE.md는 이후 모든 Claude Code 세션에서 매번 설명을 반복하는 수고를 덜어줘요. 지금 바로 내 프로젝트 루트에 CLAUDE.md를 만들고 채워나가 보세요!