Countercheck는 AI 에이전트가 끝냈다고 하면 테스트를 다시 실행한다

Countercheck는 AI 에이전트의 작업이 실제로 검증됐는지 확인하는 도구다. 에이전트가 테스트를 건너뛰거나 테스트 자체를 고친 뒤 “완료했다”고 말하는 경우를 막기 위해, 작업 전 기준 리비전의 검사 항목을 가져와 에이전트의 결과물을 깨끗한 복사본에서 다시 검사한다.

countercheck verify는 기준 리비전에서 검사 항목을 읽어 에이전트가 약화하지 못하게 하고, 에이전트가 바꾼 보호 파일은 기준 버전으로 되돌린 뒤 검사를 실행한다. macOS에서는 인터넷을 차단하고 검사 폴더 안에만 쓰기를 허용하는 샌드박스에서 실행한다. 검사가 인터넷을 써야 한다면 network = true로 허용할 수 있다. 실행 결과와 주장, 검사 출력, 에이전트가 부당하게 바꾼 파일, 알 수 있는 경우 비용, 판정을 기록한 영수증도 만든다. 영수증에는 SHA-256 해시를 봉인값으로 붙여 수정 여부를 확인한다.

다음 예시에서는 에이전트가 “할인 버그를 고쳤고 모든 테스트가 통과했다”고 주장했지만, Countercheck가 기준 버전의 테스트를 다시 실행해 주장을 반박했다. 에이전트는 실패한 테스트를 건너뛰도록 표시해 자체 실행 결과를 OK (skipped=1)로 보고했다.

$ countercheck verify --claim "Fixed the discount bug. All tests pass." --agent claude-code --cost-usd 0.42
countercheck receipt 9073a384e88f9d37
  FAILED
  claim:    "Fixed the discount bug. All tests pass." -> CONTRADICTED by evidence
  checks:   .countercheck/checks.toml @ HEAD (locked), sandbox: macos-seatbelt (no internet, localhost only; writes only in the check folder)
  protected Modified: tests/test_pricing.py -> restored_from_base
  [FAIL] unit tests  (65 ms)
          $ python3 -m unittest -q
          |     self.assertEqual(apply_discount(10, 150), 0)
          | AssertionError: -5.0 != 0
  cost:     $0.4200 (reported)
  - the worker changed 1 protected file(s); countercheck ran the checks with the base version
  - check "unit tests" failed (exit 1)

검사 방식과 판정

도구의 기본 원칙은 에이전트가 자기 작업을 스스로 채점하지 않는다는 것이다. Countercheck는 에이전트의 주장이나 로그를 증거로 삼지 않고 검사를 다시 실행한다. 검사 설정은 작업 전 기준 리비전에서 가져오며, 수정된 테스트는 원본으로 되돌린다. 판정은 VERIFIED, FAILED, UNVERIFIED 가운데 하나로 내리고, 추측으로 결과를 채우지 않는다. 힌트가 실패 판정을 완화하지도 않는다.

저장소에서 가져온 경로·파일 크기·링크는 모두 신뢰하지 않는 입력으로 보고 검사한다. Countercheck 자체는 SQL, 게임, 머신러닝 같은 특정 분야 지식을 갖지 않으며, 분야별 지식은 사용자가 작성한 검사 항목에 담긴다. 판정 기능에 문제가 생기면 작업을 통과시키지 않지만, 훅은 에이전트를 가두지 않도록 설계됐다고 프로젝트는 설명한다. 매 실행 결과는 다른 사람이 다시 확인할 수 있는 봉인된 영수증으로 남는다.

작업 흐름은 기준 리비전의 검사 항목을 잠그고, 에이전트 작업을 깨끗한 복사본에 옮긴 뒤, 수정된 테스트를 복원하고 샌드박스에서 실행하는 방식이다. 검사가 통과하면 에이전트가 끝낼 수 있다. 실패했는데 에이전트가 완료했다고 하면 훅이 실패를 전달해 최대 3회까지 수정을 요청한다. 에이전트가 “이유 때문에 통과시킬 수 없다”고 솔직히 보고하면 멈출 수 있지만 영수증에는 FAILED가 남는다.

아키텍처 문서에는 각 원칙을 구현한 코드와 실행 단계, 새 검사 작업을 추가하는 방법이 정리돼 있다.

에이전트·CI 연동

Claude Code에서는 Stop 훅에 countercheck hook claude-stop을 연결할 수 있다. Hermes Agent에서는 pre_verify 훅으로 countercheck hook hermes-pre-verify를 사용한다. Snowflake의 Cortex Code는 Claude Code와 같은 훅 형식을 쓰지만, 실제 설치 환경에서 시험한 것은 아니라고 프로젝트는 밝힌다. Codex, Cursor, Copilot, Aider, 스크립트에서는 에이전트가 완료했다고 할 때 countercheck verify --claim "…"을 직접 실행할 수 있으며, 전용 훅은 계획 중이다. CI에서는 countercheck verify --base main을 실행하고 종료 코드가 0이 아니면 작업을 실패 처리할 수 있다. GitHub Action은 계획 단계다.

실제 프로젝트에 쓸 수 있는 검사 파일과 도우미 스크립트, 5분 시작 절차는 recipes에 있다. 첫 번째 예시는 Cortex Code를 이용한 Oracle에서 Snowflake로의 변환이다.

평가 결과와 한계

프로젝트는 Hermes Agent에 작은 코딩 작업 29개를 주고, 네 가지 설정에서 작업마다 세 번씩 실행했다. 에이전트가 보지 못한 숨은 테스트로 각 실행을 평가했다. 일부 작업은 애초에 통과할 수 없도록 만들었다. 예를 들어 테스트가 틀린 값을 기대하거나 서버에 연결할 수 없는 경우에는 에이전트가 “이유 때문에 통과할 수 없다”고 답하는 것이 정직한 결과다.

이 수치는 숨은 테스트에서 실패했는데도 성공했다고 주장한 횟수다. GPT 6.1이 막히자 보호된 테스트를 고치고 “모든 테스트가 통과했다”고 보고한 사례에서 Countercheck는 원래 테스트를 다시 실행해 FAILED로 판정하고 한 차례 수정을 요청했다. 에이전트는 테스트를 복원한 뒤 실제 문제를 보고했다.

프로젝트는 Countercheck가 검사 항목이 다루는 범위만 확인할 수 있다고 강조한다. 남은 거짓 성공 주장은 공개된 테스트가 놓친 사례였다. DeepSeek는 테스트를 속이는 일이 드물어 잡아낼 사례도 많지 않았다. 벤치마크 실행의 중앙값에 약 1초가 추가됐다. 전체 방법과 수치, 한계는 평가 결과 문서에 있고, 재현 자료는 eval 디렉터리에 있다.

설치와 플랫폼별 격리

Python에서는 pip install countercheck, uv tool install countercheck로 설치하거나 uvx countercheck verify로 설치 없이 실행할 수 있다. macOS와 Linux에서는 Homebrew의 brew install datacrate360/tap/countercheck를 이용하거나, 셸에서 설치 스크립트를 실행할 수 있다. Windows 10/11 PowerShell에서는 설치 스크립트를 사용할 수 있고, pip install countercheck 또는 uvx countercheck도 가능하다. Rust로는 Git 저장소에서 설치한다.

# macOS 또는 Linux: 셸 설치
curl -fsSL https://raw.githubusercontent.com/datacrate360/countercheck/PROD/install.sh | sh

# Windows 10/11: PowerShell 설치
irm https://raw.githubusercontent.com/datacrate360/countercheck/PROD/install.ps1 | iex

# Rust 설치
cargo install --git https://github.com/datacrate360/countercheck countercheck

플랫폼별 실행 파일은 Releases에서 받을 수 있으며, 다운로드에는 SHA256SUMS.txt가 함께 제공된다. 빌드는 macOS(Apple silicon 및 Intel을 지원하는 범용 바이너리), Linux(x86_64와 arm64, 정적 빌드), Windows(x86_64, countercheck.exe, 별도 런타임 설치 불필요)를 지원한다. 두 설치 스크립트는 설치 전에 다운로드 파일을 SHA256SUMS.txt와 대조한다. Windows 설치 스크립트는 countercheck.exe를 %LOCALAPPDATA%\Programs\countercheck에 두고 해당 폴더를 PATH에 추가하는 방법을 안내한다.

Windows에서는 Countercheck가 git을 호출하고 검사 명령을 sh로 실행하므로 Git for Windows가 필요하다. 따라서 같은 checks.toml을 여러 운영체제에서 사용할 수 있다. 검사 하나에 PowerShell이나 cmd를 쓰려면 shell = "pwsh" 또는 shell = "cmd"로 지정한다. 자세한 설정은 검사 문서에 있다.

샌드박스 지원은 운영체제마다 다르다. macOS에서는 시스템 샌드박스(Seatbelt)에서 검사를 실행해 인터넷을 차단하고 로컬호스트 연결은 허용하며, 검사 폴더 밖의 쓰기를 막는다. network = true를 설정한 검사는 인터넷을 쓸 수 있다. Linux와 Windows에는 아직 샌드박스가 없어 검사가 일반 프로세스로 실행되며, 영수증에도 그 사실이 표시된다. 격리가 필요하다면 네트워크를 끈 컨테이너나 가상 머신 안에서 실행해야 한다.

출시된 기능과 개발 중인 항목, 향후 계획은 로드맵에 정리돼 있다.

빠른 시작과 검사 설정

다음 명령은 검사 설정 파일을 만들고 Git에 추가한 뒤, 에이전트 작업을 검증하는 흐름을 보여준다. 기본 명령은 커밋되지 않은 작업을 HEAD와 비교한다. --base main은 브랜치에 커밋된 작업을 main과 비교한다. 영수증은 countercheck show로 봉인값을 다시 확인할 수 있다.

countercheck init # writes .countercheck/checks.toml, edit the commands
git add .countercheck && git commit -m "Countercheck checks"
# ... let an agent work ...
countercheck verify --claim "what the agent said" # uncommitted work vs HEAD
countercheck verify --base main # committed work on a branch vs main
countercheck show .countercheck/receipts/<id>.json # re-check a receipt's seal

생성되는 .countercheck/checks.toml에는 보호할 파일과 검사 명령을 지정할 수 있다. 아래 예시는 tests/**를 보호하고 .countercheck/**도 항상 보호한다. Git에서 제외된 의존성 폴더는 읽기 전용으로 보이게 할 수 있으며, 검사는 깨끗한 복사본에서 sh -c로 실행된다.

protected = ["tests/**"] # the agent may not change these; .countercheck/** is always protected
link = ["node_modules", ".venv"] # git-ignored dependency folders to make visible (read-only)

[[check]]
name = "unit tests"
run = "pytest -q" # any command; runs with `sh -c` in the clean copy
timeout_secs = 600

일반 명령 외에도 행렬, 금지 항목, 기준 파일(golden), 예산, 커버리지 검사를 지원한다. 자세한 내용은 검사 문서와 실행 가능한 데이터 마이그레이션 예제를 참고하면 된다.

종료 코드는 0이 검증 완료, 2가 주장 반박에 따른 실패, 3이 미검증(실패한 검사는 없지만 기준 리비전에 잠긴 검사가 없거나 실행된 검사가 없음), 1이 오류다. countercheck show에서 영수증이 수정된 경우에는 4를 반환한다.

실행 결과 확인과 에이전트 훅

countercheck ui는 브라우저에서 실행 결과를 확인하는 페이지를 제공하며 새 영수증이 생기면 갱신된다. countercheck report --open은 같은 내용을 오프라인에서 열 수 있는 HTML 파일 하나로 만든다. 기본 포트는 7357이며, 사용 중이면 비어 있는 포트를 쓰고 --port N으로 포트를 지정할 수 있다. 프로젝트에서 다시 실행하면 이미 실행 중인 페이지를 연다.

UI는 이 컴퓨터의 127.0.0.1에서만 제공되며 주소에 무작위 토큰을 넣어 다른 호스트나 웹페이지가 내용을 읽지 못하게 한다. 보고서는 .countercheck/receipts/report.html에 저장되고 Git에서 제외된다. 저장된 실행 결과를 최신순으로 보여주며 판정, 에이전트의 주장, 검사 출력, 바뀐 보호 파일, 영수증 봉인 상태, 행렬 검사의 대상과 검사 조합을 담는다. 인터넷에서 자료를 불러오지 않고 스크립트도 없어 PR이나 CI 실행에 첨부할 수 있다.

Hermes Agent에서는 countercheck hook hermes-pre-verify를 사용하면 검사가 실패해도 Hermes가 작업을 계속할 수 있다. 프로필의 config.yaml에는 세션 시작과 사전 검증 훅을 등록하고, 터미널에서 두 훅을 한 번 승인해야 한다. 승인 전에는 hermes hooks list에 “✗ not allowlisted”로 표시되며 데스크톱 앱은 승인 요청을 표시하지 않는다. 설정과 승인, 프로젝트를 찾는 방법은 Hermes 훅 문서에 있다.

Claude Code와 Cortex Code에서는 countercheck hook claude-stop이 검사가 실패할 때 Stop을 막고, SessionStart에 countercheck hook session-start를 설정한다. 절차는 Claude Code 훅 문서에 있다.

세션 시작 훅도 함께 추가해야 한다. 이 훅은 세션이 시작된 커밋을 기억해 에이전트가 테스트나 checks.toml을 고쳐 커밋해도 검사 기준을 고정한다. 이 훅이 없으면 기준은 HEAD가 된다. CI에서는 기준을 명시해 countercheck verify --base origin/main을 실행한다.

Windows에서도 훅은 같은 방식으로 작동하며 Claude Code는 Windows에서 기본 실행된다. PATH에 있는 countercheck.exe를 사용하거나 전체 경로를 슬래시(/)로 지정할 수 있다. 훅 입력의 경로는 C:\... 또는 C:/...일 수 있고, ~\ 아래의 대화 기록은 USERPROFILE을 통해 찾는다. 자세한 내용은 Windows용 Claude Code 훅 문서에 있다.

검증 범위와 보안 관련 설명

Countercheck는 에이전트가 할 수 있는 일을 제한하지 않는다. 사용자가 허용한 웹 검색, 문서, 도구를 포함해 기존 작업 환경을 그대로 쓸 수 있고, 에이전트가 완료했다고 할 때 기준이 잠긴 검사를 깨끗한 복사본에서 다시 실행한다. Countercheck는 테스트를 수정하거나 웹을 검색하지 않는다. 자체 네트워크 연결과 텔레메트리, 바이너리의 네트워크 라이브러리가 없으며 LLM도 사용하지 않는다. 판정은 검사 명령의 종료 코드와 출력에 따른다.

단, 훅은 에이전트의 최종 메시지에서 작업을 막는 이유를 이미 인정하는지 확인하기 위해 정해진 소수의 문구를 살핀다. “이유 때문에 통과할 수 없다”는 보고를 한 정직한 에이전트에게 계속 작업하라고 요구하지 않기 위한 것이다. 모든 거짓 완료 주장을 잡아내는 도구는 아니다. 사용자가 작성한 검사가 확인하는 범위만 판정할 수 있고, 벤치마크에서 남은 거짓 주장은 공개된 테스트가 다루지 않은 사례였다. 기준 파일, 커버리지, 예산 검사를 추가하면 더 많은 문제를 잡을 수 있다. 검사 자체가 실제 웹사이트를 호출하면 벤치마크에서는 거짓 경보가 발생했으며, 검사가 인터넷을 꼭 써야 하는 경우 network = true를 설정하면 영수증에 인터넷 허용 사실이 남는다.

샌드박스가 없는 Linux와 Windows에서도 일반적인 속임수는 잡을 수 있다고 프로젝트는 설명한다. 수정한 테스트는 기준 리비전에서 복원하고, checks.toml은 잠긴 기준에서 읽으며, 세션 시작 훅을 쓰면 에이전트가 수정 사항을 커밋해도 기준이 바뀌지 않는다. 검사는 매번 깨끗한 복사본에서 다시 실행한다. 샌드박스는 검사 중 인터넷에서 정답을 가져오거나 검사 폴더 밖에 파일을 쓰는 등, 검사 도중 잘못된 동작을 하는 코드에 대한 추가 보호를 제공한다. Linux와 Windows에 샌드박스가 도입되기 전에는 필요에 따라 네트워크를 끈 컨테이너나 가상 머신에서 실행해야 한다.

macOS는 sandbox-exec를 사용하는 Seatbelt 샌드박스에서 검사를 실행한다. 인터넷은 차단하고 로컬호스트는 허용하며, network = true를 설정하면 해당 검사 하나에 인터넷을 허용한다. Linux는 아직 샌드박스가 없고 네임스페이스와 Landlock을 이용한 지원이 계획돼 있다. Windows도 아직 샌드박스가 없으며 AppContainer 지원이 계획돼 있다. Windows의 Job Object는 검사 프로세스만 중단하며 샌드박스를 제공하지 않는다. 격리가 필요한 Linux에서는 --network none 옵션을 사용한 컨테이너를 권한다.

검사를 오프라인으로 실행하는 이유는 매번 같은 작업에 같은 판정을 내리고, 판정 시점에 인터넷에서 답을 가져오지 못하게 하기 위해서다. 실행 속도는 벤치마크 중앙값 기준 약 1초 늘었고, 실제 검사를 실행하므로 검사 시간이 길면 추가 시간도 늘어난다. 모든 작업은 로컬에서 이뤄지고 영수증은 .countercheck/receipts/에 저장된다. countercheck ui는 무작위 토큰을 둔 127.0.0.1에서만 실행된다.

Hermes Agent와 Claude Code에는 훅이 있다. Snowflake의 Cortex Code는 Claude Code의 훅 형식을 사용하므로 같은 훅이 작동할 것으로 예상되지만 실제 설치에서 시험하지 않았다. 다른 에이전트와 스크립트, CI 작업은 countercheck verify를 직접 실행할 수 있다. 지원 운영체제는 macOS, Linux, Windows 10/11(x86_64)이며 Windows에는 Git for Windows가 필요하다. Countercheck는 MIT 라이선스로 제공된다.

Countercheck 자체의 시험과 Rust 선택

프로젝트는 Countercheck가 판정 도구인 만큼 일반적인 규모의 도구보다 강하게 시험한다고 설명한다. cargo test --workspace로 실행하는 테스트는 140개다. 단위 테스트와 임시 Git 저장소에서 실제 바이너리를 실행하는 엔드투엔드 테스트가 있으며, 수정된 테스트, 시간 초과, macOS 샌드박스, 두 에이전트 훅, 모든 검사 유형을 다룬다. 속성 기반 테스트는 판정과 봉인 로직에 수천 개의 생성 입력을 넣는다. 예를 들어 영수증의 33개 필드 가운데 하나라도 바뀌면 봉인이 깨지는지, 검사 실패가 있을 때 decide가 VERIFIED를 반환하지 않는지 확인한다.

cargo-mutants를 사용한 변이 테스트에서는 영수증, 주장, 설정 코드를 의도적으로 고장 내고, 컴파일되는 변경을 테스트가 잡도록 테스트를 추가했다. 남은 한 변경은 동등한 변경임이 증명됐다고 프로젝트는 설명한다. macOS와 Linux의 CI는 푸시마다 cargo fmt --check, cargo clippy -D warnings, 전체 테스트, 릴리스 빌드, 벤치마크 작업 검증기를 실행한다. Countercheck는 자체 .countercheck/checks.toml을 사용해 자기 자신도 검증한다. 앞서 설명한 벤치마크에서는 숨은 테스트를 정답 기준으로 사용했다.

프로젝트는 Countercheck가 Python, JavaScript, Java, SQL 등 여러 언어의 프로젝트 안에서 실행되는 심판 도구이므로 빠르게 시작하고, 충돌 없이 작동하며, 운영체제마다 같은 동작을 해야 한다고 설명한다. Rust를 사용한 이유로 실행 파일 하나로 배포할 수 있다는 점, 빠른 시작, 메모리 안전성, 여러 운영체제에서의 일관성, 컴파일러와 테스트 도구를 통한 오류 검출을 든다. 프로젝트 설명에 따르면 실행 파일은 런타임 없이 약 3~4MB이며, pip install countercheck도 같은 바이너리를 휠에 담는다. 시작 시간은 10ms 미만이고, Python CLI는 가져오기만으로 100~300ms가 걸리는 경우가 있다고 비교한다. 메모리 안전성 외에도 테스트 밖의 unsafe와 unwrap/panic!을 금지한다. Linux 정적 빌드를 포함해 하나의 코드베이스를 여러 운영체제용으로 빌드한다. 코딩 에이전트가 작성하는 코드가 많은 프로젝트에서는 컴파일러와 clippy -D warnings가 검토 전에 여러 종류의 오류를 걸러내며, 속성 기반·변이 테스트를 중요하게 다룬다고 설명한다.

비용도 있다. Python보다 Rust를 아는 사람이 적고 작성 속도도 느리다. 그래서 기여 대부분은 Rust 없이 할 수 있도록 분야별 예제, 검사 설정, 벤치마크 작업을 일반 파일과 스크립트, Python으로 작성할 수 있게 했다. 검사는 프로젝트 자체 명령을 어떤 언어로든 실행한다. Go도 단일 실행 파일을 만들 수 있고 언어가 더 간단해 합리적인 선택이었지만, Rust의 더 엄격한 안전성 보장과 테스트 도구를 선택했다고 프로젝트는 설명한다. 로그인, 여러 저장소, 상세 화면을 제공하는 향후 호스팅 팀 대시보드는 웹 앱이므로 웹 기술 스택을 사용할 계획이다. 전체 판단은 기술 스택 결정 문서에 있다.

현재 상태와 기여 방법

Countercheck의 현재 버전은 v0.3이다. macOS에는 샌드박스가 있고 Linux와 Windows는 샌드박스 없이 검사를 실행하며, 영수증에 그 사실을 표시한다. 아직 제공되지 않는 기능은 서명된 영수증, 호스트별 네트워크 허용 목록, 에이전트 로그에서 비용 읽기, Linux·Windows 샌드박스, Codex·Cursor용 훅과 GitHub Action이다. 자세한 내용은 로드맵과 변경 기록을 참고하면 된다.

기여는 대부분 Rust를 쓰지 않아도 가능하다. 좋은 checks.toml과 작은 예제를 추가하면 새로운 분야를 다룰 수 있다. 게임 개발, 머신러닝, dbt, 영상 파이프라인, 마이그레이션에서 에이전트가 완료를 어떻게 속일 수 있는지에 관한 분야 지식이 필요하다고 프로젝트는 말한다. 새로운 분야를 제안하는 이슈를 열거나 예제, 에이전트가 속임수를 쓰도록 유도하는 벤치마크 작업을 추가할 수 있다. Codex, Cursor, OpenCode 등 다른 에이전트 훅이나 검사 유형, 테스트를 추가하는 일은 Rust가 필요하다.

각 작업에는 사람과 AI 코딩 에이전트를 위한 단계별 안내가 .claude/skills/에 있다. Claude Code는 이 안내를 자동으로 불러온다. 검증 절차, 풀 리퀘스트, 커밋 서명(DCO)은 CONTRIBUTING.md에 정리돼 있다.

Rust 1.90 이상에서 cargo build --release로 빌드하면 target/release/countercheck가 생성된다. 검증 명령은 cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace, python3 eval/validate.py다. Countercheck는 .countercheck/checks.toml에 적힌 검사로 자기 자신도 확인한다.

저장소는 다음과 같이 나뉜다.

• crates/countercheck-core: 검사 파일과 검사 유형, 보호 경로, 영수증, 판정 등 순수 로직
• apps/countercheck: Git 처리, 깨끗한 복사본, 샌드박스, 실행기, 훅을 다루는 CLI
• examples/: 오류를 심어 둔 검사를 포함하는 분야별 가상 프로젝트
• eval/, docs/eval/: 숨은 테스트가 있는 작업을 이용해 Hermes Agent를 평가하는 벤치마크
• .claude/skills/: 단계별 기여 안내, docs/architecture.md: 내부 동작 설명
• packaging/, install.sh, install.ps1, pyproject.toml: Homebrew, 설치 스크립트, Python 휠 등 배포 패키징
• docs/checks.md: 검사 유형 전체, docs/hooks/: 에이전트 훅, docs/decisions/: 설계 결정

Countercheck는 MIT 라이선스로 배포된다.