Claude로 평가 설계와 힐클라이밍 자동화하기

평가(evaluation)는 앱이나 스킬이 특정 작업에서 어느 정도 성능을 내는지 알려 주는 신호입니다. 하지만 평가를 설계하는 일도, 스스로 속지 않으면서 평가 점수를 끌어올리는 일도 만만치 않습니다. 그래서 claude-api 스킬에 이 두 가지를 위한 가이드를 추가했습니다.

이 스킬을 쓰면 /claude-api build-eval를 실행해 코드베이스 안에 평가를 만들 수 있습니다. 이어서 /claude-api hillclimb를 실행하면 그 평가를 기준으로 애플리케이션을 한 번에 하나씩 개선해 나가며, 따로 떼어 둔(held-out) 예시 세트로 과적합을 잡아냅니다.

이 글에서는 먼저 좋은 평가 설계와 힐클라이밍의 원칙을 짚어 봅니다. 그다음 claude-api 스킬을 적용한 Claude Code가 이 원칙을 어떻게 구현하는지 살펴보고, 마지막으로 이 명령을 사용한 사례 몇 가지를 소개합니다.

평가 설계

잘 설계된 평가에는 몇 가지 공통 요소가 있습니다(그림 1).

1. 평가 작업은 프로덕션 환경을 반영합니다. 여기서 프로덕션이란 테스트하려는 기능이나 애플리케이션이 실제로 쓰이는 환경을 뜻합니다. 그 환경에서 중요하게 여기는 작업을 표본으로 뽑으세요. 만들기 쉽거나 채점하기 쉽다는 이유로 작업을 고르는 경우가 있는데, 작업 분포가 실제로 신경 쓰는 대상을 대표하는지 반드시 확인해야 합니다.
2. 더 강력한 모델과 더 많은 사고량일수록 성능이 좋아집니다. 일반적으로 더 뛰어난 모델과 더 높은 effort 수준에서는 평가 점수도 더 높게 나와야 합니다. 그렇지 않다면 모호한 작업이나 잘못 보정된 채점기가 성능을 깎고 있을 가능성이 큽니다.
3. 최상위 모델에도 "도달 가능한" 개선 여지가 있어야 합니다. 가장 뛰어난 모델을 가장 높은 effort로 돌렸을 때 100%에 한참 못 미쳐야 변경이 성능에 미친 영향을 믿을 만하게 판단할 수 있습니다. 다만 그 격차가 풀 수 없거나 모호한 작업 때문이어서는 안 됩니다. 반복 횟수와 관계없이 평가를 돌릴 때마다 매번 실패하는 작업이 있다면 이를 의심해 볼 만한 흔한 신호입니다. 좋은 작업이란 두 명의 도메인 전문가가 같은 결론을 내리고, 채점기가 확인하는 모든 내용이 작업 설명에 명시된 작업입니다.
4. 실행 간 편차가 작아야 합니다. 편차가 크다면 대개 작업이 허술하게 설계되어 모호하거나, 채점기가 똑같은 출력에 다른 판정을 내리기 때문입니다. 편차는 설정 속에 숨어 있기도 합니다. 예를 들어 effort가 일관되게 적용되지 않을 수 있습니다. 환경도 결과에 영향을 줍니다. 이전 시도에서 남은 상태(파일, git 기록 등)가 에이전트에게 정답을 알려 줄 수도 있습니다.

적대적 샘플링

모델의 능력은 들쭉날쭉합니다. 오늘의 모델이 실패하는 사례만 골라 담으면 한 모델의 능력 곡면에서 골짜기만 표본으로 뽑는 셈입니다(그림 2). 그러면 평가가 애플리케이션에 본질적으로 어렵거나 가치 있는 일이 아니라, 그 모델의 실패 지문을 측정하게 될 수 있습니다.

어려운 사례는 사람이 어렵다고 판단했기 때문에 골라야 합니다. 작업을 넣기 전에 왜 어려운지 설명할 수 있는지 자문해 보면 유용합니다. 프로덕션 트래픽, 버그 리포트, 티켓에서 나온 애플리케이션 고유의 실패 사례도 포함하세요. 다만 사용자 트래픽을 무조건 믿어서는 안 됩니다. 사용자는 대개 될 거라고 기대하는 것만 시도하므로, 사용자 트래픽에서만 뽑은 작업 분포는 쉬운 쪽으로 치우칠 수 있습니다.

/CLAUDE-API BUILD-EVAL

claude-api 스킬의 build-eval 명령은 이 원칙들을 단계별 안내 워크플로로 만든 것입니다. Claude Code에서 /claude-api build-eval를 실행하면 Claude가 사용자에게 질문하며 요구 사항을 파악하고, 코드베이스 안에 평가를 만들며, 정해진 지점마다 멈추고 승인을 받습니다.

예시 설계

Claude는 다음 순서로 입력을 샘플링해 평가를 구성합니다.

1. 프로덕션 대화 기록: 데이터 보관 기간과 민감 정보 여부를 먼저 확인합니다.
2. 버그 리포트와 고객 지원 티켓
3. 직접 작성한 5~10개의 사례
4. 코드베이스를 바탕으로 합성한 사례

이 스킬은 프로덕션 트래픽을 최우선으로 삼지만, 사용자가 제공한 실제 예시 몇 개를 기준 삼아 합성 데이터를 생성할 수도 있습니다. 스킬은 Claude가 모든 입력을 보여 주는 간단한 페이지를 만들고, 사용자가 확인할 때까지 기다리도록 지시합니다. 그림 3은 이메일 라우터 애플리케이션을 예로 들어, 스킬이 사용자에게 검토를 요청할 수 있는 입력 세트를 보여 줍니다.

채점기 검증

입력을 확정하고 나면 Claude는 애플리케이션의 출력 형태에 맞는 채점기 가운데 가장 저렴한 것을 제안합니다.

• 프로그래밍 방식 검증: 출력 가능한 값이 제한적이라면 코드 기반 검사를 사용합니다(완전 일치, 고정된 집합의 레이블, 스키마에 맞는 JSON, 통과하는 테스트 등).
• LLM-as-judge: 정답이 여러 개일 수 있지만 품질 기준은 분명한, 출력 공간이 열린 경우에는 기본적으로 이 방식을 씁니다. 이때는 두 번째 모델이 입력과 출력, 그리고 확인 가능한 주장 형태로 쓴 루브릭(1~5점 척도가 아님)을 읽고 근거와 함께 점수를 매깁니다. 비교할 기준선(baseline)이 있다면 심사 모델이 두 결과를 무작위 순서로 읽고, 어느 쪽이 기준선인지 모르는 상태에서 더 나은 쪽을 고릅니다. 심사 모델은 사용자가 고르며, 테스트 대상 모델과는 달라야 합니다.

Claude는 소수의 사례를 채점하고, 사용자가 다르게 채점했을 사례가 있는지 묻습니다(그림 4). 일반적으로 평가기를 믿기 전에 채점된 대화 기록을 표본으로 읽어 보는 것이 중요합니다. 채점 오류는 평가가 잘못 구성되는 가장 흔한 원인 중 하나입니다.

채점기 검증이 끝나면 스킬은 평가 세트의 규모(사례 수 × 반복 횟수 × 모델, 그리고 대략적인 소요 시간)를 알려 주고, 기준선을 실행한 뒤 신뢰구간과 함께 점수를 출력합니다. 결과물은 사례, 채점기, 실행기, 사례별 JSON 한 줄과 전체 대화 기록, 그리고 사례별 점수와 대화 기록 링크를 나열한 간단한 페이지입니다. 이 페이지 이상의 것(예: 차트)이 필요하면 요청만 하세요. Claude가 옆에 추가 페이지로 만들어 줍니다. 이런 추가 페이지는 기본적으로 로컬에서 열리는 정적 파일이며 네트워크에서 아무것도 불러오지 않습니다.

진단 검사

앞서 말한 기준선 실행 중에 Claude는 여러 가지를 점검합니다.

• 채점기: 같은 출력을 채점기로 두 번 채점해 판정이 달라졌는지 보고합니다.
• 배관(Plumbing): 타임아웃, API 오류, 잘린 답변이 있는지 확인해 인프라 노이즈가 모델 편차로 오인되지 않도록 합니다.
• 개선 여지: 기준선이 이미 95% 안팎 이상이면 스킬이 경고를 띄우고, 이 경우 힐클라이밍은 품질보다 비용이나 지연 시간을 탐색하는 쪽을 목표로 삼아야 한다고 알려 줍니다.

힐클라이밍

이제 작업 성능을 믿을 만하게 채점할 방법이 생겼으니 성능을 개선해 볼 수 있습니다. 힐클라이밍은 effort나 프롬프트처럼 비용과 성능 사이의 균형을 좌우하는 파라미터를 조정하는 데 효과적입니다. 어디에 적용할지 정할 때 참고할 일반적인 팁은 다음과 같습니다.

• 저렴한 반복 - 힐클라이밍 대상으로 삼은 부분을 수정하는 데 시간, 비용, 노력이 적게 들어야 합니다. 사내 프로젝트와 고객사 중에는 프롬프트나 스킬 같은 텍스트에 힐클라이밍을 집중한 곳이 많습니다. 이런 텍스트는 바꾸기도 되돌리기도 쉽습니다. 반면 힐클라이밍 중에 에이전트 하네스를 자유롭게 수정하도록 열어 두면 대규모 코드 변경이 따를 수 있습니다.
• 귀속 가능성 - 평가 점수의 변화는 힐클라이밍 중에 수정하는 대상 덕분이라고 설명할 수 있어야 합니다. 예를 들어 스킬 트리거링에 힐클라이밍을 적용해 성공한 사례가 여럿 있습니다. 이 경우 평가 지표(스킬 트리거율)가 수정 대상인 스킬 설명과 직접 맞물려 있습니다.
• 범위가 명확한 목표 - 흔한 실패 유형은 평가에 남은 개선 여지를 꼼꼼히 따지지 않고 "성능을 개선해 달라"고 막연히 요청하는 것입니다. 평가가 포화에 가깝거나 수정 대상의 범위가 모호하면(예: 하네스를 알아서 고쳐 달라는 요청) 진전이 멈출 가능성이 큽니다. 여러 프로젝트에서 대체로 좋은 목표로 확인된 것은 비용입니다. 평가가 포화 상태여도 성능을 그대로 유지하면서 비용을 줄일 방법을 찾아 달라고 Claude에게 요청할 수 있습니다.

과적합

아무리 잘 설계한 평가라도 프로덕션에서 중요한 실제 작업 분포와 정확히 일치하는 경우는 드뭅니다. 그래서 평가에 "과적합"되는 문제가 흔히 생기고, 그 결과 프로덕션 트래픽보다 평가에서 성능이 더 좋게 나오는 시스템이 만들어집니다.

평가가 하네스(모델을 둘러싼 코드로, 프롬프트, 도구, Claude를 호출하는 루프를 포함)로 "새어 들어가는" 경로는 다양합니다. 예를 들어 어떤 평가 작업에는 OCR이 도움이 되지만 프로덕션 작업에서는 OCR이 거의 쓸모없다고 해 봅시다. 평가용 하네스가 애플리케이션에 OCR 도구를 추가하면 벤치마크 점수는 오르지만 프로덕션에는 아무 영향이 없습니다. 더 넓게 보면, 힐클라이밍이 선택한 평가 예시의 엣지 케이스를 해결하는 기능을 하네스에 추가할 수도 있습니다. 이런 하네스 변경은 평가 점수를 올리지만 프로덕션 개선으로는 이어지지 않습니다(그림 5).

다음 세 가지가 도움이 됩니다.

• 사례 분할: 힐클라이머가 읽을 수 있는 학습(train) 세트와 한 번도 보지 못하는 테스트(test) 세트로 나눕니다. 학습 세트 점수는 오르는데 테스트 세트 점수가 그대로라면 과적합을 알리는 대표적인 경고 신호입니다.
• 실패 사례를 프롬프트에 그대로 붙여 넣지 않기: 힐클라이머가 실패한 대화 기록을 읽더라도 그 내용을 프롬프트에 그대로 붙여 넣어서는 안 됩니다.
• 정답이 구조적으로 모델의 손에 닿지 않게 하기: 모델은 평가의 정답을 직접 찾아내는 식으로 "보상 해킹(reward hack)"을 하기도 합니다.

아래에서 설명하듯 claude-api 스킬이 이 원칙들을 대신 적용해 줍니다.

/CLAUDE-API HILLCLIMB

claude-api 스킬의 hillclimb 명령은 이 원칙들을 단계별 안내 워크플로로 만든 것입니다. Claude Code에서 /claude-api hillclimb를 실행하면 Claude가 주어진 평가를 기준으로 반복하며 성능을 개선합니다. Claude가 바꿀 수 있는 대상은 사용자가 정하며, 다음이 포함됩니다.

• 시스템 프롬프트
• 스킬 또는 지침 파일
• 도구 설명
• 모델 선택, effort 수준, 기타 API 파라미터
• 하네스 코드

시작 전에 Claude는 무엇을 최적화할지(예: 성능, 또는 성능을 유지하면서 비용 절감) 묻고, 평가 세트를 무작위로 테스트 세트와 학습 세트로 나눕니다. 비용 절감이 목표라면 대표적인 비용 요인 몇 가지를 살펴봅니다. 프롬프트 캐싱, 선택한 모델과 프롬프트의 호환성 점검, 모델과 effort 설정 선택이 여기에 포함됩니다.

첫 라운드 전에 Claude는 평가의 노이즈(우연만으로 점수가 움직일 수 있는 폭)가 사용자가 실제로 반영하려는 최소 개선폭보다 작은지 확인합니다. 그렇지 않으면 그 사실을 알리고 반복 횟수나 사례를 늘리라고 제안합니다.

매 라운드마다 Claude는 직전 라운드의 학습 세트 대화 기록을 읽고 패치 형태로 변경 하나를 제안합니다. 각 라운드는 평가 노이즈를 넘어 효과가 드러날 만한 변경을 목표로 합니다. 문구 한 줄을 다듬는 대신 실패 행동의 근본 원인을 고칩니다(예: 원인이 되는 섹션을 다시 쓰거나 빠진 규칙을 추가). 그런 다음 패치를 적용한 상태로 평가를 실행합니다. 이때 Claude는 검사를 하나 수행합니다. train 세트는 좋아졌는데 test 세트는 그대로라면 과적합을 의심하고 패치를 되돌립니다. 성능이 나빠진 경우에도 되돌립니다. 학습 세트와 테스트 세트가 모두 좋아지면 패치를 유지합니다(그림 6).

점수가 두세 라운드 동안 정체되면 Claude는 남은 학습 세트 실패 사례를 하나씩 읽고 원인별로 분류합니다. 어떤 단일 수정으로도 평가 노이즈보다 큰 개선을 얻기 어렵다면 이 작업을 더 일찍 하기도 합니다. 그럴 때는 측정하기엔 너무 작은 변경에 라운드를 쓰지 않고 반복 횟수나 사례를 늘리라고 제안합니다. 이 단계에서는 모호한 평가 사례, 하네스 오류, 실행 간 편차를 찾아낼 수 있습니다.

이후 힐클라이밍 라운드에는 정당한 실패만 포함됩니다.

힐클라이밍이 끝나면 Claude는 사용자의 목표 기준으로 테스트 세트에서 가장 좋은 성과를 낸 버전으로 코드를 남겨 둡니다. 그리고 기준선 대비 테스트 결과를 신뢰구간과 함께 보고합니다(그림 7). 개선폭이 노이즈 범위 안이라면 그렇다고 알리고 병합하지 말라고 권고합니다.

사례

비용 절감을 위한 힐클라이밍

비용 절감과 성능 개선을 목표로 사내 고객 지원 벤치마크에 /claude-api hillclimb를 실행했습니다. 이 벤치마크는 티켓 44건으로 구성되며, 30건은 탐색에 쓰고 14건은 따로 떼어 두었습니다. 출발점은 기본(high) effort 설정의 Opus 4.8이었고, 탐색용 티켓에서 판정 정확도는 74.4%, 티켓당 토큰 비용은 4.6센트였습니다.

힐클라이밍은 먼저 프롬프트를 점검해 필수 도구 호출 의식(ritual), 스크래치패드 단계, 서로 모순되는 규칙을 제거했습니다. 그런 다음 Opus 5.5를 낮은 effort로 시도했습니다. 그 결과 정확도 87.8%로 기준선 정확도를 넘었고, 비용은 티켓당 1.9센트로 처음의 절반 아래로 줄었습니다.

절감분의 일부는 Opus 5.5의 가격 정책에서 나왔습니다. 입력과 출력 토큰 가격이 Opus 4.8보다 20% 저렴하고, 캐시 읽기는 60% 저렴합니다. Opus 5.5가 기준을 넘었으므로 힐클라이밍은 한 단계 아래로 내려가 더 저렴한 모델도 기준을 넘을 수 있는지 확인했습니다. Sonnet 5를 낮은 effort로 돌리자 점수는 88.9%로 거의 같았고 비용은 티켓당 약 1센트로 절반 수준이었습니다(그림 8).

마지막으로 Claude가 라우팅 규칙과 환불 한도 상호 참조를 추가해 프롬프트를 개선하자 Sonnet 5는 거의 같은 비용으로 98.9%에 도달했습니다. 탐색 과정에서 한 번도 보지 못한 14건의 테스트 티켓에서는 최종 구성이 90.5%를 기록해 원래 구성의 78.6%를 웃돌았고, 비용은 약 5분의 1이었습니다.

성능 개선을 위한 힐클라이밍

또 다른 사례는 claude-api 스킬입니다. 이 스킬은 Anthropic API 사용법과 Claude를 다루는 일반적인 팁(이 글에서 다룬 하위 명령 포함)을 안내합니다. 스킬이 API를 사용하는 코드를 정확하게 구현하는지 확인하고자, 문서를 바탕으로 평가 세트를 만들어 스킬을 테스트했습니다.

이 평가에서 스킬의 출발 점수는 66%였습니다. 힐클라이머에게 문서와 SDK에 접근할 권한을 주어 Claude가 오류를 찾아 스스로 고치게 했습니다(그림 9). Claude는 스킬에 기능 8개에 대한 내용이 빠져 있다는 것을 찾아냈습니다.

해당 섹션을 스킬에 추가하자 성능이 74%로 올랐습니다. 이어 C#과 Java 타입 표의 오류를 찾아 고치면서 77%까지 올랐습니다.

두 라운드 동안 점수가 정체되자 Claude는 남은 실패 사례를 분석해 근본 원인별로 분류했습니다. 일반 라운드에서는 가장 흔한 실패 하나를 골라 한 번 수정합니다. 이 단계에서는 수정 없이 남은 실패를 원인별로 분류하기만 합니다. 이 성찰 단계는 여러 면에서 쓸모가 있었습니다.

• 실패 사례 전체를 돌아본 힐클라이머는 스킬에 내용이 이미 있는데도 Claude가 예전 API 형태로 코드를 쓰고 있다는 것을 발견했습니다(예: 학습된 사전 지식에서 나온 형태). 이를 해결하려고 스킬 상단 근처에 Claude가 기억하는 형태를 최신 형태로 안내하는 표를 추가했습니다. 예를 들어 최근 Opus 모델에서는 API가 더 이상 받아들이지 않는 고정 토큰 예산 방식의 extended thinking을 adaptive thinking으로, 웹 검색과 웹 페치 도구의 구버전을 현재 버전으로 바꾸도록 안내하는 식입니다. 또 C#과 Java의 고정 예산 사고 방식 사용 금지 경고를 adaptive thinking 예시 위로 옮겼습니다. 이렇게 해서 성능이 80%로 올랐습니다.
• 명백한 내용 공백을 메웠는데도 성능이 끝내 오르지 않는 작업은 예시나 채점기에 결함이 있다는 신호입니다. 한 작업은 오류 유형 하나를 잡는 코드를 요구했는데 채점기는 최소 세 단계의 체인을 원했습니다. Claude는 작업 설명을 고쳐 썼습니다. 또 다른 채점기의 지침은 문서와 모순되었는데, 실제 API로 테스트해 보니 문서가 맞았습니다. 이런 문제를 바로잡고 스킬을 추가로 수정하자 성능이 약 88%까지 올랐습니다.

시작하기

이 하위 명령은 claude-api 스킬을 통해 Claude Code에서 바로 사용할 수 있습니다.

특정 문제에 맞는 평가 세트를 만들고 싶다면 /claude-api build-eval를 실행하세요. 트레이스 같은 예시에 접근할 수 있게 해 주면 방향을 잡는 데 도움이 됩니다. Claude는 이 글에서 소개한 가이드를 활용해 예시와 채점기를 설계하고, 사용자가 예시와 채점기를 반드시 승인하도록 합니다.

이미 평가가 있고 Claude가 이를 기준으로 성능을 끌어올리게 하고 싶다면 /claude-api hillclimb를 실행하세요. 목표(예: 더 나은 성능, 또는 성능을 유지하면서 비용 절감)를 기준으로 Claude가 개선을 진행합니다. Claude는 이 글에서 소개한 가이드를 활용해 개선하는 동안 과적합을 확인하고, 평가 자체의 버그도 점검합니다. 예를 들어 맞아 보이는 답을 틀렸다고 채점하는 채점기나 하네스 오류를 첫 라운드 전과 점수가 정체될 때마다 확인합니다.

스킬 개발에 힘써 주신 Misha Khalman께 특별히 감사드립니다. 검토, 기여, 제품 지원을 해 주신 Misha Khalman, Michael Segner, Matt Bell, Matt Thanabalan께도 감사드립니다.