CLAUDE.md 최적화 실전법

CLAUDE.md는 짧을수록 강해집니다

CLAUDE.md 최적화의 목적은 많은 규칙을 넣는 것이 아니라 매 세션 반드시 필요한 맥락만 남기는 것입니다. 이 파일은 클로드코드가 시작할 때 읽는 지침이므로 길어질수록 토큰을 차지하고 실제 작업에 쓸 공간을 줄입니다. 좋은 규칙은 구체적이고 검증 가능해야 합니다. "코드를 잘 작성"처럼 넓은 문장보다 "테스트 전에는 npm test를 실행"처럼 행동이 분명한 문장이 낫습니다. 팀 규칙, 빌드 명령, 디렉터리 구조, 반복되는 실수만 남기고 설명성 문단이나 오래된 배경 정보는 정리해야 합니다. 한 줄 규칙으로 바꾸기 어렵다면 매 세션 필요한 정보가 아닐 수 있습니다. 이 기준을 적용하면 파일은 짧아지고 지시는 더 선명해집니다.

반복 설명은 규칙으로 옮깁니다

사용자가 매번 같은 설명을 입력한다면 그 내용은 대화가 아니라 CLAUDE.md에 들어갈 후보입니다. 예를 들어 커밋 규칙, 금지된 라이브러리, 테스트 실행 순서, 리뷰 기준처럼 반복되는 정보는 한 번만 정리해 두는 편이 효율적입니다. 다만 모든 절차를 한 파일에 넣으면 다시 비대해집니다. 특정 디렉터리나 파일 형식에만 필요한 지침은 경로별 규칙으로 분리해야 합니다. 이렇게 하면 클로드코드가 관련 파일을 다룰 때 필요한 지침을 더 쉽게 찾고, 일반 작업에서는 불필요한 맥락을 덜 읽게 됩니다. 개인 취향은 팀 공유 파일에 넣기보다 사용자 지침이나 로컬 파일로 분리하는 편이 충돌을 줄입니다.

중복과 충돌을 정기적으로 제거합니다

CLAUDE.md가 오래 유지되면 같은 규칙이 여러 표현으로 반복되거나 서로 다른 시점의 결정이 충돌할 수 있습니다. 이런 상태에서는 토큰만 낭비되는 것이 아니라 모델이 어느 지시를 우선해야 하는지 판단하기 어려워집니다. 주기적으로 파일을 열어 현재 프로젝트 구조와 맞지 않는 문장, 이미 코드나 설정으로 강제되는 내용, 다른 문서와 중복되는 설명을 삭제해야 합니다. 가져오기 문법을 사용할 때도 주의가 필요합니다. 가져온 파일은 시작 컨텍스트에 함께 들어갈 수 있으므로, 편의를 위해 연결한 문서가 실제로 매 세션 필요한지 확인해야 합니다. 검토할 때는 "지금도 유효한가", "더 좁은 범위로 옮길 수 있는가", "도구 설정으로 대체할 수 있는가"를 기준으로 판단하는 것이 좋습니다.

맺음말

CLAUDE.md 최적화는 클로드코드 토큰 절약의 가장 기본적인 관리 지점입니다. 시작할 때 읽히는 지침이 짧고 정확하면 반복 설명이 줄고, 작업에 필요한 파일과 오류 분석에 더 많은 컨텍스트를 남길 수 있습니다. 핵심은 규칙을 구체적으로 쓰고, 반복 입력을 문서화하며, 경로별 지침으로 범위를 나누고, 오래된 내용을 정기적으로 삭제하는 것입니다. 이 기준을 유지하면 세션이 길어져도 지시가 흐려지는 문제를 줄이고 안정적인 개발 흐름을 만들 수 있습니다. 문서를 많이 쓰는 것보다 필요한 문장만 남기는 편이 실제 비용 관리에 더 직접적으로 도움이 됩니다. 팀에서는 분기마다 규칙을 점검해 불필요한 지침이 다시 쌓이지 않게 관리하는 것이 바람직합니다. 작은 관리가 누적 비용을 낮춥니다.