TL;DR

  • Claude Code가 테스트 실행 방법을 찾느라 세션마다 약 6번의 도구 호출과 2,500토큰을 쓰는 발견 비용은, MCP 도구 레지스트리를 사용하면 1번의 호출과 약 100토큰으로 줄어듦.
  • README, Makefile, package.json을 차례로 읽고 명령을 추측하는 과정에서 잘못된 실행과 재시도가 발생함.
  • 발견 과정의 낭비는 컨텍스트 압박을 키우고 에이전트의 확신을 낮추며, 사용자의 대기 시간도 늘림.
  • 작업 실행기 run의 내장 MCP 서버는 도구 이름, 설명, 형식이 지정된 매개변수, 기본값을 구조화된 레지스트리로 제공함.
  • run의 Runfile에 작업을 정의하면 다음 세션에서도 동일한 레지스트리를 사용할 수 있어 도구 발견이 결정적으로 이뤄짐.

발견 비용

  • Claude Code 세션마다 “테스트를 실행해”라고 요청하면 에이전트는 프로젝트에서 실행 방법을 찾겠다고 응답하고, README와 Makefile, package.json을 살펴봄.
  • 이후 make test를 시도했다가 실패하고, npm test도 잘못된 프로젝트에 실행한 뒤 Makefile을 다시 읽어 다른 대상을 잘못된 인수와 함께 실행하는 식으로 진행됨.
  • 실제 작업을 시작하기도 전에 도구 호출 6회, 컨텍스트 2,500토큰이 소모됨.
  • 에이전트가 모든 것을 잊고 매 세션마다 처음부터 다시 시작하므로 이 발견 비용이 반복됨.

실제 비용

  • 낭비되는 토큰 외에도 복합적인 영향이 발생함.
  • 컨텍스트 압박: 긴 세션에서는 이미 컨텍스트 창 한계와 씨름하는 상황이며, 발견에 2,500토큰을 쓰면 압축 시점이 앞당겨짐.
  • 확신 저하: 실패한 시도마다 오류 메시지가 컨텍스트에 쌓이고, 에이전트는 스스로를 의심하며 “다른 방법을 시도해 보겠다”는 식으로 주저하기 시작함. 두 번 오류를 겪은 뒤 모든 응답을 “혼란을 드려 죄송합니다”로 시작하는 모습을 볼 수 있음.
  • 사용자 시간: 몇 초 만에 직접 안내할 수 있는 파일을 에이전트가 헤매며 읽는 동안 기다려야 함.

비용 환급

  • 에이전트가 작업을 시작하기 전에 프로젝트의 도구를 이미 알고 있다면 발견 과정 자체를 줄일 수 있음.
  • 모델 컨텍스트 프로토콜(MCP)은 파일을 읽으며 도구를 발견하는 대신 도구 이름, 설명, 형식이 지정된 매개변수와 기본값을 담은 구조화된 레지스트리를 제공함. 파일 읽기와 추측, 재시도가 필요하지 않음.
  • 내장 MCP 서버를 갖춘 작업 실행기 run을 만들고, Runfile에서 작업을 정의함.
  • test 작업은 테스트 모음 실행을 설명하고 선택적 테스트 이름 필터를 인수로 받으며, cargo test --workspace --no-fail-fast에 필터를 전달함.
  • deploy 작업은 배포 환경을 인수로 받고, staging 또는 prod를 대상으로 ./scripts/deploy.sh를 실행함.
  • Claude Code 설정에서 MCP 서버 이름을 run으로 지정하고, 실행 명령을 run, 인수를 --serve-mcp로 설정함.
  • 이후 “테스트를 실행해”라는 요청은 mcp:run test 도구 호출 한 번으로 성공하며, 다음 세션에서도 같은 결과를 얻음. 소모량은 약 100토큰임.

수치 비교

  • 테스트 실행에 필요한 도구 호출은 MCP가 없을 때 약 6회, MCP 사용 시 1회임.
  • 컨텍스트 소모량은 MCP가 없을 때 약 2,500토큰, MCP 사용 시 약 100토큰임.
  • 다음 세션은 MCP가 없을 때 처음부터 시작하지만, MCP 사용 시 동일한 레지스트리를 사용함.
  • 신뢰성은 MCP가 없을 때 세션마다 달라지며, MCP 사용 시 결정적임.
  • 하루 동안의 코딩 세션을 기준으로 하면 재발견에 낭비되는 토큰 수천 개와 도구 호출 수십 회를 아낄 수 있음.
  • 발견 비용은 0임.

설치 및 추가 정보

  • 전체 내용에는 자동 잘라내기, 보안 샌드박싱, 결정적 스킬 계층도 포함됨.
  • nihilok/tap/runtool을 사용해 brew install로 설치하거나, yay -S runtool 또는 cargo install run으로 설치할 수 있음.
  • GitHub와 문서 안내가 제공됨.