CLAUDE.md 완전 가이드 — 파일명 대문자부터 100~200행 규칙, /init 실전까지

Claude Code를 쓰기 시작하면, 지시를 낼 때마다 "커밋 메시지는 한국어로", "인덴트는 스페이스 2개로"… 하고 매번 같은 설명을 쓰는 스트레스에 반드시 부딪힙니다.

이걸 해결해 주는 것이, 모든 것의 토대가 되는 CLAUDE.md 입니다.

이 글에서는 CLAUDE.md 의 개념 → 배치 장소 → 효과적인 작성법 → 실전까지를 한 편에 정리했습니다. 기초는 물론, "썼는데 지켜 주지 않는다"를 줄이기 위한 작성 요령까지 통으로 익힐 수 있는 구성입니다.

이 글에서 알 수 있는 것

• CLAUDE.md 란 무엇인가, 4가지 이점과 주의점
• 어디에 두면 무슨 일이 일어나는가(배치 장소와 역할)
• "지켜 주는" 작성법의 요령과 추천 섹션 구성
• /init 부터 시작하는 실전적인 만드는 법

제1장: CLAUDE.md란(기초)

CLAUDE.md 는 프로젝트의 규칙과 지식을 기술하는 파일입니다.

가장 큰 특징은 Claude Code가 기동 시 자동으로 읽어 들인다는 것. 매번 설명하고 싶은 내용을 써 두면 일일이 프롬프트에 넣을 필요가 없어집니다. 세션마다 자동으로 읽히니, 기억해 주길 바라는 정보를 영속화(계속 남게) 할 수 있는 셈이죠.

배치는 여러 가지가 가능하지만, 기본은 알기 쉽게 **프로젝트 루트(폴더 바로 아래)**에 두는 것을 추천합니다.

파일명은 반드시 대문자로 CLAUDE.md 소문자 등으로 쓰면 Claude Code가 올바르게 인식하지 못합니다. 여기는 요주의 포인트예요.

4가지 이점

1. 컨텍스트 공유: 프로젝트의 컨텍스트(배경 정보)를 이해한 상태로 작업을 시작해 줍니다.
2. 설명 생략: 매번 같은 설명이 필요 없어져 개발이 척척 나아갑니다.
3. 규약 통일: CLAUDE.md 의 내용은 반드시 처음에 이해되므로, 명명 규칙과 코딩 규약을 지켜 줍니다.
4. 팀 공유: 그냥 파일이라 Git으로 공유되고, 팀 전원이 같은 기준으로 품질을 지킬 수 있습니다.

주의점: 100%는 지켜지지 않는다

CLAUDE.md 에 쓰는 것은 어디까지나 "지시"이고, 반드시 전부 따르는 것은 아닙니다. 썼다고 생각해도 Claude가 잊어버리는 일은 일어날 수 있어요. 특히 너무 복잡한 규칙이나 정의가 애매한 표현은 의도대로 해석되지 않습니다.

그래서 "인덴트는 스페이스 2개"처럼 구체적이고 간결하게 쓰는 것이 중요합니다. 사람에게 규칙을 가르칠 때와 마찬가지로, 대량이고 애매한 문서는 지켜지기 어렵습니다.

제2장: 배치 장소와 역할

CLAUDE.md 계열의 메모리는 여러 장소에 둘 수 있는데, 전부 읽혀서 조합되어 쓰인다는 것이 대전제입니다. 우선 다음 3가지(+보조)만 챙기면 충분해요.

• 프로젝트: Git 관리 전제. 팀 전체에서 품질·규칙을 통일하고 싶을 때 씁니다.
• 사용자 레벨: 그 PC 안의 전체 프로젝트에 공통으로 읽힙니다. 여러 프로젝트를 개발하는 사람일수록 공통 개발 규칙을 여기에 모아 두면 편해요.
• 로컬: 자동으로 Git 관리 대상에서 빠집니다. 사용 빈도는 높지 않지만, 팀에 공유하지 않는 나 전용 정보를 담는 자리입니다.

로컬이라도 시크릿은 쓰지 않는다 프로덕션의 DB·서버 접속 정보나 환경 변수로 다룰 API 키 같은 기밀 정보는, 설령 로컬이라도 보안 관점에서 쓰지 않도록 합시다.

중복을 피하는 것이 최중요 포인트

프로젝트와 사용자 레벨은 둘 다 읽혀서 조합되기 때문에, 내용의 중복을 최대한 없애는 것이 이상적입니다. 이번에 가장 기억해 주길 바라는 것이 이 한 가지예요.

• 프로젝트 쪽 … 고유의 기술 정보·폴더 구성·API 사양
• 사용자 쪽 … 커밋 규칙·개발 방침·품질 기준(※팀 공유하고 싶은 품질 기준은 프로젝트 쪽으로)

보조 테크닉: @ 로 외부 문서를 읽힌다

CLAUDE.md 본체를 단순하게 유지하는 요령으로, @ 를 붙여 다른 문서를 참조시키는 방법이 있습니다.

@docs/api-specification.md
@docs/coding-style.md

이렇게 하면 기동 시 해당 문서가 항상 읽힙니다. 다만 너무 많이 읽히면 컨텍스트를 압박하니 양에는 주의합시다.

로드 상황 확인: /memory 와 /context

현재 읽혀 있는 메모리 파일은 /memory(알기 쉬움)나 /context 로 확인합니다. /context 에서는 각 파일이 소비하는 토큰량도 보이니, 메모리가 세션 사용량을 너무 압박하고 있지 않은지 체크하는 습관을 들입시다.

제3장: 효과적인 작성법

CLAUDE.md 는 "무엇을 쓰나"뿐 아니라 "어떻게 쓰나"가 중요합니다. 여기가 허술하면 "썼는데 안 움직여 준다"가 일어나요.

길고 자세하게 쓰면 된다, 는 오해

CLAUDE.md 는 기동 시 전문이 컨텍스트(=Claude의 머리)에 읽힙니다. 너무 길면 본래의 작업 영역을 압박하는 데다, 중요한 규칙이 다른 정보에 파묻혀 옅어지고, 강제력까지 약해집니다.

결론은 단순합니다. 간결하고 구체적으로가 정답이에요.

헷갈리면 이 추천 5섹션

무엇을 쓸지 헷갈리면 우선 이 구성을 토대로 삼읍시다.

1. 개요 … 프로젝트의 목적·주요 기능
2. 기술 스택 … 언어·프레임워크·라이브러리(무엇에 기반하는지를 메타 인지시킨다)
3. 디렉터리 구조 … 주요 폴더의 역할, 어디에 무엇을 두는지의 규칙
4. 코딩 규약 … 명명 규칙·포맷
5. 개발 워크플로 … 커밋 규약·테스트 방침·오류 처리

소스 코드를 읽으면 Claude 스스로도 어느 정도 파악하지만, AI는 건네받은 정보에서 좁혀 들어가기 때문에, 먼저 전체 그림(개요·기술 스택)을 보여 주면 효율적으로 움직여 줍니다.

구체적·행동 지향으로 쓴다

가장 흔한 실수가 "애매한 지시"입니다. "깔끔하게 써", "제대로 테스트해", "적절히 보안 대응"은 사람에 따라 해석이 갈립니다.

"어떻게 한다", "무엇을 해야 한다"라는, 바로 실천할 수 있는 형태로 쓰는 것이 요령입니다. 규칙의 언어화가 어렵다면, 그것 자체를 Claude Code에 맡겨 버리는 것도 추천해요.

이미 아는 용어를 활용한다

AI가 이미 학습한 일반적인 용어를 쓰면 짧아도 효과적으로 전달됩니다.

- 커밋은 Conventional Commits 를 따른다
- 설계는 DDD(도메인 주도 설계)를 기본으로 한다
- TDD(테스트 주도 개발)로 진행한다

금지 사항은 "대체안"과 세트로

금지만이 아니라 "대신 무엇을 할지"를 곁들이면 인식이 강해져, 금지 사항을 피하기 쉬워집니다.

- 오류를 catch로 뭉개는 것은 금지 → 반드시 로그를 출력한다
- any 타입은 금지 → unknown + 타입 가드로 좁힌다

적절한 사이즈감은 "100~200행"

방심하면 금세 비대해집니다. 처음엔 100~200행 정도를 기준으로, 상세한 해설과 실례는 아껴 두고 간결한 개조식으로 담읍시다. "조금 짧은가?" 싶은 정도가 딱 좋습니다. 모자라면 나중에 덧붙이고, 너무 늘면 별도 기능인 "규칙(.claude/rules)"으로 분할하는 식으로 키워 가는 것을 추천합니다.

제4장: 실전 — /init 부터 만든다

여기서부터는 실제로 CLAUDE.md 를 만드는 흐름입니다. React + TypeScript 초기 프로젝트를 예로 듭니다.

1. /init 으로 밑틀을 생성

Claude Code 안에서 /init 을 실행하면 프로젝트의 코드를 자동으로 읽어 들여, 제법 정돈된 CLAUDE.md 를 만들어 줍니다. 손으로 쓰는 것보다 압도적으로 편하니 우선 이걸 토대로 삼읍시다(파일 편집 허가를 요구받으면 편집 모드를 활성화합니다).

2. 한국어화할까 영어 그대로 둘까

생성물은 대개 영어입니다. 한국어화할지는 취향으로 정해도 OK지만, 한국어는 영어보다 토큰 소비가 많다는 배경이 있습니다. 토큰을 아끼고 싶은 사람은 영어 그대로, 구조를 파악하기 쉽게 하고 싶은 사람은 한국어화, 로 구분합시다. 한국어화하고 싶을 때는 "CLAUDE.md 를 한국어로 바꿔 주세요"라고 전하기만 하면 됩니다.

3. 코딩 규약을 덧붙이게 한다

작은 프로젝트라면 /init 의 내용으로도 충분하지만, 규약과 개발 워크플로가 있으면 지침이 명확해집니다. 규칙이 미정이라면 Claude와 상의해 정하는 것이 편해요.

이 프로젝트의 코드 품질을 올리기 위한 코딩 규약을 CLAUDE.md 에 덧붙여 주세요.

프로젝트를 파악하고 있는 Claude Code가 최적의 규약을 생각해 통일감 있게 써 줍니다.

4. 장황한 코드 예시는 깎는다

덧붙일 때 코드 예시를 대량으로 쓰는 경우가 있는데, 이건 컨텍스트를 압박합니다. 제3장에서 말했듯 기존 코드를 읽으면 아는 내용은 깎는 것이 정답입니다.

컨텍스트 절약 관점에서 코드 예시는 삭제해 주세요.

이렇게 하면 "any를 금지하고 unknown + 타입 가드"처럼, 개발자라면 아는 수준까지 간결해집니다.

5. 공통 규칙은 사용자 레벨로 나눠 담는다

커밋 규약과 테스트 방침은 어느 프로젝트에서든 거의 공통입니다. 프로젝트의 CLAUDE.md 가 아니라 사용자 레벨의 ~/.claude/CLAUDE.md 에 쓰면 중복이 사라집니다(제2장의 "중복을 피한다"와 직결됩니다).

정리: CLAUDE.md 체크리스트

• 파일명은 대문자 CLAUDE.md, 기본은 프로젝트 루트에 둔다
• 기동 시 전문이 읽힌다. 그러니 간결하고 구체적으로(기준 100~200행)
• 배치 장소는 "프로젝트/사용자/로컬"을 구분해 쓰고, 내용의 중복을 없앤다
• 작성법은 애매함을 피하고 행동 지향(어떻게 한다·무엇을 해야 한다)으로
• 금지 사항은 대체안과 세트, 이미 아는 용어(Conventional Commits / DDD / TDD)를 활용
• 헷갈리면 개요·기술 스택·디렉터리 구조·코딩 규약·개발 워크플로의 5섹션
• 우선 /init 으로 밑틀을 만들고 조금씩 다듬는다
• /memory·/context 로 로드 상황과 토큰 소비를 확인

CLAUDE.md 는 "프로젝트의 기억"입니다. 100% 지켜지는 마법이 아니기에, 단순하고 명확한 규칙을 마음에 새겨 갑시다. 이 글이 기존 파일을 재점검하는 계기가 되면 기쁘겠습니다.