클로드 코드 실전 팁 4편 - CLAUDE.md 체계적으로 관리하기

CLAUDE.md는 매 세션이 시작할 때부터 함께 읽히는 유일한 파일입니다. 클로드 코드 성능을 결정짓는 가장 큰 요인 중 하나로 꼽히는 이유도 여기 있습니다. 근데 문제는 "안 쓰는 것"이 아니라 "쓰고 나서 방치하는 것"입니다. 좋다고 하니 계속 추가만 하고, 예전에 넣은 규칙이 지금도 맞는지는 아무도 확인하지 않습니다. 방치된 CLAUDE.md는 안 쓰는 것보다 못할 수 있습니다.

늘리기는 쉬운데 줄이는 건 의도적인 노력이 필요합니다. 불필요한 것, 중복된 것, 예전엔 맞았지만 지금은 안 맞는 것들을 주기적으로 걷어내야 이 파일이 진짜 힘을 발휘합니다.

200줄이 넘어가면 일단 의심합니다. 파일시스템만 봐도 뻔히 드러나는 정보(디렉터리 구조, 의존성 목록 같은 것)는 빼고, 저장소의 숨겨진 함정과 관례만 남깁니다. 이런 정보는 코드를 보면 알 수 있는데도 CLAUDE.md에 그대로 옮겨 적어두는 경우가 많은데, 클로드가 코드에서 스스로 파악할 수 있는 내용까지 매 세션 다시 읽게 만들 필요는 없습니다. 저도 성능이 아쉬울 때마다 CLAUDE.md를 열어 불필요한 걸 직접 줄이고, 클로드에게 점검을 맡기기도 합니다.

/doctor 커맨드로 이걸 자동으로 점검할 수도 있습니다. 클로드가 코드베이스에서 알아낼 수 있는 내용은 잘라내고, 다른 방식과 다르게 동작하는 부분이나 함정, 근거처럼 정말 남겨야 할 것만 골라 정리안을 제안해줍니다.

CLAUDE.md 하나에 다 넣지 말고, 두 가지 방식으로 조건부 로딩을 활용합니다.

두 방식 모두 핵심은 하나입니다. "모든 작업에 항상 필요한 것"과 "특정 상황에서만 필요한 것"을 구분하는 것. 루트 CLAUDE.md가 계속 늘어난다면, 지우기 전에 이 둘 중 어디로 옮길 후보인지부터 봅니다.

CLAUDE.md는 한 번에 완성하는 문서가 아니라, 같은 실수를 반복할 때만 한 줄씩 추가하는 목록으로 다룹니다. 클로드가 같은 실수를 두 번 하거나, 코드 리뷰에서 클로드가 몰랐어야 할 게 아닌 걸 지적받거나, 지난 세션에 했던 말을 또 하고 있다면 - 그게 CLAUDE.md에 빠진 한 줄입니다.

클로드에게 "이거 추가해줘"라고 맡기면 한 줄이 수십 줄로 부풀려지는 경우가 흔합니다. 저는 문장 자체는 클로드에게 맡기되, 최대한 간결하게 추가해달라고 프롬프트에 못박고 어떻게 추가됐는지는 항상 직접 확인합니다.

.claude/rules/나 하위 폴더 CLAUDE.md로도 정리가 안 되는 게 있습니다. 특정 작업을 할 때만 필요한 절차, 한 번씩만 참고하면 되는 긴 설명 같은 것들입니다. 이런 건 CLAUDE.md에 남겨두지 말고 스킬이나 별도 문서로 완전히 옮기고, CLAUDE.md에는 "이 작업을 할 땐 이 문서를 먼저 읽어라"는 포인터 한 줄만 남깁니다.

CLAUDE.md는 목차 역할만 하고, 실제 내용은 필요할 때 찾아 읽게 만드는 것 - 클로드 코드가 스킬을 다루는 방식과 같은 원리입니다.

지금 CLAUDE.md를 열어서 세 문장 넘게 이어지는 절차 설명이 있는지 봅니다. 있다면 그 부분만 별도 파일로 옮기고, 자리엔 포인터 한 줄만 남깁니다.

한 번 정리해도 시간이 지나면 다시 방치됩니다. 사람이 매번 안 챙겨도 되게, 프로젝트마다 점검 주기를 걸어둡니다.

지금 이 저장소에 점검 주기가 걸린 Routine이나 cron이 하나라도 있는지 확인해봅니다. 없다면 /schedule로 하나 만들어두는 것부터 시작합니다.