Claude Code는 왜 항상 많은 토큰을 소모할까? 코드베이스를 반복해서 읽을 때 낭비되는 지점과 컨텍스트 비용을 낮추는 방법

사용량 보고서는 입력 토큰과 출력 토큰을 구분하고, 캐시 관련 입력 항목도 따로 보여줍니다(공식 사용량 보고서의 항목 설명). 이 구분이 말해 주듯 Claude Code의 토큰 소모를 코드베이스 전체의 반복 읽기로만 설명할 수는 없습니다. 이번 주에는 작업 범위를 먼저 좁히고, 파일 내용·도구 출력·대화 기록 중 어느 쪽이 늘었는지 사용 내역과 작업 기록으로 확인하세요.

이 글은 큰 코드베이스를 분석하다 토큰 소모가 부담스러운 개발자를 위한 안내입니다.
파일 읽기와 도구 출력, 대화 기록의 관계를 파악하려는 엔지니어에게도 도움이 됩니다.
팀 차원의 Claude Code 사용 규칙을 마련하려는 기술 책임자라면 점검표부터 적용해 보세요.

전체 저장소 읽기와 필요한 파일 탐색의 차이

Claude Code가 매번 전체 코드베이스를 처음부터 읽는다고 전제하면 원인을 잘못 찾을 수 있습니다. 조사 과정에서는 현재 요청에 필요한 파일을 검색하고, 도구 결과를 참고하며, 이전 대화의 정보를 이용할 수 있습니다. 무엇이 실제로 입력됐는지는 작업 기록과 사용량을 함께 봐야 합니다.

대화 중 도구 호출과 결과를 검토하려면 대화 기록 확인 방법을 설명하는 공식 안내를 참고하세요. 결과를 확인할 때는 “저장소를 다시 읽었나?”라고만 묻지 말고, 새로 열린 파일이 무엇인지, 검색 결과가 얼마나 넓었는지, 이전 결과가 다시 등장했는지 살펴야 합니다.

이 구분은 반복 읽기와 필요한 추가 탐색을 가르는 출발점입니다. 파일을 다시 확인한 상황이라도 수정 전후를 대조하거나 호출 흐름을 잇는 데 필요한 경우라면 모두 낭비라고 볼 수 없습니다.

주의: 사용량 수치만으로 어떤 파일이 입력됐는지 단정하지 마세요. 같은 토큰 증가라도 파일 내용, 명령 결과, 대화 기록이 원인일 수 있습니다.

토큰이 늘어나는 위치와 작업별 차이

반복 탐색의 비용은 파일 내용에만 생기지 않습니다. 넓은 검색이 많은 코드 조각을 반환하면 검토할 대상이 늘고, 긴 명령 결과가 대화에 들어오면 그 내용도 맥락의 일부가 됩니다. 여기에 오류 설명과 앞선 대화가 이어지면 파일을 다시 읽지 않은 상황에서도 입력량이 커질 수 있습니다.

각 단계에서 새로 필요한 정보와 이미 주어진 정보를 나누면 원인을 더 잘 찾을 수 있습니다. 예를 들어 오류를 찾을 때 테스트 실패 로그는 필요할 수 있지만, 성공한 테스트의 모든 출력까지 늘 필요한 것은 아닙니다. 마찬가지로 함수 호출 관계를 확인한다면 주변 파일 탐색이 의미 있을 수 있으나, 무관한 디렉터리까지 넓히면 불필요한 결과가 섞입니다.

컨텍스트를 키우는 작업 습관

큰 파일을 한꺼번에 확인하거나 검색 범위를 넓게 잡으면 답변에 필요한 것보다 많은 내용이 들어올 수 있습니다. 조사 중 목표를 바꾸거나 서로 다른 변경 요청을 한 대화에 계속 더하는 것도 누적을 키우는 요인입니다.

프로젝트 안내 파일과 대화 기록도 살펴보세요. 공식 메모리 안내는 프로젝트 안내가 어떤 방식으로 읽히고 확인되는지 설명합니다(프로젝트 메모리와 로딩 동작 안내). 팀 규칙이 여러 안내 파일에 중복되거나 현재 작업과 무관한 내용까지 길게 포함되면, 필요한 지침을 찾기 어려워집니다. 프로젝트 안내에는 자주 필요한 실행 방법과 중요한 제약을 남기고, 매번 달라지는 배경은 해당 작업에서만 제공하세요.

대화가 다른 문제로 옮겨 갔다면 새 대화에서 관련 파일과 목표를 다시 지정하는 방법도 있습니다. 대화 재개와 이어서 진행하는 방법은 공식 명령줄 사용 안내에서 확인할 수 있습니다. 새 대화가 언제나 더 적은 토큰을 보장하는 것은 아니지만, 불필요한 이전 맥락을 덜고 작업 목표를 분명히 하는 데 도움이 될 수 있습니다.

작업 범위와 출력량을 좁히는 방법

막연한 요청과 범위를 정한 요청은 읽기 경로부터 달라집니다. “코드베이스를 살펴보고 개선점을 찾아 달라”는 말은 여러 영역을 탐색하게 할 수 있습니다. 반면 “결제 오류가 발생하는 경로를 찾아 특정 함수와 호출자를 확인하고, 수정은 하지 말라”처럼 목표와 범위를 지정하면 조사해야 할 대상을 제한할 수 있습니다.

도구 출력도 요청에 포함해 관리하세요. 검색이나 테스트 결과에서 성공 항목 전체보다 실패 원인과 그 주변 문맥을 먼저 요청하면 읽을 내용이 선명해집니다. 다만 진단에 필요한 출력까지 무조건 잘라 내면 근거를 놓칠 수 있으므로, 먼저 원본 결과를 보존할 필요가 있는지 판단해야 합니다.

프로젝트 안내의 범위와 팀 공유 설정은 설정 파일의 적용 범위를 설명하는 공식 문서에서 확인할 수 있습니다. 자동으로 추가되는 지침과 작업별 요청을 구분하고, 여러 곳에 같은 설명을 반복해서 두지 마세요. 기능이나 설정은 문서에 명시된 적용 범위를 확인한 뒤 도입해야 합니다.

검색과 연동 결과의 출력 관리

검색 결과가 지나치게 많으면 관련 없는 코드까지 검토하게 됩니다. 검색어를 오류 문구나 함수 이름처럼 좁히고, 먼저 위치만 확인한 뒤 필요한 파일을 살펴보세요. 결과 전체가 아니라 판단에 필요한 부분을 요청하는 방식도 유용합니다.

외부 도구나 연동 서버를 쓰는 작업이라면 반환 데이터의 크기도 살펴야 합니다. 공식 연동 안내는 출력 제한과 큰 결과에 대한 경고를 설명합니다(연동 도구의 출력 제한 안내). 도구가 반환하는 결과가 크다면 범위나 필터를 조정하고, 작업에 필요한 정보만 전달하는지 확인하세요.

재사용 가능한 작업 절차를 팀에 추가할 때는 설명이 언제 읽히는지도 확인해야 합니다. 공식 안내는 슬래시 명령과 스킬의 로딩 시점 차이를 다룹니다(명령과 스킬의 로딩 동작 비교). 이 차이를 고려하지 않고 모든 지침을 상시 적용되는 설명에 넣으면, 현재 작업과 무관한 배경이 맥락에 남을 수 있습니다.

참고: 출력 제한이나 지침 정리는 필요한 정보를 숨기라는 뜻이 아닙니다. 원본 로그가 장애 분석에 필요한 경우에는 보관하고, 대화에는 판단에 필요한 구간을 전달하세요.

자주 묻는 질문

코드베이스를 다시 읽는지 어떻게 확인하나요?

대화 기록에서 파일을 확인한 도구 호출과 반환 결과를 살펴보세요. 새로 확인한 파일과 이전 결과를 다시 참고한 경우를 구분하면 됩니다. 도구 기록이 없거나 사용량만 확인할 수 있는 상황에서는 전체 저장소를 다시 읽었다고 단정하지 말고, 다음 작업에서 범위를 좁혀 기록을 비교하세요.

반복 읽기와 필요한 추가 조사를 어떻게 구별하나요?

앞선 단계에서 이미 확인한 내용이 그대로 다시 들어왔는지, 아니면 새 질문에 필요한 파일이나 호출 흐름을 추가로 확인했는지 보세요. 새 정보가 목표와 연결된다면 필요한 조사일 수 있습니다. 작업 목표와 무관한 결과가 계속 늘어나거나 같은 배경을 되풀이해 넣는다면 범위를 조정할 신호입니다.

프로젝트 안내를 줄이면 무조건 토큰이 줄어드나요?

안내가 짧아져도 필요한 규칙이 빠지면 다시 설명해야 하므로 전체 대화량이 오히려 늘 수 있습니다. 중복 설명과 자주 쓰지 않는 배경을 걷어내되, 실행 절차나 중요한 제약은 남기세요. 수정 전후에 비슷한 작업을 수행해 실제 읽기 범위와 안내 내용이 어떻게 달라졌는지 확인하는 편이 안전합니다.

이전 대화를 이어 가는 것과 새 대화를 여는 것 중 무엇이 낫나요?

같은 기능을 계속 조사하고 있고 앞선 분석이 필요하다면 이어서 진행하는 편이 자연스럽습니다. 목표가 다른 문제로 바뀌었거나 이전 논의가 현재 판단을 흐린다면 새 대화에서 목표와 관련 경로를 다시 지정하세요. 어느 쪽이든 고정된 절감 효과를 가정하지 말고, 같은 유형의 작업에서 기록과 사용량을 비교해야 합니다.

변경 효과를 확인하는 점검표

최적화는 설정을 바꾸는 것만으로 확인되지 않습니다. 비슷한 목표를 가진 작업을 기준으로 변경 전후를 비교하고, 작업 종류나 모델이 달라졌다면 그 차이도 기록하세요. 사용량 기록을 확인할 수 있다면 입력과 출력, 캐시 관련 항목을 나눠 살펴보세요. 사용량 보고서의 항목 정의는 공식 보고서 문서를 기준으로 읽으면 됩니다.

• [ ] 요청에서 조사 목표와 수정 여부를 분명하게 정합니다.
• [ ] 관련 디렉터리와 파일을 지정하고, 먼저 위치를 찾은 뒤 필요한 부분만 읽게 합니다.
• [ ] 검색 결과와 명령 출력에서 판단에 필요한 내용이 무엇인지 확인합니다.
• [ ] 프로젝트 안내의 중복 설명과 현재 작업에 필요 없는 배경을 정리합니다.
• [ ] 서로 다른 목표가 한 대화에 쌓이면 새 대화로 분리합니다.
• [ ] 비슷한 작업끼리 읽은 파일, 도구 결과, 대화 기록, 사용량을 비교합니다.
• [ ] 줄어든 출력 때문에 진단에 필요한 근거나 오류 문맥이 빠지지 않았는지 확인합니다.

기존 개발 환경에 비해 원격 작업은 실행 환경 관리 부담을 덜 수 있지만, 네트워크 연결과 원격 접속 설정, 작업 파일 관리가 추가 고려 사항입니다. 물리 장치 연결이 꼭 필요하거나 장기간 일정한 부하를 로컬에서 처리해야 한다면 직접 보유한 맥이 더 맞을 수 있습니다. 반대로 짧은 기간 원격 맥 환경이 필요하거나 팀의 AI 에이전트 작업 환경을 분리하려는 경우에는 Hashvps의 환경 안내와 이용 가능한 구성 안내를 확인해 현재 작업 방식과 비교해 보세요. 환경을 바꾸기 전에 먼저 점검표로 토큰이 파일 읽기, 도구 출력, 대화 기록 중 어디에서 늘었는지 확인하면 선택 기준도 분명해집니다.