Claude Code 토큰 소모를 40% 줄이는 실전 컨텍스트 관리

Claude Code는 편리하지만 대규모 프로젝트에서 생각 없이 쓰다 보면 금방 바닥을 드러냅니다. 프로젝트 전체를 훑게 내버려 두면 인공지능은 수만 개의 토큰을 탐색 비용으로 낭비하고, 결국 컨텍스트가 가득 차서 헛소리를 하기 시작합니다. 1인 개발자가 일일 할당량 안에서 복잡한 기능을 끝내려면 인공지능의 시야를 강제로 좁혀야 합니다.

기능 단위로 울타리를 치는 프로젝트 구조

프로젝트의 모든 파일을 노출하는 건 모델의 주의력 예산을 길바닥에 뿌리는 짓입니다. Anthropic이 발표한 프롬프트 캐싱은 정적 데이터에는 효과적이지만, 코드를 계속 수정하는 동적 개발 환경에서는 물리적인 컨텍스트 격리가 훨씬 강력합니다. 인공지능이 수만 개의 토큰을 탐색하는 대신 현재 작업에만 집중하게 만들어야 합니다.

작업 범위를 제한하려면 src/features/[feature-name] 구조를 쓰세요. 그리고 현재 구현할 기능에 직접 연결된 파일 리스트인 context-manifest.json을 작성해야 합니다. 여기에 핵심 의존성 경로와 인터페이스 명세만 적어두고 Claude에게 이 파일들만 읽으라고 명령하세요. MadAppGang의 사례를 보면 이런 컨텍스트 관리 전략만으로도 토큰 소비량을 40% 이상 아낄 수 있습니다.

설계부터 확정하고 코드를 짜는 단계별 접근

로직을 한꺼번에 생성하면 코드가 길어질수록 문맥을 놓치기 쉽습니다. 작은 오타 하나 때문에 전체 코드를 다시 뽑아내느라 토큰을 버리는 상황은 짜증을 넘어 손해입니다. 소프트웨어 엔지니어링 리포트에 따르면 이런 오버헤드를 제어하지 못할 경우 AI 보조 개발의 생산성 향상은 10% 내외에 그칩니다.

골조를 먼저 세우고 살을 붙여야 합니다. Claude에게 실제 구현을 시키기 전에 'Pseudo-code Architecture'부터 가져오라고 하세요.

1. 함수의 입출력과 데이터 구조를 정의하는 타입(Type)이나 인터페이스만 먼저 작성해 승인합니다.
2. 확정된 인터페이스 위에서 전체 흐름을 설명하는 의사코드를 뽑아 논리적 허점을 찾습니다.
3. 검증이 끝난 논리만 실제 코드로 변환합니다.

이 방식을 쓰면 재작업 확률이 30% 이상 줄어듭니다.

꼬인 세션을 버리고 즉시 롤백하는 워크플로우

Claude Code의 rewind 기능이 만능은 아닙니다. 대화가 길어져서 모델이 파일 이름을 헷갈리거나 이전 결정을 잊기 시작했다면, 토큰을 써서 수정하려 들지 말고 그냥 세션을 새로 시작하는 게 낫습니다. Shopify 엔지니어링 팀이 강조했듯 AI 도구 활용에서 가장 중요한 건 명확한 상태 관리입니다.

로컬 Git 환경을 활용해 기능 단계마다 마이크로 커밋을 남기세요. Claude가 맥락을 망가뜨렸다면 주저 없이 git checkout으로 작업 전 지점으로 돌아가야 합니다. 그 다음 프로젝트 루트에 STATUS.md를 만들어 현재 상태와 다음 할 일을 적고, 새 세션의 Claude에게 이 파일만 읽게 하세요. 몇 백 토큰만으로도 모델의 사고방식을 즉시 복구할 수 있습니다.

파일명	역할	주요 내용
STATUS.md	현재 상태 요약	진행 중인 작업, 다음 작업 리스트, 블로커
CHANGES.md	의사결정 로그	아키텍처 선택 이유, 수정된 버그 내역
SPEC.md	구현 명세서	기능 요구사항, 정의된 인터페이스, 테스트 케이스

시야를 가리는 라이브러리 노이즈 제거

Claude Code가 node_modules 내부를 뒤지게 두는 건 토큰을 블랙홀에 던지는 것과 같습니다. 인공지능이 라이브러리 구현을 파악하려고 수천 개의 파일을 훑는 동안 당신의 할당량은 녹아내립니다. 라이브러리가 어떻게 생겼는지보다 어떻게 호출하는지가 훨씬 중요합니다.

.claudecodeignore 파일을 정교하게 설정해서 빌드 결과물이나 대규모 JSON, 외부 소스 코드를 철저히 배제하세요. 대신 docs/snippets 폴더를 만들고 자주 쓰는 API의 핵심 패턴이나 .d.ts 파일의 요약본을 마크다운으로 저장해두는 게 좋습니다. 외부 검색 대신 이 스니펫만 참고하게 강제하면 검색 지연이 사라지고 코드 일관성을 90% 이상 유지할 수 있습니다.