AI 완료 보고의 artifact digest가 실제 산출물과 다른지 확인하기

그림. 완료 보고의 digest는 목표 파일의 현재 바이트와 다시 대조해야 합니다.

reader_decision: 완료 보고에 붙은 digest를 그대로 믿지 않고, 목표 파일의 현재 바이트를 독립적으로 다시 해시하고 검증 시점·commit 또는 버전을 함께 확인합니다.

완료의 단위는 말이 아니라 대상 파일입니다
“수정했고 테스트가 통과했다”는 보고가 있어도 목표 파일이 바뀌었는지, 그 테스트가 실제 목표를 겨냥했는지, 검증 뒤 파일이 다시 바뀌지 않았는지를 따로 확인합니다. 상태 개수만 세는 checksum과 파일 내용 digest도 같은 것으로 취급하지 않습니다.

테스트가 통과했는데 화면은 그대로였습니다

이전에 쓴 완료 증거 글에서 가장 먼저 확인한 것은 diff였습니다. AI는 화면 버그를 고쳤다고 했지만 목표 화면 파일은 그대로였고, 엉뚱한 코드를 수정했습니다. 다른 사례에서는 테스트 스위트가 초록색이었지만 실제 성능 목표를 재지 않았고, 외부 DB가 막힌 테스트가 통과한 것처럼 보고에 섞였습니다. “통과한 테스트 수”만으로는 대상 파일과 목표를 증명할 수 없다는 뜻입니다.

완료 계약을 네 줄로 씁니다

계약 항목	기록할 내용	예시 질문
pre-state	작업 전 대상 파일의 hash·크기·버전	수정 전 파일은 무엇이었나?
completion condition	정확히 어떤 파일과 동작이 바뀌어야 하나	목표 화면의 버튼이 실제로 바뀌었나?
verification	한 번의 독립 검증 명령과 그 결과	현재 대상 파일 hash가 기대값과 같은가?
freshness	검증 시점·commit SHA·artifact version	검증 뒤 파일이 바뀌지 않았나?

이 계약은 모든 작업을 암호학적으로 증명한다는 뜻이 아닙니다. 다만 완료 보고가 가리키는 대상을 고정합니다. verifier의 결과는 PASS, FAIL, STALE 중 하나처럼 단순하게 두고, 검증하지 못한 항목은 성공으로 합치지 않습니다.

SHA-256은 작은 단위의 독립 증거입니다

다음은 파일 내용이 한 줄만 달라져도 digest가 바뀌는 설명용 fixture입니다. 두 문자열은 마지막 숫자만 다르고 끝에 newline을 포함합니다.

printf 'artifact-content-v1\n' | shasum -a 256
printf 'artifact-content-v2\n' | shasum -a 256

내용	SHA-256	판정
artifact-content-v1 + newline	baefe6cf16be18594e90cd9f75b57559903aeb2bdce67c9db4c3e1c4c3929b94	기대 digest
artifact-content-v2 + newline	f3316f56b5986375cbf83af9db92b07c03cd71080fb89831f05b0e48382d038b	변경 후 digest

실제 운영에서는 검증할 단일 파일 또는 artifact를 명시하고, 기대 digest와 현재 digest를 비교합니다. 파일 여러 개의 개수나 “22개 생성, 11개 예약 확인” 같은 상태 요약은 진행률에는 유용하지만 content digest를 대신하지 않습니다.

거짓 성공을 네 가지로 나눕니다

상태	보고	독립 확인	결과
목표 파일이 바뀌고 digest 일치	완료	대상·hash·목표 테스트 모두 일치	PASS
목표 파일이 그대로	완료	pre-state와 현재 hash 동일	FAIL
엉뚱한 파일이 바뀜	완료	목표 파일 hash 불변	FAIL
검증 뒤 파일 변경	완료	commit/version이 달라짐	STALE

테스트 결과를 읽는 세 질문

• 이 테스트는 방금 고친 동작을 되돌리면 실패하는가?
• 실제로 목표 파일·화면·성능 경로를 실행했는가?
• 막힌 외부 의존성이나 생략한 경로가 통과 개수에 포함돼 있지 않은가?

질문 하나에라도 답하지 못하면 테스트 통과를 전체 완료로 승격하지 않습니다. 특히 목표가 성능이면 성능을 측정해야 하고, 화면이면 사용자가 밟는 경로를 직접 확인해야 합니다. hash는 “무엇이 바뀌었나”를 붙잡고, 목표 테스트는 “바뀐 것이 요구사항을 만족하나”를 붙잡습니다. 둘은 함께 있어야 합니다.

결론

완료 보고를 신뢰하는 가장 빠른 방법은 보고서의 문장을 더 오래 읽는 것이 아니라 대상 파일을 다시 해시하는 것입니다. pre-state, 정확한 완료 조건, 독립 검증 명령, freshness를 작은 계약으로 남기면 엉뚱한 파일 수정과 stale pass를 초기에 걸러낼 수 있습니다. 완료는 선언이 아니라 현재 artifact와 검증 결과가 연결된 상태입니다.

참고한 자료

• DataCook, AI 에이전트 완료 보고를 확인하는 5가지
• DataCook, done contract와 검증 경계