Claude 전반의 컨텍스트 관리가 엉망이다. 내가 해결한 방법.
Source: Dev.to
저는 Claude를 너무 다양한 형태로 사용합니다. 빠른 질문을 위한 채팅 앱, 장기적인 작업을 위한 Projects, 데스크톱 앱, 몇 개의 스크립트에서 사용하는 API, 그리고 실제 코드베이스와 관련된 모든 작업을 위해 터미널에서 사용하는 Claude Code까지 말이죠.
아무도 경고하지 않습니다. 컨텍스트는 이동하지 않는다는 비용을. 각 인터페이스는 서로 독립된 섬과 같습니다. 프로젝트의 규칙을 Claude에게 채팅으로 설명하고 좋은 결과를 얻은 뒤, 다음 날 Claude Code를 열면 다시 처음부터 설명해야 합니다. 이런 상황이 반 정도 되는 프로젝트에 걸치면, 재설명이 AI를 사용할 때 가장 큰 비용이 됩니다.
지난 몇 달 동안 저는 거의 모든 프로젝트 관련 작업을 Claude Code로 통합했습니다. 모델이 다르기 때문이 아니라, 단 하나의 파일, CLAUDE.md 때문이었습니다. 제가 정성 들여 모은 컨텍스트가 실제로 유지되는 유일한 장소가 바로 여기였습니다.
CLAUDE.md를 제대로 작동시키는 데는 생각보다 시간이 걸렸습니다. 제 정신 모델이 잘못됐기 때문이죠. 가장 큰 오해는 이것이 시스템 프롬프트—모델이 절대 어기지 않는 규칙—라고 생각한 것이었습니다. 실제로는 일반 메시지로 전달되는 조언일 뿐입니다. Claude는 이를 읽고 따르려 하지만, 파일이 길거나 모순이 있으면 금방 사라집니다. 대문자로 적은 규칙을 Claude Code가 무시하고 지나가는 모습을 처음 봤을 때, 저는 시스템이 깨졌다고 생각했지만, 사실은 파일이 너무 길어 규칙이 묻힌 것이었습니다.
이때부터 일련의 탐구가 시작됐고, 제가 배운 내용들은 정말 직관에 반했습니다:
- 모든 줄이 매 턴마다 토큰을 소모합니다. 부풀려진 CLAUDE.md가 Claude를 더 똑똑하게 만들지는 않으며, 오히려 무시하게 됩니다. 이제는 “이 줄을 삭제해도 실수가 발생하지 않을까?” 라는 테스트를 모든 줄에 적용합니다. 문제가 없으면 삭제합니다.
- /compact 후에는 프로젝트 루트에 있는 CLAUDE.md만 남고, 하위 디렉터리의 중첩 CLAUDE.md 파일이나 채팅에서만 언급한 내용은 모두 사라집니다. 세션 중에 규칙이 사라지는 이유를 전혀 알지 못했습니다.
- @path 임포트는 컨텍스트를 절약해 주지 않습니다. 파일을 여러 개로 나눠 로드 부담을 줄일 수 있을 거라 생각했지만, 실제로는 실행 시점에 모두 로드됩니다. 조직에는 도움이 되지만 컨텍스트 절감에는 도움이 되지 않죠.
- 이러한 내용은 마케팅 자료에 전혀 없습니다. 직접 겪어보면서 깨달은 것이었습니다.
정신 모델이 맞춰지자, 잘 알려지지 않은 몇 가지 기능이 프롬프트 튜닝보다 훨씬 큰 효과를 보여줬습니다:
- 경로 기반 규칙: CLAUDE.md가 하나의 파일에 비해 커지면,
.claude/rules/*.md폴더에 분리합니다. - paths: glob이 지정된 규칙은 Claude가 해당 파일을 읽을 때만 로드됩니다. 즉, 서브시스템 전용 가이드는 필요할 때만 컨텍스트를 차지하고, 매 턴마다 비용이 들지 않습니다.
- 입력 트리거: CLAUDE.md에 무엇을 넣을지 고민하던 시간을 멈추고, “다시 설명해야 할 순간”에 바로 한 줄을 추가합니다—Claude가 같은 실수를 두 번 저지르거나, 리뷰에서 놓친 내용이 있거나, 새로운 팀원이 같은 컨텍스트가 필요할 때 말이죠.
- “완료” 검증: Stop 훅을 사용해 체크가 통과될 때까지 턴이 끝나는 것을 막거나,
/goal조건에 별도 평가자를 두어 Claude가 목표를 만족할 때까지 작업을 지속하게 할 수 있습니다.
이 덕분에 긴 작업도 “다 끝난 것 같다”는 식으로 중간에 멈추지 않고, 진짜로 완료될 때까지 진행할 수 있습니다.
어느 순간, 저는 다른 사람들도 같은 교훈을 동시에 역공학하고 있다는 사실을 깨달았습니다. 하지만 좋은 가이드는 블로그, GitHub 레포, Hacker News 스레드 등에 흩어져 있었고, Claude Code가 업데이트되면서 금방 오래돼 버렸습니다.
그래서 저는 State of CLAUDE.md를 만들었습니다. 실무자들이 배우는 내용을 정리한 CLAUDE.md 템플릿으로, 모든 기술적 주장마다 공식 문서와 교차 검증을 거칩니다. 이 검증 과정이 생각보다 중요합니다—그럴듯해 보이는 팁이라도 문서에 없으면 제외됩니다. 예를 들어 “안정적인 규칙은 프롬프트 캐시 히트를 최대화