[Claude 활용 24회 — AI에게 일을 위임하는 법] 5/24화: CLAUDE.md 작성법 5가지 — 저장소의 헌법을 쓰는 실전 가이드
3줄 요약
① CLAUDE.md는 AI가 코드를 건드리기 전에 반드시 읽는 ‘저장소의 헌법’이다.
② 빌드 명령, 코딩 컨벤션, 금지사항, 도메인 용어, 디렉터리 지도 — 이 5가지만 넣으면 80%는 해결된다.
③ 하지만 500줄 넘기면 성능이 되레 떨어진다. 짧고 정확한 게 최고다.
지난주에 AI한테 여행 예약 시스템의 API 엔드포인트 하나를 추가해달라고 했다. 4화에서 다룬 대로 맥락도 줬고, 제약도 걸었고, 완료 조건도 명시했다. 결과물이 올라왔다. 돌아가긴 한다. 그런데 ORM을 안 쓰고 raw SQL을 박아놨다.
우리 프로젝트는 3년째 SQLAlchemy만 쓴다. 모든 데이터 접근은 ORM 레이어를 거친다. 예외 없다. 이건 코드 어디에도 명시적으로 적혀 있지 않다. 신입이 오면 첫 PR 리뷰에서 한 번 깨지고 나서 체득하는 것이다. AI는 PR 리뷰에서 깨질 일이 없으니, 같은 실수를 영원히 반복한다.
한 번 더. 결제 모듈에서 버그를 잡아달라고 했더니 새 파일을 src/payment/ 루트에 만들었다. 우리 규칙: 비즈니스 로직은 반드시 src/payment/core/ 안에 둔다. 유틸리티는 src/payment/utils/에. 이것도 어디에 문서화되어 있지 않다. “원래 그렇게 하는 거야”의 세계다.
이런 종류의 지식을 ‘암묵지(tacit knowledge)’라고 부른다. 팀에 2년 있으면 공기처럼 아는 것들. 네이밍 규칙, 에러 처리 패턴, 절대 건드리면 안 되는 레거시 코드 영역, 특정 라이브러리를 쓰는 이유. 이것들이 수십 개 쌓여 있는데, 매번 프롬프트에 다 적을 수는 없다. 그래서 CLAUDE.md가 필요하다.
AI가 코드를 짜주는 시대가 아니라, AI에게 일을 위임하는 시대다. 그런데 위임하려면 규칙이 있어야 한다. 사람한테 위임할 때도 “우리 팀 규칙”을 알려주고 맡기지 않나. CLAUDE.md는 AI에게 건네는 그 규칙서다.
“이건 우리 팀에서만 통하는 룰인데” — 암묵지가 AI를 망치는 순간
20년 넘게 백엔드를 해오면서, 팀마다 암묵지의 양이 다르다는 걸 체감했다. 규제가 강한 환경일수록, 운영 이력이 길수록, 암묵지가 두껍다. “여기는 왜 이렇게 해요?”라고 물으면 돌아오는 대답이 항상 같다.
“2년 전에 장애 터져서 그때부터 그렇게 하기로 했어.”
이런 규칙이 팀 위키에 적혀 있으면 다행이다. 대부분은 사람 머릿속에만 있다. 때로는 그 사람이 퇴사하면 규칙 자체가 증발한다. 누군가 또 같은 장애를 겪고 나서야 규칙이 다시 만들어진다.
AI가 코드를 건드릴 때 겪는 문제가 정확히 이것이다. 코드의 구조를 읽을 수는 있다. 패턴을 추론할 수도 있다. 하지만 “왜 이 패턴이 여기에 존재하는지”는 코드만 봐서 알 수 없다. 특히 금지사항 — “이것만은 절대 하지 마라” — 은 코드에서 추론이 불가능하다. 안 한 것은 안 보이니까.
실제로 겪은 사례 몇 가지를 더 들어보자.
- 테스트 프레임워크 선택: 프로젝트에
pytest와unittest파일이 섞여 있었다. 레거시가unittest이고 신규는 전부pytest로 쓰기로 한 건데, AI는 주변 파일을 보고unittest로 테스트를 짰다. 레거시 코드를 보고 배운 것이다. - 환경변수 네이밍: 서비스 접두사가
TRAVEL_인데, AI가APP_DATABASE_URL이라고 만들었다. 일반적으로는 틀리지 않지만 우리 컨벤션이 아니다. - 에러 응답 포맷: RFC 7807(Problem Details) 형식을 쓰기로 팀 합의가 있었는데, AI는
{"error": "message"}형태로 내보냈다. 기존 코드에 두 포맷이 섞여 있어서 AI가 이전 것을 참고한 결과다. - 로그 레벨 규칙: 외부 API 호출 실패는
WARNING, 내부 로직 실패는ERROR로 찍기로 했는데, AI는 전부ERROR로 통일했다. 알람 폭탄이 터질 뻔했다.
하나하나는 사소하다. 하지만 코드 리뷰에서 매번 이걸 잡아내는 건 결국 사람 몫이다. AI한테 일을 위임한 건데 리뷰가 더 힘들어지는 역설이 생긴다. 4화에서 “작업 지시서에 제약을 넣으라”고 했지만, 프로젝트 전체에 걸리는 규칙을 매번 복붙하는 건 현실적이지 않다.
CLAUDE.md는 이 문제를 구조적으로 해결한다. 한 번 써두면 모든 대화에서 자동으로 적용된다. 프롬프트에 일일이 넣지 않아도 된다.
CLAUDE.md 계층 구조 — 전역, 프로젝트, 디렉터리
CLAUDE.md는 단순히 프로젝트 루트에 하나 두는 파일이 아니다. 세 단계 계층으로 동작한다. 이 구조를 이해해야 효율적으로 쓸 수 있다.
1단계: 전역 CLAUDE.md
위치: ~/.claude/CLAUDE.md (홈 디렉터리 하위)
이 파일은 내가 참여하는 모든 프로젝트에 공통으로 적용된다. 개인 취향이나 업무 환경에 대한 지침을 여기에 넣는다.
# 전역 CLAUDE.md 예시
## 개인 작업 환경
- OS: Windows 11
- 셸: PowerShell 7
- 패키지 매니저: uv
- 에디터: VS Code
## 공통 코딩 스타일
- 한국어 주석 사용
- 커밋 메시지는 한국어로 작성
- 타입 힌트 필수 (Python)
## 금지사항
- rm -rf 명령 실행 금지
- 프로덕션 데이터베이스 직접 접속 금지
- API 키를 코드에 하드코딩하지 않기
예를 들어 나는 모든 프로젝트에서 Python 타입 힌트를 쓴다. 이걸 프로젝트마다 반복 적는 대신, 전역 파일에 한 번 넣으면 된다. 여기에 적은 “rm -rf 금지” 같은 안전 규칙도 모든 프로젝트에 자동 적용된다.
2단계: 프로젝트 CLAUDE.md
위치: 프로젝트 루트의 CLAUDE.md (Git 저장소 최상단)
이 파일이 핵심이다. 해당 프로젝트의 빌드 방법, 컨벤션, 도메인 규칙을 담는다. 3화에서 /init 명령을 실행했을 때 자동 생성된 파일이 바로 이것이다. 초기에 자동 생성된 내용은 뼈대 수준이므로, 여기에 살을 붙이는 것이 오늘의 주제다.
# CLAUDE.md — 여행 예약 시스템 (TravelBook)
## 프로젝트 개요
FastAPI 기반 여행 예약 백엔드. 숙소·항공 검색, 예약 생성, 결제 처리.
## 빌드 & 테스트
- 의존성 설치: uv sync
- 테스트 실행: uv run pytest -q
- 린트: uv run ruff check . && uv run ruff format --check .
- 타입 체크: uv run mypy src/ --strict
## 기술 스택
- Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic
- DB: PostgreSQL 16
- 캐시: Redis 7
- 테스트: pytest + pytest-asyncio + httpx
이 파일은 Git에 커밋한다. 팀원 모두가 공유한다. AI만을 위한 것이 아니라 AI를 포함한 팀 전체를 위한 문서다. 신입 개발자가 이 파일을 읽으면 프로젝트 맥락을 빠르게 파악할 수 있다. 여기서 뒤에 다시 다룰 ‘온보딩 문서 자동 생산’ 효과가 나온다.
3단계: 디렉터리 CLAUDE.md
위치: 하위 디렉터리의 CLAUDE.md (예: src/payment/CLAUDE.md)
대규모 프로젝트에서 진가를 발휘한다. 특정 모듈이나 도메인에만 적용되는 규칙을 여기에 넣는다.
# src/payment/CLAUDE.md — 결제 모듈 규칙
## 이 디렉터리의 역할
결제 처리 전 과정을 담당한다.
PG사 연동, 환불 처리, 정산 데이터 생성.
## 구조
- core/: 비즈니스 로직 (여기에만 새 로직을 추가할 것)
- adapters/: PG사별 연동 어댑터
- utils/: 통화 변환, 수수료 계산 등 유틸리티
## 이 모듈의 금지사항
- 결제 금액 계산에 float 사용 금지 → 반드시 Decimal
- PG사 API 키를 코드에 두지 않기 → 환경변수로만 주입
- 결제 상태 변경 시 반드시 이벤트를 발행할 것
- 직접 DB 쿼리 금지 → PaymentRepository를 통해서만 접근
AI가 결제 모듈에서 작업할 때는 프로젝트 루트의 CLAUDE.md 위에 이 파일이 추가로 로드된다. 전역 → 프로젝트 → 디렉터리 순서로 쌓이는 구조다.
적용 우선순위: 디렉터리 CLAUDE.md > 프로젝트 CLAUDE.md > 전역 CLAUDE.md. 더 구체적인 규칙이 더 일반적인 규칙을 덮어쓴다. CSS의 specificity와 비슷한 원리다.
이 계층 구조 덕분에 프로젝트 루트 파일이 비대해지지 않는다. 결제 모듈만의 특수 규칙은 결제 디렉터리에, 검색 모듈만의 규칙은 검색 디렉터리에 두면 된다. 각각의 CLAUDE.md는 짧게 유지하면서도, AI가 실제로 작업하는 디렉터리에서는 필요한 맥락이 전부 로드되는 구조다.
여기서 한 가지 실무 팁. 디렉터리 CLAUDE.md를 남발하지는 말자. 프로젝트 루트 하나로 충분한 소규모 프로젝트가 대부분이다. 모듈별로 규칙이 실제로 다를 때만 분리한다. 규칙이 같은데 디렉터리마다 파일을 두면 유지보수 포인트만 늘어난다.
CLAUDE.md에 반드시 넣어야 할 5가지
계층 구조를 이해했으니 이제 본론이다. 뭘 적어야 하는가. 수십 개 프로젝트에 CLAUDE.md를 써보고 나서, 결국 필요한 건 5가지로 수렴했다. 하나씩 보자.
1. 빌드·테스트 한 줄 명령
AI가 코드를 수정하면 테스트를 돌려서 확인해야 한다. 그런데 프로젝트마다 테스트 실행 방법이 다르다. pytest인지 jest인지, make test인지 npm test인지. 가상환경 활성화가 필요한지, Docker가 필요한지. 이걸 매번 추론하게 두면 삽질한다.
## 빌드 & 실행
### 의존성 설치
uv sync
### 개발 서버
uv run uvicorn travelbook.app:app --reload --port 8000
### 테스트
uv run pytest -q # 전체
uv run pytest tests/unit/ -q # 단위 테스트만
uv run pytest -k "test_booking" -q # 특정 키워드
### 코드 품질
uv run ruff check . # 린트
uv run ruff format --check . # 포맷 검사
uv run mypy src/ --strict # 타입 체크
### DB 마이그레이션
uv run alembic upgrade head # 최신 스키마 적용
uv run alembic revision --autogenerate -m "설명" # 새 마이그레이션 생성
왜 중요한가: 이 섹션이 없으면 AI는 pyproject.toml을 읽고 빌드 시스템을 추론한다. 대부분은 맞추지만 가끔 틀린다. 특히 모노레포(monorepo)거나 커스텀 스크립트가 있는 프로젝트에서는 거의 확실히 틀린다. 한 줄 적어두면 그 추론 과정 자체가 생략된다. 토큰도 아끼고 정확도도 올라간다.
실무 팁: 복사-붙여넣기로 바로 실행 가능한 형태로 적어야 한다. “환경에 따라 다름” 같은 애매한 설명은 AI에게도 사람에게도 쓸모없다. uv sync가 정답이면 uv sync라고 쓰면 된다.
2. 코딩 컨벤션
린터가 잡아주는 것도 있지만, 린터가 모르는 컨벤션이 더 많다. 네이밍 규칙, 함수 크기 제한, import 순서, 에러 처리 패턴 같은 것들.
## 코딩 컨벤션
### Python
- 네이밍: snake_case (변수, 함수, 모듈), PascalCase (클래스), UPPER_SNAKE (상수)
- 타입 힌트: 모든 함수의 인자와 반환에 필수. Any 사용 금지
- import 순서: stdlib → 서드파티 → 로컬 (isort 기본 설정)
- 문자열: f-string 사용. .format() 이나 % 포맷 사용하지 않기
- 독스트링: 퍼블릭 클래스와 함수에 Google 스타일 독스트링
- 예외: 커스텀 예외는 travelbook.exceptions 모듈에 정의
- 최대 함수 길이: 50줄 초과 시 분리 검토
### 에러 응답
- HTTP API 에러는 RFC 7807 (Problem Details) 형식
- 에러 코드 체계: BOOKING_001, PAYMENT_001, SEARCH_001 (도메인_순번)
### 로그
- 외부 API 호출 실패: WARNING
- 내부 로직 에러: ERROR
- 비즈니스 이벤트 (예약 생성, 결제 완료): INFO
- 구조화 로깅 (structlog) 사용. print() 금지
여기서 핵심은 린터가 잡지 못하는 것을 적는 것이다. ruff가 잡아주는 import 순서를 또 CLAUDE.md에 적을 필요는 없다. AI는 린터를 돌릴 수 있고, 린터 결과를 보고 자기 코드를 고칠 수 있다. 린터가 모르는 것 — 에러 응답 포맷, 로그 레벨 규칙, 독스트링 스타일 — 을 적어야 한다.
만약 .editorconfig, ruff.toml, tsconfig.json 같은 설정 파일에 이미 강제되는 규칙이라면 CLAUDE.md에 또 적지 말자. 중복은 불일치의 씨앗이다. 설정 파일을 바꾸고 CLAUDE.md를 안 바꾸면 AI는 모순되는 두 지침 사이에서 혼란에 빠진다.
3. 금지사항
개인적으로 CLAUDE.md에서 가장 가치 있는 섹션이라고 생각한다. AI에게 “이것을 해라”는 맥락에서 추론 가능하지만, “이것만은 절대 하지 마라”는 명시하지 않으면 모른다.
## 금지사항 (Hard Constraints)
### 절대 금지 — 위반 시 PR 거부
1. raw SQL 직접 사용 금지 → 반드시 SQLAlchemy ORM을 통할 것
2. requirements.txt 수정 금지 → pyproject.toml로 의존성 관리
3. .env 파일을 Git에 커밋하지 않기
4. 결제 금액에 float 타입 사용 금지 → Decimal만 허용
5. print() 디버깅 금지 → structlog 사용
6. sleep()으로 타이밍 제어 금지 → 이벤트 기반으로 처리
7. 외부 API 호출 시 타임아웃 미설정 금지 → 반드시 timeout 지정
### 강한 비선호 — 불가피한 경우 사유 주석 필수
- 전역 변수 사용
- monkey-patching
- *args, **kwargs 남용 (명시적 매개변수 선호)
- 중첩 3단계 이상의 if/for
“절대 금지”와 “강한 비선호”를 구분하는 게 중요하다. 둘을 섞어놓으면 AI는 모든 것을 같은 강도로 해석한다. 결과적으로 진짜 중요한 금지사항의 무게가 희석된다.
금지사항은 반드시 이유와 대안을 함께 적어야 한다. “raw SQL 금지”만 적으면 AI가 대안을 추론해야 한다. 그 추론이 의도와 다를 수 있다. “raw SQL 금지 → SQLAlchemy ORM 사용”이라고 적으면 추론의 여지가 없다.
실제로 운영하면서 발견한 것: 금지사항이 10개를 넘으면 AI가 일부를 놓치기 시작한다. 정말 중요한 것 7~10개만 남기고, 나머지는 린터 규칙이나 CI 검사로 잡는 게 낫다. 6화에서 다룰 ‘훅(Hooks)’이 바로 그 역할을 한다.
4. 도메인 용어 사전
모든 프로젝트에는 그 도메인만의 용어가 있다. AI는 범용 언어 모델이므로, 도메인 특화 용어의 맥락을 정확히 모를 수 있다. 특히 일반 영어 단어를 도메인에서 다른 의미로 쓰는 경우가 문제다.
## 도메인 용어
| 용어 | 우리 시스템에서의 의미 | 주의 |
|------|----------------------|------|
| Booking | 예약 건 하나를 나타내는 최상위 도메인 객체 | Order와 혼용하지 않음 |
| Segment | 하나의 여정 구간 (서울→도쿄 = 1 Segment) | 항공업계 표준 용어 |
| PNR | Passenger Name Record, 예약 참조 번호 | 6자리 영문+숫자 조합 |
| Inventory | 잔여 좌석/객실 수량 | 재고가 아님 — 물류 용어와 다름 |
| Fare Class | 요금 등급 코드 (Y, B, M, H 등) | 좌석 등급(이코노미/비즈니스)과 다름 |
| GDS | Global Distribution System, 항공/호텔 예약 중계 시스템 | Amadeus, Sabre 등 |
| Voucher | 숙소 바우처, 현장 제시용 확인서 | 할인 쿠폰이 아님 |
| Markup | 판매가 - 원가 차이 (우리 마진) | HTML 마크업과 무관 |
“Markup”이 좋은 예시다. AI에게 “markup을 계산하는 함수를 만들어줘”라고 하면, 맥락 없이는 HTML 마크업 파싱 함수를 만들 수도 있다. 도메인 용어 사전이 있으면 이런 혼선이 사라진다.
용어 사전의 두 번째 효과: 코드에서 사용하는 이름이 통일된다. “Booking”을 어떤 곳에서는 “Reservation”, 다른 곳에서는 “Order”라고 부르는 네이밍 혼란을 막을 수 있다. AI는 용어 사전에서 정한 이름만 쓰게 된다.
실무 팁: 용어를 100개 나열하지 말 것. 혼동 가능성이 높은 것 10~20개면 충분하다. 누구나 아는 범용 용어(“사용자”, “로그인”)는 넣지 않는다.
5. 디렉터리 지도
AI에게 “어디에 파일을 만들어야 하는지”를 알려주는 섹션이다. 프로젝트 구조가 있으면 AI는 그 구조를 존중한다. 없으면 자기 판단으로 아무 데나 만든다.
## 디렉터리 구조
```
src/travelbook/
├── api/ # FastAPI 라우터 (HTTP 표면)
│ ├── bookings.py # /v1/bookings 엔드포인트
│ ├── search.py # /v1/search 엔드포인트
│ └── payments.py # /v1/payments 엔드포인트
├── core/ # 비즈니스 로직 (외부 의존 없음)
│ ├── booking.py # 예약 생성·수정·취소
│ ├── pricing.py # 요금 계산·마크업 적용
│ └── inventory.py # 재고(좌석/객실) 확인
├── adapters/ # 외부 시스템 연동
│ ├── gds.py # GDS API 클라이언트
│ ├── pg_payment.py # PG사 결제 연동
│ └── email.py # 이메일 발송
├── models/ # Pydantic 스키마 + SQLAlchemy 모델
│ ├── schemas.py # API 요청/응답 스키마
│ └── db.py # DB 모델
├── config.py # 설정 로딩 (환경변수)
└── exceptions.py # 커스텀 예외 클래스
tests/
├── unit/ # 단위 테스트 (외부 의존 mock)
├── integration/ # 통합 테스트 (실제 DB 사용)
└── conftest.py # 공용 fixture
```
### 파일 배치 규칙
- 새 API 엔드포인트 → api/ 에 라우터 파일 추가
- 새 비즈니스 로직 → core/ 에 모듈 추가 (DB/외부API 직접 접근 금지)
- 새 외부 연동 → adapters/ 에 클라이언트 추가
- 테스트는 대응하는 소스 파일과 같은 이름: core/booking.py → tests/unit/test_booking.py
“파일 배치 규칙”이 없으면 디렉터리 트리만으로는 부족하다. 트리가 있어도 새 파일을 어디에 둘지는 별개의 문제다. “비즈니스 로직은 core/에, 외부 연동은 adapters/에”라는 한 줄이 있으면 AI가 절대 잘못된 위치에 파일을 만들지 않는다.
특히 core/ 디렉터리에 “DB/외부API 직접 접근 금지”를 적어둔 것에 주목하자. 이건 아키텍처 의사결정이다. 헥사고날 아키텍처(Hexagonal Architecture), 또는 클린 아키텍처(Clean Architecture)의 의존성 규칙을 한 줄로 강제하는 것이다. 이런 아키텍처 규칙이야말로 코드에서 추론하기 어렵고, 명시해야 하는 것이다.
디렉터리 지도가 있으면 AI가 파일을 새로 만들 때마다 사람이 “거기 아니고 여기에 만들어”라고 정정할 일이 사라진다. 리뷰 비용이 확 줄어든다.
실습 — 레거시 프로젝트에 CLAUDE.md 심기
이론은 충분하다. 지금 당장 해볼 수 있는 실습이다. 여러분의 프로젝트에 CLAUDE.md를 만들어보자.
Step 1: 기본 뼈대 생성
Claude Code를 열고 프로젝트 루트에서 시작한다. 3화에서 이미 /init을 실행했다면 CLAUDE.md가 있을 것이다. 없다면 지금 만든다.
# 터미널에서 Claude Code 실행 후
/init
/init은 프로젝트 구조를 스캔해서 CLAUDE.md 초안을 자동 생성한다. 하지만 이건 시작점일 뿐이다. 자동 생성된 내용은 pyproject.toml이나 package.json에서 읽은 빌드 명령 정도다. 위에서 다룬 5가지 항목 중 1번(빌드 명령)만 채워진 상태다.
Step 2: 5가지 항목 채우기
아래 템플릿을 프로젝트에 맞게 수정한다. 복사해서 붙여넣고, 대괄호 안의 내용만 바꾸면 된다.
# CLAUDE.md — [프로젝트 이름]
## 프로젝트 개요
[한 줄 설명. 이 프로젝트가 뭘 하는지.]
## 1. 빌드 & 테스트
[복사-붙여넣기로 바로 실행 가능한 명령어들]
## 2. 코딩 컨벤션
[린터가 잡지 못하는 팀 규칙들]
## 3. 금지사항
[절대 하면 안 되는 것 7~10개. 이유와 대안 포함]
## 4. 도메인 용어
[혼동 가능성 높은 용어 10~20개. 표 형태 권장]
## 5. 디렉터리 구조
[트리 + 파일 배치 규칙]
이게 전부다. 거창하게 시작하지 말자. 20줄짜리 CLAUDE.md가 0줄보다 백 배 낫다.
Step 3: 효과 확인
CLAUDE.md를 만들었으면 바로 검증해보자. AI에게 이전에 잘못했던 유형의 작업을 시켜본다.
# CLAUDE.md가 없을 때 AI가 raw SQL을 짰던 그 작업을 다시 시킨다
"BookingRepository에 날짜 범위로 예약을 검색하는 메서드를 추가해줘.
체크인 날짜가 start_date ~ end_date 사이인 예약만 반환."
CLAUDE.md에 “raw SQL 금지 → SQLAlchemy ORM 사용”이 적혀 있으면, 이번에는 ORM 쿼리로 짠다. “테스트는 tests/unit/에 대응 파일로”가 적혀 있으면, 테스트 파일 위치도 맞춘다.
Before/After를 비교해보면 차이가 체감된다.
# Before (CLAUDE.md 없음) — AI가 만든 코드
class BookingRepository:
async def find_by_date_range(self, start: date, end: date):
query = "SELECT * FROM bookings WHERE checkin_date BETWEEN $1 AND $2"
rows = await self.db.fetch(query, start, end)
return [dict(r) for r in rows]
# After (CLAUDE.md 있음) — AI가 만든 코드
class BookingRepository:
async def find_by_date_range(
self, start: date, end: date
) -> Sequence[Booking]:
stmt = (
select(Booking)
.where(Booking.checkin_date.between(start, end))
.order_by(Booking.checkin_date)
)
result = await self.session.execute(stmt)
return result.scalars().all()
After 코드는 ORM을 쓰고, 타입 힌트가 있고, 정렬까지 우리 컨벤션에 맞다. CLAUDE.md 한 파일의 차이다.
레거시 암묵지가 온보딩 문서로 바뀌는 순간
여기서 예상치 못한 부수 효과가 하나 있다.
CLAUDE.md를 쓰려고 팀의 암묵지를 정리하다 보면, 자연스럽게 신입 온보딩 문서가 만들어진다. 생각해보면 당연하다. AI에게 알려줘야 하는 것 = 새로 합류한 사람에게 알려줘야 하는 것이다.
- 빌드 방법 → 신입이 첫날 환경을 세팅하는 가이드
- 코딩 컨벤션 → 첫 PR 리뷰에서 깨지지 않는 비결
- 금지사항 → “이것만은 하지 말아줘”의 목록
- 도메인 용어 → 회의에서 무슨 말인지 알아듣기 위한 사전
- 디렉터리 지도 → “이 파일 어디 있어요?” 질문 90% 차단
규제가 강한 환경이나 감사 이력이 남아야 하는 조직에서는 이 효과가 더 크다. 암묵지를 문서화하는 건 컴플라이언스 요구사항이기도 하다. AI를 위해 쓴 문서가 감사 대비 문서가 되는 것이다.
나는 실제로 팀에서 CLAUDE.md를 도입한 뒤 “신입 온보딩 기간이 줄었다”는 피드백을 받았다. AI를 위해 쓴 게 사람한테도 통한 것이다. 위임할 줄 아는 사람이 조직의 지식을 구조화하는 사람이 된다.
함정 — 500줄짜리 CLAUDE.md가 성능을 깎는 이유
여기까지 읽으면 “그럼 최대한 자세히 쓰면 좋은 거 아냐?”라는 생각이 든다. 그래서 함정에 빠진다.
내가 처음 CLAUDE.md를 쓸 때의 실수: 500줄짜리 대서사시를 만들었다. 코딩 컨벤션 200줄, 도메인 용어 100줄, 디렉터리 구조 100줄, 금지사항 50줄, 기타 50줄. “이 정도면 AI가 완벽하게 이해하겠지”라고 생각했다.
결과는 정반대였다.
AI의 응답이 오히려 느려졌다. 더 중요한 건, 정말 중요한 규칙을 놓치기 시작했다. 500줄 중에 “Decimal 사용” 규칙이 묻혀서 float로 금액을 계산하는 코드가 나왔다. 정보가 너무 많으면 핵심이 희석된다. 사람이 100페이지짜리 매뉴얼을 대충 훑는 것과 같은 원리다.
Claude Code의 공식 문서에서도 CLAUDE.md를 간결하게 유지하라고 권장한다. 이유는 명확하다:
- 컨텍스트 윈도우(context window): AI가 한 번에 처리할 수 있는 텍스트 분량에는 물리적 한계가 있다. CLAUDE.md가 길면 그만큼 실제 코드를 볼 수 있는 공간이 줄어든다.
- 주의(attention) 분산: 정보가 많으면 각 규칙에 할당되는 가중치가 떨어진다. 10줄짜리 금지사항의 각 항목은 100줄짜리 금지사항의 각 항목보다 더 확실하게 지켜진다.
- 모순 위험: 길어질수록 앞에서 한 말과 뒤에서 한 말이 충돌할 가능성이 높아진다. AI는 모순을 발견하면 어느 쪽을 따를지 자체 판단하는데, 그 판단이 의도와 다를 수 있다.
적정 분량은 얼마인가
경험칙으로 프로젝트 루트 CLAUDE.md는 100~200줄이 적정선이다. 모든 컨벤션을 다 적으려 하지 말고, “AI가 모르면 즉시 문제가 되는 것”만 적는다.
다음 체크리스트로 줄일 수 있다:
- ✂️ 린터/포매터가 이미 잡는 규칙을 적었는가? → 삭제. AI는
ruff나eslint결과를 읽고 자기 코드를 고칠 수 있다. - ✂️ 코드를 보면 바로 알 수 있는 패턴을 적었는가? → 삭제. 기존 코드의 95%가 따르는 패턴이면 AI도 추론한다.
- ✂️ “일반적인 모범 사례”를 적었는가? → 삭제. “변수명을 의미 있게 지어라” 같은 건 AI가 기본으로 안다.
- ✂️ 특정 파일에서만 적용되는 규칙을 프로젝트 루트에 적었는가? → 해당 디렉터리 CLAUDE.md로 이동.
줄이고 나면 남는 건 진짜 중요한 것들이다. 팀만의 고유 규칙, 반직관적인 결정, 과거 장애에서 배운 교훈. 이것들이 CLAUDE.md의 진짜 가치다.
너무 짧은 것도 문제다
반대의 함정도 있다. 5줄짜리 CLAUDE.md에 “Python 프로젝트입니다. pytest 쓰세요.”만 적으면, 그건 없는 것과 크게 다르지 않다. AI가 pyproject.toml에서 자체 추론하는 것보다 나을 게 없다.
적정 분량 가이드:
- 소규모 프로젝트 (1~3명, 파일 50개 이하): 50~100줄
- 중규모 프로젝트 (3~10명, 파일 200개 이하): 100~200줄
- 대규모 프로젝트 (10명 이상): 프로젝트 루트 150줄 이내 + 디렉터리 CLAUDE.md 활용
규모에 상관없이 프로젝트 루트 CLAUDE.md는 200줄을 넘기지 않는 것을 권한다. 넘기게 되면 그건 디렉터리 분리의 신호다.
분리가 필요한 시점
200줄이 넘어가기 시작하면, 특정 모듈에만 해당하는 규칙을 디렉터리 CLAUDE.md로 옮길 때다.
# 프로젝트 루트 CLAUDE.md에서 결제 관련 규칙을 빼고
# src/payment/CLAUDE.md로 이동
# Before: 루트 CLAUDE.md 250줄
# After: 루트 CLAUDE.md 170줄 + src/payment/CLAUDE.md 50줄
# + src/search/CLAUDE.md 30줄
이렇게 하면 AI가 결제 코드를 작업할 때는 루트 + payment 규칙이 로드되고, 검색 코드를 작업할 때는 루트 + search 규칙이 로드된다. 불필요한 정보가 줄고, 핵심 규칙에 집중할 수 있다.
CLAUDE.md도 유지보수 대상이다
마지막 함정. CLAUDE.md를 한 번 쓰고 방치하면 점점 현실과 괴리가 벌어진다. 컨벤션이 바뀌고, 디렉터리 구조가 바뀌고, 새 도구를 도입하는데 CLAUDE.md는 그대로다. AI가 6개월 전 규칙대로 코드를 짜는 상황이 벌어진다.
해법: 코드 변경이 CLAUDE.md의 진술을 깨면, 같은 PR에서 CLAUDE.md도 함께 고친다. 이건 코드 옆에 두는 문서의 보편적 원칙이다. PR 리뷰 체크리스트에 “CLAUDE.md 동기화 확인”을 넣어두면 잊을 일이 없다.
이번 회차의 수익화 지점
CLAUDE.md를 잘 쓰는 능력은 다음과 같은 형태로 가치를 만든다.
팀 컨설팅: “우리 팀에 AI 도구를 도입했는데 효과가 없어요”라는 조직의 90%는 CLAUDE.md가 없거나 부실하다. 해당 팀의 암묵지를 인터뷰해서 CLAUDE.md로 구조화해주는 것 자체가 컨설팅 상품이 된다. 암묵지 → 문서화는 20년 경력이 10년 경력보다 잘할 수밖에 없는 영역이다.
CLAUDE.md 템플릿 팩: 업종별 · 기술 스택별 CLAUDE.md 시작 템플릿을 모아 판매할 수 있다. “FastAPI 프로젝트용”, “Next.js 프로젝트용”, “데이터 파이프라인용” 같은 분류. 오늘 만든 여행 예약 시스템 템플릿이 바로 그 재료다. 12화에서 다룰 ‘플러그인 패키징’과 연결하면 마켓플레이스 배포까지 갈 수 있다.
신입 온보딩 가속: 자기 회사에서 CLAUDE.md 도입 → 온보딩 시간 단축이 정량적으로 확인되면, 그 사례를 강의나 블로그 콘텐츠로 만들 수 있다. “CLAUDE.md 하나로 신입 첫 PR까지 3일 → 1일”이 실제 사례로 나오면 설득력이 다르다.
위임할 줄 아는 사람이 하나의 회사가 된다. CLAUDE.md는 그 위임의 기반 문서다.
다음 회 예고: CLAUDE.md가 ‘이렇게 해줘’라면, 6화의 주제는 ‘이것만은 하지 마’. 권한 모드, OS 레벨 샌드박싱, 그리고 AI가 절대 우회할 수 없는 유일한 통제점 — 훅(Hooks)을 다룬다. 프롬프트에 “하지 마”라고 쓰는 건 통제가 아니다.
시리즈 내비게이션
- 이전: 4화 — 프롬프트가 아니라 작업 지시서를 쓴다
- 다음: 6화 — 권한과 훅: AI의 행동 범위를 통제하는 법
- 관련: 3화 — 첫 30분, 설치부터 첫 성공까지 | 9화 — Skills: 반복 작업을 자동화하는 나만의 도구
◀ 이전 4화 (다음 차수는 아직 게시되지 않았습니다)
자주 묻는 질문
CLAUDE.md에 꼭 넣어야 할 내용은 무엇인가요?
빌드 명령, 코딩 컨벤션, 금지사항, 도메인 용어, 디렉터리 지도 이 5가지를 넣으면 80%는 해결됩니다. 이 항목들은 팀의 암묵지를 AI가 읽을 수 있는 형태로 명시해 주는 역할을 합니다.
CLAUDE.md를 너무 길게 쓰면 어떻게 되나요?
500줄을 넘기면 오히려 AI 성능이 떨어집니다. 짧고 정확하게 핵심 규칙만 담는 것이 가장 효과적이며, 불필요한 설명을 줄이고 팀에서 실제로 지켜야 하는 규칙 위주로 작성해야 합니다.
CLAUDE.md 없이 프롬프트에만 규칙을 적으면 안 되나요?
팀의 암묵지는 네이밍 규칙, 에러 처리 패턴, 디렉터리 구조, 프레임워크 선택 등 수십 개에 달하기 때문에 매번 프롬프트에 다 적을 수 없습니다. CLAUDE.md에 한 번 정리해두면 AI가 코드를 건드리기 전에 반드시 읽게 되므로, 반복적인 실수를 줄이고 코드 리뷰 부담도 낮출 수 있습니다.
[…] [Claude 활용 24회 — AI에게 일을 위임하는 법] 5/24화: CLAUDE.md 작성법 5가지 — … […]
[…] 시리즈: Claude 활용 24회 — AI에게 일을 위임하는 법 (총 24화 중 6화)◀ 이전 5화 (다음 차수는 아직 게시되지 […]