Claude Code CLAUDE.md 작성법 — 프로젝트 맞춤 설정 가이드

CLAUDE.md 파일이 필요한 이유

Claude Code를 처음 써보면 매번 같은 설명을 반복하게 되는 경우가 있습니다. "이 프로젝트는 Python으로 되어 있고, 테스트는 pytest를 쓰고, 코딩 스타일은 이렇게 해줘"처럼 대화할 때마다 같은 맥락을 전달해야 하는 상황이 반복됩니다. CLAUDE.md는 이런 반복을 없애주는 프로젝트 설정 파일입니다.

프로젝트 루트 폴더에 CLAUDE.md 파일을 하나 만들어두면, Claude Code가 대화를 시작할 때 이 파일을 자동으로 읽습니다. 매번 같은 맥락을 설명할 필요 없이, 파일에 적어둔 규칙과 배경 정보를 Claude Code가 알아서 참고하는 구조입니다. 쉽게 말해 CLAUDE.md는 Claude Code에게 건네는 프로젝트 매뉴얼이라고 생각하면 됩니다. 사람이 새 팀에 합류할 때 온보딩 문서를 읽는 것처럼, Claude Code도 CLAUDE.md를 읽고 프로젝트 상황을 파악합니다.

CLAUDE.md가 없을 때와 있을 때의 차이는 상당합니다. CLAUDE.md가 없으면 Claude Code는 매번 코드를 처음 보는 사람처럼 행동합니다. "이 프로젝트는 뭘 하는 건가요?"부터 시작해야 하고, 코딩 스타일도 일관성 없이 제각각으로 나옵니다. 반면 CLAUDE.md가 있으면 프로젝트의 기술 스택, 코딩 규칙, 디렉토리 구조를 이미 파악한 상태에서 대화가 시작됩니다. 같은 질문을 해도 응답의 품질이 확연히 달라집니다.

특히 프로젝트마다 사용하는 언어, 프레임워크, 코딩 컨벤션이 다를 때 CLAUDE.md의 가치가 극대화됩니다. Python 프로젝트에서 snake_case를 쓰는데 Claude Code가 camelCase로 코드를 작성하면 일일이 수정해야 합니다. CLAUDE.md에 규칙을 명시해두면 이런 수정 작업이 사라집니다.

 

 

CLAUDE.md 파일을 만드는 구체적인 방법

CLAUDE.md를 만드는 방법은 아주 간단합니다. 두 가지 방법이 있습니다.

방법 1: /init 명령어로 자동 생성

가장 쉬운 방법은 Claude Code 대화 중에 /init 명령어를 입력하는 것입니다. Claude Code가 프로젝트 폴더를 분석하고, 기본적인 CLAUDE.md 파일을 자동으로 생성해 줍니다.

# 프로젝트 폴더에서 Claude Code 실행
cd 프로젝트경로
claude

# 대화 모드에서 /init 실행
/init

이 방법의 장점은 Claude Code가 프로젝트의 파일 구조, 사용하는 언어, 패키지 정보를 자동으로 분석해서 초안을 만들어 준다는 것입니다. 다만 자동 생성된 내용이 완벽하지 않을 수 있으므로, 생성 후에 직접 확인하고 보완하는 것이 좋습니다.

방법 2: 직접 파일 생성

프로젝트 최상위 폴더에 CLAUDE.md라는 이름으로 마크다운 파일을 직접 생성하는 방법입니다. VS Code를 쓰고 있다면 탐색기 패널에서 우클릭 후 새 파일을 만들면 됩니다. 터미널에서도 간단히 생성할 수 있습니다.

# 빈 CLAUDE.md 파일 생성
touch CLAUDE.md

# 또는 VS Code로 바로 열기
code CLAUDE.md

 

 

파일 이름은 반드시 대문자 CLAUDE.md로 해야 합니다. claude.md나 Claude.md처럼 소문자가 섞이면 Claude Code가 인식하지 못할 수 있습니다. 또한 파일 위치도 중요합니다. 프로젝트 루트 디렉토리에 놓아야 자동으로 로드됩니다. 하위 폴더에 넣으면 해당 폴더에서 작업할 때만 적용되니, 프로젝트 전체에 적용하고 싶다면 최상위에 두는 것이 맞습니다.

 

CLAUDE.md에 작성해야 할 실전 항목과 예시

CLAUDE.md에는 Claude Code가 프로젝트를 이해하는 데 필요한 핵심 정보를 적습니다. 필수 항목 4가지와 선택 항목 3가지를 나눠서 설명하겠습니다.

필수 항목 4가지:

# 프로젝트 개요
이 프로젝트는 FastAPI 기반의 REST API 서버입니다.
Python 3.11을 사용하고, 패키지 관리는 pip을 씁니다.
데이터베이스는 PostgreSQL, ORM은 SQLAlchemy를 사용합니다.

# 코딩 규칙
- 함수와 변수 이름은 snake_case를 사용합니다.
- 타입 힌트를 항상 작성합니다.
- 한 함수는 30줄을 넘지 않도록 합니다.
- docstring은 Google 스타일을 따릅니다.
- 상수는 UPPER_SNAKE_CASE로 작성합니다.

# 테스트
- pytest로 테스트를 실행합니다.
- 테스트 파일은 tests/ 폴더에 위치합니다.
- 테스트 함수 이름은 test_로 시작합니다.
- 테스트 커버리지 80% 이상을 유지합니다.

# 자주 쓰는 명령어
- 서버 실행: uvicorn main:app --reload
- 테스트 실행: pytest -v
- 린트 검사: ruff check .
- 마이그레이션: alembic upgrade head

 

 

선택 항목 3가지:

# 디렉토리 구조
- src/ : 메인 소스 코드
- tests/ : 테스트 코드
- docs/ : 문서
- migrations/ : 데이터베이스 마이그레이션

# 금지 사항
- print()를 디버깅용으로 남기지 마세요. logging 모듈을 사용하세요.
- SQL 쿼리를 직접 작성하지 마세요. ORM을 사용하세요.
- .env 파일의 내용을 코드에 하드코딩하지 마세요.

# 참고 사항
- API 응답은 항상 JSON 형식이어야 합니다.
- 에러 처리는 HTTPException을 사용합니다.
- 환경 변수는 pydantic-settings로 관리합니다.

이렇게 작성해두면 Claude Code에게 "테스트 코드 작성해줘"라고만 말해도 pytest 스타일로 tests 폴더에 파일을 만들어 줍니다. 프로젝트 개요, 코딩 규칙, 테스트 방법, 자주 쓰는 명령어 이 네 가지가 가장 기본적인 항목입니다. 너무 길게 작성하면 오히려 핵심이 묻힐 수 있으니, 처음에는 필수 항목 4가지만 간결하게 채우는 것을 추천합니다. 나중에 필요한 항목을 하나씩 추가하면 됩니다.

 

CLAUDE.md를 효과적으로 관리하고 활용하는 팁

CLAUDE.md를 만들었다고 끝이 아닙니다. 잘 관리해야 효과를 제대로 발휘합니다. 실전에서 도움이 되는 팁 5가지를 정리했습니다.

첫째, 프로젝트가 변할 때마다 함께 업데이트합니다. 라이브러리를 바꾸거나 폴더 구조를 변경했다면 CLAUDE.md에도 반영해야 Claude Code가 최신 상태를 정확히 파악합니다. 오래된 정보가 남아 있으면 오히려 잘못된 답변을 유도할 수 있습니다.

둘째, 금지 사항을 명시하면 실수를 줄일 수 있습니다. "console.log를 프로덕션 코드에 남기지 마세요"처럼 하지 말아야 할 것을 적어두면, Claude Code가 코드를 작성할 때 이를 지켜 줍니다. 금지 사항은 프로젝트에서 반복적으로 실수가 발생하는 부분을 중심으로 추가하면 효과적입니다.

셋째, 하위 폴더에 별도의 CLAUDE.md를 둘 수 있습니다. 프론트엔드와 백엔드가 한 저장소에 있다면, frontend/CLAUDE.md와 backend/CLAUDE.md를 각각 만들어서 폴더별 규칙을 분리할 수 있습니다. Claude Code는 현재 작업 중인 폴더의 CLAUDE.md를 우선 적용하고, 상위 폴더의 CLAUDE.md도 함께 참고합니다. 이 계층 구조 덕분에 공통 규칙은 루트에, 세부 규칙은 하위 폴더에 분리할 수 있습니다.

 

 

넷째, CLAUDE.md는 Git으로 버전 관리하는 것을 권장합니다. 팀원이 함께 쓰는 프로젝트라면 CLAUDE.md를 커밋해두면 모두가 같은 설정을 공유할 수 있어서 일관된 결과를 얻을 수 있습니다. 코드 리뷰 과정에서 CLAUDE.md 변경 사항도 함께 검토하면 팀 전체의 AI 활용 품질이 올라갑니다.

다섯째, 분량은 200줄 이내로 유지하는 것이 좋습니다. CLAUDE.md가 너무 길면 Claude Code가 모든 내용을 처리하는 데 토큰(token)을 많이 소모합니다. 핵심 규칙 위주로 간결하게 작성하고, 자세한 문서는 별도 파일에 두는 것이 효율적입니다. "이 파일을 참고해줘"라는 식으로 경로만 적어두면, 필요할 때 Claude Code가 해당 파일을 읽어서 참고합니다.

제가 여러 프로젝트에서 CLAUDE.md를 써본 결과, 가장 큰 체감 효과는 코딩 스타일 일관성입니다. CLAUDE.md 없이는 같은 프로젝트 안에서도 함수 이름 규칙이 들쭉날쭉해지는데, CLAUDE.md에 규칙을 명시하면 매번 동일한 스타일의 코드를 생성해 줍니다. 5분이면 만들 수 있고, 그 5분이 이후 수십 시간의 수정 작업을 줄여줍니다.