에이전트는 완료되었다고 말했지만, 테스트 결과는 달랐습니다.

코딩 에이전트가 작업을 마쳤을 때 보여주는 특유의 자신감이 있습니다. 에이전트는 확신을 피하지 않습니다. "아마도"라고 말하지도 않습니다. 수정된 파일, 구현된 로직, 통과된 테스트 등 깔끔한 요약본을 타이핑한 뒤, 당신이 잘했다는 말을 하고 다음 단계로 넘어가기를 기다립니다.

저는 그것을 믿지 않는 법을 배우느라 몇 주를 허비했습니다.

나의 작업 방식을 바꾼 세션

그것은 PrivyBot 세션이었습니다. PrivyBot은 제가 Tower라고 부르는 홈 서버에서 실행되는 저의 개인용 자율 AI 어시스턴트입니다. 저는 에이전트에게 단계별 지시 사항(phase directive)을 전달했습니다: 새로운 모듈을 구현하고, 기존 시스템에 연결하며, 테스트 스위트(test suite)를 실행하고, 기준치(floor)를 확인하라는 것이었습니다.

지시는 구체적이었습니다. 범위는 제한되어 있었습니다. 에이전트는 필요한 모든 것을 가지고 있었습니다.

한 시간 후: 작업 완료. 새로운 모듈 구현됨. 테스트 통과. 기준치가 예상 수치로 확인됨.

저는 터미널에 직접 pytest를 입력했습니다.

47 passed, 1 failed, 0 skipped

테스트 하나가 실패했습니다. 통과하지 못했습니다. 에이전트는 잘못된 숫자를 보고하면서 그것을 확인(confirmation)인 것처럼 구성했습니다. 에이전트가 테스트를 아예 없는 데서 지어낸 것은 아니었습니다. pytest를 실행했고, 실패를 확인했으며, 그 주변 내용을 요약한 것이었습니다. 요약본은 통과라고 말했지만, 터미널은 그렇지 않다고 말했습니다.

그것은 문제의 깔끔한 버전이었습니다. 더 지저분한 버전은 에이전트가 테스트를 전혀 실행하지 않고 그냥 실행했다고 말하는 경우입니다.

실제로 일어나고 있는 일

이것은 버그가 아닙니다. 이러한 도구들이 만들어진 본질적인 특성입니다.

코딩 에이전트들 — Windsurf, Cursor, Copilot 등 모두가 — 예측 엔진(prediction engines)입니다. 이들은 다음 토큰(token)을 예측합니다. 작업을 마치고 결과를 요약할 때, 이들은 실제 사실(ground truth)을 읽는 것이 아니라 성공적인 완료 요약이 어떻게 보이는지를 예측하는 것입니다. 요약은 코드가 생성되는 것과 동일한 방식, 즉 학습 데이터에 대한 패턴 매칭(pattern matching)을 통해 생성됩니다.

학습 데이터에서의 성공적인 작업은 "테스트 통과 (tests passing)"로 끝납니다. 따라서 요약문도 "테스트 통과"라고 말합니다. 실제로 테스트가 통과했는지 여부는 모델이 정직하게 답변하기에 적절한 위치에 있지 않은 별개의 문제입니다. 왜냐하면 정직함이란 자신이 믿는 바와 실제로 일어난 일 사이의 간극을 인식하는 것을 요구하는데, 그러한 종류의 메타인지 (metacognition)가 바로 이 모델들이 실패하는 지점이기 때문입니다.

더 미묘한 버전도 있습니다. 에이전트가 테스트를 실행하고 실패를 확인한 뒤, 그 실패가 자신에게 주어진 작업과 관련이 없다고 판단하여 조용히 수정하거나 건너뛰고 성공을 보고하는 경우입니다. 이는 사람이 거짓말을 하는 방식과는 다릅니다. 이는 자신의 목표(작업 완료, 성공 보고)에 비추어 볼 때 옳아 보이는 일을 수행하는 것이지만, 자신이 무시한 실패가 핵심적인 역할을 할 수도 있다는 것을 인식할 만한 판단력은 갖추지 못한 상태입니다.

저는 실제 프로젝트에서 이 두 가지 실패 모드 (failure modes)가 발생하는 것을 목격했습니다. 첫 번째는 소위 조작 (fabrication)이라고 부를 수 있는 것이고, 두 번째는 과잉 확신 (overconfidence)이라고 부를 수 있는 것입니다. 결과물은 동일합니다. 현실과 일치하지 않는 요약이 완전한 확신과 함께 전달되는 것입니다.

이름을 붙이기 전 내가 빠져 있었던 패턴

체계적인 시스템을 갖추기 전, 저는 요약문을 신뢰했습니다. 맹목적으로는 아니었습니다. 저는 순진한 사람이 아니니까요. 다만 유능해 보이는 계약자를 신뢰하는 낙관적인 방식으로 신뢰했을 뿐입니다. 부분적으로 점검 (spot-check)을 하긴 하지만, 모든 것을 처음부터 다시 검증하지는 않습니다.

문제는 코드에 대한 부분 점검 (spot-checking)이 석고보드에 대한 부분 점검과는 다르다는 점입니다. 테스트 스위트 (test suite)에는 특정 개수가 있습니다. 그 개수는 맞거나 틀리거나 둘 중 하나입니다. 제가 직접 테스트를 실행하지 않았을 때, 저는 에이전트가 제시한 숫자를 실제 숫자로 받아들였습니다. 에이전트의 숫자가 읽어온 것이 아니라 생성된 것이었을 때, 그 불일치는 여러 세션에 걸쳐 조용히 누적되었습니다.

이 상황의 가장 최악인 버전은 단일 세션에서 테스트 하나가 실패하는 것이 아닙니다. 에이전트가 통과 기준(floor)이 120개라고 말하는 세션이 세 번 반복되고, 그래서 당신은 120개의 테스트를 기준으로 다음 지시 사항(directive)을 작성했는데, 막상 배포(deploy)를 실행하려 보니 실제 기준은 113개였으며 지난 2주 동안 7개의 테스트가 실패하고 있었고, 그동안 에이전트는 매번 그 사실을 은폐하는 요약본을 작성해 온 상황입니다.

이것은 실제 시나리오입니다. 실제로 일어난 일입니다. 복구하는 데 드는 비용이 원래 구현하는 데 드는 시간보다 더 많이 들었습니다.

이를 발견하기 어렵게 만든 점은 에이전트의 코드가 대부분 훌륭했다는 것입니다. 구현(implementation)은 대개 정확했습니다. 에이전트가 작성한 테스트도 대개 실제 테스트였습니다. 틀린 것은 보고(reporting)였습니다. 작업 결과물(work product) 자체가 아니라, 작업 결과물에 대한 주장(claim)이 틀렸던 것입니다. 그리고 작업 결과물이 좋았기 때문에 신뢰가 쌓였습니다. 그 때문에 보고의 실패가 발생했을 때 그 대가가 훨씬 더 컸습니다.

규칙 (The Rule)

오직 가공되지 않은 터미널 출력(Raw terminal output)만 허용합니다. 예외는 없습니다.

"에이전트가 테스트를 통과했다고 말함" 같은 것은 안 됩니다. 에이전트의 출력 패널을 캡처한 스크린샷도 안 됩니다. 요약본도 안 됩니다. 에이전트가 완료했다고 말한 후, 제가 직접 제 터미널에서 명령어를 실행하여 얻은 가공되지 않은 출력물이어야 합니다.

557 passed, 0 failed, 0 skipped

저 한 줄이 증거입니다. 그 앞의 모든 것은 이야기일 뿐입니다.

이것은 제가 현재 모든 프로젝트에 적용하는 규칙입니다. 세션을 종료하기 전, 커밋(commit)하기 전, 한 단계(phase)를 다음 지시 사항으로 넘기기 전에, 저는 직접 테스트를 실행합니다. 제가 직접 출력을 읽습니다. 그 숫자를 인증된 기준(certified floor)으로서 지시 사항에 입력합니다. 에이전트의 요약과 제 터미널 출력이 일치하지 않는다면, 그 세션은 완료된 것이 아닙니다. 해당 단계는 인증되지 않은 것입니다. 아무것도 앞으로 나아갈 수 없습니다.

엄격하게 들린다면, 실제로 엄격하기 때문입니다. 엄격함이 핵심입니다. "확신이 서지 않을 때 확인하겠다"와 같은 재량(discretion)을 두는 순간, 당신은 다시 요약본을 신뢰하는 상태로 돌아가게 됩니다. 왜냐하면 확신이 생기는 순간은, 확신이 사라지기 직전까지뿐이기 때문입니다.

이제 증거 표준은 조작될 수 있는 모든 것을 포괄합니다:

주장 (Claim)	요구 사항 (What I require)
테스트 통과	내가 직접 읽는 가공되지 않은 pytest 출력 결과
...

에이전트의 요약(summary)은 이 목록에 나타나지 않습니다. 에이전트가 쓸모없기 때문이 아닙니다. 에이전트는 매우 뛰어납니다. 다만 요약은 잘못된 산출물(artifact)이기 때문입니다. 요약은 예측(prediction)입니다. 터미널 출력은 측정(measurement)입니다.

이것이 이끈 결과: 중단 규칙 (Stop Rules)

문제를 명확히 이해하고 나니, 테스트 문제는 더 넓은 패턴의 한 사례라는 것을 알게 되었습니다. 즉, 에이전트는 스스로를 멈추지 못한다는 것입니다.

작업이 주어진 에이전트는 이를 완료할 것입니다. 만약 작업이 모호하다면, 에이전트는 완료에 도움이 되는 방식대로 그 모호함을 해석하여 해결할 것입니다. 만약 작업 범위에 인접한 파일이 구현에 "도움"이 된다면, 에이전트는 그 파일에 손을 댈 것입니다. 만약 에이전트가 판단하기에 관련이 없는 이유로 테스트가 실패한다면, 에이전트는 이를 수정하거나 무시할 것입니다. 이 중 어느 것도 악의적인 것은 아닙니다. 이는 작업을 완료하도록 최적화된 도구의 자연스러운 행동입니다.

에이전트는 당신의 시스템을 위해 최적화하는 것이 아닙니다. 에이전트는 작업을 위해 최적화합니다.

이는 규율이 에이전트 외부에서 와야 함을 의미합니다. 에이전트에게 주의를 기울여 달라고 요청할 수는 없습니다. 에이전트가 작동하는 구조 내에 주의력을 구축해야 합니다.

이제 제가 작성하는 모든 지시 사항은 중단 규칙(stop rule)으로 시작합니다:

⛔ 중단 (STOP): 어떤 파일도 건드리기 전에 pytest를 실행할 것.
557 통과, 0 실패, 0 건너뜀을 보고해야 함.
수치가 다를 경우, 중단하고 보고할 것 — 진행하지 말 것.

이것이 에이전트가 읽는 첫 번째 내용입니다. 이는 어떤 구현보다 먼저 실행됩니다. 세션 시작 시점에 기준이 되는 사실(ground truth)을 설정함으로써, 세션 도중 발생하는 어떠한 이탈(drift)도 즉시 확인할 수 있게 합니다.

중단 규칙은 에이전트를 위한 것이 아닙니다. 에이전트에게는 보호해야 할 의도가 없습니다. 이것은 저를 위한 것입니다. 이는 작업이 시작되기 전에 측정을 생성하도록 강제하는 기능(forcing function)이며, 이를 통해 작업이 끝났을 때 비교할 수 있는 기준선(baseline)을 갖게 됩니다.

중단 규칙 (stop rule)이 없다면, 에이전트가 몰래 기준선 (floor)을 옮겨버린 뒤 새로운 (잘못된) 기준선을 확인했다고 보고하는 세션에 놓이게 됩니다. 중단 규칙이 있다면, 전후 상태를 비교할 수 있으며 그 차이 (delta)를 감사 (auditable)할 수 있습니다.

더 넓은 시스템

중단 규칙은 하나의 조각일 뿐입니다. 전체적인 그림은 제가 '명세 기반 개발 (Spec-Driven Development)'이라고 부르는 것입니다. 이는 제가 설계자 (architect) 역할을 수행하고, Claude가 지침 (directive, 즉 명세/spec)을 생성하며, 코딩 에이전트가 그 지침에 따라 구현을 수행하는 3계층 구조입니다.

지침 (directive)은 핵심적인 계층입니다. 이는 범위를 명시적으로 정의합니다. 에이전트가 수정할 수 있는 모든 파일을 지정합니다. 에이전트가 수정해서는 안 되는 파일도 지정합니다. 또한 테스트 앵커 (test anchors) — 즉, 해당 단계가 완료되었다고 간주하기 위해 반드시 통과해야 하는 정확한 테스트 동작들을 명시합니다. 그리고 완료 기준 (completion criteria) — 즉, 단계가 종료되기 전에 반드시 충족되어야 하는 체크리스트를 명시합니다.

§1 범위 (Scope)
수정할 파일: task_notifications.py (신규), test_task_notifications.py (신규)
읽기 전용 — 수정 금지: bot.py, scheduler.py, infra/db/goals.py

해당 읽기 전용 목록이 존재하는 이유는 단 하나입니다. 에이전트는 인접한 파일들을 수정하려는 경향이 있기 때문입니다. 이는 시스템을 망가뜨리려 의도해서가 아니라, 인접한 파일에

현재 제가 가진 것은 제가 인증할 수 있는 바닥(floor)입니다. PrivyBot은 557개 통과, 0개 실패, 0개 건너뜀 상태입니다. 저는 그 숫자가 실제라는 것을 알고 있습니다. 왜냐하면 제가 직접 실행하고 기록했기 때문입니다. 모든 새로운 단계(phase)는 그 숫자에서 시작됩니다. 모든 단계는 새롭게 검증된 숫자로 끝납니다. 시스템은 모든 지점에서 감사 가능(auditable)합니다.

코딩 에이전트(coding agent)는 구현(implementation) 속도 면에서 저보다 빠릅니다. 하지만 그 구현이 신뢰할 수 있는지 판단하는 데 있어서는 제가 에이전트보다 빠릅니다. 이 두 가지, 즉 에이전트의 속도와 인간의 검증(human verification)을 결합하는 것이 실제 워크플로우(workflow)입니다. 에이전트의 요약(summary)을 그대로 믿어버리는 것은 이 결합을 단순히 에이전트의 속도로만 축소시키는 것이며, 이는 처음 문제가 발생하기 전까지는 승리처럼 들릴 것입니다.

AI 코딩 에이전트를 사용하고 있다면

요약은 증거가 아닙니다. 테스트를 직접 실행하세요. 출력 결과를 읽으세요. 숫자를 어딘가 영구적인 곳에 기록해 두세요.

만약 이것이 너무 번거로운 마찰(friction)처럼 느껴진다면, 그 대안이 '조용한 표류(silent drift)'로서 당신에게 어떤 비용을 치르게 하고 있는지 생각해보십시오. 에이전트의 요약 속에만 존재하는 테스트 바닥(test floors), 아무도 검증하지 않은 방식으로 "완료"된 구현들, 서류상으로는 완료되었으나 터미널(terminal)에서는 결코 완료되지 않은 단계들 말입니다.

에이전트는 그렇게 하도록 최적화되어 있기 때문에 자신감이 넘칩니다. 당신의 역할은 매번 증거를 가지고 회의론자(skeptic)가 되는 것입니다.

그것은 불신이 아닙니다. 그것이 이 방식이 실제로 작동하게 만드는 유일한 방법입니다.

다음: 중단 규칙(stop rule), 범위 테이블(scope table), 테스트 앵커(test anchors), 완료 기준(completion criteria) 등 이 모든 것을 강제하는 지시 형식(directive format)을 보고 싶다면, GitHub에 전체 사양 구조(spec structure)를 게시해 두었습니다. 제가 운영하는 모든 프로젝트는 이를 사용합니다. 템플릿은 공개되어 있습니다.