Claude Code 설정 파일(settings.json) 최적화로 토큰 낭비 줄이는 방법

AI 코딩 도구를 실무 프로젝트에 붙이면 처음에는 질문만 잘하면 된다고 생각하기 쉽다. 하지만 사용 시간이 늘어날수록 비용과 속도 문제는 프롬프트 문장보다 프로젝트 설정에서 더 자주 생긴다. 필요 없는 파일까지 컨텍스트로 읽거나, 빌드 산출물과 로그 파일을 계속 훑거나, 매번 같은 설명을 긴 대화로 반복하면 토큰 사용량이 빠르게 늘어난다.

Claude Code를 쓸 때도 마찬가지다. settings.json과 프로젝트 지침을 정리하지 않으면 모델은 코드베이스를 이해하기 위해 넓은 범위를 탐색하려고 한다. 이 탐색은 도움이 될 때도 있지만, 오래된 산출물이나 거대한 데이터 파일까지 함께 읽게 되면 응답 속도와 비용이 모두 나빠질 수 있다.

토큰 낭비가 생기는 지점

불필요한 맥락이 쌓이는 구조

AI 코딩 도구의 비용은 단순히 답변 길이만으로 결정되지 않는다. 모델이 읽는 파일, 대화 기록, 도구 호출 결과, 오류 로그도 모두 맥락에 포함될 수 있다. 프로젝트 루트에 빌드 결과물, 번들 파일, 대형 JSON, 테스트 스냅샷, 로그가 그대로 섞여 있으면 모델은 실제 소스보다 주변 잡음을 더 많이 보게 된다. 따라서 설정 최적화의 첫 단계는 모델이 보지 않아도 되는 것을 줄이는 일이다. 소스 코드, 설정 파일, 테스트, 문서는 필요하지만 빌드 산출물, 커버리지 리포트, 의존성 폴더, 대형 로그 같은 파일은 대부분 작업 판단에 직접 필요하지 않다.

settings.json은 작업 경계를 알려주는 장치다

settings.json은 도구의 동작 방식과 프로젝트별 기본값을 정리하는 데 사용할 수 있다. 실제 지원 항목은 사용 환경과 버전에 따라 다를 수 있으므로, 공식 문서나 현재 설치된 도구의 설정 화면을 확인해야 한다. 다만 원칙은 동일하다. 자동으로 읽는 범위를 줄이고, 자주 쓰는 명령과 제외 경로를 분명히 하며, 위험한 작업에는 확인 단계를 두는 것이다. 설정 파일 하나로 모든 비용 문제가 해결되지는 않지만, 기본 탐색 범위를 줄이는 것만으로도 불필요한 토큰 사용을 줄이는 데 도움이 된다.

성능과 가성비는 함께 봐야 한다

토큰을 줄인다고 해서 필요한 맥락까지 없애면 답변 품질이 떨어질 수 있다. 핵심은 적게 읽는 것이 아니라 필요한 것을 먼저 읽게 하는 것이다. 프로젝트 구조, 테스트 명령, 핵심 모듈 위치처럼 판단에 필요한 정보는 잘 드러내고, 산출물과 반복 로그는 제외하는 방식이 좋다. 특히 팀 프로젝트에서는 개인이 매번 프롬프트로 설명하는 것보다 설정과 지침 파일로 공통 기준을 남기는 편이 안정적이다.

실제로 적용할 수 있는 방법

제외 경로를 먼저 정리하기

프로젝트에서 모델이 읽지 않아도 되는 경로를 목록으로 만든다. 빌드 산출물, 의존성 폴더, 커버리지 리포트, 임시 파일, 대형 데이터 샘플이 우선 대상이다. 설정 파일에서 직접 제외할 수 있는 항목이 있다면 그곳에 넣고, 도구가 별도 ignore 파일을 지원한다면 함께 관리한다. 아래는 구조를 설명하기 위한 예시이며, 실제 키 이름은 현재 사용하는 Claude Code 설정 형식에 맞춰 조정해야 한다.

{
  "context": {
    "exclude": [
      "node_modules/**",
      "dist/**",
      "coverage/**",
      ".next/**",
      "logs/**",
      "*.min.js"
    ]
  }
}

자주 쓰는 검증 명령을 고정하기

모델이 매번 어떤 명령을 실행해야 하는지 찾으면 탐색 비용이 늘어난다. 테스트, 린트, 타입 체크처럼 자주 쓰는 명령을 프로젝트 지침에 적어두면 작업 후 검증 흐름이 일정해진다. 아래처럼 명령을 명시해두면 매번 새로 탐색하지 않아도 된다.

npm test
npm run lint
npm run typecheck

대형 파일은 요약본으로 대체하기

스키마 덤프, API 응답 샘플, 대형 로그는 원본 전체보다 요약 문서가 더 유용할 때가 많다. 핵심 구조만 정리한 요약 문서를 두고, 원본 대형 파일은 제외 경로에 넣으면 모델이 필요한 정보를 빠르게 파악할 수 있다.

작업 전 범위 확인을 습관화하기

모델에게 바로 수정하게 하기보다 먼저 이번 작업에 필요한 파일만 찾아서 요약하라고 요청하면 불필요한 탐색을 줄일 수 있다. 설정 파일은 기본 경계를 제공하고, 프롬프트는 작업별 경계를 좁히는 역할을 한다.

주의할 점

제외 경로를 너무 넓게 잡으면 필요한 파일까지 숨겨질 수 있다. 예를 들어 데이터 폴더를 통째로 제외하면 실제 콘텐츠 데이터나 설정 파일을 읽지 못할 수 있다. 제외 규칙은 넓은 패턴부터 넣기보다 실제로 비용을 키우는 폴더를 확인한 뒤 하나씩 추가하는 편이 좋다.

또 하나의 함정은 비용 절감을 이유로 검증 명령을 생략하는 것이다. 토큰 사용량은 줄어들 수 있지만, 잘못된 코드가 들어가면 나중에 더 큰 비용이 든다. 설정 최적화의 목표는 검증을 없애는 것이 아니라 불필요한 맥락을 줄이고 필요한 검증을 빠르게 실행하는 것이다.

정리

Claude Code의 토큰 낭비를 줄이려면 프롬프트만 다듬는 것보다 프로젝트 설정과 파일 구조를 함께 정리해야 한다. 모델이 읽지 않아도 되는 경로를 제외하고, 자주 쓰는 검증 명령과 핵심 문서를 고정하며, 대형 파일은 요약본으로 대체하는 방식이 현실적이다. 필요한 맥락은 남기고 잡음을 줄이는 것이 비용과 품질을 함께 지키는 출발점이다.