[TIL][Claude Code] CLAUDE.md 가 500줄이 된 이유

2025년 12월에 Claude Code 를 처음 접했다

CLAUDE.md 는 10줄이었다

# CLAUDE.md
- Python 프로젝트
- 한국어로 대답해줘
- pytest-bdd 사용

3개월 뒤, 506줄이 되었다

왜 늘어나는가

같은 실수가 반복되기 때문이다

Claude Code 는 대화가 끝나면 컨텍스트를 잊는다

"Step 파일에 locator 직접 쓰지 마" 라고 말해도 다음 대화에서 또 쓴다

그래서 CLAUDE.md 에 적는다

❌ 금지: Step 안에 UI 탐색 로직, 폴백 전략, 대기 코드 직접 작성
✅ 필수: Page Object 메서드 호출 + context 관리 + 로깅만

한 번 적으면 매 대화 시작 시 자동으로 읽는다

더 이상 말로 반복할 필요가 없다

규칙이 추가된 실제 과정

Phase 1: 기본 설정 (12월)

- 한국어로 대답
- pytest-bdd, Playwright 사용
- POM 패턴 준수

이 정도면 될 줄 알았다

Phase 2: "이거 하지 마" 가 쌓이기 시작 (1월)

Claude 가 자꾸 하는 것들:

Step 파일에 page.locator() 직접 씀             → 규칙 추가
Page Object 에 셀렉터 문자열 하드코딩            → 규칙 추가
except Exception: pass 로 에러 무시             → 규칙 추가
bool("false") 가 True 되는 버그                → 규칙 추가
커밋 메시지에 Test Case ID 넣음                 → 규칙 추가

한 건씩 터질 때마다 한 줄씩 추가됐다

Phase 3: 규칙만으로 안 되는 것들 (2월)

규칙을 써놔도 무시하는 경우가 있었다

CLAUDE.md: "XPath 사용 금지"
Claude: (XPath 사용)
나: "왜 XPath 썼어?"
Claude: "죄송합니다, 수정하겠습니다"
(다음 대화)
Claude: (또 XPath 사용)

그래서 Hook 으로 강제하기 시작했다

CLAUDE.md 에 규칙 작성  → 읽긴 하는데 가끔 무시
Hook 으로 차단 (exit 2) → 물리적으로 못 씀

CLAUDE.md 에는 "왜 안 되는지" 설명, Hook 에는 "차단" 로직

둘이 같이 가야 한다

Phase 4: 구조화 (3월)

500줄이 되니까 Claude 가 필요한 규칙을 못 찾는 문제가 생겼다

# 이전: 규칙이 시간순으로 나열
- 금지 1
- 금지 2
- 금지 3
(200줄 뒤)
- 금지 47

# 이후: 카테고리별 정리 + 문서 분리
## 🔐 보안 규칙
## 🔴 자주 위반하는 규칙
## ✅ Hook 이 자동으로 막아주는 것
## 📝 새 코드 작성 체크리스트
## 📚 상세 문서 (필요할 때 참고)

자주 위반하는 규칙은 맨 위로 올렸다

Claude 가 CLAUDE.md 를 읽을 때 앞부분에 더 가중치를 두기 때문이다

상세 규칙은 별도 문서로 분리하고 CLAUDE.md 에서는 참조만 한다

## 📚 상세 문서 (필요할 때 참고)
| 카테고리 | 문서 | 설명 |
|---------|------|------|
| 코드 작성 | docs/LOCATOR_STRATEGY.md | 로케이터 우선순위 |
| 코드 작성 | docs/POM_STRUCTURE.md | Page Object 패턴 |
| 문제 해결 | docs/TROUBLESHOOTING.md | Timeout, Strict Mode 등 |

현재 구조 (v3, 506줄)

섹션	줄 수	역할
보안 규칙	~30줄	API 키, 비밀번호 관련
작업 시작 전 확인	~30줄	이슈 목록, data-testid 요청
자주 위반하는 규칙	~150줄	MCP 먼저, POM 패턴, 로케이터 분리, 디버깅, 컨텍스트
Hook 이 막아주는 것	~30줄	자동 강제되는 규칙 목록
품질 게이트	~30줄	셀프 리뷰 체크리스트
새 코드 작성 체크리스트	~80줄	Feature/Step/Page Object 별
기본 규칙	~20줄	한국어, 코드 스타일
프로젝트 구조	~20줄	디렉토리 설명
상세 문서 참조	~30줄	docs/ 링크 테이블
스킬 가이드	~20줄	어떤 상황에 어떤 커맨드
주요 명령어	~30줄	make, pytest 명령어
자주 하는 실수	~20줄	Timeout, Strict Mode 해결
Git 작업 규칙	~30줄	커밋, amend, black

🐣 나의 CLAUDE.md 작성 요령

1. "하지 마" 와 "해라" 를 같이 쓴다

# ❌ "하지 마" 만 쓰면
- XPath 사용 금지

# ✅ 대안까지 같이 써야 한다
❌ 금지: page.locator("//button[@class='save']")
✅ 필수: page.get_by_role("button", name="저장")

금지만 쓰면 Claude 가 뭘 해야 하는지 모른다

2. 왜 안 되는지도 쓴다

# ❌ 이유 없이
- bool() 함수 금지

# ✅ 이유와 함께
# bool("false") 는 True 가 된다 (버그!)
if headless_str == 'true':
    headless = True
else:
    headless = False

이유가 있으면 비슷한 상황에서 스스로 판단할 수 있다

3. 자주 위반되는 규칙은 앞으로

Claude 가 컨텍스트 윈도우 앞부분에 더 집중한다

500줄 중 400번째 줄에 있는 규칙은 종종 무시된다

4. Hook 으로 강제할 수 있으면 Hook 으로

CLAUDE.md 규칙은 권고, Hook 은 강제

CLAUDE.md: "Step 에 page.locator() 쓰지 마"  → 가끔 무시됨
Hook (exit 2): Step 에 page.locator() 감지 → 편집 차단  → 100% 방어

둘 다 쓰되, 중요한 건 Hook 으로 이중 방어한다

5. 문서가 길어지면 분리한다

# CLAUDE.md — 핵심만 (500줄)
# docs/LOCATOR_STRATEGY.md — 상세 (필요할 때만)
# docs/POM_STRUCTURE.md — 상세 (필요할 때만)

CLAUDE.md 는 매 대화 시작 시 전부 읽는다

2000줄이면 토큰 낭비가 심하다

핵심만 남기고 나머지는 docs/ 로 빼야 한다

규칙 추가 기준

아무거나 다 넣으면 안 된다

✅ CLAUDE.md 에 넣어야 하는 것:
- 2회 이상 반복된 실수
- 말로 교정이 안 되는 것 (매번 같은 실수)
- 프로젝트 전체에 적용되는 규칙

❌ CLAUDE.md 에 안 넣어도 되는 것:
- 1회성 실수 (한 번 말하면 고쳐지는 것)
- 특정 파일에만 해당하는 것 (해당 파일 주석으로)
- 코드를 읽으면 알 수 있는 것 (구조, 패턴 등)

주의점

• CLAUDE.md 가 너무 길면 오히려 역효과 — 핵심이 묻힌다
• 규칙과 Hook 이 모순되면 안 된다 (CLAUDE.md 는 허용하는데 Hook 이 막으면 혼란)
• 버전을 관리한다 — v1 → v2 → v3 로 구조를 개선하면서 중복/불필요한 규칙을 정리