Claude Code가 매번 코드베이스를 다시 읽는 이유
현재 Claude Code가 리포지토리를 처리하는 방식
단일 세션 내에서 Claude Code는 파일을 읽고, 의존성을 추적하며, 무엇이 어디에 있는지 학습하는 등 실제적인 이해를 구축합니다. 이러한 이해는 컨텍스트 창(context-window) 상태로 존재합니다. 세션이 종료되거나 컨텍스트 창이 가득 차서 이전 콘텐츠가 압축되어 사라지면, 그 맵도 함께 사라집니다. 다음 세션에서 유일하게 지속되는 입력값은 디스크의 파일과 CLAUDE.md에 있는 내용뿐이므로, 어제 알고 있던 내용을 재구축하기 위해 다시 grep하고 다시 읽어야 합니다.
지속되지 않는 기술적인 이유
Claude Code가 세션 간에 유지하는 코드베이스의 영구적인 인덱스가 없습니다. CLAUDE.md는 직접 작성한 규칙서로, 컨벤션을 정의하는 데는 좋지만 모듈, 역할, 그리고 각 요소가 어떻게 연결되는지 보여주는 살아있는 맵은 아닙니다. 따라서 매 세션마다 탐색을 통해 이 맵을 재구성해야 하며, 대규모 리포지토리에서는 실제 작업을 시작하기도 전에 이 탐색 과정에서 많은 시간과 토큰 비용이 발생합니다.
이로 인해 발생하는 비용
매 세션마다 '시작 세금'이 부과됩니다. 작업 시간 동안 몇 분씩 걸리는 grep과 파일 열기 작업이 반복되며, API 과금 방식의 경우 토큰 비용으로 고스란히 청구됩니다. 대규모 코드베이스일수록 상황은 더 심각합니다. 재탐색해야 할 파일이 더 많고, 실제 작업 대신 재탐색에 더 많은 컨텍스트 창을 소모하게 됩니다. 게다가 이는 중복 작업입니다. 구조적 지식은 매주 안정적으로 유지되는데도 매번 버려지고 새로 구축됩니다.
Claude Code의 기본 해결책 (그리고 한계)
CLAUDE.md
빌드 명령어, 컨벤션, 상위 수준의 아키텍처 노트 등 안정적인 사실을 기록하기에 가장 적합한 곳입니다. 하지만 수동적이고 깊이가 얕다는 한계가 있습니다. 대규모 코드베이스의 전체적이고 최신 상태인 맵을 Markdown 파일에 직접 유지 관리하는 사람은 없기 때문에, Claude는 여전히 빈틈을 채우기 위해 다시 탐색해야 합니다.
세션 재개 (Resuming a session)
최근 세션을 이어가면 해당 대화 기록의 컨텍스트를 복구할 수 있어 맥락을 이어가는 데 도움이 됩니다. 하지만 영구적인 코드베이스 모델을 제공하지는 않으며, 대화 기록이 길어지면 컨텍스트 한계에 도달하여 재개한 목적이었던 세부 정보가 압축되어 사라집니다.
더 큰 컨텍스트 창 (Bigger context windows)
컨텍스트 창이 커지면 Claude가 한 번에 더 많은 리포지토리를 담을 수 있어 세션 내에서는 도움이 됩니다. 하지만 세션 간에 아무것도 영구적으로 보존하지 못하므로, 매일 아침 더 높은 토큰 비용을 지불하며 더 큰 창을 동일한 재탐색 내용으로 다시 채울 뿐입니다.
공통된 장벽: 이 중 어느 것도 세션 간에 유지되고 쿼리할 수 있는 지속적인 코드베이스 모델이 아닙니다. 이는 Claude Code가 프로젝트 컨텍스트를 잊어버리는 이유의 이면에 있는 근본적인 공백과 동일합니다.
해결책: Claude Code에 영구적인 코드베이스 메모리 부여하기
지속 가능한 설정은 아키텍처, 모듈 역할, 주요 결정 사항 등 리포지토리의 영구적인 모델을 보관하는 메모리 레이어를 두는 것입니다. 이를 통해 Claude는 모델을 재구축하는 대신 이를 검색하여 가져옵니다. MemoryLake는 이 지식을 한 번 저장하면 검색이 가능하고 Git 스타일로 버전이 관리되어 아키텍처의 진화 과정을 추적할 수 있으며, 종단간 암호화(end-to-end encrypted)를 통해 코드가 안전하게 보호됩니다.
1단계: API 키 생성하기
MemoryLake에 로그인하고 키를 생성한 후 첫 번째 요청을 보내세요. 약 30초 정도 걸립니다.
2단계: 첫 번째 메모리 업로드하기
아키텍처 개요, 모듈 역할, 주요 API 및 데이터 흐름 문서, 그리고 그 이면의 결정 사항 등 코드베이스의 지속적인 모델을 추가하세요. 문서, 이미지 및 기타 파일 모두 지원됩니다. 매 세션이 아니라 구조가 실제로 변경될 때만 업데이트하면 됩니다.
3단계: AI 및 에이전트 연결하기
Claude Code는 기본적으로 MCP를 지원합니다. API 키를 사용하여 MCP 설정에 MemoryLake를 추가하면, Claude Code가 작업을 시작할 때 다시 grep하여 재구성하는 대신 코드베이스 모델을 검색하여 가져옵니다. 동일한 메모리를 MCP 또는 API를 통해 Codex, OpenClaw 및 기타 에이전트에서도 사용할 수 있으므로, 모든 도구와 장비에서 단 하나의 코드베이스 모델을 공유할 수 있습니다.
재탐색으로 인해 실제로 발생하는 비용
시간과 토큰 측면에서의 시작 세금
매 세션마다 대규모 리포지토리를 재탐색하는 것은 실제 시간(분 단위)과 종량제 사용 시 실제 비용을 소모합니다. 탐색 자체에 토큰이 소비되고, 실제 작업에 사용해야 할 컨텍스트 창 공간이 낭비됩니다. 팀의 모든 개발자가 매 세션마다 독립적으로 이 동일한 장벽에 부딪힌다고 생각하면 그 비용은 배가 됩니다.
다시 grep하는 대신 검색하기
영구적인 모델을 사용하면 Claude는 처음부터 구조를 유추하는 대신 필요할 때 "이 서비스의 구조는 다음과 같습니다"라는 정보를 가져옵니다. 더 빠른 시작, 실제 작업을 위한 더 많은 컨텍스트 창 확보, 그리고 비용 절감 효과를 누릴 수 있습니다. MemoryLake의 토큰 절약 계산기(Token Saving Calculator)를 통해 사용량에 따른 효과를 예측해 보세요.
코드베이스 메모리 구축을 위한 모범 사례
코드가 아닌 맵을 저장하세요
디스크에서 이미 읽을 수 있는 원시 소스 코드를 그대로 쏟아붓는 대신, Claude가 재구축해야 하는 모델인 아키텍처 개요와 모듈 역할을 메모리에 보관하세요. 중요한 가치는 파일 내용이 아니라 구조에 있습니다.
실제 구조적 변화가 있을 때 업데이트하세요
매 세션이 아니라 새로운 서비스 추가, 대규모 리팩터링 등 아키텍처가 실제로 변경될 때 메모리를 갱신하세요. 안정적인 맵이야말로 재탐색을 불필요하게 만드는 핵심입니다.
리포지토리별로 범위를 지정하세요
리포지토리당 하나의 메모리 범위를 지정하면 검색의 정확성을 유지할 수 있으며, 각 프로젝트의 Claude Code 세션이 자체 맵만 가져오도록 제한할 수 있습니다.
결론
Claude Code는 훌륭한 페어 프로그래머이지만, 매일 아침 리포지토리를 처음부터 다시 학습하는 의식을 치릅니다. 이 의식은 매 세션마다 시간, 토큰, 컨텍스트 창 공간을 소모하며, 가장 큰 도움이 필요한 대규모 코드베이스에서 가장 큰 비용을 초래합니다. Claude Code에 영구적인 코드베이스 모델을 제공하면 이러한 재탐색이 중단됩니다. 어떤 장비에서든 다른 에이전트와 함께 필요한 정보를 검색하여 바로 작업을 시작할 수 있습니다. 이미 작성한 코드를 다시 설명하는 데 비용을 낭비하지 마세요.