첫 출근날 건네는 업무 매뉴얼 | CLAUDE.md

Overview

새 대화를 시작할 때마다 프로젝트 규칙·컨벤션·아키텍처 결정을 다시 설명하고 있다면, 매번 반복되는 그 오리엔테이션을 한 번만 쓰고 자동으로 전달되는 자리가 CLAUDE.md 입니다.

이번 레슨에서는 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는 두 곳에 둘 수 있고, 새 세션 시작 시 둘 다 합쳐져 Context에 올라갑니다.

프로젝트 파일에는 "상태 관리는 Zustand 로 통일", 개인 파일에는 "한국어로 응답", "코드 리뷰 시 보안 항목 먼저" 같은 내용이 들어갑니다. 회사 매뉴얼이 이직하면 사라지듯 프로젝트 CLAUDE.md도 저장소 안에 머물고, 개인 노트는 어떤 프로젝트로 가든 따라옵니다.

매뉴얼에 적을 기준: 돌아다녀서 알 수 없는 것

신입 사원이 사무실에 들어서면, 회의실 위치는 걸어 다니다 보면 알게 되고 장비 사용법은 장비 옆 라벨에서 찾습니다. 매뉴얼에 사무실 지도나 장비 라벨까지 옮겨 적으면 매뉴얼만 두꺼워지고, 정작 중요한 팀의 합의 사항이 묻힙니다.

CLAUDE.md도 마찬가지입니다. 판단 기준은 하나입니다. 바로 "이 정보를 모델이 package.json 이나 코드베이스에서 스스로 찾을 수 있는가?" 입니다. 찾을 수 있으면 빼고, 없으면 넣습니다.

넣을 것: 코드에 없는 합의

코드에서 추론할 수 없는 팀의 합의는 대개 세 범주에 들어갑니다.

• 아키텍처 결정 이유: 무엇을 쓰는지는 코드에서 보이지만, 왜 그렇게 결정했는지는 코드 어디에도 없습니다. "Server Components 우선, 상태는 Zustand 로 통일" 처럼 원칙을 적어두면 새 기능을 만들 때도 같은 방향을 따릅니다
• 팀 워크플로우: 커밋 메시지 규칙, 브랜치 명명, PR 요구사항. 코드에서 추론할 수 없는 팀의 합의입니다. "커밋 메시지는 Conventional Commits 로" 같은 한 줄이 매 대화마다 적용됩니다
• 제약사항: "NEVER Shadcn 컴포넌트 원본 수정", "새 라이브러리 설치 시 팀 확인" 같은 경계선

뺄 것: 코드가 더 정확한 정보

"분홍 코끼리를 생각하지 마세요." 이 문장을 읽는 순간 떠오르듯, Context에 올라간 정보는 어떤 형태로든 출력에 영향을 줍니다. 지침의 저주도 다시 작동해, 불필요한 한 줄을 추가할 때마다 나머지 모든 규칙의 영향력이 함께 희석됩니다. 다음 네 가지는 매뉴얼이 아닌 다른 자리에 둡니다.

• 모델이 코드에서 찾을 수 있는 정보: 기술 스택, 디렉토리 구조, 빌드·테스트 명령어. 버전·경로·스크립트는 코드가 바뀌면 매뉴얼이 먼저 낡습니다. 코드를 단일 출처로 두면 모델이 항상 최신 상태를 읽습니다
• 모델이 이미 아는 일반 원칙: "변수 이름은 의미 있게", "함수는 작게" 같은 상식. "에러를 적절히 처리" 가 아니라 "에러는 Sentry 로 보낸다" 처럼 이 프로젝트만의 규칙만 남깁니다
• 민감 정보: API 키, 비밀번호. CLAUDE.md는 git에 올라가 팀 전체가 봅니다. 비밀은 환경 변수에 둡니다
• 자주 바뀌는 정보: 특정 티켓 번호, 이번 주 임시 해결책. CLAUDE.md는 안정적인 규칙의 자리입니다

두꺼운 매뉴얼의 함정

신입 사원에게 500 페이지짜리 매뉴얼을 주면 표지만 들춰보고 덮습니다. CLAUDE.md도 같습니다. Claude는 매뉴얼을 그대로 다 따르지 않습니다. CLAUDE.md가 200줄을 넘으면 중요한 규칙이 잡음에 묻혀 준수율이 떨어지고, 대화마다 지침의 저주까지 쌓입니다. 그래서 200줄 미만으로 유지합니다. 실제로 반복해서 발목을 잡는 패턴만 담고, 아직 일어나지 않은 문제는 다루지 않습니다.

잘 쓴 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 과 파일 시스템에서 이미 읽을 수 있기 때문입니다.

[실습] 내 프로젝트의 첫 매뉴얼 한 줄

예시를 봤으니 직접 한 줄을 추가하고 실제로 로드되는지 확인합니다.

Step 1: 프로젝트 CLAUDE.md에 한 줄 추가

프로젝트 루트의 CLAUDE.md 를 열고(없으면 새로 만듭니다) 마지막에 한 줄을 붙입니다.

- 모든 대화에서 한국어로만 대답한다

Step 2: 새 세션에서 영어로 질문

CLAUDE.md는 새 세션 시작 시 로드됩니다. /clear 로 초기화하거나 새 터미널에서 claude 를 실행한 뒤, 영어로 물어봅니다.

What does this project do?

Claude가 한국어로 답하면 매뉴얼이 정상적으로 주입된 것입니다. 영어로 답하면 규칙을 무시한 게 아니라 CLAUDE.md가 로드되지 않은 경우가 많습니다. 파일이 프로젝트 루트에 있는지, 세션이 새로 시작됐는지 먼저 확인합니다.

핵심 포인트 정리

1. CLAUDE.md = 매 세션 자동 주입되는 업무 매뉴얼: 프로젝트 루트(./CLAUDE.md)와 홈 디렉토리(~/.claude/CLAUDE.md)가 병합되어 System Prompt에 실립니다. 한 번 써두면 매 대화에서 Claude가 이미 읽은 상태로 시작합니다
2. 돌아다녀서 알 수 없는 것만 적기: 기술 스택·디렉토리·명령어는 모델이 직접 찾을 수 있으니 뺍니다. 아키텍처 결정 이유·팀 워크플로우·제약사항만 남깁니다
3. 200줄 미만으로 유지: CLAUDE.md는 강제 규칙이 아니라 권고이고, 200줄을 넘으면 중요한 규칙이 잡음에 묻혀 준수율이 떨어집니다. 넘치면 Skills로 분리합니다

FAQ

• Q: CLAUDE.md를 언제 업데이트해야 하나요?

  • A: Claude에게 같은 설명을 두 번 이상 반복하고 있다면 그때가 업데이트 시점입니다. 작업 중에 # 키로 즉석 메모를 남길 수 있고, 메모가 쌓이면 정리해서 CLAUDE.md에 옮깁니다

• Q: /init 명령으로 자동 생성하면 편하지 않나요?

  • A: /init 은 프로젝트를 분석해 초안을 만들지만, 결과물 대부분이 기술 스택·디렉토리 구조·실행 명령어처럼 모델이 이미 찾을 수 있는 정보입니다. 빈 파일에서 결정 이유·팀 워크플로우·제약사항 세 가지만 직접 적는 편이 더 효과적입니다

• Q: 프로젝트 CLAUDE.md와 개인 CLAUDE.md가 충돌하면 어떻게 되나요?

  • A: 둘 다 로드됩니다. 같은 주제에 서로 다른 지침이 들어 있으면 모델이 혼란스러워할 수 있으므로, 프로젝트 파일에는 팀 규칙만 두고 개인 파일에는 팀 규칙과 겹치지 않는 개인 선호만 담는 편이 좋습니다

이어서 배울 내용

CLAUDE.md가 팀이 합의해 써두는 매뉴얼이라면, 대화 중에 Claude가 배우는 내 개인적 습관(비유 스타일, 설명 길이, 자주 교정하는 말투)은 어떻게 유지할까요? 이런 선호까지 팀 매뉴얼에 쓰면 매뉴얼이 개인 메모로 오염됩니다.

• 대화 중 학습을 세션 간에 유지하는 Memory 시스템
• CLAUDE.md와 Memory가 충돌할 때의 우선순위