Claude Code 팀은 코드를 생성하기 전에 검증한다. 이러한 계층적 접근은 AI Agent가 실제 프로젝트를 맡을 수 있는가를 가르는 핵심 요소다.
Claude Code 검증법: 코드보다 근거를 먼저 남기자
Anthropic은 《How the Claude Code team thinks about verification》를 공개하며 Claude Code 팀의 코드 검증 절차를 설명했다.
Anthropic 공식 엔지니어링 팀이 정리한 내용은 특정 기능의 사용법이 아니다. AI 프로그래밍 Agent가 근거를 통해 생성 결과를 통제하는 방식에 관한 논의다.
핵심 변화는 모델의 코드 작성 능력이 아니라, 검증이 생성 과정에介入하기 시작했다는 데 있다.
관련 링크는 Hacker News 메인 페이지에 올라가 119 points와 123 条评论를 확보했다. 팀 내부에서 코드를 어떻게 검증하는지는 AI Agent가 실제 프로젝트를 맡을 수 있는지와 직접 연결된다.
검증은 생성 뒤에 덧붙이는 패치가 아니다
전통적인 개발 흐름에서는 테스트를 코딩 뒤에 배치한다.
- 개발자가 기능을 구현한다.
- 테스트를 작성하거나 보완한다.
- 테스트를 실행하고 실패한 부분을 수정한다.
- code review를 통해 변경 사항을 점검한다.
AI 프로그래밍 Agent에서는 이 순서가 다른 형태로 바뀌기 쉽다. Agent가 한 번에 많은 코드를 생성한 뒤, 테스트 결과에 따라 반복해서 패치한다.
겉보기에는 빨라졌지만 위험은 뒤로 모인다. 코드가 많아질수록 빠뜨리는 경계 조건도 늘어난다. 다른 생성 코드가 오류를 그럴듯하게 ‘설명’하면 잘못된 자기일관성까지 만들어질 수 있다.
Claude Code 팀은 검증을 훨씬 이른 단계에서 워크플로에 넣는다. Agent는 구현을 쓰기 전에 요구사항이 어떻게 검사 가능한 조건으로 바뀔지 먼저 확인한다.
예를 들어 어떤 인터페이스가 두 입력 제약을 만족해야 하고, 반환값을 기존 호출부가 사용할 수 있어야 한다고 하자. 검증 작업은 마지막에 pytest를 한 번 돌리는 데서 끝나서는 안 된다. 먼저 실행 가능한 단언으로 만들어야 한다.
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
quantity: int
@app.post("/items")
def create_item(item: Item) -> dict:
if not item.name.strip():
raise HTTPException(status_code=422, detail="name must not be empty")
if item.quantity <= 0:
raise HTTPException(status_code=422, detail="quantity must be positive")
return {"name": item.name.strip(), "quantity": item.quantity}
여기서 중요한 것은 FastAPI가 아니다. 테스트 의도를 명확한 규칙으로 먼저 적고, 구현이 그 규칙에 책임을 지도록 만드는 것이 핵심이다.
생성된 코드가 실행된다는 사실은 문법과 일부 경로가 맞다는 것만 증명한다. 정확하게 인도하려면 더 많은 근거가 필요하다.
계층적 검증의 실제 적용
공식 글은 하나의 테스트 명령을 제시하지 않는다. 대신 여러 층의 검사 방식을 설명한다. 검증 대상은 세 가지로 나눌 수 있다.
첫 번째 층: 자동 테스트
테스트는 입력과 출력, 상태 변화, 예외 경로, 회귀 동작처럼 반복 가능한 기계적 검사를 담당한다.
최소한의 단위 테스트는 다음과 같다.
from fastapi.testclient import TestClient
from app import app
client = TestClient(app)
def test_create_item_rejects_empty_name():
response = client.post(
"/items",
json={"name": " ", "quantity": 1},
)
assert response.status_code == 422
def test_create_item_rejects_non_positive_quantity():
response = client.post(
"/items",
json={"name": "keyboard", "quantity": 0},
)
assert response.status_code == 422
이런 근거는 CI에 넣기에 가장 적합하다. 커밋 전에 한 번 실행하고, 병합 전에 다시 실행한다. 실패 메시지는 어떤 제약이 깨졌는지 곧바로 가리켜야 한다.
Agent가 단순히 ‘확인했다’고 말하고 명령 출력이나 테스트 결과, 실패 기록을 제시하지 않는다면 그것은 검증이 아니다.
두 번째 층: 정적 규칙
정적 검사는 테스트로 잡기 어려운 문제를 찾는다. 예를 들어 형식, 타입, 사용하지 않는 변수, 프로젝트 내부에서 정한 아키텍처 경계가 여기에 해당한다.
Python 프로젝트에서는 다음 명령들을 조합해 실행할 수 있다.
ruff check .
ruff format --check .
mypy app
pytest -q
이 도구들은 업무 의미 전체를 이해하지 않는다. 이해할 필요도 없다. 검증 체계는 각기 다른 종류의 문제를 서로 다른 도구가 처리하도록 구성하는 것이 맞다.
테스트는 ‘동작이 올바른가’를, linter는 ‘코드가 형식 규칙을 지켰는가’를, type checker는 ‘타약이 일관되는가’를 답하는 데 적합하다. 모든 일을 ‘문제가 없도록 확인해 달라’ 하나로 섞으면 Agent는 안정적인 피드백을 얻지 못한다.
세 번째 층: 사람의 판단
사람의 판단은 당분간 기계가 증명하기 어려운 부분을 담당한다. 제품 의도가 합리적인지, API 설계가 명확한지, 변경이 요구사항을 넘어섰는지, 코드가 장기적으로 유지될 가치가 있는지가 여기에 해당한다.
Claude Code 팀의 직접 경험이 중요한 이유다. AI Agent는 국소적인 구현을 가속할 수 있지만, 복잡한 프로젝트에 존재하는 목표 충돌, 암묵적 제약, 아키텍처상의 절충은 여전히 엔지니어링 판단이 필요하다.
따라서 사람의 검사는 모든 함수 끝에서 코드를 다시 훑는 일로 이해할 필요가 없다. 더 적절한 위치는 변경 흐름의 핵심 지점이다. 요구사항 경계, 인터페이스 설계, 핵심 동작, 최종 차이 같은 지점이 대상이 된다.
모델 자기 점검에서 엔지니어링 제약으로
많은 Agent 도구는 모델이 답변하기 전에 ‘자기 코드를 점검해 보라’고 지시한다. 이것은 모델 자기 점검이며 도움이 되지만 근거 수준은 낮다.
이유는 단순하다. 모델이 구현자와 평가자 역할을 동시에 맡는다. 방금 저지른 오류를 놓칠 수 있고, ‘그럴듯해 보인다’를 ‘검증했다’로 표현할 수도 있다.
더 안정적인 방법은 판단을 엔지니어링 제약으로 바꾸는 것이다.
- 요구사항을 인수 조건으로 작성한다.
- 인수 조건을 테스트로 바꾼다.
- 프로젝트 규칙은 정적 도구에 맡긴다.
- 고위험 경로에는 사람의 확인을 요구한다.
- 모든 결론에 재현 가능한 명령과 결과를 첨부한다.
CI에서 사용할 검증 진입점은 다음처럼 간결하게 유지할 수 있다.
name: verify
on:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install -r requirements-dev.txt
- run: ruff check .
- run: ruff format --check .
- run: mypy app
- run: pytest -q
Claude Code 같은 AI Agent에서는 자연어 자기 평가보다 도구 출력이 중요하다. 실패할 때는 테스트가 결정적인 입력, 실제 출력, 예상 출력을 제시해야 한다. 그래야 Agent는 안정적인 수정 근거를 얻는다.
검증 워크플로의 본질은 모델에게 ‘더认真해 달라’고 요구하는 데 있지 않다. 더 저렴하고 일관된 피드백을 제공하는 데 있다.
전통적인 개발 흐름과의 차이
사람이 직접 코드를 작성하는 방식을 Claude Code와 결합하는 것은 키보드를 채팅창으로 바꾸는 것과 다르다.
전통적인 흐름은 보통 하나의 함수를 중심으로 진행된다. 구현을 작성하고, 테스트를 보완하고, bug를 수정한다. 반면 Agent 式 개발은 한 번에 열 개가 넘는 파일을 수정하며 설정, 의존성, 마이그레이션 스크립트, 호출부까지 건드릴 수 있다.
따라서 검증 대상도 하나의 함수에서 전체 변경 흐름으로 확장된다.
- 수정이 최초 요구사항을 빠짐없이 다뤘는가.
- 새 인터페이스가 기존 호출부와 호환되는가.
- 데이터 마이그레이션을 반복 실행해도 안전한가.
- 실패 경로에서 롤백하거나 안전하게 종료하는가.
- 문서와 실제 동작이 일치하는가.
- 전체 자동 검사를 통과했는가.
전통적인 code review는 주로 diff를 살펴본다. AI Agent 협업에서는 ‘근거 체인’도 확인해야 한다. 예를 들어 코드가 동시성 문제를 수정했다고 주장한다면, 그에 대응하는 동시성 테스트나 재현 가능한 스크립트가 있어야 한다. 그럴듯한 lock 처리 코드만 제출해서는 안 된다.
검증 비용도 달라진다. 과거에는 테스트 비용을 코딩 후 정리하는 비용으로 여겼다. Agent 방식에서는 실행 중 제어에 더 가깝다. 테스트가 구체적일수록 Agent가 미지의 영역에서 추측하는 일은 줄어든다.
커뮤니티 논쟁과 적용 경계
이 글은 Hacker News 메인 페이지에 올라가 119 points와 123 条评论를 얻었다. 수치는 해당 Hacker News 토론 페이지에서 확인할 수 있다.
높은 관심背后에는 합리적인 의문이 하나 있다. 계층적 검증은 규칙을 증명할 수 있지만, 규칙 자체를 올바르게 선택했다는 것까지 증명하지는 못한다.
테스트와 명세가 같은 근원에서 나오면 Agent는 잘못된 이해를 코드에 옮기고, 그 이해에 충실하게 통과하는 테스트를 작성할 수도 있다. 정적 규칙은 타입은 검사하지만 제품 결정이 합리적인지는 알지 못한다. 사람의 review도 시간과 주의력의 제약을 받는다.
복잡한 프로젝트에는 현실적인 문제가 세 가지 더 있다.
- 과거 테스트 자체가 불완전하거나 과거의 오류를 그대로 고정해 두었을 수 있다.
- 엔드투엔드 환경을 구축하는 비용이 커서 Agent가 매 변경마다 전체를 재현하기 어렵다.
- 검증 스크립트도 유지보수가 필요하다. 규칙이 많아지면 피드백 노이즈가 증가한다.
따라서 검증은 개수를 늘리는 경쟁이 되어서는 안 된다. 테스트가 많을수록 좋은 것이 아니라, 핵심 동작에 충분한 근거가 있어야 한다. 결제 로직, 권한 경계, 데이터 마이그레이션에는 더 엄격한 검사가 필요하지만, 단순히 보여주기 위한 문구에는 복잡한 절차를 구축할 필요가 없을 수 있다.
Claude Code에 대한 평가도 이 경계 안에서 해야 한다. 국소적인 변경을 잘 수행한다는 점과 프로젝트의 신뢰성을 같은 차원으로 놓을 수는 없다. 실제로 비교할 만한 항목은 실패를 재현할 수 있는지, 오류 위치를 찾을 수 있는지, 수정 후 자동 회귀 검사가 가능한지, 사람이 제한된 시간 안에 핵심 결정을 검토할 수 있는지다.
적용은 다음 세 단계부터 시작할 수 있다.
- 핵심 요구사항에 실행 가능한 인수 조건을 작성한다.
- CI에서 테스트, lint, 타입 검사 명령을 고정한다.
- Agent에게 실패 재현 방법, 실제 출력, 검증 결과를 제출하도록 요구한다.
원문 자료:
편집자 생각
Claude Code 팀의 이 글에서 중요한 것은 또 하나의 테스트 기법을 제시했다는 데 있지 않다. AI 프로그래밍의 경쟁 기준을 ‘얼마나 많은 코드를 생성했는가’에서 ‘얼마나 많은 검증 가능한 근거를 제출했는가’로 옮겼다는 데 있다. 과거에는 코드 생성 비용이 커서 검증이 축소되는 경우가 많았다. Agent를 통해 생성이 거의 무료가 되면서, 희소한 자원은 인수 규칙, 테스트 설계, 실패 위치 추적으로 이동하고 있다.
검증 능력은 코드 생성 능력을 대체하지 않지만 생성 능력의 평가 방식을 바꿀 것이다. 핵심 동작을 어떻게 검증할지 설명하지 못하는 Agent가 2,000줄의 코드를 빠르게 작성하더라도 실제 인도 가치는 30줄만 수정하고 회귀 테스트까지 첨부한 Agent보다 낮을 수 있다.
이번 접근이 과거와 다른 점은 공식 엔지니어링 팀이 검증을 Agent 워크플로의 앞부분에 배치했다는 데 있다. 테스트는 생성 완료 후 치우는 작업이 아니라 모델의 행동을 제약하는 제어 계층이 됐다. 다만 이 계층적 방식이 대형 레거시 시스템에서도 선형으로 확장될지는 판단하기 어렵다. 규칙 노이즈, 테스트 유지보수 비용, 사람의 판단 병목은 여전히 효과를 제한할 수 있다. Claude Code 같은 도구를 평가할 때는 데모에서 보여준 완료 속도보다 실패 근거와 변경 흐름을 우선해서 살펴야 한다.