CLAUDE.md가 뭔가요? 설정 하나로 반복 설명이 사라집니다

Claude Code에 이것저것 시켜봤는데, 어딘가 말이 안 통한다는 느낌을 받은 적 있으신가요. 매번 같은 방식으로 설명해도 Claude가 엉뚱하게 이해하거나, 조금 전에 한 말을 금방 잊는 것처럼 행동할 때가 있습니다. 그 답이 CLAUDE.md에 있습니다.

뭔지도 몰랐던 파일 하나가, 제대로 설정하면 매번 반복하던 설명을 대신해줍니다. 어떻게 쓰는 건지, 그리고 왜 가끔 말을 안 듣는 것처럼 느껴지는지까지 함께 살펴보겠습니다.

CLAUDE.md가 뭔가요?

CLAUDE.md는 Claude Code를 실행할 때 자동으로 읽어들이는 지침 파일입니다. 쉽게 말해, “이 프로젝트에서 Claude가 항상 따라야 할 규칙 모음”이에요.

ChatGPT를 써봤다면 “맞춤 지침(Custom Instructions)” 기능이 익숙할 거예요. 거기에 “답변은 짧게 해줘”, “한국어로만 대답해줘” 같은 설정을 저장해두면 매번 말 안 해도 반영되잖아요. CLAUDE.md도 같은 역할입니다. 프로젝트 폴더에 이 파일을 만들어두면 Claude Code가 대화를 시작할 때 자동으로 읽고 반영해요.

ChatGPT 맞춤 지침과 다른 점은, 프로젝트 폴더마다 따로 설정할 수 있다는 거예요. 블로그 프로젝트에는 “경어체로 작성”, 업무 자동화 폴더에는 “TypeScript로만 코드 작성” 식으로 다른 규칙을 적용할 수 있습니다. 팀 프로젝트라면 Git에 커밋해서 팀 전체가 같은 규칙으로 쓰는 것도 가능하고요.

CLAUDE.md에 꼭 들어가야 하는 것들

그렇다면 파일에 무엇을 담아야 할까요? Claude Code 내부 동작을 분석하는 것으로 알려진 HumanLayer의 가이드는 세 가지 질문을 기준으로 잡습니다.

WHAT — 이 프로젝트가 무엇인가요? 기술 스택과 프로젝트 구조를 설명합니다. 특히 여러 폴더가 얽힌 프로젝트라면, Claude가 맥락 없이 작업하다가 엉뚱한 파일을 건드리는 걸 막아줍니다.

WHY — 왜 만들어진 프로젝트인가요? 프로젝트의 목적과 각 부분의 역할을 적습니다. 같은 코드 수정이라도 맥락을 알면 더 적합한 방향으로 판단하거든요.

HOW — 어떻게 작업하면 되나요? 빌드, 테스트, 배포 명령어와 작업 순서를 적습니다. 반복적으로 설명하게 되는 워크플로우가 있다면 여기에 넣어두는 게 좋습니다.

예를 들어 이런 식입니다.

 ## 프로젝트 (WHAT)
 매주 거래처에 보내는 엑셀 리포트를 자동으로 만들어주는 Python 스크립트.
 data/ 폴더의 CSV 파일을 읽어서 output/ 폴더에 엑셀로 저장.
 ​
 ## 왜 만들었나 (WHY)
 기존에는 매주 수작업으로 엑셀을 정리했는데, 실수가 잦고 시간이 오래 걸려서 자동화.
 거래처마다 포맷이 달라서 각 거래처별 템플릿 파일이 templates/ 폴더에 있음.
 ​
 ## 작업 방법 (HOW)
 - 실행: python report.py
 - 출력 파일 날짜 형식: YYYY-MM-DD
 - 새 거래처 추가 시 templates/ 에 템플릿 파일 먼저 만들기

세션마다 반복해서 말해야 하는 내용이 있다면, 그게 CLAUDE.md에 들어가야 할 내용입니다.

명령어 하나로 초안 시작하기

넣어야 할 내용이 정리됐다면, Claude Code의 /init 명령어로 초안을 자동 생성할 수 있습니다. 프로젝트의 패키지 파일, 설정 파일, 코드 구조를 분석해서 WHAT·WHY·HOW에 해당하는 내용을 정리해줘요.

다만 자동 생성된 파일은 출발점입니다. 명확한 패턴은 잘 잡아내지만 실제 작업 방식의 세부 사항까지는 담지 못하거든요. 생성 후에 직접 다듬어야 제대로 된 CLAUDE.md가 됩니다.

쓰다 보면 빠지는 함정, CLAUDE.md 비대화

처음엔 간단하게 시작했다가, 쓰다 보면 CLAUDE.md가 점점 불어납니다. “이것도 넣으면 좋겠다”, “저것도 Claude가 알면 좋겠다” 하다가 수백 줄이 되는 거예요.

이때 흔히 넣게 되는 것들이 있습니다.

• 코드 스타일 규칙: 들여쓰기, 따옴표 방식, 세미콜론 여부 등
• 특정 작업에만 해당하는 지침: “지금 이 기능 만들 때는 이렇게 해줘”
• 모호한 품질 기준: “항상 좋은 코드를 작성해줘”, “자연스럽게 써줘”

그런데 이런 내용들은 CLAUDE.md에서 큰 효과를 못 냅니다. 코드 스타일은 ESLint, Prettier 같은 자동화 도구가 훨씬 확실하게 강제하고, 특정 작업에만 해당하는 지침은 그 작업을 시작할 때 직접 말하는 게 낫습니다. 모호한 기준은 Claude가 해석할 수 없어서 그냥 넘어가는 경우가 많고요.

문제는 이렇게 파일이 커질수록 정작 중요한 규칙이 묻혀버린다는 겁니다. 그리고 이게 다음 문제로 이어집니다.

CLAUDE.md가 작동을 안 한다?

CLAUDE.md를 만들었는데 Claude가 규칙을 무시하는 것처럼 느껴진다면, 원인은 대부분 아래 세 가지 중 하나입니다.

Claude Code가 CLAUDE.md에 단서를 달아서 전달하기 때문

Claude Code는 CLAUDE.md를 그대로 지시로 전달하지 않습니다. 내부적으로 다음 문구를 덧붙여서 전달해요.

“this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.”

“이 내용은 현재 작업과 관련이 있을 수도, 없을 수도 있습니다. 작업과 직접 관련이 있을 때만 따르세요.”

Claude 입장에서는 “반드시 따라야 할 명령”이 아니라 “상황에 따라 판단해도 되는 참고 사항”으로 해석될 여지가 생깁니다. dev.to 분석에 따르면, 파일에 특정 작업에만 해당하는 내용이 많을수록 Claude가 다른 내용도 함께 무시할 가능성이 높아집니다. 앞에서 설명한 “쓸데없는 내용이 너무 많아진 CLAUDE.md”가 바로 이 문제를 악화시키는 거예요.

대화가 길어질수록 초반 지침이 밀려나기 때문

Claude의 컨텍스트 창은 200,000 토큰이지만 실제로는 생각보다 빨리 채워집니다. Claude Code 자체의 시스템 지침과 도구 정의가 상당한 양을 차지하는 데다, 대화가 쌓이면 코드 파일과 검색 결과까지 더해지거든요.

컨텍스트가 가득 차면 Claude는 이전 내용을 압축하는 컨텍스트 컴팩션(compaction)을 수행하는데, 이 과정에서 CLAUDE.md 내용이 요약되거나 우선순위에서 밀릴 수 있습니다. 긴 작업 세션에서 규칙이 갑자기 안 지켜지는 느낌이 드는 건 이 때문이에요. 이럴 때 가장 빠른 해결책은 새 대화 세션을 시작하는 겁니다.

지시가 너무 많기 때문

HumanLayer 분석에 따르면, 최신 LLM도 150~200개 정도의 지시를 일관되게 따르는 데 한계가 있습니다. Claude Code의 시스템이 이미 약 50개의 지시를 사용하고 있어서 실제로 활용 가능한 슬롯은 그보다 적어요. 파일이 길수록 중요한 규칙이 덜 중요한 것들과 경쟁하다가 밀려납니다.

결국 핵심은 하나입니다. CLAUDE.md는 어떤 작업을 하든 항상 적용되는 내용만, 짧게 담아야 합니다. 300줄 미만이 권장 기준이고, HumanLayer는 60줄 이하로 운영합니다.

자주 묻는 질문

CLAUDE.md 파일은 어디에 만들어야 하나요?

프로젝트 폴더의 루트(가장 상위 폴더)에 CLAUDE.md라는 이름으로 만들면 됩니다. Claude Code가 실행될 때 자동으로 읽어요. 하위 폴더에 별도로 만들면 해당 폴더에서 작업할 때 추가 규칙으로 적용됩니다.

전역 CLAUDE.md와 프로젝트 CLAUDE.md의 차이는 뭔가요?

전역 파일(~/.claude/CLAUDE.md)은 모든 프로젝트에 공통 적용되고, 프로젝트 파일은 해당 폴더에서만 적용됩니다. 둘 다 있으면 둘 다 읽히며 프로젝트 파일이 우선합니다.

CLAUDE.md 없어도 Claude Code를 쓸 수 있나요?

네, 없어도 됩니다. 다만 반복적으로 같은 지시를 해야 하는 게 생긴다면 그때 만들어도 늦지 않습니다.

GitHub에 올려도 되나요?

네. CLAUDE.md를 Git에 커밋하면 팀원 모두가 같은 규칙으로 Claude Code를 사용할 수 있습니다. 단, 개인 API 키나 비밀 정보는 절대 포함하지 마세요.