새로운 모델이 출시될 때마다 항상 똑같은 의식이 반복됩니다. 모델 문자열(model string)을 바꾸고, 에이전트를 실행하고, 몇 개의 답변을 읽어본 뒤, 괜찮아 보이면 배포하는 것이죠.

답변은 에이전트에서 눈에 보이게 거의 깨지지 않는 유일한 부분입니다. 실제로 깨지는 것은 행동(behavior)입니다. 도구 호출(tool call)이 조용히 사라지거나, 인자(argument)가 어긋나거나, 환불 금액에서 소수점이 사라지는데도 에이전트는 모든 것이 정상인 것처럼 계속 말을 합니다. 저는 모델 교체로 인해 에이전트가 사용자에게 구독이 취소되었다고 계속 말하면서도 정작 cancel_subscription 함수는 호출하지 않게 되었을 때 이 교훈을 뼈아프게 배웠습니다.

이번 주에 새로운 프런티어 모델(frontier model)이 출시되면서 많은 모델 문자열이 변경될 예정입니다. 이것은 제가 이제 어떤 교체 작업을 하기 전에도 실행하는 체크리스트입니다. 약 20분이 소요되며, 단순한 느낌(vibe check) 대신 실제 차이점(diff)을 만들어냅니다.

1. 아무것도 건드리기 전에 기준점(baseline)을 기록하세요

이 단계는 나중에 복구할 수 없는 단계입니다. 일단 교체하고 나면 이전의 행동은 사라집니다.

기록 프록시(recording proxy)를 시작하고 코드 변경 없이 에이전트를 그곳으로 향하게 하세요:

npx whatbroke-cli record --out baseline.jsonl

OPENAI_BASE_URL=http://127.0.0.1:4141/v1     # openai sdk
ANTHROPIC_BASE_URL=http://127.0.0.1:4141     # anthropic sdk

에이전트를 실제 시나리오를 통해 실행하세요. 에이전트는 비결정론적(nondeterministic)이므로, 각 시나리오를 세 번씩 실행하고 실행 이름을 refund-flow#1, refund-flow#2, refund-flow#3로 지정하세요 (요청당 x-whatbroke-run 헤더를 사용하거나 --run 옵션 사용). 시나리오당 세 개의 샘플이면 일시적인 변동(flaps)과 실제 변화를 구분하기에 충분합니다.

에이전트가 무언가를 '수행'해야 하는 시나리오를 선택하세요: 도구 호출, API 호출, 기록 작성 등. 순수 대화 시나리오는 눈에 보이게 깨지는 것이 거의 없으므로 정보를 가장 적게 제공합니다.

2. 모델을 교체하세요. 오직 모델만 바꾸세요.

모델 문자열을 변경하세요. 그 외에는 아무것도 하지 마세요. 만약 새로운 모델을 위해 프롬프트(prompt)도 조정하고 싶다면, 별도의 차이점(diff)을 가진 두 번째 교체 작업으로 진행하세요. 그렇지 않으면 어떤 변경 사항이 무엇을 유발했는지 절대 알 수 없습니다.

3. 동일한 시나리오를 다시 기록하세요

npx whatbroke-cli record --out swapped.jsonl

동일한 시나리오, 동일한 이름, 각각 세 번의 실행을 수행합니다.

4. 차이점 비교 (Diff)

npx whatbroke-cli diff baseline.jsonl swapped.jsonl

위에서 아래 방향으로 읽으세요:

• breaking (파괴적) 결과부터 확인: 누락된 도구 호출 (tool calls), 이제는 실패하는 실행 (runs), 사라진 출력값 (outputs) 등을 확인합니다. 이 중 하나라도 해당된다면, 모델 교체가 기존 기능을 그대로 대체(drop-in)하지 못한다는 의미입니다.
• changed (변경됨) 결과 확인: 인자 드리프트 (argument drift)는 교묘하게 발생합니다. 도구는 여전히 호출되지만, 서로 다른 인자 (args)로 호출되는 경우입니다. 모든 항목을 수동으로 확인하십시오.
• **flap rate (플랩 비율)**는 발견된 결과가 실제 문제인지 알려줍니다. 3/3은 매번 발생함을 의미합니다. 베이스라인 (baseline)에서도 플랩이 발생했던 항목에 대해 1/3이 나왔다면, 이는 단순히 에이전트 (agent) 고유의 특성일 뿐이며, diff 도구가 이를 자동으로 순위에서 제외합니다.
• 비용 (Cost)과 지연 시간 (latency)은 교체할 때마다 변동합니다. 특정 비율을 초과하는 성능 저하 (regressions)가 발생하면 플래그가 지정됩니다 (기본값: 지연 시간 1.5배, 비용 1.25배).

5. CI에 유지하기

npx whatbroke-cli diff baseline.jsonl current.jsonl --fail-on breaking

파괴적 변경 사항 (breaking changes)이 있을 경우 종료 코드 (exit code) 1을 반환하며, --md 옵션을 사용하면 PR (Pull Request) 댓글에 바로 붙여넣을 수 있는 보고서를 생성합니다.

베이스라인 없이 이미 교체했나요?

만약 사용 중인 에이전트가 Langfuse, LangSmith 또는 OTel GenAI 스팬 (spans)을 생성하는 환경 뒤에서 실행되고 있다면, 이미 베이스라인을 가지고 있는 셈입니다. 단지 아직 비교 (diff)하지 않았을 뿐입니다. 지난주의 트레이스 (traces)와 이번 주의 트레이스를 내보내기 (export) 하세요:

npx whatbroke-cli import last-week-export.json --run baseline
npx whatbroke-cli import this-week-export.json --run swapped
npx whatbroke-cli diff last-week-export.whatbroke.jsonl this-week-export.whatbroke.jsonl

이 도구는 결정론적 (deterministic)이며, 완전히 오프라인으로 작동하고, MIT 라이선스를 따르며, 귀하의 트레이스는 절대 기기를 벗어나지 않습니다: https://github.com/arthi-arumugam-git/whatbroke

답변은 모두 정상적으로 보이지만 교체 시 실제로 무엇이 변하는지에 대한 실제 사례를 보고 싶다면, 동일한 에이전트를 3배 더 작은 모델에서 실행하고 실제로 무엇이 변했는지 작성해 두었습니다.

다음 교체 전에 이 도구를 실행하여 무언가 포착된다면, 그것이 무엇이었는지 진심으로 듣고 싶습니다.