18개월간 실무에서 사용해 본 5가지 CLAUDE.md 패턴
5 CLAUDE.md patterns I use in production after 18 months
핵심 요약
Claude Code를 실무에 적용하며 얻은, 모델의 성능을 극대화하는 CLAUDE.md 작성 노하우를 공유합니다.
- 아키텍처 제약 — 모호한 설명 대신 명확한 금지 규칙과 행동 지침을 설정함
- 코드 검색 지시 — 새로운 코드 작성 전 기존 패턴을 grep하도록 강제함
- 예시 파일 참조 — 장황한 설명 대신 모범 사례가 담긴 파일을 직접 링크함
- 세션 체크리스트 — 방대한 문맥 대신 필수 확인 사항 위주로 간결하게 구성함
20만 줄이 넘는 TypeScript 코드베이스(NestJS 백엔드, Next.js 프론트엔드, 모노레포)에서 1년 반 정도 Claude Code를 돌려봤거든. 그동안 CLAUDE.md 파일만 한 40번은 갈아엎은 것 같다. 이것저것 시도해보고 버린 것들 말고, 진짜 효과 본 패턴 5가지만 정리해봄.
1. 아키텍처 경계는 '설명'이 아니라 '절대 넘지 마'라는 규칙으로 박아라
초반에는 CLAUDE.md에 "우리는 도메인, 애플리케이션, 인프라 계층으로 나뉜 클린 아키텍처를 쓴다"라고 적어놨었음. 근데 이건 그냥 문서일 뿐이라 모델이 바쁠 땐 그냥 배경 지식 정도로 치부하고 무시하더라. 그래서 아예 강제 제약 조건으로 바꿨음: "도메인 계층은 인프라 계층을 절대 임포트하지 마. 도메인 파일에 NestJS 데코레이터가 필요하면 일단 멈추고 나한테 물어봐." 이렇게 모델이 절대 하면 안 되는 행동으로 규정하고, 멈춰야 할 구체적인 트리거를 주니까 코드 생성할 때 아키텍처 경계 넘기는 일이 확 줄었음. 설명은 대충 훑고 지나가지만, 제약 조건은 확실히 체크하거든.
2. "쓰기 전에 grep부터 해라"는 무조건 넣어야 함
이 파일에서 가장 가성비 좋은 한 줄임: "새로운 함수나 타입을 구현하기 전에, 코드베이스에서 이미 비슷한 게 있는지 grep부터 해라." 이거 넣기 전에는 모델이 기존 코드 대신 지 학습 데이터만 믿고 UserProfile 타입을 또 만들거나, 날짜 포맷팅 헬퍼를 3개씩 만들어대서 골치 아팠음. 딱 한 문장인데, 그 어떤 규칙보다 값어치를 톡톡히 함.
3. 줄글로 설명하지 말고 코드 예시를 찍어줘라
예전에는 에러 핸들링 규칙을 문단으로 길게 설명했었음. 지금은 그냥 CLAUDE.md에 "에러 핸들링 패턴은 src/shared/errors/http-error.ts를 봐라. 그 형태 그대로 따라해"라고 적고, 관심사별로(유효성 검사, 에러 처리, 리포지토리 패턴 등) 표준이 되는 파일 2~3개를 링크 걸어둠. 모델은 글로 쓴 사양을 읽는 것보다 기존 파일을 보고 패턴을 맞추는 걸 훨씬 잘함. 이제는 규칙 하나 설명하려고 두 문장 이상 쓰게 되면, 그냥 파일 참조로 바꿔버림.
4. 세션 시작 체크리스트를 만들어라, 문맥을 벽처럼 쌓지 말고
한동안 내 CLAUDE.md는 거의 위키 수준이었음. 기술 스택, 컨벤션, 히스토리까지 3,000단어가 넘었거든. 근데 세션 시작할 때 보니까 모델이 그 내용을 거의 안 쓰더라고. 그래서 상단에 짧은 체크리스트로 다 쳐냈음: package.json 읽기, 작업이랑 관련된 파일 2~3개 읽기, 새 테스트 짜기 전에 기존 테스트 파일 있는지 확인하기. 나머지는 다 링크된 문서로 빼서, 모델이 그 영역을 건드릴 때만 읽게 만들었음. 세션 시작도 빨라졌고, 무엇보다 모델이 텍스트 뭉치를 대충 훑는 대신 체크리스트를 진짜로 지키기 시작함.
5. 모르면 추측하지 말고 확실히 말하라고 시켜라
"변경 사항이 시스템의 다른 부분에 영향을 주는지 확실하지 않으면, 코드 짜기 전에 미리 말해. 추측해서 진행하지 마." 이건 결과물의 퀄리티보다는 신뢰도 문제임. 이거 넣기 전에는 모델이 공유 코드 건드릴 때 지 맘대로 확신에 차서 틀린 코드를 짜놓는 경우가 있었음. 이제는 "이거 공유 인증 가드 건드리는 건데, 바꾸기 전에 영향 범위 확인하고 싶어"라고 먼저 말해주니까, 내가 diff 리뷰 다 하고 나서 고치는 게 아니라 코드 짜기 전에 미리 방향을 잡아줄 수 있음.
효과 없었던 것들
모델한테 금지 패턴 리스트("any 쓰지 마, as 캐스팅 쓰지 마, 등등...")를 길게 주는 건 거의 다 실패함. 부정적인 지시는 모델이 당장 생성하려는 내용이랑 충돌해서 결국 무시당하더라고. 똑같은 규칙이라도 예시 파일을 가리키는 긍정적인 지시문으로 바꾸는 게 부정적인 버전보다 훨씬 잘 먹혔음.
TL;DR: 설명보다는 제약 조건을 거는 게 훨씬 낫고, "작성하기 전에 grep부터 하라"는 문구는 내가 추가한 것 중 단연 최고임. 줄글로 길게 늘어놓지 말고 파일 위치를 딱 집어주고, 세션 시작 부분은 짧게 끊고, 모델이 모르는 건 숨기지 말고 무조건 털어놓게끔 지시하셈. 뭐 대단한 비법 같은 건 아님. 그냥 18개월 동안 데모용이 아니라 실제 코드베이스에 굴려보면서 살아남은 팁들임.
