DevClaude CodeCLAUDE.md

CLAUDE.md 잘 쓰는 법: 토큰만 낭비하는 안티패턴 5가지

2026.04.16

CLAUDE.md를 처음 쓰면 다 길어진다

Claude Code를 본격적으로 쓰기 시작하면 누구나 CLAUDE.md를 쓰게 된다. 처음 쓰면 점점 길어진다. 내 첫 CLAUDE.md는 800줄이었다. 프로젝트 구조, 컨벤션, 사용 라이브러리, 자주 쓰는 패턴, 디렉토리 설명, 팀 규칙... 모든 걸 적었다.

결과는 이상했다. AI가 내 컨벤션을 더 자주 어겼다. 길게 적을수록 효과가 떨어졌다.

이유를 추적해보니 CLAUDE.md를 쓰는 방법에 대해 내가 잘못 알고 있던 게 많았다. 이 글은 그 잘못된 패턴 5가지와, 거기서 빠져나온 방법이다.

CLAUDE.md가 어떻게 동작하는가

본격 안티패턴 전에 CLAUDE.md가 무엇인지 정리한다.

  • Claude Code 실행 시 작업 디렉토리에서 가장 가까운 CLAUDE.md를 찾아서 시스템 프롬프트에 자동 주입한다
  • 디렉토리별로 따로 둘 수 있다 (예: 프로젝트 루트 + frontend/CLAUDE.md)
  • 모든 세션, 모든 호출에 들어간다 — 토큰 비용이 곱셈으로 누적된다
  • 가장 앞쪽에 들어가는 만큼 캐싱이 잘 된다 — 변하지 않으면 캐시 히트

이 마지막 두 가지가 중요하다. 자주 변하면 캐시가 깨지고, 길면 비용이 누적된다.

안티패턴 1: 일반론 나열

가장 흔한 실수다. 이런 내용이 잔뜩 적혀 있다.

## 코딩 원칙
- 가독성을 우선합니다
- DRY 원칙을 따릅니다
- SOLID 원칙을 지킵니다
- 의미 있는 변수명을 사용합니다
- 주석은 명확하게 작성합니다

이건 토큰을 버리는 거다. AI는 이런 일반론을 이미 알고 있다. "가독성을 우선한다"라고 적어도, 적지 않아도 똑같이 가독성 있는 코드를 만들려 한다.

CLAUDE.md에 적어야 하는 건 AI가 모르는 것, 또는 다르게 적용해야 하는 것이다.

## 이 프로젝트의 특이 규칙
- DRY보다 명확성 우선 — 3번 반복까지는 추상화하지 않는다 (과거 inv-432 경험)
- 의미 있는 변수명 우선이지만, 회계 도메인 약어(AR, AP, GL)는 그대로 사용

같은 "가독성" 주제라도, 우리 프로젝트의 규칙은 일반론과 다르다는 걸 적는다.

안티패턴 2: 디렉토리 구조 설명

이런 내용도 자주 본다.

## 프로젝트 구조
- src/components/ : React 컴포넌트
- src/lib/ : 유틸리티 함수
- src/api/ : API 라우트
- src/hooks/ : 커스텀 훅
...

AI는 ls나 Glob을 한 번 돌리면 즉시 알 수 있는 정보다. 굳이 토큰을 써서 매번 주입할 필요가 없다.

대신 구조에서 직관과 다른 부분만 적는다.

## 구조 주의사항
- src/api/는 Next.js Route Handler가 아니라 클라이언트 호출 래퍼들
- 실제 API는 services/* 디렉토리에 있음

이건 추측만으로는 알 수 없는 부분이다. 이게 CLAUDE.md의 자리다.

안티패턴 3: 모든 라이브러리 나열

## 사용 라이브러리
- React 19
- Next.js 15
- Tailwind CSS 4
- Zustand
- React Query
- Zod
- ...

package.json을 보면 다 나오는 정보다. AI는 필요할 때 읽는다.

써야 하는 건 라이브러리 자체가 아니라 선택 이유와 사용 제약이다.

## 라이브러리 사용 규칙
- 상태 관리는 Zustand만 — Redux/Jotai 도입 금지 (논의된 결정)
- 서버 상태는 React Query, 클라이언트 상태는 Zustand로 명확히 분리
- form 라이브러리는 react-hook-form + zod 조합만 사용

라이브러리 이름이 아니라 결정의 이유를 적는다. 이게 AI가 추측으로는 알 수 없는 부분이다.

안티패턴 4: 자주 변하는 정보 적기

이게 가장 비싼 안티패턴이다.

## 현재 진행 중인 작업
- feature/login 브랜치에서 OAuth 작업 중
- 다음 주까지 결제 모듈 마무리 예정
- TODO: 검색 기능 리팩토링

이런 정보는 며칠 단위로 변한다. CLAUDE.md가 변하면 프롬프트 캐시가 통째로 깨진다. 캐싱 글에서 다뤘듯이 캐시가 깨지면 비용이 즉시 뛴다.

자주 변하는 정보는 다른 곳으로 보낸다.

  • TODO는 GitHub Issues, Linear, Notion 등으로
  • 진행 중인 작업은 git branch 이름과 PR description으로
  • 일정은 캘린더로

CLAUDE.md에는 3개월 이상 안 바뀔 내용만 둔다. 이 기준으로 거르면 절반은 빠진다.

안티패턴 5: 명령형 톤이 약하다

이런 표현을 자주 본다.

- 가능하면 함수형 스타일을 선호합니다
- 클래스보다는 함수를 권장합니다
- 인터페이스 사용을 검토하세요

"가능하면", "권장합니다", "검토하세요"는 AI가 무시하기 좋은 표현이다. AI는 부드러운 권고와 강한 규칙을 구분한다. 강한 규칙이 아니면 상황에 따라 어긴다.

규칙이라면 단호하게 적는다.

- 함수형 스타일만 사용. 새 클래스 도입 금지
- 인터페이스 대신 type 별칭 사용 (프로젝트 컨벤션)

"금지", "만 사용", "필수" 같은 명확한 단어를 쓴다. 권고와 규칙이 섞이면 AI가 어떤 게 어떤 건지 헷갈린다.

짧고 강력한 CLAUDE.md 쓰는 원칙

위 안티패턴을 거르고 나면 본질이 남는다. 내가 굳어진 원칙은 이렇다.

원칙 1: AI가 추측 못 하는 것만 적는다

ls, package.json, 코드 자체에서 추측 가능한 정보는 빼라. AI에게 추측 비용은 싸다 (Glob 한 번). CLAUDE.md 토큰은 비싸다 (모든 호출에 곱하기).

원칙 2: 결정의 이유를 적는다

"무엇을 쓴다"보다 "왜 그걸 골랐는지"를 적는다. 이유가 같이 있으면 AI가 엣지 케이스에서도 같은 방향의 결정을 한다.

원칙 3: 자주 변하는 건 외부로 빼라

3개월 이상 안 바뀔 내용만 둔다. 그 외에는 git, issue tracker, slack 등 휘발성 도구로 보낸다.

원칙 4: 명령형, 단호하게

권고와 규칙을 섞지 않는다. 규칙은 "금지", "필수", "만". 권고는 빼라.

원칙 5: 디렉토리별 CLAUDE.md를 활용

루트에 모든 걸 적지 말고, frontend/CLAUDE.md, backend/CLAUDE.md처럼 분산한다. AI는 작업 디렉토리에 가까운 것을 우선 읽는다. 토큰 사용도 균형 잡힌다.

내 현재 CLAUDE.md

이 블로그 프로젝트의 루트 CLAUDE.md는 짧다. 50줄도 안 된다. 안에는 이런 게 있다.

  • 이 프로젝트가 Cloudflare Pages에 배포된다는 사실 (Vercel 가정 방지)
  • Next.js 버전이 최신이라 일부 API가 다르다는 경고
  • 표 대신 시각화 컴포넌트를 쓴다는 규칙
  • 브랜치 워크플로우 (master 직접 커밋 금지)
  • Obsidian 블로그 시드 폴더 위치

전부 "AI가 추측 못 하고, 결정의 이유가 있고, 변하지 않는" 정보다. 길게 적던 시절보다 컨벤션을 더 잘 따른다. 짧을수록 강력하다는 게 직관에 어긋나지만 사실이다.

정리

CLAUDE.md는 매 세션, 매 호출에 들어가는 가장 비싼 위치다. 그 자리에 일반론을 채우면 가치 없는 토큰만 남는다.

다섯 가지 안티패턴을 한 줄씩 정리한다.

  1. 일반론 나열 — AI가 이미 안다
  2. 디렉토리 구조 설명 — Glob 한 번이면 된다
  3. 모든 라이브러리 나열 — package.json에 있다
  4. 자주 변하는 정보 — 캐시를 깬다
  5. 약한 톤 — AI가 무시한다

지금 CLAUDE.md를 열어서 이 다섯 항목으로 한 번 거르면, 길이가 절반 이하로 줄 거다. 그리고 그 짧아진 파일이 더 강하게 동작한다. 토큰 효율은 부수 효과다. 진짜 효과는 AI가 우리 컨벤션을 더 잘 따른다는 거다.