Claude Code 팀은 검증을 어떻게 바라보는가

TMT

https://claude.dev/blog/how-the-claude-code-team-thinks-about-verification/

코딩 에이전트가 엔드투엔드 테스트, 속성 기반 테스트, 차등 테스트로 자신의 작업을 근거와 함께 검증하는 방법과 Claude Code 팀이 검증 절차 자체의 신뢰성을 확인하는 방법을 소개합니다.

Claude Code 팀에서는 전체 코드의 약 90%를 Claude가 작성하고 리뷰합니다. 이 정도 규모에서는 에이전트가 자기 작업을 근거와 함께 검증할 수 있게 해 주는 일이 특히 중요합니다.

Claude에 더 많은 일을 맡기려면 검증 루프가 필요합니다. 검증 루프가 없으면 모든 결과를 직접 확인해야 하므로 Claude를 한 번에 한두 개 정도만 실행할 수 있습니다. 검증 루프를 갖추면 수십 개, 수백 개를 동시에 실행할 수 있습니다.

에이전트에게 자기 결과물을 검증할 방법을 주면 작업 품질이 높아집니다. 구조화된 파일 생성에 관한 내부 실험에서는 별도의 평가기가 채점 기준에 따라 Claude의 결과를 검토하도록 했을 때 일반적인 프롬프트 반복 방식보다 작업 성공률이 최대 10포인트 높아졌습니다. 특히 가장 어려운 문제에서 개선 폭이 컸습니다.

예전에는 테스트나 벤치마크, 명세를 마련하고 시스템을 처음부터 끝까지 실행해 검증하는 데 비용이 많이 들었습니다. 이제는 에이전트에게 큰 부담 없이 맡길 수 있습니다. 에이전트는 코드를 만들듯 테스트, 벤치마크, 명세도 빠르게 만들 수 있습니다. 한 번 만든 테스트와 벤치마크는 소프트웨어로 실행되므로, 반복해서 돌려도 토큰이 많이 들지 않습니다.

검증 결과를 다시 에이전트에 반영해 해당 작업에서 더 나은 결과를 내도록 하면 검증 루프가 완성됩니다. 예를 들어, 로그에 사용자 데이터가 찍히는지 확인하는 테스트에 에이전트가 반복해서 실패한다면 훅을 만들거나 CLAUDE.md에 더 명확한 규칙을 적어 둘 수 있습니다. 그러면 같은 문제가 반복되는 일을 대부분 막을 수 있습니다.

이처럼 좋은 코드를 빠르게 만들려면 검증이 중요합니다. 어떤 테스트를 쓰고 개발 과정의 어느 단계에서 실행해야 할까요? 이 글에서는 그 질문에 답하고 Claude Code 팀이 실제로 사용하는 절차도 소개합니다.

시간을 들일 만한 테스트 세 가지

어떤 종류의 테스트를 쓰든 피해야 할 문제가 몇 가지 있습니다.

테스트 결과가 불안정하면 에이전트는 실패할 때마다 테스트를 다시 돌리는 습관을 들입니다. 그러면 실패 원인을 고치기 어려워집니다. 테스트가 느리면 에이전트가 여러 작업을 묶어 처리하는 동안 테스트를 덜 돌리게 되어 문제가 생긴 지점을 찾기 어려워질 수 있습니다. 실행 비용이 큰 테스트는 변경 사항을 커밋하기 전에 돌리는 편이 좋습니다.

제가 시간을 들일 가치가 가장 크다고 보는 테스트는 다음 세 가지입니다.

엔드투엔드 테스트

한 가지 테스트에만 집중해야 한다면 엔드투엔드(E2E) 테스트를 고르세요. E2E 테스트는 상품을 장바구니에 담고 결제한 뒤 확인 페이지로 이동하는 것처럼, 사용자가 실제로 거치는 과정을 테스트합니다.

E2E 테스트가 효과적인 이유는 기능 전체가 동작해야 통과하기 때문입니다. 어느 상태에 도달해야 성공인지 분명하고, 문제가 생기면 어느 지점에서 무엇이 잘못됐는지 구체적으로 알려 줍니다.

image

그림 A. 단위 테스트에는 ‘30초 제한 시간 초과’라는 메시지만 나올 수 있습니다. 엔드투엔드 테스트는 스크린샷과 함께 어떤 부분이 동작하지 않았는지 보여 줄 수 있습니다.

단위 테스트는 더 빠르고 결과도 안정적인 편이지만, 모두 통과해도 기능이 망가질 수 있습니다. 에이전트와 단위 테스트 모두 작업 전체를 파악하지 못할 수 있기 때문입니다.

E2E 테스트에서는 에이전트가 실제로 실행 중인 시스템을 직접 조작하고 화면이나 응답을 확인할 수 있게 하면 효과적입니다. CDP, 시뮬레이터, API 테스트 하네스 같은 도구로 앱을 실행한 뒤 조작하고 결과를 확인하는 스킬을 만들 수 있습니다.

기능 맵은 에이전트의 사용 안내서이자 평가 기준으로 쓸 수 있습니다. 기능 맵에는 보통 사용자 관점에서 기능을 나열하고, 기능에 도달하는 경로와 키보드 단축키, 셀렉터, 예상 결과를 적어 둡니다.

속성(Property) 기반 테스트로 반드시 지켜야 할 조건을 확인합니다

많은 테스트는 사람이 미리 예상한 문제에서 출발합니다. 속성 기반 테스트는 사람이 놓치기 쉬운 경계 사례까지 살핍니다. 에이전트가 자주 실패하는 곳도 이런 경계 사례입니다.

먼저 어떤 입력에서도 성립해야 한다고 보는 조건을 적습니다. 그런 다음 JS/TS의 fast-check, Python의 Hypothesis, Rust의 proptest 같은 테스트 라이브러리로 입력을 수천 개 만들어 그 조건을 깨뜨리는 사례를 찾습니다.

거의 모든 소프트웨어 프로젝트에서 다음과 같은 속성을 찾을 수 있습니다.

  • 인코딩 왕복. X를 인코딩한 뒤 다시 디코딩하면 X가 나옵니다. 파싱과 직렬화에도 같은 원리를 적용할 수 있습니다.
  • 불변식. 계좌 잔액은 음수가 될 수 없다는 조건처럼 언제나 참이어야 합니다.
  • 멱등성. 마이그레이션, 정규화, 재시도 같은 작업을 두 번 해도 한 번 했을 때와 결과가 같습니다.
  • 동등성. 최적화한 코드가 단순하지만 올바른 구현과 같은 결과를 냅니다.

속성 기반 테스트 라이브러리는 원래 코드를 구현한 에이전트가 미처 고려하지 못했을 경계 사례를 만들어 결과를 검증할 수 있게 해 줍니다. 명세와 운영 환경의 실제 동작이 달라져 명세를 검증 기준으로 삼기 어려울 때 코드를 다시 작성하는 작업에도 특히 유용합니다.

차등(Differential) 테스트에서는 기존 시스템을 기준으로 삼습니다

동작을 그대로 유지해야 하는 대규모 마이그레이션에는 차등 테스트가 특히 효과적입니다. 기존 시스템과 새 시스템을 같은 입력으로 실행해 결과가 다른지 확인합니다. 결과가 다르면 수정해야 할 버그나 호환성을 깨뜨리는 변경이 있는지 살펴야 합니다.

차등 테스트에서는 무작위로 생성한 입력이나 운영 트래픽의 표본을 쓰는 것이 중요합니다. 공백처럼 결과에 영향을 주지 않는 차이는 정규화하고, 의도적으로 동작을 바꾼 경우에 대비해 승인한 변경 사항의 목록을 관리하는 편이 좋습니다.

Claude Code 팀의 검증 방식

이전에 Anthropic이 코드 리뷰를 하는 방식을 소개했습니다. 이번에는 우리가 작업 결과를 검증하는 과정을 더 자세히 살펴봅니다.

검증하려면 변경한 기능을 직접 실행합니다

앱을 처음부터 끝까지 직접 실행해 보는 일은 테스트를 돌리는 것보다 중요합니다. iOS 앱을 변경했으면 배포 전에 시뮬레이터에서 직접 실행해 봅니다. Claude에도 같은 기준을 적용합니다.

Claude는 사람이나 QA 엔지니어가 하듯 앱 전체를 테스트할 수 있습니다. 웹 변경에는 Claude Chrome 확장 프로그램을, 모바일 앱에는 iOS나 Android MCP를, 데스크톱 앱에는 컴퓨터 사용 기능을 쓰게 할 수 있습니다. 백엔드 작업이라면 서비스를 로컬에서 실행하게 하면 됩니다.

시뮬레이터를 시작하거나 앱을 실행하는 절차를 기록하려면 verify라는 스킬을 만드세요. 저장소의 .claude/skills/ 디렉터리에 두되 관련 코드와 가깝게 배치하고, 필요한 만큼 만들어도 됩니다. Claude는 변경 사항을 커밋하기 전에 verify 스킬을 사용해야 한다는 것을 압니다.

그다음에는 verify 스킬이 빠르고 안정적으로 동작하도록 다듬으세요. Claude에 스킬을 여러 번 개선하고 스트레스 테스트를 해 보라고 요청할 수 있습니다. 기본 동작을 빠르게 확인하는 스모크 테스트에 쓰이므로, 실행할 때마다 믿을 수 있는 결과를 내야 합니다.

Claude가 변경 사항을 처음부터 끝까지 스모크 테스트할 수 있게 하면 결과가 훨씬 좋아집니다. 사람처럼 변경과 검증을 반복하며 실제 오류를 더 빨리 찾아냅니다. Anthropic에서는 거의 모든 변경 사항을 이렇게 테스트합니다.

테스트가 계속 실패하면 사람이 확인합니다

모든 변경 사항을 사람이 읽을 수는 없으므로, 검증 실패를 사람이 개입할 때를 판단하는 신호로 씁니다. Claude가 검사를 실행하고 실패한 항목을 고치려고 시도합니다. 세 차례를 거쳐도 검사가 계속 실패하면 Claude는 작업을 멈추고 사람에게 확인을 요청합니다.

코드 담당자가 검사를 작성합니다

코드를 맡은 사람이 검사를 직접 작성하고, 자신이 리뷰에서 지적할 만한 문제를 검사로도 찾아낼 수 있게 다듬습니다. 검사 결과에 따라 리뷰어에게 확인을 요청할 때는 그 이유를 함께 알려 줘야 합니다. 그래야 리뷰어가 변경 내역을 보며 요청 이유부터 추측할 필요가 없습니다.

변경 내역에 따라 신뢰성 검사를 실행합니다

우리는 39개 항목으로 구성된 신뢰성 체크리스트를 관리합니다. 각 항목에는 변경 내역에서 파악할 수 있는 실행 조건, 확인할 사항, 그 항목의 근거가 된 장애 사례나 PR을 적습니다. 한 항목은 ‘--resume으로 예전 세션 기록을 불러올 수 있는가’입니다. 세션을 저장하는 방식이나 메시지 타입이 바뀌면 새 필드가 없어도 예전 기록을 안전하게 불러올 수 있는지 확인합니다.

Claude는 변경 내역을 읽고 실행 조건에 해당하는 항목만 검사합니다. 보통 3~10개입니다. 덕분에 팀원이 과거의 장애를 일일이 기억할 필요가 없습니다.

리뷰어 한 명이 여러 차례 검토합니다

우리는 먼저 기존 리뷰어가 더 잘 검토하도록 조정합니다. 이미 리뷰어가 있는 상황에서 비용이 더 많이 드는 리뷰어를 한 명 추가하는 방식은 효과가 떨어질 때가 많습니다. 우리는 REVIEW.md에 해당 코드에서 리뷰어가 주의 깊게 살펴볼 내용을 적습니다.

리뷰와 검증은 앞 단계의 결과를 이어받아 진행하는 편이 좋다고 생각합니다. 매번 앞선 검토 결과와 과거 실패 사례를 참고하도록 합니다. 처음부터 전부 다시 검사할 때보다 비용이 적게 들고 문제도 더 많이 찾습니다.

변경 사항은 자신을 평가하는 검사를 수정할 수 없어야 합니다

변경 사항이 자신을 평가할 검사를 수정할 수 있다면 검사는 제 역할을 하지 못합니다. Code Review는 베이스 브랜치나 기본 브랜치에 있는 REVIEW.md를 읽습니다. PR에 포함된 REVIEW.md 수정은 해당 PR의 리뷰에 적용할 수 없습니다. Claude Code 팀은 변경 사항의 통과 여부를 결정하는 규칙을 해당 변경으로 수정할 수 없는 브랜치에 둡니다.

Claude Code 팀은 리뷰 대상을 특정 커밋으로 고정합니다. 리뷰가 진행되는 동안 누군가 새 커밋을 푸시하면 그 리뷰 결과는 쓸모를 잃습니다. 이전 커밋이 리뷰를 통과했어도 새 커밋의 상태는 알 수 없습니다.

팀에서는 비용이 적게 드는 검사부터 실행합니다. 에이전트가 로컬에서 테스트하기 전에 푸시하면, 스스로 잡을 수 있었던 버그에 팀의 리뷰 시간과 CI 자원을 쓰게 됩니다. 우리 팀에서 Claude는 PR을 열기 전에 테스트, 빌드, 린터를 실행합니다. Claude가 작업을 마칠 때 테스트를 실행하는 훅을 두거나, 테스트 모음 전체가 통과하도록 /goal에 목표를 지정해 이 절차를 적용할 수 있습니다.

커밋을 차단하는 새 규칙은 관찰 모드에서 시작합니다

우리 저장소에서는 각 커밋에 어떤 방식으로 검증했는지 기록합니다. 검증을 거치지 않았으면 none을 남겨 나중에 검색할 수 있게 합니다.

세션에서 /code-review나 /verify를 실행한 기록이 없을 때 커밋을 차단할 수 있는 장치도 만들었습니다. 모드는 off(끄기), observe(관찰), enforce(강제 적용) 세 가지입니다.

관찰 모드에서는 차단했을 커밋을 로그에만 남깁니다. 실제 작업에 영향을 주지 않으면서 잘못 차단할 사례가 있는지 검토할 수 있습니다.

강제 적용 모드에서는 커밋을 차단합니다. 검증을 거치지 못한 이유는 커밋 메시지에 적을 수 있습니다. 한 세션에서 두 번 차단되면 다음 커밋은 허용합니다. Claude Code도 잘못 판단할 수 있으므로 작업이 계속 막히는 일을 피하기 위해서입니다.

실제로 중요했던 문제로 검사 성능을 평가합니다

Claude Code 팀은 리뷰어의 성능도 정기적으로 검토합니다. 머지한 뒤 되돌린 변경 건수와 메인테이너가 머지 전에 거절한 변경 건수를 추적합니다. 문제 없이 유지된 변경 중에서도 앞의 사례와 변경 규모가 비슷한 표본을 골라 추적합니다.

별도의 평가를 설계할 수도 있습니다. 코드 리뷰에 관한 글에서 Code Review 팀이 과거 장애 사례와 변경을 되돌린 사례로 평가를 구성한 방법을 소개했습니다. 팀은 각 사례의 저장소를 당시 리뷰 시점으로 복원하고, 어떤 버그가 있었는지 한 문장으로 정답을 제공합니다. 해당 버그를 정확하게 설명한 지적만 점수를 받습니다. 문제를 과도하게 지적하지 않게 하려고 머지한 뒤에도 안정적으로 동작한 변경을 대조군으로 사용합니다. 튜닝에 쓰는 데이터와 시스템 평가에 쓰는 고정 테스트 세트는 따로 관리합니다.

최초 탐지 결과, 검증을 거친 결과, 최종 리뷰에서 각각 재현율도 측정했습니다. 그러면 시스템이 앞 단계에서 이미 찾은 버그를 어디서 놓치는지 알 수 있습니다. 전체 과정에 점수 하나만 부여하면 단계별로 무엇이 달라졌는지 파악하기 어렵습니다.

지적이 타당한지도 중요하지만, 실제로 수정할 필요가 얼마나 큰지도 살핍니다. 좋은 리뷰어는 기술적으로 지적할 만한 사항을 대부분 찾아냅니다. 리뷰를 받는 사람에게는 그중 반드시 고쳐야 할 버그와 고치는 편이 좋은 버그, 사소한 지적을 구별하는 일도 중요합니다.

Code Review는 이런 차이를 Important, Nit, Pre-existing으로 표시합니다. Pre-existing은 원래 있던 버그라는 뜻으로, 리뷰어가 이번 PR 작성자에게 그 문제까지 해결하라고 요구해서는 안 된다는 표시입니다.

마지막으로 Claude Code 팀은 실제 버그를 더 잡아낼 수 있는 범위에서 재현율을 높입니다. 다음 조정이 평가 데이터에 과적합할 것으로 보이면 멈춥니다.

놓친 문제를 규칙으로 남깁니다

Claude Code 저장소에서는 놓친 사례를 규칙으로 바꾸는 방법을 두 가지 씁니다. 첫째, 사람이 남긴 코드 리뷰 댓글과 PR을 되돌린 사례에서 반복되는 문제를 찾습니다. 규칙 후보로 삼으려면 PR 두 건 이상에서 반복되고, 변경 내역에서 식별할 수 있어야 합니다. 에이전트 세 개가 이 규칙에 반례가 있는지 확인하고, 사람이 PR에서 검토해 승인합니다.

둘째, 이미 알려진 장애와 관련된 PR에 버그 탐지 에이전트 세 개를 다시 실행합니다. 둘 이상이 버그를 찾으면 탐지 가능한 버그로 봅니다. 규모가 작은 변경 내역에서조차 버그를 놓쳤다면 REVIEW.md에 규칙을 추가해 그 빈틈을 메울 만합니다.

결과가 불안정한 테스트도 같은 방식으로 다룹니다. Claude는 테스트를 건너뛰거나, 대기 시간을 넣거나, 통과할 때까지 재시도할 수 없습니다. 근본 원인을 찾지 못하면 테스트를 삭제하고 그 이유를 기록합니다.

규칙도 주기적으로 정리합니다. 내버려 두면 테스트 모음과 검증 단계, Markdown 파일이 계속 늘어나기 때문입니다.

좋은 테스트가 좋은 결과를 만듭니다

에이전트가 제대로 된 피드백을 받으며 자신의 작업을 검증할 수 있게 하면 결과가 크게 달라진다는 것을 확인했습니다. 검증 체계도 다른 시스템과 마찬가지로 관리하세요. 평가 대상인 변경이 검증 체계에 손댈 수 없게 하고, 실제로 중요했던 버그를 잡는지 평가하세요. 놓친 문제가 반복되지 않도록 배운 점을 기록하고, 계속 적용할 가치가 있는 규칙만 남기세요.

이렇게 하면 사람의 역할은 모든 변경 내역을 읽는 일에서 완료 기준을 정하고 검증 근거를 검토하는 일로 옮겨갑니다. 그 덕분에 여러 Claude를 동시에 실행할 수 있습니다.

Edit this page

Search the archive

Find a page by title, or search the text inside one.