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

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는 지금 9줄이다

안티패턴을 늘어놨으니 내 것도 공개하는 게 맞겠다. 이 블로그 레포의 CLAUDE.md는 지금 9줄이고, 그중 첫 줄은 @AGENTS.md 한 줄짜리 import다. 불려오는 AGENTS.md는 5줄이다. 합쳐서 14줄.

AGENTS.md에 뭐가 있냐면 딱 이거다. 이 프로젝트의 Next.js는 당신이 아는 그 Next.js가 아니고, 코드를 쓰기 전에 node_modules/next/dist/docs/의 해당 가이드를 읽으라는 것.

이 다섯 줄이 «코드를 깔끔하게 짜세요» 같은 문장 백 줄보다 낫다. 에이전트가 모르는 사실 하나를 알려주기 때문이다. 깔끔하게 짜라는 말은 이미 아는 이야기라 토큰만 먹고 아무것도 바꾸지 못한다.

나머지 8줄은 세션에서 나온 글감을 Obsidian 어느 경로에 저장할지다. 이것도 같은 성격이다 — 경로는 알려주지 않으면 절대 모른다.

기준은 하나로 정리됐다. 읽지 않으면 틀리게 될 내용만 남긴다. 읽든 안 읽든 결과가 같은 문장은 지운다.

정리

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

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

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

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