show-me-the-work (smtw): AI 에이전트 실행 증거 검증 도구 완벽 가이드

show-me-the-work (smtw): AI 에이전트 작업 증거 감독 도구 분석

version 2.6.1 License: MIT

코딩 AI가 실제로 테스트나 코드를 실행하지 않은 채 "작업을 완료했다"고 거짓 보고하거나, 다음 작업을 약속하고 멈추는 현상을 경험해 보셨나요?

show-me-the-work(smtw, 쇼미더워크)는 AI가 완료를 선언하기 전에 실제 실행 증거가 있는지 검사하는 로컬 훅 기반 작업 감독 도구입니다.

1. 한 문장으로 이해하기

AI가 작업 완료를 주장하면 show-me-the-work는 로컬 훅 이벤트를 관측하고 실행 증거를 확인하여, 근거 없는 완료 보고에 이의를 제기합니다.

• 검증 없는 완료 보고를 최대 2회 되돌려 보냅니다.
• 2회 후에는 무한 교착을 막기 위해 경고 및 감사기록을 남긴 뒤 통과(fail-open)시킵니다.
• 모델 능력 자체를 바꾸는 것이 아니라, 조사·검증·완료 규율 절차를 강제하는 도구입니다.

프로젝트 명칭 유래: 본 도구는 원래 fable-lite라는 실험 프로젝트로 시작했습니다. "모델 자체의 능력을 이식할 순 없어도 절차적 규율은 구현할 수 있다"는 결론을 얻은 후, v2.0에서 좁고 정직한 제품 범위를 나타내는 show-me-the-work로 이름을 재정의했습니다.

2. 보장하는 것과 보장하지 않는 것

제공하도록 설계된 보장

• verification command의 실제 실행 여부 및 성공/실패 결과 관측
• 인정된 검증 이후 파일이 재수정되었을 때 fresh verification이 아님을 탐지
• 일부 high-risk 작업에 대한 identity별 계약 요구
• R2가 타 에이전트의 미정산 변경이나 보호 상태를 지우는 파괴 작업 차단
• 완료를 최대 2회 되돌린 후 명시적 감사기록을 남기는 fail-open 게이트 제공
• 턴·invocation·경로·goals·scorecard·차단 명령의 로컬 감사 증거 기록

보장하지 않는 것

• 코드, 조사 내용, 시각 결과가 100% 정답이라는 보장
• DB·서비스·네트워크·원격 부작용의 완전한 관측
• 의도적인 arbitrary-code 우회에 대한 완전 방어
• 인간 검토나 운영 승인의 전면 대체
• 모든 AI host의 live 지원 및 모든 shell·PowerShell·동적 언어 문법의 완전한 해석

실험 결과에 따르면 프롬프트 지시만 사용했을 때는 준수율이 0/3이었으나, Stop 게이트를 켠 세션에서는 3/3 모두 실제 증거를 갖춘 차단 후 회복으로 수렴했습니다. 5개 과제 A/B 테스트에서도 검증 규율 부분에서 ON 상태가 5/5로 우수함을 증명했습니다.

호스트 지원 현황

호스트	현재 상태
Claude Code	라이브 훅 체인 확인
Codex CLI	라이브 훅 체인 확인
Antigravity	host 1.1.2+에서 payload·config load 정합성 확인 (config-path 훅 live 실행 미확인)

3. 이름·패키지·경로 표준화

canonical 표면과 기존 legacy/호환 표면의 대응 관계입니다.

표면	canonical	legacy / 호환
제품	show-me-the-work	fable-lite (과거 이름)
CLI	smtw	fable-lite
Python import	smtw	fable_lite
distribution	당분간 fable-lite	동일 distribution
runtime state	신규·이관 프로젝트의 .smtw/	미이관 프로젝트의 .fable-lite/
project config	.smtw.toml, 그다음 pyproject.toml [tool.smtw]	.fable-lite/config.json fallback
runtime env	SMTW_*	FABLE_LITE_* read alias

한 시점에 authoritative state tree는 단 하나만 존재합니다.

4. 1분 설치 및 환경 설정

전제 조건: PATH에 등록된 Python 3.12+ (표준 라이브러리만 사용). 오버헤드를 줄이기 위해 project scope 설치를 강력히 권장합니다.

git clone https://github.com/pinetreeB/show-me-the-work
cd show-me-the-work
claude plugin marketplace add .
claude plugin install show-me-the-work@show-me-the-work --scope project
smtw init --root .
smtw doctor --root .

• smtw init은 사용자 홈 위치를 거절하며 기존 config를 덮어쓰지 않습니다.
• 기본적으로 .smtw.toml을 생성하고 .gitignore에 runtime 패턴을 제안합니다.
• --config pyproject 옵션으로 pyproject.toml에 설정을 추가할 수 있습니다.
• 개인 전용 미커밋 플러그인 등록 시 Claude의 --scope local을 활용하십시오.

5. 프로젝트 설정 파일 예시

권장 전용 설정 파일 (.smtw.toml):

# .smtw.toml
schema_version = 1
supervision = true

설정 우선순위: 1) .smtw.toml > 2) pyproject.toml [tool.smtw] > 3) .fable-lite/config.json

상위 우선순위 파일이 존재하지만 유효하지 않은 경우 하위 설정으로 조용히 fallback하지 않고 오류를 발생시킵니다(fail-closed).

6. 상태 Authority 및 마이그레이션

smtw status 및 smtw doctor로 레이아웃 상태를 점검합니다.

layout	의미	authority / 조치
EMPTY	state tree가 없음	다음 활성 write는 .smtw/ 사용
LEGACY	미이관 legacy tree만 있음	.fable-lite/; migration은 선택적·명시적
NATIVE	migration marker 없는 canonical tree 존재	.smtw/
MIGRATING	legacy source와 소유된 staging state 존재	.fable-lite/; migration 대기 또는 조사 필요
MIGRATED	검증·publish된 canonical tree 존재	.smtw/; 보존된 legacy는 fallback 대상 아님
CONFLICT	단일 authority 증명 불가	authority 없음; 관련 작업 block 또는 degraded

smtw status --root .
smtw migrate --root . --check
smtw migrate --root .
smtw doctor --root .

마이그레이션은 원자적으로 실행되며 active turn이나 open invocation이 있는 경우 연기(defer)됩니다.

7. 주요 CLI 운영 명령

smtw doctor --root .              # 시스템 종합 진단 (종료코드: 0 정상, 1 오류, 2 조치필요)
smtw doctor --root . --json       # JSON 형식 출력
smtw status --root .              # 요약 런타임 뷰
smtw migrate --root . --check     # 마이그레이션 사전 검사 (Write-free)
smtw quarantine list --root .     # 격리된 차단 명령 목록 확인
smtw scorecard --root . --view coordination
smtw goals status --root . --identity <host:session-id:agent>

멀티 스토리 목표 관리 및 위임 작업 예시:

# 목표 설정 및 검증
smtw goals plan --root . --goal "release" --story "Windows 검증" --verify-cmd "python -m pytest"
smtw goals verify --root . --story "Windows 검증" --evidence "pytest green"

# wmux 형태의 위임 및 점검
smtw brief --paths "core/**,tests/**" --verify-cmd "python -m pytest tests/" --sentinel tmp/.done --target codex
smtw check --root . --agent codex --since-file tmp/.delegation-start

8. 게이트 동작 및 검증 정책

gate / 경계	event	사용 증거	block cap	실패 정책
N1 조사	prompt routing, Stop	가설/증거/거절 마커	Stop cap 2회	cap 이후 감사기록과 함께 fail-open
N2 goals/intent/design	prompt, completion	identity별 plan·검증증거·확정 intent	gate별 2회	cap 이후 감사기록과 함께 fail-open
verification completion	Stop / AfterAgent	성공 command observation	2회	cap 이후 감사기록과 함께 fail-open
R1 high-risk contract	PreToolUse	evidence-bearing identity contract	일반 cap 없음	contract 전까지 hard block
R2 파괴 보호	PreToolUse	parsed target, ownership, protected state	cap 없음	fail-closed (모호성 및 위험 차단)
scope drift	PostToolUse	요청 scope vs 관측 경로 비교	advisory	턴별 dedupe 경고 출력
stale mutation	PreToolUse	현재 turn identity 및 lifecycle	cap 없음	mutation deny
runtime env conflict	활성 hook 전체	canonical/legacy 변수 일치 여부	cap 없음	fail-closed
state layout conflict	state consumer/mutation	검증된 layout 및 migration marker	cap 없음	authority 없음, block 또는 degraded

일반 관측 실패는 fail-open하여 작업 교착을 방지하지만, R2 파괴 보호, 환경변수 충돌, Authority 충돌은 fail-closed로 단호히 차단합니다.

9. 멀티에이전트 운영 핵심

• Exact Identity: host:session-id:agent 포맷을 사용합니다.
• Candidate Ownership: 도구 선언 경로는 attribution용으로, 실제 resolve 경로는 R2 피어 매칭용으로 분리 추적합니다.
• Settlement: 피어의 open invocation 또는 unsettled revision은 파괴 작업 전 명시적으로 정산되어야 합니다.
• Quarantine (격리): R2로 차단된 명령은 authoritative tree에 보관되며 필요시 operator가 조회/삭제(smtw quarantine clear)할 수 있습니다.
• Stale Turn: 오래된 turn의 변경 작업은 정지되며 새 prompt를 제출해 turn을 시작해야 합니다.

LazyCodex/OmO의 ulw가 작업 완수를 이끌고, smtw가 완료 증거를 검증하는 방식으로 서로 완벽히 보완될 수 있습니다.

10. 하위 호환성 정보

legacy state/config/environment 읽기 및 fable_lite Python shim은 v3.x 동안 계속 유지되며 v4 이전에는 제거되지 않습니다.

legacy 표면	지원 상태	canonical 대체
fable-lite console script	호환 상태 지원	smtw
import fable_lite 및 모듈	DeprecationWarning 발생 alias	import smtw
python -m fable_lite	지원 (deprecated)	python -m smtw
python -m fable_lite.cli / scorecard / migrate	thin shim 지원	smtw [subcommand]

11. 성능·스코프·개인정보 관리

• 성능 스코프: 관측 엔트리 10,000개, 파일 용량 256 MiB 제한. full reconciliation 8초, incremental 2초 예산 적용.
• 개인정보 보완: 명령, 파일 다이제스트, intent, 로그 등 민감 정보가 포함될 수 있으므로 state를 git commit 하지 않도록 주의해야 합니다.
• Quarantine 보관 제한: 최대 64개, 총 16 MiB, 7일간 보관되며 건당 1 MiB 초과 시 metadata만 남깁니다.

smtw quarantine list --root .
smtw quarantine clear --root . --all

12. 개발·검증 CI 및 출처

Ubuntu·Windows 환경의 Python 3.12 매트릭스 검증 과정:

python scripts/sync_version.py --check
ruff check core adapters fable_lite goals tests eval contrib scripts smtw --exclude eval/ab
python -m pytest tests/ -q
python eval/run_probes.py --strict --output tmp/smtw-probes.json
python eval/e2e_smoke.py
python -m compileall -q core adapters fable_lite goals eval contrib scripts smtw
python -m eval.provenance.run --output tmp/smtw-provenance.json
python -m build --wheel --outdir dist
python scripts/check_wheel_contents.py --wheel-dir dist

출처 및 라이선스 정보

본 도구의 절차 및 아이디어는 다음 오픈소스 프로젝트의 핵심 가치를 바탕으로 재작성되었습니다.

• 조사·검증·분해 절차 참고: fivetaku/fablize (MIT)
• Intent Interview 기법 차용: Yeachan-Heo/gajae-code (MIT)
• 평가 루프 참고: opus-fable-playbook & fablever

MIT License © pinetreeB
원문 출처: https://github.com/pinetreeB/show-me-the-work/blob/main/README.ko.md