우리는 파일 기반 에이전트 워크플로우 (file-based agent workflows)에서 동일한 실패 패턴에 계속 부딪혔습니다. 업데이트는 "완료(done)"라고 말하지만, 그 뒤에는 아무것도 없는 경우입니다. 즉, 아티팩트 (artifact)도 없고, 실행된 체크 (check)도 없으며, 나중에 지목할 수 있는 근거가 전혀 없는 상태를 말합니다. 악의적인 의도가 있는 것이 아니라, 단순히 "요청을 인지함 (acknowledged the request)"과 "작업을 증명함 (proved the work)" 사이의 간극이 발생하는 것입니다.

그래서 우리는 내부 도구 중 가장 작은 조각을 추출하여 공개했습니다: ack-is-not-done-guard는 Claude Code의 파일 기반 워크플로우를 위한 의존성 없는 (dependency-free) 검증기입니다.

이 도구는 acknowledged, working, artifact_delivered, proven_done의 네 가지 상태를 정의합니다. 오직 마지막 상태만이 completion_claim: true를 설정할 수 있으며, 이는 최소 하나 이상의 아티팩트가 존재하고, 비어 있지 않은 증거와 함께 통과된 것으로 기록된 최소 하나 이상의 비어 있지 않은 체크가 있을 때만 가능합니다. 검증은 페일 클로즈 (fail-closed) 방식으로 작동합니다. 즉, 기록에 아티팩트가 나열되어 있다면 해당 경로가 실제 파일로 해결되어야 하며, 그렇지 않으면 실패 처리됩니다.

이것은 프레임워크가 아니며, 여러분을 대신해 무언가를 감시하지도 않습니다. 이미 더 큰 에이전트 운영 (agent-ops) 시스템을 실행 중이라면, 그 아래에서 완료 확인 레이어 (completion-checking layer)로 끼워 넣도록 설계되었습니다. 만약 그렇지 않다면, 템플릿, 응답 규약 (response contract), 예시 및 테스트가 전체 인터페이스가 됩니다. 여러분의 기존 프로세스는 여전히 기록을 생성하고 업데이트하지만, 이 도구는 선언된 스키마 (schema) 및 파일 존재 확인을 충족하지 않는 완료 기록을 거부합니다.

솔직한 한계점: 이 도구는 Claude Code의 파일 기반 워크플로우에만 국한됩니다. Codex나 Cursor는 지원되거나 검증되지 않았습니다. 또한 아티팩트가 올바른지 또는 실행된 체크가 적절한 체크였는지를 확인하는 것이 아니라, 내부적 일관성(경로 존재 여부, 검증 항목이 비어 있지 않은 증거와 함께 통과로 기록되었는지 여부, 스키마 준수 여부)을 확인합니다. MIT 라이선스로 제공되며, 셀프 서비스 방식이며, 별도의 설정 지원은 제공하지 않습니다.

여러분의 에이전트 워크플로우에서도 동일한 "인지됨 vs 실제로 완료됨" 사이의 간극을 겪고 있다면, 이를 포착하기 위해 무엇을 사용하고 계신지 궁금합니다.