CLAUDE.md가 무엇인지는 알겠는데 "그래서 첫 파일을 어떻게 만들지?"가 막막할 수 있습니다. 사실 아주 간단합니다. 완벽하게 채울 필요 없이 한 줄부터 시작하면 됩니다. 이 글은 Claude Code에서 첫 CLAUDE.md를 실제로 만드는 과정을 초보자 눈높이로 안내합니다. (CLAUDE.md가 무엇인지부터 알고 싶다면 CLAUDE.md가 뭔가요?를 먼저 보세요.)
두 가지 시작 방법
첫 CLAUDE.md는 두 가지 방법으로 만들 수 있습니다. 처음이라면 방법 A(/init)를 권합니다.
방법 A — /init 명령 (가장 빠름·추천)
공식 문서가 권하는 가장 빠른 방법은 /init 명령입니다. 프로젝트 폴더에서 Claude Code를 실행한 뒤 /init를 입력하면, Claude가 프로젝트를 살펴보고(빌드 시스템·테스트 도구·코드 패턴을 감지) 시작용 CLAUDE.md를 자동으로 만들어 줍니다.
- 프로젝트 폴더에서 Claude Code를 실행합니다.
/init를 입력합니다.- Claude가 코드베이스를 살펴봅니다(이때 파일을 읽기 위한 명령 실행을 물어볼 수 있는데, 대부분 허용해도 괜찮습니다).
- 생성된 CLAUDE.md를 열어 검토하고 필요에 맞게 다듬습니다.
중요한 점: /init가 만든 파일은 '완성본'이 아니라 '시작점'입니다. 자동 감지는 눈에 보이는 패턴은 잘 잡지만, 여러분 팀만 아는 세부 규칙은 놓칠 수 있으니 직접 검토·보완하세요.
방법 B — 직접 만들기
아주 작은 프로젝트이거나 직접 손으로 시작하고 싶다면, 프로젝트 폴더 루트에 CLAUDE.md라는 이름의 파일을 만들고 평범한 글로 적으면 됩니다. 정해진 형식은 없습니다. 마크다운(제목·목록을 쓰는 평문)이면 충분하고, 사람과 Claude가 빠르게 이해할 수 있게 간결하게 쓰는 것이 권장됩니다.
참고로 파일 이름은 대소문자를 구분하므로 정확히 CLAUDE.md로 저장하세요.
처음엔 이렇게 짧아도 충분해요
완벽하게 채우려 하지 말고, "매번 다시 설명하던 것" 한두 가지부터 적으세요. 예를 들어 자주 쓰는 명령과 기본 규칙만 적어도 큰 도움이 됩니다.
# 프로젝트 안내
## 명령
- 개발 서버: npm run dev
- 테스트: npm test
## 규칙
- 설명과 주석은 한국어로
- src/legacy 폴더는 수정 금지이 정도만 있어도 Claude가 매 세션 시작 때 자동으로 읽어, "테스트는 어떻게 돌려?", "이 폴더 건드려도 돼?" 같은 반복 설명이 줄어듭니다.
작게 시작해 점점 키우기
CLAUDE.md는 한 번에 완성하는 문서가 아니라 '살아있는 문서'입니다. 쓰다가 "이거 또 설명하네" 싶은 게 생기면 그때 한 줄씩 추가하세요.
- 파일 만들기 —
/init또는 직접 생성. - 한두 줄 적기 — 자주 쓰는 명령부터.
- 검토·커밋 — 내용을 확인하고, 팀 프로젝트라면 버전 관리(Git)에 커밋해 함께 공유합니다.
- 계속 추가 — 반복 설명이 생길 때마다 한 줄씩.
처음 채울 때 좋은 것들
- 프로젝트 한 줄 소개 — "이건 Stripe 결제가 붙은 Next.js 쇼핑몰" 같은 한 문장.
- 자주 쓰는 명령 — 빌드·테스트·실행 명령.
- 코드 스타일 — 들여쓰기, 이름 규칙 등.
- 주의사항(gotcha) — 건드리면 안 되는 파일, 특이한 우회 방법 등.
너무 길어지면 지저분해지므로, 자세한 절차나 특정 부분에만 해당하는 내용은 별도 문서나 스킬로 옮기는 것이 좋습니다.
정리
첫 CLAUDE.md 만들기는 어렵지 않습니다. 가장 빠른 길은 /init이고, 직접 만들 때도 한 줄부터 시작하면 됩니다. 만든 뒤 검토·커밋하고, 반복 설명이 생길 때마다 키워 나가세요. 더 깊이 들어가려면 같은 사이트의 CLAUDE.md 완벽 가이드와 실전 예제 모음을 이어서 보세요.
본 글은 Anthropic 공식 문서(code.claude.com/docs, claude.com/blog)의 공개 정보를 초보자용으로 정리했습니다. 명령·동작은 제품 업데이트로 바뀔 수 있으니 실제 화면과 공식 문서를 확인하세요. 본 사이트는 Anthropic 공식 사이트가 아닙니다.