Claude Code의 토큰 낭비를 줄이는 코드베이스 구조 분석 도구 'nervx'

실용적 조언

Claude Code 사용 시 토큰 소모가 심하다면 nervx를 설치하고 'nervx build .'를 실행하여 구조 지도를 생성해라.
CLAUDE.md 파일에 생성된 지침을 포함시켜 Claude가 Grep 대신 구조 지도를 먼저 참조하도록 설정해라.

섹션별 상세

Claude Code가 코드베이스 탐색 과정에서 발생하는 비효율성이 주요 문제로 제기됐다. 인증 관련 질문 하나에도 60회 이상의 Grep 검색을 수행하거나 잘못된 파일을 반복해서 읽는 과정에서 실제 작업 시작 전 이미 컨텍스트 윈도우의 절반이 소모되는 현상이 발생했다.

nervx는 Tree-sitter를 활용해 전체 저장소를 파싱하고 SQLite 기반의 함수, 클래스, 호출 체인, 임포트 그래프를 구축한다. 로컬 환경에서 5초 이내에 실행되며 LLM 호출이나 API 키 없이 순수 연산만으로 NERVX.md라는 구조적 지도를 생성하여 프로젝트의 실행 흐름과 주요 파일을 명시한다.

생성된 구조 지도는 CLAUDE.md 파일에 자동 통합되어 Claude가 스스로 nervx nav 명령어를 사용하도록 유도한다. 별도의 프롬프트 엔지니어링 없이도 Claude가 리팩터링 전 영향 범위를 확인하거나 효율적인 탐색을 수행하게 함으로써 에이전트의 자율적 판단 능력을 보조한다.

FastAPI 저장소를 대상으로 한 벤치마크 결과에서 실질적인 성능 향상이 입증됐다. 도구 호출 횟수는 93회에서 56회로 40% 감소했고, 출력 토큰은 15,694개에서 8,196개로 48% 절감됐으며, 특히 Grep 검색 횟수는 63회에서 22회로 65% 급감하는 성과를 거뒀다.

용어 해설

트리 시터(Tree-sitter): — 프로그래밍 언어의 소스 코드를 구문 트리로 파싱하는 증분 파싱 라이브러리이다. 코드의 구조적 관계를 빠르고 정확하게 분석하여 함수, 클래스, 변수 간의 의존성을 파악하는 데 필수적인 역할을 한다.
컨텍스트 윈도우(Context Window): — LLM이 한 번의 추론 과정에서 동시에 처리하고 기억할 수 있는 텍스트의 최대 범위이다. 코드베이스 탐색 시 불필요한 파일을 많이 읽으면 이 공간이 낭비되어 실제 문제 해결에 필요한 정보가 누락될 수 있다.
정적 분석(Static Analysis): — 프로그램을 실제로 실행하지 않고 소스 코드 자체를 분석하여 구조와 잠재적 오류를 파악하는 기법이다. LLM 호출 없이 로컬 연산만으로 코드의 호출 그래프나 의존 관계를 생성할 수 있어 비용 효율적이다.
호출 그래프(Call Graph): — 프로그램 내의 함수나 서브루틴 간의 호출 관계를 나타낸 유향 그래프이다. 어떤 함수가 어디에서 호출되는지 시각화하여 코드 변경 시의 영향 범위(Blast Radius)를 파악하는 데 사용된다.

언급된 도구

nervx추천링크

코드베이스 구조 분석 및 AI 에이전트 탐색 보조

Claude Code중립

Anthropic의 CLI 기반 코딩 에이전트

언급된 리소스

GitHubnervx GitHub Repository