2026. 4. 10. 07:51ㆍClaude Code 시작하기
CLAUDE.md 파일이 필요한 이유
Claude Code는 터미널에서 코드를 읽고 수정해 주는 AI 도구입니다. 그런데 처음 실행하면 한 가지 문제가 생깁니다. Claude Code가 이 프로젝트가 무엇인지 전혀 모른다는 점입니다.
어떤 언어를 쓰는지, 폴더 구조가 어떤지, 코딩 규칙이 뭔지 아무 정보가 없습니다. 그래서 매번 대화할 때마다 같은 설명을 반복해야 합니다. "이 프로젝트는 Python이고, 테스트는 pytest로 돌리고, 변수명은 snake_case로 써줘"처럼 말입니다.
CLAUDE.md는 이 문제를 해결하는 파일입니다. 프로젝트 루트에 이 파일을 하나 만들어 두면, Claude Code가 대화를 시작할 때 자동으로 읽습니다. 매번 설명을 반복할 필요가 없어지는 겁니다. 사람으로 치면 프로젝트 온보딩 문서를 건네주는 것과 같습니다.
제가 직접 써보니, CLAUDE.md가 있을 때와 없을 때 응답 품질 차이가 꽤 큽니다. 특히 코드 스타일이나 폴더 규칙을 지켜야 할 때, 이 파일 하나로 잘못된 응답이 크게 줄었습니다.
CLAUDE.md 파일 만드는 방법
만드는 방법은 아주 간단합니다. 프로젝트 최상위 폴더에 CLAUDE.md라는 이름으로 파일을 하나 생성하면 됩니다. 확장자는 .md, 즉 마크다운(Markdown) 형식입니다.
Windows 기준으로 설명하겠습니다. 먼저 프로젝트 폴더를 VS Code나 탐색기에서 엽니다. 최상위 경로에서 새 파일을 만들고, 파일 이름을 정확히 CLAUDE.md로 입력합니다. 대소문자를 반드시 지켜야 합니다. claude.md나 Claude.md가 아니라 전부 대문자인 CLAUDE.md입니다.
터미널에서 만들 수도 있습니다. 프로젝트 폴더로 이동한 뒤 아래 명령어를 실행하면 빈 파일이 생깁니다.
touch CLAUDE.md
또는 Claude Code 안에서 직접 만들 수도 있습니다. Claude Code를 실행한 상태에서 "CLAUDE.md 파일을 만들어줘"라고 요청하면, AI가 프로젝트를 분석해서 초안까지 작성해 줍니다.
제가 처음에는 파일 이름을 소문자로 써서 인식이 안 됐습니다. 반드시 대문자 CLAUDE.md인지 확인하시길 바랍니다. 단순한 실수지만, 의외로 자주 발생하는 문제입니다.
CLAUDE.md에 작성할 핵심 내용
빈 파일을 만들었으면, 이제 안에 무엇을 쓸지가 중요합니다. 복잡하게 생각할 필요 없습니다. Claude Code에게 알려주고 싶은 프로젝트 정보를 마크다운으로 적으면 됩니다.
가장 기본적으로 포함할 항목은 다음과 같습니다.
프로젝트 개요: 이 프로젝트가 무엇인지 한두 줄로 설명합니다. 예를 들어 "이 프로젝트는 Python Flask 기반 할일 관리 웹앱입니다"처럼 쓰면 됩니다.
기술 스택: 사용하는 언어, 프레임워크(framework), 주요 라이브러리를 나열합니다. Claude Code가 코드를 생성할 때 이 정보를 참고합니다.
코딩 규칙: 변수명은 camelCase인지 snake_case인지, 들여쓰기는 탭인지 스페이스인지 적어 둡니다. 이 규칙이 없으면 Claude Code가 제멋대로 스타일을 섞어 씁니다.
폴더 구조: 주요 폴더가 어떤 역할인지 간단히 설명합니다. src/는 소스코드, tests/는 테스트 파일처럼 적으면 충분합니다.
아래는 간단한 예시입니다.
# 프로젝트
Python Flask 기반 할일 관리 웹앱
# 기술 스택
- Python 3.11, Flask, SQLAlchemy
- 프론트엔드: Jinja2 템플릿 + Bootstrap 5
# 코딩 규칙
- 변수명: snake_case
- 함수 docstring 필수
- 커밋 메시지: 한국어로 작성
처음부터 완벽하게 쓸 필요는 없습니다. 제가 직접 운영해 본 경험으로는, 처음에 5줄 정도만 적어 두고 Claude Code를 쓰면서 점점 내용을 추가하는 방식이 가장 현실적이었습니다. 한 번에 다 쓰려고 하면 오히려 시작이 늦어집니다.
CLAUDE.md 작성 시 주의할 점
CLAUDE.md는 Claude Code가 매 대화 시작 시 자동으로 읽는 파일입니다. 따라서 너무 길면 컨텍스트 윈도우(context window)를 불필요하게 소모합니다. 컨텍스트 윈도우란 AI가 한 번에 처리할 수 있는 텍스트 용량을 뜻합니다.
권장하는 분량은 A4 한 장 이내, 대략 50줄 미만입니다. 핵심 정보만 간결하게 담는 것이 좋습니다. 프로젝트의 모든 것을 적으려 하지 마십시오. Claude Code가 알아야 할 "규칙"과 "맥락"만 적으면 충분합니다.
또한 CLAUDE.md는 Git에 함께 커밋하는 것을 권장합니다. 팀 프로젝트라면 팀원 모두가 같은 CLAUDE.md를 공유할 수 있습니다. 개인적인 설정은 홈 디렉토리의 ~/.claude/CLAUDE.md에 별도로 작성할 수 있습니다. 프로젝트용과 개인용을 분리하는 구조입니다.
한 가지 더 주의할 점이 있습니다. CLAUDE.md에 비밀번호, API 키 같은 민감한 정보는 절대 쓰지 마십시오. 이 파일은 Git에 올라갈 수 있고, Claude Code가 매번 읽기 때문에 보안상 위험합니다.
제가 초기에 겪은 실수 중 하나는 CLAUDE.md를 너무 상세하게 작성한 것이었습니다. 100줄이 넘어가니 오히려 Claude Code의 응답 속도가 느려지고, 정작 중요한 규칙을 놓치는 경우가 생겼습니다. 짧고 명확하게 쓰는 것이 훨씬 효과적입니다.