첫 출근날 건네는 업무 매뉴얼 | CLAUDE.md
매 세션 자동 로드되는 CLAUDE.md를 신입 사원 업무 매뉴얼에 비유해, 무엇을 넣고 무엇을 제외할지 판단 기준을 세웁니다
Overview
매번 같은 규칙·컨벤션·아키텍처 결정을 설명하는 대신 CLAUDE.md 를 한 번 작성해 두면, 새 세션마다 Claude에게 자동으로 전달됩니다.
이번 레슨에서는 CLAUDE.md를 신입 사원에게 건네는 업무 매뉴얼로 이해하고, 매뉴얼에 무엇을 넣고 무엇을 제외할지 판단 기준을 세웁니다.
학습 목표
- 새 세션마다 CLAUDE.md가 Context에 어떻게 전달되는지 설명합니다
- "모델이 코드에서 찾을 수 없는 것만 추가한다"라는 원칙에 따라 무엇을 추가하고 빼야 할지 판단합니다
- 프로젝트 CLAUDE.md와 개인 CLAUDE.md의 역할 차이를 구분합니다
매 출근마다 백지인 신입 사원
실력 좋은 개발자가 오늘 처음 출근했다고 상상해 보세요. 면접을 통과할 만큼 똑똑하지만, 회사의 아키텍처 결정 이유·코딩 컨벤션·브랜치 규칙은 전혀 모릅니다. 심지어 이 신입 사원은 매일 출근할 때마다 전날 배운 것을 전부 잃어버립니다. 오늘 설명해 준 팀 규칙을 내일 아침에 또 설명해야 합니다.
터무니없는 상황 같지만 LLM은 정확히 이렇게 동작합니다. 새 세션을 시작하거나 /clear 를 실행하면 직전 대화의 모든 맥락이 사라집니다. LLM은 대화와 대화 사이에 아무것도 기억하지 않는 무상태(Stateless) 시스템이기 때문입니다.
매번 같은 설명을 반복하면 시간만 낭비되는 게 아니라 Context도 낭비됩니다. 필요한 건 매 출근마다 자동으로 전달되는 매뉴얼입니다.
CLAUDE.md: 첫 출근날 건네는 업무 매뉴얼
CLAUDE.md가 이 매뉴얼입니다. 프로젝트 루트에 텍스트 파일 하나를 두면, 새 세션이 시작될 때마다 Claude의 System Prompt에 자동으로 합쳐져 Context에 올라갑니다. 한 번 작성해 두면 매 대화에서 Claude가 이미 매뉴얼을 읽은 상태로 시작합니다.
매뉴얼에 남길 기준: 돌아다녀서 알 수 없는 것
신입 사원이 사무실에 들어서면, 회의실 위치는 돌아다니다 보면 알게 되고 장비 사용법은 기기에 붙은 안내를 보면 됩니다. 이런 것까지 매뉴얼에 옮겨 적으면 분량만 늘고, 정작 중요한 팀의 합의 사항을 찾기 어려워집니다.
CLAUDE.md도 같은 기준으로 무엇을 추가하고 무엇을 빼야 할지 정합니다.
추가할 것: 코드에 없는 합의
모델이 package.json 이나 코드베이스에서 스스로 찾을 수 없는 정보를 매뉴얼에 작성합니다. 코드에서 추론할 수 없는 팀의 합의는 대개 세 범주에 들어갑니다.
- 아키텍처 결정 이유: 무엇을 쓰는지는 코드에서 보이지만, 왜 그렇게 결정했는지는 코드 어디에도 없습니다.
"Server Components 우선, 상태는 Zustand 로 통일"처럼 원칙을 작성해 두면 새 기능을 만들 때도 같은 방향을 따릅니다 - 팀 워크플로우: 커밋 메시지 규칙, 브랜치 명명, PR 요구사항처럼 코드에서 추론할 수 없는 팀의 합의입니다.
"커밋 메시지는 Conventional Commits 로"같은 한 줄이 매 대화마다 적용됩니다 - 제약사항:
"NEVER Shadcn 컴포넌트 원본 수정","새 라이브러리 설치 시 팀 확인"같은 경계선입니다
절대 금지 규칙에는 NEVER를 붙이기
규칙이 많아지면 중요한 것을 찾기 어려워집니다. 절대 금지해야 하는 줄에는 NEVER 같은 키워드를 붙이면 모델이 더 확실히 따릅니다. 예: "**NEVER** .env 파일 커밋".
빼야 할 것: 코드가 더 정확한 정보
반대로 모델이 코드에서 직접 읽어낼 수 있는 정보는 매뉴얼에서 뺍니다. Context에 올라간 정보는 무엇이든 출력에 영향을 주고, Context Rot으로 불필요한 지침이 늘수록 나머지 규칙의 힘이 약해집니다. 그래서 다음 네 가지는 매뉴얼에서 뺍니다.
- 모델이 코드에서 찾을 수 있는 정보: 기술 스택, 디렉토리 구조, 빌드·테스트 명령어는 코드가 바뀌면 매뉴얼이 실제 코드와 어긋납니다. 코드를 단일 출처로 두면 모델이 항상 최신 상태를 읽습니다
- 모델이 이미 아는 일반 원칙:
"변수 이름은 의미 있게","함수는 작게"같은 상식은 빼고,"에러를 적절히 처리"가 아니라"결제 금액은 클라이언트 계산값을 믿지 않고 서버에서 다시 계산한다"처럼 이 프로젝트만의 규칙만 남깁니다 - 민감 정보: API 키, 토큰, 암호는 CLAUDE.md에 적지 않습니다. 환경 변수나 배포 환경의 시크릿 저장소에서 관리합니다
- 자주 바뀌는 정보: 특정 티켓 번호, 이번 주 임시 해결책은 금세 바뀝니다. 임시 정보는 작업 이슈나 대화에 남기고, CLAUDE.md에는 여러 작업에서 반복해서 쓰는 기준만 남깁니다
두꺼운 매뉴얼의 함정
신입 사원에게 500페이지짜리 매뉴얼을 주면 표지만 들춰보고 덮습니다. CLAUDE.md도 마찬가지입니다. 200줄을 넘으면 중요한 규칙이 잡음에 섞여 준수율이 떨어집니다. 그래서 CLAUDE.md는 200줄을 넘기지 않는 편이 좋습니다. 반복해서 겪는 문제만 담고, 아직 일어나지 않은 문제는 다루지 않습니다.
매뉴얼이 200줄을 넘어갈 때
전문 분야별 지침이 많아지면 나중에 배울 Skills로 분리할 수 있습니다. Skills는 호출될 때만 로드되므로, CLAUDE.md에는 매 대화에 필요한 핵심 규칙만 남기고 나머지는 Skills로 내보내면 Context Rot을 피할 수 있습니다.
잘 쓴 CLAUDE.md 전체 예시
# Todo App
## Architecture
Server Components 우선, 클라이언트 상태는 최소화.
상태 관리가 필요하면 Zustand 사용.
## Workflow
- 커밋 메시지: Conventional Commits (feat:, fix:, refactor:)
- 브랜치: feature/<name>, fix/<name>
- PR 전 lint + test 통과 필수
## Rules
- **NEVER** Shadcn 컴포넌트 원본 수정
- 새 라이브러리 설치 시 팀 확인
- 커밋 전 테스트 실행기술 스택·디렉토리 구조·실행 명령어가 빠졌습니다. 이 셋은 모델이 package.json 과 파일 시스템에서 이미 읽을 수 있기 때문입니다.
회사 매뉴얼과 개인 업무 노트
CLAUDE.md는 두 곳에 둘 수 있고, 새 세션 시작 시 둘 다 합쳐져 Context에 올라갑니다.
| 위치 | 범위 | 업무 매뉴얼 비유 |
|---|---|---|
./CLAUDE.md (프로젝트 루트) | 팀 전체 (git에 커밋해 공유) | 회사 공식 매뉴얼: 모든 팀원이 같은 내용을 받음 |
~/.claude/CLAUDE.md (홈 디렉토리) | 개인 (모든 프로젝트에 적용) | 개인 업무 노트: 직장을 옮겨도 들고 다니는 내 습관 |
프로젝트 파일에는 "상태 관리는 Zustand 로 통일", 개인 파일에는 "한국어로 응답", "코드 리뷰 시 보안 항목 먼저" 같은 내용이 들어갑니다. 회사 매뉴얼이 이직하면 사라지듯 프로젝트 CLAUDE.md도 저장소 안에만 있고, 개인 노트는 어떤 프로젝트로 가든 따라옵니다.
이 패턴은 Claude Code 전체 설정에 적용됩니다
프로젝트 폴더(.claude/)에 두면 git으로 팀 전체에 공유되고, 홈 디렉토리(~/.claude/)에 두면 개인 전용으로 모든 프로젝트에 적용됩니다. Part 2에서 다룰 Commands·Skills·Agents·MCP가 모두 이 규칙을 따릅니다.
| 설정 | 프로젝트 (팀 공유) | 개인 (모든 프로젝트) |
|---|---|---|
| CLAUDE.md | ./CLAUDE.md | ~/.claude/CLAUDE.md |
| Commands | .claude/commands/ | ~/.claude/commands/ |
| Skills | .claude/skills/ | ~/.claude/skills/ |
| Agents | .claude/agents/ | ~/.claude/agents/ |
| MCP | .mcp.json | ~/.claude.json |
[미션] 첫 CLAUDE.md 작성하기
예시를 봤으니 같은 질문을 전후로 던져 보고, 프로젝트 CLAUDE.md 한 줄이 새 세션의 응답을 어떻게 바꾸는지 확인합니다.
ch03-02 브랜치가 이 미션의 시작점입니다.
git fetch origin
git checkout ch03-02Step 1: 작성 전 답변 확인
먼저 프로젝트 CLAUDE.md에 한국어 응답 규칙을 추가하기 전, 새 세션에서 영어 답변을 명시적으로 요청합니다.
What does this project do?
영어 답변이 나오면 아직 프로젝트 CLAUDE.md가 응답 언어를 바꾸지 않는 상태입니다.
Step 2: 프로젝트 CLAUDE.md에 한 줄 추가
프로젝트 루트에 CLAUDE.md 파일을 만들고 다음 한 줄을 작성합니다.
- 모든 답변은 반드시 한국어로 한다이 한 줄은 CLAUDE.md가 새 세션에서 로드되는지 확인하기 위한 최소 규칙입니다. 다음 Step에서 같은 질문을 다시 던졌을 때 답변 언어가 바뀌면 프로젝트 CLAUDE.md가 적용된 것입니다.
Step 3: 새 세션에서 같은 질문 다시 하기
CLAUDE.md는 새 세션 시작 시 로드됩니다. /clear 로 초기화하거나 새 터미널에서 claude 를 실행한 뒤, 같은 질문을 다시 입력합니다.
What does this project do?
질문에서 영어로 답하라고 명시적으로 요청했는데도 Claude가 한국어로 답하면 프로젝트 CLAUDE.md가 적용된 것입니다. 여전히 영어로 답한다면 규칙을 무시했다기보다 CLAUDE.md 자체가 로드되지 않았을 가능성이 높으니, 파일이 프로젝트 루트에 있는지, 세션이 새로 시작됐는지 먼저 확인합니다.
핵심 포인트 정리
- CLAUDE.md = 매 세션 자동 주입되는 업무 매뉴얼: 프로젝트 루트(
./CLAUDE.md)와 홈 디렉토리(~/.claude/CLAUDE.md)가 병합되어 System Prompt에 실립니다. 한 번 작성해 두면 매 대화에서 Claude가 이미 읽은 상태로 시작합니다 - 돌아다녀서 알 수 없는 것만 작성하기: 기술 스택·디렉토리·명령어는 모델이 직접 찾을 수 있으니 빼고, 아키텍처 결정 이유·팀 워크플로우·제약사항만 남깁니다
- 200줄을 넘기지 않기: CLAUDE.md 규칙은 강제가 아니라 권고이며, 200줄이 넘으면 중요한 규칙이 잡음에 섞여 준수율이 떨어집니다. 넘치면 Skills로 분리합니다
FAQ
이어서 배울 내용
CLAUDE.md가 팀이 합의해 써두는 매뉴얼이라면, 대화 중에 Claude가 배우는 내 개인적 습관(비유 스타일, 설명 길이, 자주 교정하는 말투)은 어떻게 유지할까요? 이런 선호까지 팀 매뉴얼에 쓰면 매뉴얼이 개인 메모로 오염됩니다.
- 이런 습관을 세션이 바뀌어도 기억하는 Memory
- CLAUDE.md와 Memory가 충돌할 때의 우선순위