Claude Code가 프로젝트 전체를 다시 읽는 이유와 해결 방법

Ailoot 문서: API, 키, 연결.

Claude Code는 왜 매번 프로젝트를 처음부터 다시 읽을까요?#

많은 사람이 이를 버그라고 생각합니다. 사실 Claude Code는 원래 이렇게 설계되었습니다. 자체 프로젝트 인덱스가 없는 것이죠. 무언가를 수정해 달라고 요청하면 미리 준비된 코드 지도가 없으므로 관련 파일을 찾고, 필요한 문자열을 검색하고, 파일을 메모리에 읽어 들이며 프로젝트를 다시 탐색합니다.

이 접근 방식에는 분명한 장점이 있습니다. 코드가 항상 최신 상태이며 오래된 인덱스가 없습니다. 설정할 것도 없습니다. 코드가 어떤 데이터베이스로도 전송되지 않습니다.

하지만 단점도 있습니다. 새 작업을 시작할 때마다 파일을 새로 검색하고 읽어야 합니다. Claude가 이전 세션에서 이미 파악한 내용인데도 모든 항목이 어디 있는지 다시 알아내는 데 토큰을 씁니다. 프로젝트가 클수록 사전 조사 비용도 커집니다. 에이전트가 “모든 것을 읽는” 것처럼 느껴지는 정확한 이유가 이 메커니즘입니다.

실제로 토큰이 얼마나 소모될까요?#

비용은 요청을 보내기 전부터 발생합니다. 한 독립적인 측정 결과 Claude Code는 메시지의 첫 글자를 읽기도 전에 시스템 프롬프트와 도구 설명으로 약 33,000토큰을 보냅니다. 비교하자면 OpenCode는 약 7,000토큰에서 시작합니다.

그다음에는 파일을 다시 읽는 비용이 발생합니다. 파일 검색과 읽기는 매번 컨텍스트에 토큰을 추가합니다. Claude Code 공식 문서는 파일 읽기가 컨텍스트 사용량의 대부분을 차지한다고 명시합니다. 2,400토큰 분량의 auth.ts를 분석하면 Claude가 2,400토큰을 보게 되며, 사전 조사 중 여는 모든 파일도 마찬가지입니다.

독자에게 이는 비용과 사용 한도로 이어집니다. 바이브 코딩을 시작하는 사람들이 가장 두려워하는 것은 “결제했는데 한도만 헛되이 다 썼다”는 상황입니다. 에이전트가 모든 작업마다 프로젝트를 훑고 파일을 처음부터 다시 읽으면 컨텍스트가 두 배 빠르게 소모됩니다. 먼저 시스템 오버헤드에, 그다음 사전 조사에 쓰이기 때문입니다. “Claude Code 토큰은 어디에 쓰일까” 가이드에서 Claude Code 토큰이 정확히 어디로 가는지 전체 지도를 다뤘습니다. 프로젝트 재독은 그곳에서 설명한 아홉 가지 패턴 중 하나입니다.

지속적인 코드 메모리란 무엇인가요?#

코드 메모리는 Claude가 프로젝트를 다시 읽게 만드는 바로 그 공백을 메웁니다. 아이디어는 간단합니다. 도구가 코드를 한 번 전부 스캔해 지도를 만들고, 그 지도를 필요할 때 쓸 수 있도록 보관하는 것입니다. 그러면 에이전트가 매번 처음부터 검색할 필요 없이 지도에 질문하면 됩니다.

기술적으로는 다음과 같이 작동합니다. 별도의 도구가 프로젝트를 스캔해 구성 요소로 나눕니다. 어떤 함수와 클래스가 있는지, 무엇이 무엇을 호출하는지, 어떤 파일이 서로 연결되어 있는지 파악합니다. 이 구조는 디스크에 저장됩니다. Claude가 결제 로직의 위치나 함수를 수정했을 때 무엇이 깨질지 알아야 하면 수십 개의 파일을 읽는 대신 지도에 한 번의 구체적인 질의를 보냅니다.

이 지도는 MCP를 통해 연결됩니다. MCP는 Claude Code에 외부 도구를 연결하는 표준 방식입니다(“Claude Code용 MCP 서버” 가이드에서 다른 서버 연결 방법을 다뤘습니다). 코드 메모리 도구는 자체 지도 검색 명령을 추가하고, Claude는 프로젝트의 구조를 파악해야 할 때 이를 자율적으로 사용합니다.

실제로는 “함수 하나를 찾으려고 폴더 전체를 읽기”와 “지도에 함수의 위치 묻기”의 차이입니다. 전자는 수만 토큰이 들고 후자는 수백 토큰이 듭니다.

코드 메모리의 두 가지 접근법: 무엇이 다를까요?#

코드 메모리 도구는 프로젝트에서 무엇을 만들어 내는지에 따라 다릅니다. 쉽게 생각하면 하나는 수술용 집도 도구처럼 정밀 편집을 돕고, 다른 하나는 의미로 검색합니다.

GitHub 스타 수는 2026년 7월 15일 기준입니다(GitHub API 기준). 두 도구 모두 무료 오픈소스이며 Claude Code에서 작동하고 MCP 서버로 연결됩니다.

프로그래머가 아닌 분들을 위해 간단히 정리하겠습니다. Serena는 수술용 집도 도구와 같습니다. 프로젝트 전반에서 같은 부분을 수정하고 정밀도가 중요할 때 사용하세요. claude-context는 의미 기반 검색 도구입니다. 설명으로 코드를 찾지만 클라우드 데이터베이스 설정과 키가 필요합니다.

Serena나 claude-context는 언제 선택해야 할까요?#

두 도구는 하나의 자리를 놓고 경쟁하지 않습니다. 각자 기억하는 내용이 다르므로 작업에 따라 선택하면 됩니다.

리팩터링을 많이 한다면 Serena를 선택하세요. 지능형 개발 환경과 비슷한 코드 탐색 기능을 에이전트에 제공합니다. 함수 정의와 실제 호출 위치를 모두 찾은 다음 프로젝트 전반에 걸쳐 함수 이름을 신중하게 바꾸거나 본문을 교체합니다. 저자는 그 이점을 이렇게 설명합니다.

Serena는 절감 비율을 정확히 공개하지 않으므로 지어낸 수치를 덧붙이지 않겠습니다. 이 도구의 이점은 다릅니다. 일반 검색은 주석과 문자열까지 포함해 일치 항목 40개를 반환하고, Claude가 파일 네 개 전체를 읽을 수 있지만 Serena는 몇 번의 정밀한 질의로 답합니다. 따라서 호출 횟수와 잘못된 일치가 줄어들고 에이전트가 엉뚱한 부분을 수정할 위험도 낮아집니다.

의미 기반 검색이 필요하고 설정이 부담스럽지 않다면 claude-context를 선택하세요. 코드를 벡터(의미를 나타내는 수치 지문)로 바꿔 “결제 로직이 어디 있는지 찾아 줘”처럼 설명으로 검색합니다. 함수 이름을 몰라도 됩니다. 다만 이 검색을 위해 추가 설정이 필요합니다.

claude-context에는 외부 벡터 데이터베이스, 임베딩 제공업체 키, 최신 버전의 Node가 필요합니다. 두 도구 중 설정이 더 복잡하므로 초보자에게는 다른 도구부터 시작하라고 권합니다.

타사 도구 없이 Claude Code에서 바로 할 수 있는 일은 무엇인가요?#

타사 도구를 설치하기 전에 Claude Code에 이미 포함된 기능을 최대한 활용하세요. 다음 명령은 무료이며 바로 사용할 수 있습니다.

1. /context는 시스템 프롬프트, CLAUDE.md, 메모리, 도구, 파일 등 컨텍스트 창을 차지하는 항목을 실시간으로 보여 줍니다. /mcp 명령은 연결된 서버별 비용을 표시하고, /memory는 시작 시 불러온 항목을 보여 줍니다.
2. /compact는 대화 기록을 짧은 요약으로 압축하고 같은 작업을 계속합니다. /compact에 보존할 내용을 추가해 요약의 초점을 지정할 수 있습니다.
3. /clear는 기록 전체를 버립니다. 관련 없는 작업으로 전환할 때 실행하라는 것이 공식 권장 사항입니다. 그래야 이전 대화가 필요한 파일의 공간을 차지하지 않습니다.
4. /doctor(2026년 7월 8일에 도입된 /checkup이라고도 함)는 설정을 진단하고 수정 방법을 제안합니다. CLAUDE.md의 중복을 제거하고, 사용되지 않는 도구와 서버를 찾고, 느린 핸들러를 감지합니다.

CLAUDE.md에 관한 별도 참고 사항입니다. 이 파일은 모든 세션 시작 시 컨텍스트에 로드되고 모든 메시지에 포함됩니다. 지나치게 길면 계속 비용을 지불하게 됩니다. 공식 권장 사항은 200줄 미만으로 유지하고 참고용 세부 정보는 필요할 때 로드되는 스킬로 옮기는 것입니다. CLAUDE.md를 올바르게 구성하는 방법은 별도 가이드 “CLAUDE.md 구성 방법”에서 다뤘습니다.

또 다른 내장 수단은 서브에이전트입니다. 별도의 컨텍스트를 사용하므로 메인 창을 부풀리지 않고 많은 읽기와 사전 조사를 맡길 수 있습니다. Anthropic은 엔지니어링 분석에서 일반 원칙을 다음과 같이 설명합니다.

MCP 서버를 추가하면 컨텍스트가 더 커질까요?#

“서버를 하나 더 추가하면 컨텍스트 오버헤드도 늘어난다”는 생각은 이전에는 맞았지만 Claude Code가 달라졌습니다. 기본 설정에서는 MCP 도구 설명을 나중에 불러옵니다. 시작할 때는 서버 이름만 컨텍스트에 포함하고 작업에 특정 도구가 필요할 때 전체 설명을 로드합니다. 문서에도 이 내용이 명시되어 있습니다.

코드 메모리의 계산은 간단합니다. 도구 이름에 드는 작고 고정된 오버헤드와 에이전트가 파일을 다시 읽지 않아 절약되는 수천 토큰을 비교하면 됩니다. 인덱스를 쓰는 편이 분명히 유리합니다.

마법을 기대하지 않도록 솔직한 주의 사항도 두 가지 말씀드리겠습니다. 인덱스는 가끔 다시 만들어야 합니다. 지도는 스캔 당시의 코드를 반영하므로 큰 수정 후에는 업데이트가 필요합니다(도구마다 다릅니다. 자동으로 처리하는 것도 있고 명령을 실행해야 하는 것도 있습니다). 또 “토큰이 120배 적게 든다” 같은 큰 수치는 일부 질의에서 가능한 최선의 경우를 설명하며 모든 작업에서 얻을 수 있는 결과는 아닙니다. 실제 절감 폭은 더 작지만 여전히 눈에 띕니다. 일반적으로 Claude Code 한도 소진을 피하는 방법을 자세히 알아보고 싶다면 별도 분석인 “Claude Code 한도를 소진하지 않는 방법”을 참고하세요.

오늘은 어디서부터 시작하면 좋을까요?#

불필요한 것을 모두 덜어 내면 오늘 할 일은 간단합니다.

1. /doctor를 실행하고 제안된 내용을 정리합니다. CLAUDE.md의 중복 항목과 사용하지 않는 도구를 제거합니다.
2. CLAUDE.md를 200줄로 줄이고 참고 자료를 스킬로 옮깁니다.

그다음 필요에 따라 선택하세요. 리팩터링을 많이 한다면 정밀한 편집을 위해 Serena를 추가하고, 의미 기반 검색이 필요하다면 claude-context를 설정합니다. 코드 메모리와 정돈된 컨텍스트로 오늘의 주요 불편을 해결할 수 있습니다.

Ailoot를 통해 AI 모델을 이용해야 한다면 Ailoot을 확인해 보세요.