| name | checklist-loop |
| description | 개발이 스펙대로 됐는지 구현 주장 항목을 코드 대조로 0~100 채점하고, 95점 미만은 되먹여 재작업하는 검증 루프를 돈다. carve-verify-loop 워크플로가 없거나(타 에이전트·일반 세션) 손으로 돌릴 때 사용. |
checklist-loop — 스펙→개발→체크리스트→채점→재작업 루프 (모델 무관 SOP)
권위는 도구가 아니라 이 절차에 있다(fable-team-guide 4절).
carve-verify-loop 워크플로는 이 절차를 코드로 자동 실행할 뿐이다.
Fable/Opus/Sonnet 어떤 세션이든, 훅 없는 다른 에이전트든 아래를 그대로 수동 실행하면 동일하게 동작한다.
핵심 불변식
- 생성자(builder)와 채점자(evaluator)는 절대 같은 에이전트가 아니다 (Self-Eval Blindspot 방지, AGENTS.md 6절).
- 주장을 믿지 않는다. "구현했다"는 claim은 실제 코드 대조 + 테스트 실행으로만 인정한다.
- 완료 = 모든 항목 score ≥ 임계(기본 95). 하나라도 미달이면 루프는 끝나지 않는다.
- 에이전트 간 통신은 파일 기반 —
specs/checklist.json이 단일 진실원.
specs/checklist.json 스키마 (정본)
{
"goal": "주문 취소 API",
"iteration": 2,
"threshold": 95,
"items": [
{
"id": "c1",
"claim": "POST /orders/{id}/cancel 구현",
"acceptance": "204 반환 + 상태 CANCELLED 전이 테스트 통과",
"owns": ["src/api/cancel/**"],
"attempts": 2,
"score": 88,
"pass": false,
"gaps": ["멱등성 미검증", "이미 취소된 주문 409 테스트 없음"],
"evidence": "src/api/cancel/route.ts:12; test 3/4 pass"
}
]
}
claim/acceptance/owns: 분해 단계에서 채운다. owns glob은 항목끼리 겹치면 안 된다(파일 오너 1개).score/pass/gaps/evidence/attempts: 채점 단계에서 채운다. pass = score >= threshold.
루프 SOP (순서 고정)
S1. Spec/분해 목표를 리서치 → 3~7개 항목으로 분해(claim·acceptance·owns 비중복).
상호의존 파일(구현 + 그 테스트, 모듈 + 그 마이그레이션)은 반드시 같은 항목 owns에 함께 둔다 —
항목은 격리 worktree에서 채점돼 다른 항목 파일을 못 보므로, 구현·테스트를 쪼개면 테스트 항목이 영구 미달.
specs/checklist.json 작성(전 항목 score:null). → Stop 게이트가 이때부터 완료를 막는다.
S2. Build 미해결 항목(pass=false)마다 builder 1개. worktree 격리, 동시 3~5개 상한.
owns 밖 쓰기 금지. 재작업이면 아래 S4의 반성 프롬프트 + gaps를 입력으로 준다.
S3. Score 항목마다 evaluator(read-only)에 채점 위임 → 코드 대조 + 테스트 실행으로 0~100.
결과를 checklist.json에 반영(score·pass·gaps·evidence·attempts++).
S4. Loop score<임계 항목만 골라 gap을 builder에 되먹여 S2로. 미달 항목만 재작업(전수 아님).
반성 프롬프트 강제: "무엇이 실패했나? 어떤 구체적 변경이 임계를 넘기나? 같은 접근 반복 중인가?"
S5. 종료 전 항목 pass=true → S6. / 특정 항목 3회(MAX_ATTEMPTS) 재작업에도 미달 → [ESCALATION] 후
그 항목 failed 기록하고 루프 탈출(무한 재시도 금지, orchestration.md 5절).
S6. 최종 evaluator 통합 최종 판정(항목 간 계약 위반·회귀 점검). 통과분만 완료로 선언.
가드레일: 항목당 재작업 3회, 외곽 루프 8회(MAX_ITERATIONS)를 상한으로 둔다. 예산 85% 도달 시 일시정지 보고.
완료 게이트 연동 (checklist-gate 훅)
specs/checklist.json이 존재하고 score<threshold거나 미채점(score:null) 항목이 남으면
Stop 훅 checklist-gate.sh가 완료를 **차단(exit 2)**한다("미완 N개 — 루프 계속"). 워크플로 없이 손으로 돌려도 강제력이 걸린다.
파일이 없으면 무동작 — 루프를 쓰지 않는 작업은 방해받지 않는다.
- 루프 시작: checklist.json 작성(전 항목 미채점) → 게이트 활성.
- 루프 종료: 전 항목 pass=true → 게이트 통과. 또는 escalated 항목을 사람이 승인 후 checklist.json에서 제거/조정.
워크플로로 자동 실행
/verify-loop 주문 취소 API 구현
또는 발화에 carve-verify-loop 실행 / ultracode. 인자로 항목을 직접 줄 수도 있다:
{ "goal": "주문 취소 API",
"threshold": 95,
"tasks": [
{ "id": "api", "claim": "취소 엔드포인트", "acceptance": "204+CANCELLED 전이 테스트 통과", "owns": ["src/api/cancel/**"] }
] }
참고
- 루프 코드:
.claude/workflows/carve-verify-loop.js
- 게이트 훅:
.claude/hooks/checklist-gate.sh
- 채점자:
.claude/agents/evaluator.md(채점 모드 절)
- 오케스트레이션 규칙:
docs/md/orchestration.md, docs/md/fable-team-guide.md
