verification-workflow

Verification Workflow

A risk-gated pipeline from requirement to commit. The review/verification stages can be implemented by any agent roster — role names below (researcher, architect, reviewer, executor) are roles, not specific agents. Simple one-off work needs only self-verification (lint/type/test) plus the commit gate.

Full flow

요구사항 입력
    ↓
[모호함 체크] → 해당 시 사용자에게 질문
    ↓
[복잡도 판단] → 단순(1-2파일): 계획 직행 / 복잡(3+파일): Research 단계 진입
    ↓
★ Research (복잡 작업 필수) — 대상 영역 분석 → research.md → 사용자 확인
    ↓
★ 계획 — 계획 출력 템플릿 준수, 유사 기존 구현 참조 필수 → plan.md
    ↓
★ Annotation Cycle (복잡 작업 필수, 1-3회)
  → 사용자 주석/피드백 → 계획 갱신 → "아직 구현하지 마라"
    ↓
★ 계획 검증 — 결함·누락 / 보안 / 정책 정합성 관점의 독립 리뷰
    ↓
[공유 모듈 변경?] → YES: 영향 모듈 식별
    ↓
구현 (외과적·최소 diff·컨벤션 준수)
    ↓
테스트 단계 (references/testing.md) — 요구사항 기반·예외/경계·회귀·커버리지
    ↓
린트/타입/테스트 (스택별 fresh 출력)
    ↓
★ 코드 검증 — 독립 리뷰. CERTAIN 지적은 자동 수정 / QUESTION은 사용자 확인
    ↓
[E2E 필요 시] 브라우저/실환경 검증 (액션 후 스크린샷 증거)
    ↓
커밋 전 검증 체크리스트 (아래) → Commit
    ↓
[검증 실패] → 자동 수정 루프 (아래)

Research 단계 (복잡 작업 필수)

트리거: 3개+ 파일 변경 예상, 또는 기존 아키텍처 이해가 필요한 작업

1. 대상 코드를 깊이 분석 (관련 클래스, 의존성, 호출 흐름)
2. 분석 결과를 docs/{key}/research.md 등 프로젝트 문서 위치에 기록: 현재 구조 요약 / 데이터 흐름 / 제약 조건 / 변경 영향 범위
3. 사용자에게 research.md 검토 요청 → 잘못된 이해를 사전 차단
4. 사용자 승인 후에만 계획 단계로 진행

핵심: 잘못된 리서치는 이후 모든 단계를 망친다. 가장 비용이 큰 실패를 여기서 차단. 스킵 조건: 단순 버그 수정, 1-2파일 변경, 사용자가 "skip research" 명시

계획 출력 템플릿 (필수 준수)

## 1. 변경 파일 목록      — path + 변경 이유 한줄
## 2. 참조한 기존 구현    — path + 이 패턴을 따르는 이유
## 3. 핵심 코드 스니펫    — 주요 시그니처/핵심 로직 스케치
## 4. 대안 및 트레이드오프 — 선택 vs 대안 (최소 1개), 각각 장단점 (기록 구조: references/design-decisions.md)
## 5. 리스크             — 회귀 가능성, 성능 영향, 마이그레이션 여부
## 6. 예상 소요과 컷라인  — Phase별 구현/테스트 예상 + 근거(참조 구현 크기·파일 수·미지수),
##                        시간 초과 시 자를 순서 (동작 우선 → 기본 기능 → 심화)

참조 구현 패턴: 계획 작성 전 기존 코드에서 유사 구현을 먼저 검색한다 — 동일 도메인 유사 기능 → 동일 패턴의 다른 모듈 → 기존 설계 문서. 기존 패턴과 다르게 구현하면 반드시 이유를 트레이드오프 섹션에 기록.

Annotation Cycle (복잡 작업 필수)

트리거: 3개+ 파일 변경, 아키텍처 결정 포함, 새로운 패턴 도입