심화 — CLAUDE.md 관리·최적화

CLAUDE.md는 세션이 시작될 때 항상 주입된다. 세 도구 중 '항상 필요한 사실'을 담는 자리 — 그래서 무작정 많이 넣으면 안 된다. 정보의 '중복'이 성능 하락과 비용 증가의 핵심 원인이다.

세 도구 — 어디에 무엇을항상 필요한 '사실'은 CLAUDE.md에, '절차'는 스킬에, 반드시 지켜야 할 '강제'는 훅에.

① 중복 정보를 넣지 마라

React 18 · TypeScript · React Query 같은 정보는 Claude가 package.json을 열어 스스로 알 수 있다. 굳이 적을 필요가 없다.

불일치의 함정실제 package.json은 버전 19로 올라갔는데 CLAUDE.md에는 18로 적혀 있다면 — 이 불일치가 LLM에게 혼란을 주어 오히려 성능을 떨어뜨린다.

문제	/init은 프로젝트 전체를 훑느라 시간과 토큰을 크게 소모한다.
남는 것	디렉토리 구조, build.gradle처럼 AI가 스스로 파악할 수 있는 뻔한 정보가 파일에 기록된다.
권장	자동 생성된 정보는 지운다. 아예 /init을 쓰지 않고 직접 작성하는 편이 낫다.

남겨야 할 필수 정보팀만의 컨벤션 · 금지 사항 · 아키텍처 결정 이유(ADR) — 파일을 열어봐도 알 수 없는, 항상 알아야 하는 핵심 사실만.

금지만 하면 AI가 수많은 대안 중 무작위로 하나를 고른다. 반드시 대안을 명시한다.

이렇게 쓰면 (✗)	이렇게 써야 (✓)
Lodash 쓰지 마라 → AI가 다른 라이브러리를 임의로 선택	Lodash 금지 — 대신 Native Array / Object를 사용하라 → 의도대로 동작

공식 문서는 CLAUDE.md를 200줄 이내로 관리할 것을 권장한다. 넘칠 경우 별도 규칙 파일을 만들고, 최상단 프론트매터(Frontmatter)로 적용 조건을 건다.

rules/typescript.md — 조건부 규칙

--- applyTo: "src/**/*.ts" # 이 경로의 TS 파일을 건드릴 때만 주입 --- - 상태 관리는 Zustand만 사용 (Redux 금지) - API 호출은 services/ 레이어를 통해서만 - ...

효과조건에 맞는 파일을 건드릴 때만 규칙이 주입되므로, 평상시 컨텍스트를 크게 아낄 수 있다.

클로드코드 시작하기심화 · CLAUDE.md