Claude Code를 3배 빠르게 만드는 5가지 CLAUDE.md 튜닝 기법

CLAUDE.md 작성 방법에 따라 Claude Code의 응답 정확도, 속도, 토큰 소비량이 크게 달라집니다. - '금지 사항 명시', '컨텍스트 압축', '도구 사용 제약'의 3가지 축이 특히 효과적입니다.

Anthropic에서 제공하는 Claude Code는 프로젝트 루트에 CLAUDE.md를 배치함으로써 에이전트의 동작을 제어할 수 있습니다. 하지만 '일단 적어두자'라는 인식으로 접근하면, 토큰만 소모하는 장황한 지시가 되기 쉽습니다.

본 기사에서는 Claude Code 공식 문서와 실제 시행착오를 거치며 파악한 '실제로 효과적인' 5가지 튜닝 패턴을 소개합니다.

Claude Code는 다음 타이밍에 CLAUDE.md를 읽어 들입니다.

즉, 파일이 길어질수록 컨텍스트 창을 차지하여 실제 작업에 사용할 토큰이 줄어듭니다. '가능한 한 자세하게 작성하자'는 것은 역효과가 될 수 있습니다.

Claude Code는 '무엇을 해야 하는지'보다 **'무엇을 하지 말아야 하는지'**에 대한 지시에 특히 충실하게 움직입니다.

하고 싶지 않은 작업을 서두에 ## 금지 사항 섹션으로 묶어주면, 오작동률이 낮아집니다.

## 금지 사항 (절대 지켜야 할 것)
- `git push --force`는 실행하지 않기
- `DROP TABLE` / `DELETE FROM`을 확인 없이 실행하지 않기
...

포인트: 목록형 동사를 '〜하지 않기'로 통일하는 것이 좋습니다. '〜해주세요' 같은 긍정형과 혼재시키면 우선순위가 모호해집니다.

default 상태의 Claude Code는 필요 이상으로 많은 파일을 Read하려고 합니다.

CLAUDE.md에서 '참조해도 좋은 경로'를 명시해주면 탐색 비용이 줄어들어 응답 속도가 빨라집니다.

Claude Code는 디렉터리에 진입했을 때 이 지침을 읽고 자동으로 멈춥니다.

관점	튜닝 전	튜닝 후
오작동 (강제 푸시 등)	주 1~2건 발생	거의 제로
...
수치는 어디까지나 필자의 환경에서의 체감값이며, 프로젝트 규모・복잡도에 따라 달라집니다.

CLAUDE.md

튜닝의 핵심 포인트를 정리합니다.

금지 사항을 상단에 모으기 — 긍정형과 혼재시키지 않고 '〜하지 않기'로 통일 -
도구 범위를 좁히기 — 참조 OK / 금지 경로를 명시하여 비용 절감 -
용어 사전을 선출시하기 — 프로젝트 고유어를 정의하여 컨텍스트 절약 -
Think Before Act 강제하기 — 설계 메모를 금지 형태로 의무화 -
서브 디렉터리에서 역할 분리하기 — 모노레포는 책임별로 CLAUDE.md를 분할

파일 크기 기준으로, 루트의 CLAUDE.md는 80행 이내에 수렴하도록 의식하면 비대화를 막기 쉽습니다.

✍️ 본 기사 작성자: 合同会社ジモラボ

지모라보는 하치오지에 거점을 두고 AI를 활용한 SaaS를 다수 개발하고 있습니다. 본 기사의 기술 검증 역시 그러한 개발 과정의 부산물입니다.

관심을 가져주시면 각 SNS 팔로우도 부탁드립니다!

claude-code

/ AI

/ 개발 효율화

/ 프롬프트 엔지니어링

/ markdown

요약