Proof of done (완료 증명)
당신은 작업이 완료되었다고 결정하지 않습니다. 스크립트가 증명서(receipt)를 통해 결정합니다. 당신의 역할은 계약(contract)을 작성하고, 증명을 생성하며, 스크립트가 계산한 판정(verdict)을 그대로 보고하는 것입니다.
요청: $ARGUMENTS
규칙
증명서 없음, 주장 없음.
증명서는 해당 증명을 생성한 코드에서만 유효합니다.
판정은 계산되며, 수동으로 작성되지 않습니다.
"완료", "수정됨", "작동함", "통과", "준비됨", "배포됨", "모두 좋음", 체크 표시, 또는 독자에게 이러한 상태 중 하나를 믿게 하는 모든 문장은 주장(claim)입니다. "아마 작동할 것이다"도 마찬가지이며, 이는 변명이 붙은 주장입니다. 모든 주장은 현재 트리(tree)에 대해 원장(ledger)에 PROVEN(증명됨) 행이 있어야 합니다. 그렇지 않으면 주장할 수 없습니다.
엔진
이 스킬 폴더(보통 ~/.claude/skills/proof-of-done/scripts/proof.py 또는 프로젝트 내 .claude/skills/proof-of-done/...)에 있는 scripts/proof.py입니다. 표준 라이브러리, Python 3.8+ 필요. 세션당 한 번 설정하세요:
P="python3 $(ls -d ~/.claude/skills/proof-of-done .claude/skills/proof-of-done 2>/dev/null | head -1)/scripts/proof.py"
모든 것은 프로젝트 루트의 .proof/ 디렉토리에 저장됩니다: acceptance.md (계약, 커밋 필수), contract.lock 및 contract-log.md (커밋 필수), receipts.jsonl 및 artifacts/ (로컬 증거, git에 무시됨).
다섯 단계
1. 코드보다 먼저 계약 작성
$P init 실행 후 .proof/acceptance.md를 작성합니다. 기준(criterion)당 한 줄, 네 개의 필드:
- AC1 :: 로그인한 사용자가 Gmail을 연결하고 "연결됨"을 볼 수 있다 :: e2e :: run: npx playwright test tests/gmail-connect.spec.ts
- AC2 :: 이메일이 제목을 제목으로 하는 작업이 된다 :: integration :: run: pytest tests/test_email_to_task.py -q
- AC3 :: 받은 편지함 페이지가 새로고침 없이 새 작업을 표시한다 :: visual :: see: 이메일 하나 변환 후 스크린샷
- 기준은 누군가(사용자, 호출자, 파일, 행)가 관찰할 수 있는 것을 명시해야 하며, 어떤 코드가 존재하는지가 아닙니다. "핸들러를 추가함"은 기준이 아닙니다.
- rung(강도)는 주장에 필요한 증명의 강도입니다. references/proof-ladder.md를 읽고 선택하세요: UI 주장은 최소
e2e또는visual, 버그 수정은 수정 전에 실패한 테스트 필요, 배포는 배포 대상에서의runtime필요. run:은 기준이 충족될 때만 종료 코드 0을 반환하는 정확한 명령어입니다. 실제 실행할 그대로 작성하세요. 좁게(하나의 테스트 파일)는 괜찮지만, 공허하게(true,echo ok, 단언 없는 테스트)는 안 됩니다.- 사용자가 기준을 제시했다면 그 말을 사용하세요. 그렇지 않다면 요청에서 기준을 도출하여 한 짧은 블록으로 보여주고 진행하세요 (기준이 정말 모호한 경우가 아니라면 기다리지 마세요). 요청되지 않은 사항을 평가하지 않도록
## 범위 외목록을 추가하세요. $P freeze. 이 시점부터 기준 제거, 강도 낮추기, 또는 명령어를 더 쉬운 것으로 바꾸는 것은contract-log.md에 기록되며 사용자 동의와 함께--reason플래그가 필요합니다. 기준 추가는 항상 허용됩니다.
한 줄 변경의 경우 계약은 하나의 기준일 수 있습니다. 그래도 계약은 존재합니다.
2. 증명하며 개발
정상적으로 구현하세요. 각 일관된 단계 후에 $P run AC2 (또는 $P run --all)를 실행하고 출력을 읽으세요. FAILED 행은 장애물이 아니라 정보입니다: 출력을 읽고, 원인을 수정하고, 다시 실행하세요. 버그 수정의 경우 수정 전에 새 테스트를 실행하고 그 실패한 증명서를 기억하세요: 결코 실패하지 않은 회귀 테스트는 아무것도 증명하지 못합니다 (빨간색, 그다음 초록색).
see: 기준의 경우: 증거(Playwright 스크린샷, curl -i 출력을 파일로 저장, 내보낸 CSV, 로그 발췌)를 생성하고, 열어서 확인한 후(이미지 읽기, 파일 읽기), $P attach AC3 path/to/shot.png --note "변환 후 받은 편지함, 작업 표시됨"을 실행하세요. 파일은 .proof/artifacts/로 복사되어 다른 증명서를 방해하지 않습니다. 확인하지 않은 스크린샷을 첨부하는 것은 실행하지 않은 테스트를 인용하는 것과 같은 거짓말입니다.
3. 판정
$P run --all # 최종 트리에서 모든 run: 기준에 대한 새 증명서
$P verdict # 원장과 판정; DONE일 때만 종료 코드 0
상태: PROVEN (현재 트리에서 증명서 통과), FAILED, PENDING (증명서 없음), STALE (증명 후 코드 변경됨), MISMATCH (증명서가 계약과 다른 명령어를 실행함), SUSPECT (종료 코드 0이지만 테스트 실행 없음, 건너뛰기만 있음, 도구 누락, 또는 증명이 트리를 수정함), BLOCKED, WAIVED. 판정: DONE, DONE WITH WAIVERS, BLOCKED, NOT DONE.
마지막 실행 후 편집(주석 포함)은 증명서를 STALE로 만듭니다. 그것이 핵심입니다: 마지막에 다시 실행하고, 바로 후에 보고하세요.
4. 독립 검증
만든 사람이 자신의 작업을 평가하지 않습니다. 작업이 사소한 변경을 넘거나, UI, 배포 또는 데이터를 다루거나, 하위 에이전트가 수행한 경우, references/checker.md의 프롬프트를 사용하여 하나의 검증 하위 에이전트를 실행하세요. 검증자는 계약을 다시 읽고, 증명을 직접 재실행하고, 첨부 파일을 확인하고, diff를 읽어 범위 외 작업과 게이트 변조를 확인하고, 이유와 함께 ACCEPT 또는 REJECT를 반환합니다. REJECT는 2단계로 돌아갑니다. 하위 에이전트가 성공했다고 말할 때도 동일하게 처리하세요: git diff --stat 실행, 직접 증명 실행.
5. 보고
계산된 판정 줄로 시작하고, 증명서를 표로 보고하세요:
판정: DONE (또는 NOT DONE / BLOCKED / DONE WITH WAIVERS)
| 기준 | 증명 | 결과 |
|---|---|---|
| AC1 사용자가 Gmail 연결, "연결됨" 표시 | npx playwright test tests/gmail-connect.spec.ts | 종료 코드 0, 3개 통과 |
| AC2 이메일이 작업이 됨 | pytest tests/test_email_to_task.py -q | 종료 코드 0, 5개 통과 |
| AC3 받은 편지함에 새로고침 없이 작업 표시 | .proof/artifacts/AC3-...png (확인함) | 작업이 상단에 표시됨 |
검증자: ACCEPT (또는 REJECT: ...)
미증명: 없음 (또는 각 미해결 기준, 이유, 다음 조치)
범위 외: ...
NOT DONE인 경우 먼저 명확히 말하고, 무엇이 증명되었는지, 무엇이 아닌지, 다음 최소 단계를 설명하세요. 명확한 NOT DONE은 좋은 보고서입니다. 거짓으로 판명된 DONE은 사용자의 디버깅 시간과 신뢰를 잃게 합니다.
언어 경비
메시지를 보내기 전에 검사하세요. 다음은 현재 트리에 대해 PROVEN 증명서가 필요하며, 없으면 제거해야 합니다:
- 완료, 끝남, 끝, 수정됨, 해결됨, 작동함, 작동 중, 통과, 초록색, 준비됨, 배송됨, 배포됨, 라이브, 모두 좋음, 아마 작동할 것, 아마 수정되었을 것, 아마, 좋아 보임, ✅, "완벽해!", "좋아, 작동했어"
- "테스트 통과" (하위 집합만 실행한 경우); "빌드 통과" (린터만 실행한 경우); "배포됨" (푸시만 한 경우); "수정됨" (코드를 변경하고 증상을 재현하지 않은 경우)
실행한 것과 반환된 결과를 말하세요: "pytest tests/test_email_to_task.py: 5개 통과, 종료 코드 0"은 그 자체로 충분합니다. 실행하지 않은 경우: "아직 확인되지 않음".
변명의 전체 표와 증명이 조작되는 방법은 references/anti-gaming.md에 있습니다. 프로젝트당 한 번 읽으세요; 요약: 절대 증명을 약화시키거나, 건너뛰거나, 모의 처리하거나, 삭제하지 말고, 잘못된 출력에 맞게 테스트를 수정하지 마세요.
중지 훅 (선택 사항, 프로젝트별)
$P hook --install은 ./.claude/settings.local.json (--shared는 커밋된 settings.json)에 Stop 훅을 추가합니다. .proof/acceptance.md가 있는 프로젝트에서 세션이 판정이 DONE이 아닌 상태로 종료되려고 할 때, 훅은 마지막 메시지에 이미 판정: NOT DONE 또는 판정: BLOCKED가 없는 경우에만 한 번 미해결 기준을 보내며 세션을 되돌립니다. 절대 반복되지 않으며(두 번째 중지는 통과시킴), 계약이 없는 프로젝트에서는 아무 작업도 하지 않습니다. 장시간 또는 무인 작업에 설치하고, 사용자에게 훅이 있다고 알리세요.
증명을 실행할 수 없는 경우
브라우저 없음, 스테이징 접근 권한 없음, 비밀 키 누락, 유료 API: 약한 증명으로 조용히 대체하지 마세요. $P block AC4 --reason "스테이징 자격 증명 없음"을 실행하고 BLOCKED로 정확히 무엇이 누락되었고, 사용 가능해지면 어떤 명령어로 증명할 수 있을지 보고하세요. $P waive는 사용자가 명시적으로 포기한 기준(사용자의 말 그대로, 이유에 인용)에 대해서만 존재합니다.
작은 작업
오타나 한 줄 설정 변경: 하나의 기준, 하나의 명령어, 하나의 증명서, 보고서 한 줄 (판정: DONE + 명령어와 결과). 절차는 축소되지만 규칙은 축소되지 않습니다.