로그·테스트·MCP 출력의 토큰 예산

핵심 요약

• 5편의 목표는 셸·테스트·검색·diff·MCP 출력에 기본 예산을 두고 필요한 경우에만 단계적으로 넓히는 것임
• 긴 도구 출력은 한 번 읽는 비용으로 끝나지 않고 세션의 다음 턴에 다시 포함될 수 있으므로 조기 제한의 효과가 큼
• 기본값은 검색 50줄, 실패 로그 30줄 안팎, diff 요약 우선, 통과 테스트는 집계만 남기는 방식이 적절함
• 출력 제한으로 원인을 놓치면 절감이 아니므로 재호출 횟수와 진단 성공률을 함께 측정해야 함
• 이 편의 산출물인 tool-budget.md는 6편의 모델 라우팅에서 작업 난이도를 판정하는 증거가 됨

handoff의 가장 큰 덩어리는 도구 출력임

• 4편의 handoff가 짧아도 세션 안의 원본 로그가 길면 다음 턴의 컨텍스트는 이미 커져 있음

  • 전체 테스트 로그, minified stack trace, 수천 줄 검색 결과가 대표적인 원인임
  • 명령의 목적보다 출력의 양을 먼저 제한해야 함

• 도구 출력은 넓게 찾고 좁게 읽는 깔때기로 다룸

  • 첫 단계는 파일명·심볼·오류 코드의 위치만 찾음
  • 둘째 단계는 상위 후보의 앞뒤 문맥만 읽음
  • 셋째 단계는 가설을 구분하는 데 필요할 때만 전체 범위를 엶

• Anthropic은 긴 로그를 에이전트에 넣기 전에 마지막 20~30줄 또는 관련 구간으로 자르도록 권장함¹

  • 이 숫자는 모든 도구의 절대 상한이 아니라 첫 진단에 필요한 기본 범위임
  • 오류가 앞쪽에 있거나 여러 실패가 연쇄되면 구간을 명시해 추가로 읽어야 함

도구별 기본 예산을 명시함

• 검색은 결과 개수와 출력 필드를 함께 제한함

  • 파일 목록은 상위 50개, 본문 일치는 상위 30개와 줄 번호만 먼저 봄
  • 결과가 많으면 확장자·경로·심볼을 추가해 쿼리를 좁힌 뒤 다시 실행함

• 테스트는 실패 우선 출력으로 운영함

  • 통과 시 명령·통과 수·소요 시간만 기록함
  • 실패 시 첫 실패의 메시지와 스택 20~30줄을 보고 가설이 없을 때만 다음 실패를 읽음
  • 전체 suite는 완료 검증에 사용하되 전체 성공 로그를 대화에 붙이지 않음

• diff는 크기에서 내용으로 점진적으로 이동함

  • 먼저 git diff --stat와 파일 목록으로 범위를 확인함
  • 다음으로 의심 파일의 hunk만 검토함
  • 마지막 검증에서만 전체 diff를 읽되 생성물과 lockfile은 별도 취급함

• 표의 수치는 작성자의 시작값이며 저장소에 맞춰 조정해야 함
  • 컴파일러 오류처럼 첫 줄이 핵심인 도구와 분산 시스템 로그처럼 시간 문맥이 필요한 도구는 다른 예산이 필요함

클라이언트가 제공하는 제한 기능을 사용함

• Gemini CLI는 셸 도구 출력 요약에 토큰 예산을 설정할 수 있음²

  • model.summarizeToolOutput.run_shell_command.tokenBudget는 셸 출력 요약 크기를 제한함
  • 요약 자체가 중요한 행을 버릴 수 있으므로 원본 로그의 보관 위치와 재조회 명령을 handoff에 남김

• Codex의 MCP 구성은 도구 허용 목록과 도구별 출력 토큰 제한을 지원함³

  • 필요한 도구만 enabled_tools에 두면 도구 설명 자체와 잘못된 호출 가능성을 줄일 수 있음
  • tools.<tool>.output_token_limit는 MCP 출력의 상한을 정하므로 큰 응답을 내는 검색·이슈 도구부터 적용할 수 있음

• MCP 서버의 설명도 컨텍스트 비용의 일부임

  • OpenAI는 서버 instructions의 첫 512자가 독립적으로 이해되도록 작성하라고 안내함³
  • 핵심 제약을 앞에 두고 긴 예시는 연결 문서로 빼는 구성이 도구 선택과 컨텍스트 모두에 유리할 가능성이 있음

재호출 비용으로 과도한 절단을 찾음

• 도구 예산 실험은 총 출력량과 진단 반복을 함께 기록해야 함

  • tool_output_lines, tool_calls, repeated_calls, time_to_first_hypothesis를 추가함
  • 같은 명령을 범위만 넓혀 세 번 이상 호출하면 기본 예산이 너무 작았을 가능성이 있음

• 절감 판정은 완료 작업당 도구 출력과 재작업의 동시 개선임

  • 완료 작업당 출력 줄 중앙값이 줄어야 함
  • 첫 원인 가설까지의 시간과 테스트 통과율이 나빠지지 않아야 함
  • 잘린 로그를 사람이 다시 읽는 시간이 늘면 절감으로 보지 않음

• 민감 정보 제거는 토큰 절감보다 우선하는 별도 제약임

  • 로그를 요약하기 전에 자격 증명·개인정보·내부 URL을 삭제함
  • 짧아졌다는 이유로 민감한 출력이 외부 모델에 전송 가능한 것은 아님

다음 편으로 난이도 신호를 넘김

• tool-budget.md에는 기본 예산과 함께 상향 조건을 기록함

  • 여러 패키지의 실패, 재현되지 않는 오류, 세 번째 가설 실패는 난이도 상승 신호임
  • 단일 파일·명확한 오류·하나의 검증 명령은 가벼운 모델 후보임

• 6편에서는 출력이 많다는 이유만으로 강한 모델을 선택하지 않음

  • 먼저 출력을 좁힌 뒤 남은 추론 난이도로 모델을 결정함
  • 두 번의 검증 실패처럼 관찰 가능한 조건에서만 상위 모델로 올림

실행 제안

• 가장 출력이 큰 다섯 명령을 찾아 기본 줄 수와 재조회 명령을 tool-budget.md에 기록해야 함
• MCP는 작업마다 필요한 서버와 도구만 켜고 큰 응답을 내는 도구부터 출력 상한을 설정해야 함
• 열 건 뒤 출력 줄 수가 줄었지만 재호출과 진단 시간이 늘었다면 예산을 한 단계 되돌려야 함

Footnotes

1. Anthropic, Claude Code의 모델·사용량·한도 — 긴 로그를 관련 구간으로 줄이는 사용량 절감 지침을 설명함 ↩

2. Google, Gemini CLI 설정 — 셸 도구 출력 요약과 tokenBudget 설정을 설명함 ↩

3. OpenAI, Codex의 MCP — 도구 허용 목록, 도구별 출력 토큰 제한, 서버 지침의 앞부분 작성 원칙을 설명함 ↩ ↩²