Verification Engine

검증 원칙

Iron Law, Gate Function, Common Failures 체크리스트는 rules/verification.md에 정의되어 있다. 이 스킬은 해당 원칙의 실행 엔진이다.

Overview

통합 검증 엔진 스킬은 /handoff-verify 커맨드의 핵심 동작을 정의한다. v5의 /verify 단독 커맨드에서 v6의 /handoff-verify 통합 커맨드로 진화하였다.

핵심 변경: Task 도구로 verify-agent 서브에이전트를 생성하여 fresh context에서 검증. /clear 없이도 편향 없는 검증이 가능하다.

Trigger Conditions

직접 호출

자동 호출

Architecture (v6)

Copy code
/handoff-verify 커맨드 (부모 컨텍스트)
   │
   ├── [1] handoff.md 자동 생성
   │     └── git diff 분석, 변경 의도 문서화
   │
   ├── [2] verify-agent 서브에이전트 생성 (Task 도구)
   │     └── Fresh context! (/clear 대체)
   │         │
   │         ├── handoff.md 읽기
   │         ├── 검증 파이프라인 실행
   │         ├── 실패 시 자동 수정 + 재시도
   │         └── 결과 반환
   │
   └── [3] 결과 수신 및 처리
         ├── PASS → handoff.md 정리, 다음 단계 안내
         └── FAIL → 에러 보고, 권장 조치 안내

v5 대비 아키텍처 변경

Verification Pipeline

단계별 실행 순서 (verify-agent 내부)

Copy code
[1단계] 환경 파악
   ├── handoff.md 읽기 (변경 의도)
   ├── git status / diff
   ├── 프로젝트 타입 감지
   └── 패키지 매니저 감지
         │
[2단계] 빌드 검증
   ├── npm run build / go build / cargo build
   └── 빌드 실패 시 → Fixable 자동 수정
         │
[3단계] 타입 검사
   ├── tsc --noEmit / mypy / go vet
   └── 타입 오류 → Fixable 자동 수정
         │
[4단계] 린트 검사
   ├── eslint / golangci-lint / clippy
   └── 린트 오류 → Fixable 자동 수정
         │
[5단계] 테스트 실행
   ├── npm test / go test / cargo test
   └── 실패 시 → 에러 분석 + 수정 시도
         │
[6단계] 코드 리뷰 (effort에 따라)
   ├── low: 건너뜀
   ├── medium: 변경 파일만
   ├── high: 변경 파일 + 의존성
   └── max: 전체 영향 분석
         │
[7단계] 보안 검토 (--security 또는 effort:max)
   └── security-reviewer 서브에이전트 연동

루프 동작 원리

Copy code
[실행 #1]
   │ FAIL → Fixable 자동 수정 → 재실행
   │
[실행 #2]
   │ FAIL → Fixable 자동 수정 → 재실행
   │
[실행 #3~5]
   │ FAIL → 수정 시도 → 재실행
   │
[5회 실패]
   └── /learn --from-error 제안
       최종 에러 리포트 → 부모에게 반환

Fixable Auto-Repair

자동 수정 가능한 오류 9가지. 서브에이전트가 사용자 승인 없이 즉시 수정한다.

Fixable 목록

수정 불가 항목 (사용자 판단 필요)

• 로직 오류 (비즈니스 로직 변경)
• 아키텍처 변경이 필요한 타입 오류
• 테스트 로직 자체의 오류
• 보안 취약점 (security-pipeline이 처리)

Effort별 동작 차이

Coverage Mode (--coverage)

/handoff-verify --coverage 실행 시 테스트 커버리지를 분석한다.

출력 형식

Copy code
커버리지 리포트
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
전체:      72.3% (목표: 80%)
신규 코드:  45.2%
미커버 파일: 3개
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

미커버 함수:
  src/utils/parser.ts:parseConfig (0%)
  src/api/handler.ts:processRequest (12%)
  src/lib/cache.ts:invalidate (0%)

권장 테스트:
  1. parseConfig - 정상/비정상 입력 테스트
  2. processRequest - 요청/응답 통합 테스트
  3. invalidate - 캐시 무효화 단위 테스트

Extract Mode (--extract)

/handoff-verify --extract 실행 시 에러를 추출하고 분류한다.

분류 체계

출력 형식

Copy code
에러 추출 결과
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
총 에러: 12개
  BUILD:    3개 (Fixable: 2)
  TYPE:     4개 (Fixable: 3)
  LINT:     2개 (Fixable: 2)
  TEST:     2개 (Fixable: 0)
  SECURITY: 1개 (Fixable: 0)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
자동 수정 가능: 7/12 (58%)

Integration Points

/handoff-verify 커맨드

이 스킬은 /handoff-verify 커맨드의 핵심 로직을 정의한다. 커맨드 파일(commands/handoff-verify.md)이 이 스킬의 파이프라인을 실행한다.

verify-agent 에이전트

서브에이전트(agents/verify-agent.md)가 이 스킬의 파이프라인을 실제로 실행한다. 부모 컨텍스트와 분리된 fresh context에서 동작한다.

security-pipeline 스킬

--security 플래그 또는 effort:max 시 security-pipeline 스킬과 연동한다. 보안 검증 부분은 security-pipeline에 위임한다.

/learn 커맨드

5회 루프 실패 시 /learn --from-error를 자동 제안하여 에러 패턴을 CLAUDE.md에 기록한다.

/commit-push-pr 커맨드

커밋 전 사전 검증 게이트로 동작한다:

• PASS: 모든 검증 통과 → 커밋 진행
• WARN: 비치명적 이슈 존재 → 경고 후 계속
• FAIL: 빌드/타입/테스트 실패 → 커밋 차단