CLAUDE.md — AI에게 건네는 첫 번째 악수

Claude Code를 쓰기 시작하면서 가장 먼저 맞닥뜨리는 비효율이 있다. 매 세션마다 "이 프로젝트는 Node 기반이고, 테스트는 Vitest로 돌리고, 포트는 3000번입니다"라고 반복 설명하는 일이다. CLAUDE.md는 그 반복을 끊는 파일이다. 한 번 써두면 Claude가 프로젝트를 열 때마다 그 맥락을 기억한 채로 시작한다.

1. 왜 지금 이걸 봐야 하나

Claude Code는 세션이 끊기면 직전 대화를 기억하지 못한다. 컨텍스트 창이 리셋되기 때문이다. 그래서 신규 세션마다 개발자는 같은 설명을 다시 타이핑하거나, Claude가 엉뚱한 패키지 매니저를 쓰거나 금지된 패턴을 되풀이하는 걸 사후에 수정하는 데 시간을 쓴다.

실측해보면 CLAUDE.md 없이 작업할 때 첫 3~5개 턴이 대부분 맥락 재설명으로 소진된다. 여러 프로젝트를 동시에 돌리거나 n8n 자동화처럼 반복 세션이 잦은 환경에서는 이 낭비가 토큰 비용으로 직결된다.

비유를 하나 들자면, 암기력 제로인 금붕어 수조 옆에 포스트잇을 붙여두는 것과 같다. Claude가 수조 안의 금붕어라면, CLAUDE.md는 그 포스트잇이다. 구두로 열 번 설명하는 것과 A4 한 장 쥐여주는 것의 차이다.

2. 핵심 아이디어

CLAUDE.md는 Claude Code가 프로젝트를 실행할 때 컨텍스트 창 맨 앞자리에 자동으로 올라오는 파일이다.

claude 명령어를 치는 순간, Claude는 프로젝트 루트의 CLAUDE.md를 먼저 읽는다. 신입 개발자에게 건네는 온보딩 문서와 정확히 같은 역할이다. 이 파일이 있으면 Claude는 첫 응답부터 프로젝트 컨벤션을 알고 있는 상태로 시작한다.

파일이 없어도 Claude Code는 동작한다. 하지만 파일이 있을 때와 없을 때의 첫 응답 품질 차이는 꽤 크다. 없으면 Claude가 범용 모드로 추측하며 답하고, 있으면 이 프로젝트에 맞춘 답을 낸다.

핵심은 완벽하게 쓰려다 안 만드는 것보다, 5줄짜리라도 지금 만드는 것이다.

3. 바로 따라하는 방법

작성에 필요한 내용은 세 가지다. 기술 스택, 금지 사항, 자주 쓰는 명령어.

아래가 실전에서 바로 쓸 수 있는 최소 구성이다.

Project: my-quant-bot

Stack
- Runtime: Node 20 / TypeScript
- Test: Vitest (vitest run)
- Formatter: Prettier (prettier --write .)

Rules
- console.log 절대 남기지 말 것
- PR 전 타입 체크 필수: npx tsc --noEmit
- 패키지 매니저는 pnpm만 사용

Common Commands
- 개발 서버: npm run dev
- 전체 테스트: npm test
- 빌드: npm run build

이 파일이 있으면 Claude는 console.log를 써도 될지 묻지 않는다. 처음부터 안 쓴다.

직접 작성이 막막하다면 Claude에게 초안을 맡기면 된다. 프로젝트 폴더에서 아래 명령어 한 줄을 실행한다.

claude 'CLAUDE.md 초안 작성해줘. 현재 폴더 구조와 package.json 기준으로.'

Claude가 폴더 구조와 package.json을 읽고 스택, 스크립트, 의존성을 파악해 초안을 뽑아준다. 이후 Rules 섹션에 팀 컨벤션과 금지 패턴만 추가하면 된다.

초안이 나왔으면 실제로 동작하는지 확인한다.

# 새 세션을 열고 맥락 없이 물어보기
claude '이 프로젝트의 테스트 명령어가 뭔지 알려줘'

CLAUDE.md가 제대로 읽혔다면 Claude는 파일에 적힌 명령어를 그대로 답한다. 엉뚱한 npm test 대신 vitest run이 나온다면 정상이다.

4. 운영할 때 조심할 점

파일 크기를 관리해야 한다. CLAUDE.md는 컨텍스트 창을 차지한다. 너무 길면 실제 작업에 쓸 컨텍스트가 줄어든다. 경험상 500줄을 넘어가면 정리가 필요하다는 신호다. 자주 쓰는 명령어와 핵심 규칙만 남기고, 상세 설명은 별도 문서로 빼는 것이 낫다.

Rules 섹션은 구체적으로 써야 효과가 있다. "코드 품질을 유지하세요" 같은 추상적인 지시는 Claude가 실행하기 어렵다. "PR 전 npx tsc --noEmit 통과 필수", "async 함수에 try-catch 없이 await 금지" 처럼 검증 가능한 형태로 적어야 한다.

여러 환경을 함께 쓴다면 환경별 차이를 명시한다. Mac과 Linux에서 동시에 개발하거나 Docker 내부에서 실행한다면 경로 구분자나 패키지 매니저 동작이 달라질 수 있다. 이 경우 운영 환경 정보를 스택 섹션에 함께 적어두는 게 좋다.

CLAUDE.md는 주기적으로 갱신해야 한다. 프로젝트가 Node 18에서 Node 22로 올라가거나 테스트 프레임워크를 바꿨는데 파일이 옛날 정보를 담고 있으면 Claude가 잘못된 명령어를 낸다. 스택 변경 시 함께 업데이트하는 습관이 필요하다.

자주 묻는 질문

CLAUDE.md는 언제 쓰는 게 좋을까?
세션을 반복적으로 여는 모든 프로젝트에 적합하다. 특히 팀 협업 프로젝트, 자동화 워크플로우, 장기 운영 코드베이스처럼 맥락 공유가 잦은 상황에서 효과가 크다. 개인 프로젝트라도 하루 이틀 이상 이어지는 작업이라면 만들어두는 게 이득이다.

CLAUDE.md를 적용하기 전에 무엇을 확인해야 할까?
현재 프로젝트의 실제 스택과 파일 내용이 일치하는지 먼저 점검한다. 오래된 정보가 담긴 CLAUDE.md는 없는 것보다 위험할 수 있다. 초안을 만들었다면 package.json의 스크립트 목록과 대조해서 명령어가 맞는지 확인하는 것을 권한다.

결과가 제대로 나왔는지 어떻게 검증할까?
새 세션을 열고 CLAUDE.md에 적힌 내용을 직접 물어보는 방식이 가장 빠르다. "이 프로젝트의 빌드 명령어가 뭐야?", "어떤 테스트 프레임워크를 쓰고 있어?" 같은 질문에 파일 내용과 일치하는 답이 나오면 정상이다. 반대로 Claude가 파일에 없는 내용을 추측해서 답한다면 파일이 읽히지 않았거나 경로가 틀린 것이다.

마무리

CLAUDE.md 하나로 매 세션의 시작점이 달라진다. 재설명에 쓰던 첫 5개 턴을 바로 실제 작업에 쓸 수 있다. 지금 당장 프로젝트 루트에 5줄짜리라도 만들어 두는 것이 시작이다.

다음 글에서는 CLAUDE.md를 팀 전체에서 어떻게 관리하는지, 그리고 .claudeignore와 함께 쓸 때 달라지는 점을 다룰 예정이다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 입문
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독