Claude Code의 저품질 결과물 원인: 하위 모델(Haiku) 사용 문제

실용적 조언

Claude.md 파일에 'Use only Sonnet or Opus for subagents'와 같은 규칙을 추가하여 Haiku 사용을 차단하라.
에이전트가 수행하는 진단 작업의 로그를 확인하여 어떤 모델이 정보를 수집하고 있는지 모니터링하라.

섹션별 상세

Claude Code가 스캔 및 탐색 작업 시 내부적으로 Haiku 모델을 호출하여 정보를 수집하는 현상이 관찰되었다. 메인 에이전트가 진단 단계에서 Haiku로부터 낮은 품질의 정보를 전달받으면 최종 결과물의 정확도가 떨어진다. 이는 비용 절감을 위한 모델 혼합 전략이 실제 코딩 성능에는 악영향을 미칠 수 있음을 시사한다.

작성자는 채팅 규칙이나 Claude.md 설정 파일을 통해 Sonnet 또는 Opus 모델만 서브에이전트로 사용하도록 강제하는 해결책을 제시했다. 사용자가 명시적으로 'Sonnet or Opus subagents only'라는 규칙을 추가한 결과, 이전보다 작업 품질이 개선되는 효과가 확인되었다. 에이전트의 내부 모델 선택 로직을 사용자가 직접 제어함으로써 성능 저하를 방지할 수 있다.

용어 해설

서브에이전트(Subagent): — 메인 AI 에이전트의 지시를 받아 특정 하위 작업을 수행하는 보조 모델이다. 복잡한 워크플로를 분산 처리하여 효율성을 높이지만, 성능이 낮은 모델을 서브에이전트로 사용할 경우 전체 결과물의 품질이 저하될 수 있다.
진단 작업(Diagnostics): — 코드의 오류나 구조를 분석하여 메인 모델에게 정보를 제공하는 사전 탐색 단계이다. 이 단계에서 정확한 정보가 수집되지 않으면 메인 모델이 잘못된 근거를 바탕으로 코드를 작성하게 되는 원인이 된다.
Claude.md: — Claude Code와 같은 에이전트 도구의 동작 방식이나 규칙을 정의하는 설정 파일이다. 사용자는 이 파일을 통해 에이전트가 특정 모델만 사용하도록 강제하거나 작업 처리 가이드라인을 명시할 수 있다.

언급된 도구

Claude Code중립

Anthropic의 공식 CLI 코딩 에이전트

Claude.md추천

에이전트 행동 규칙 및 프로젝트 컨텍스트 설정 파일