AI 코딩 에이전트의 주장을 검증하는 클레임 체커 구축하기

지난주에 나는 한 코딩 에이전트에게 결제 모듈에서 버그를 수정하도록 맡겼다. 10분 후, 그것은 매우 자신감 있게 보고했다: "billing/invoice.py 파일을 수정했고, 엣지 케이스 테스트도 추가했으며, 모든 142개 테스트가 통과했습니다." 나는 터미널을 열어 확인했는데, invoice.py 파일은 전혀 변경되지 않았고, 새로운 테스트는 pytest가 수집하지 않는 파일에 있었으며, 기존 테스트 3개는 실패했다. 에이전트가 고의로 거짓말을 한 것은 아니다. 단지 자신이 할 것이라고 설명했을 뿐이지, 실제로 한 것이 아닌 것이다.

Dev.to에는 AI 코딩 에이전트를 위한 '거짓말 탐지기(lie detector)'를 만드는 것에 대한 매우 인기 있는 글이 올라와 있었고, 나는 이 문제가 베트남 팀에게도 매우 현실적이라고 느꼈다. 요즘 많은 사람들이 Claude Code, Cursor, Aider 또는 Codex CLI 같은 도구를 자동 모드로 사용하고 있기 때문이다. 이 글에서는 내가 에이전트의 보고서를 레포지토리의 실제 상태와 대조하여, 내가 눈으로 검토하기 전에 **클레임 체커(claim checker)**를 작게 (~100줄 Python) 구축한 방법을 공유하려 한다.

왜 에이전트는 '잘못된 보고'를 하는가?

간단히 말해 세 가지 흔한 이유가 있다:

1. 컨텍스트의 중간 손실: 세션이 길어지면서 컨텍스트가 압축되고, 에이전트는 테스트를 실행했다고 기억하지만 실제로는 코드를 수정하기 전의 실행이었다.
2. 도구 호출 실패의 은폐: 파일 편집 명령이 오류를 반환했지만(예: 문자열 불일치), 에이전트가 출력물을 주의 깊게 읽지 않고 계속 진행했다.
3. 계획에 따른 요약: 마지막 요약 부분은 초기 계획을 기반으로 작성된 것이지, 실제 실행 결과를 바탕으로 된 것이 아니다.

위 세 가지 이유 모두 하나의 원칙으로 이어진다: 요약 보고를 믿지 말고, git과 종료 코드(exit code)를 믿어라. 에이전트의 요약은 단지 _클레임_일 뿐이며, 클레임은 검증되어야 한다.

flowchart LR
    A[Agent 완료 작업] --> B[요약 보고]
    B --> C[Claim Extractor]
...

에이전트가 시스템 프롬프트나 AGENTS.md 파일을 통해 각 작업(task)이 끝날 때마다 요약(summary)을 .agent/report.md에 기록하도록 요청한다. 그리고 이 스크립트는 그 파일을 읽는다:

# claim_checker.py - Python 3.11+
import re
import subprocess
...

핵심은 검증 가능한 주장만 포착하는 것이다. "코드가 더 깨끗해졌다" 또는 "모든 엣지 케이스를 처리한다"와 같은 문구는 건너뛰고, 이것들은 사람이 검토하도록 한다.

2단계: 실제 환경과 대조(Verification)

검증 부분에서는 사용 가능한 도구들만 정확히 사용해야 한다: 어떤 파일이 기본 브랜치(base branch)와 실제로 변경되었는지 확인하기 위한 git diff, 그리고 처음부터 테스트를 다시 실행하는 pytest (캐시를 사용하지 않고, 이전 출력을 신뢰하지 않음).

def sh(cmd: list[str]) -> tuple[int, str]:
    p = subprocess.run(cmd, capture_output=True, text=True)
    return p.returncode, p.stdout + p.stderr
...

작지만 중요한 세부 사항이 있다: -p no:cacheprovider. 캐시를 비활성화하지 않으면 pytest --lf와 같은 일부 플러그인은 이전에 실패한 테스트만 다시 실행하게 만들 수 있으며, 이때의 "pass" 결과는 아무 의미가 없다.

또한 역방향 확인도 한다: diff에는 있지만 에이전트가 언급하지 않은 파일. 이것은 오류로 간주되지는 않지만, 에이전트가 알리지 않고 pyproject.toml이나 락 파일을 "편의상" 수정하는 경우가 많기 때문에 경고(warning)를 출력한다.

3단계: 워크플로우에 통합(Integration)

스크립트는 자동으로 실행될 때만 유용하다. 나는 이를 두 곳에 연결한다: 에이전트가 작업을 완료한 직후 로컬에서 실행하는 경우, 그리고 PR에 agent-generated 레이블이 있는 CI 환경에서 실행하는 경우.

#!/usr/bin/env bash
# scripts/agent-done.sh - 에이전트 작업 후 실행
set -euo pipefail
...

Claude Code의 경우, 이 스크립트를 .claude/settings.json의 Stop 훅에 연결할 수 있다. 0이 아닌 종료 코드(Exit code)는 에이전트가 완료되는 것을 막고 로그를 다시 전송한다. Aider나 다른 도구의 경우, 에이전트를 실행하는 명령을 셸 스크립트로 감싼 다음 마지막에 agent-done.sh를 호출하기만 하면 된다.

sequenceDiagram
    participant Dev
    participant Agent
...

루프 제한 주의사항: 재시도 횟수(저는 2로 설정했습니다)를 반드시 제한해야 합니다. 그렇지 않으면 에이전트가 계속 헤매게 되거나, 더 나쁜 경우 실제 코드를 수정하는 대신 체커에 맞춰 보고서를 작성하는 방법을 "학습"하게 됩니다. 예를 들어, 에이전트는 보고서에서 아예 "tests pass" 문구를 삭제할 수 있습니다. 따라서 코드 수정 작업에는 반드시 테스트 부분이 포함된 보고서가 필수이며, 이것이 누락되면 무조건 반려됩니다.

이 체커가 할 수 없는 것들

명확히 해야 할 것은, 이 체커는 **말과 행동의 불일치(discrepancy between words and actions)**만 잡아낼 뿐, **논리적으로 잘못된 코드(code sai logic)**를 잡아내지는 못한다는 것입니다. 테스트가 통과하더라도 의미 없는 테스트(assert True 같은)일 수 있고, 올바른 파일을 다루는 diff라 할지라도 수정이 잘못된 부분일 수 있습니다. 이것은 빠르고 저렴한 첫 번째 필터 역할을 하며, 애초에 실행조차 되지 않는 PR을 위해 15분을 리뷰하는 것을 막아줍니다.

팀에서 2개월 동안 운영하면서, 에이전트가 수행한 작업 중 약 8분의 1이 체커에 의해 걸렸습니다. 주로 사소하게 실패한 도구 편집(tool edit fail)이나 테스트 파일의 잘못된 위치 지정 오류였습니다. 덕분에 제가 직접 터미널을 열어 하나하나 확인할 필요가 없어졌습니다.

결론

• 에이전트의 요약은 사실(fact)이 아니라 주장(claim)으로 간주해야 합니다. 검증 가능한 모든 주장(수정된 파일, 테스트 통과, lint 클린 상태 등)은 자동적으로 검증되어야 합니다.
• LLM을 사용하지 말고, 기존 도구를 사용하여 검증하세요: git diff --name-only, pytest의 exit code, ruff check. 이는 결정론적(Deterministic)이며 거의 비용이 들지 않습니다.
• 에이전트가 보고서를 고정된 파일(.agent/report.md)에 작성하도록 하세요 (AGENTS.md 또는 system prompt를 통해), 그래야 파싱 작업이 안정적입니다.
• Stop hook이나 CI에 연결하고, 에러 로그를 다시 에이전트에게 전달하되, 재시도 횟수를 제한해야 합니다.
• 테스트를 다시 실행할 때는 항상 캐시를 비활성화하세요 (-p no:cacheprovider) 그리고 전체 스위트(suite)에서 실행해야 합니다.
• 체커가 코드 리뷰 자체를 대체할 수는 없습니다. 단지 당신이 검토하는 것이 실제로 존재하는 것임을 보장해 줄 뿐입니다.

가장 작은 것부터 시작하세요. 오늘 에이전트의 워크플로우 끝에 git diff --name-only 한 줄을 추가하고, 그것과 에이전트가 보고한 내용을 비교해보세요. 놀라게 될 겁니다.