Flow Verifier

Flow Verifier

구현 전 다이어그램 → 구현 후 검증 — 코드가 설계대로 흐르는지 확인합니다.

기존 mermaid-diagrams 스킬로 플로우차트를 그리고, 구현 완료 후 실제 코드 경로가 다이어그램의 노드/분기와 일치하는지 자동 검증합니다.

여러 독립 흐름을 분석할 때만 읽기 전용 역할(Claude Explore, Codex explorer, Antigravity research, Grok explore)에 초안 또는 근거 반환을 위임할 수 있습니다. 작업자는 파일을 쓰지 않으며, 메인 컨텍스트만 .mmd, 인덱스, 검증 보고서와 최종 매칭 판정을 갱신합니다. 위임이 없거나 병렬 이득이 없으면 메인 컨텍스트에서 같은 절차를 순차 실행합니다.

사용법

# 1단계: 구현 전 — 프로세스 다이어그램 생성
/flow-verifier plan "사용자 로그인 → JWT 발급 → 리프레시 토큰"

# 2단계: 구현 후 — 코드 흐름 검증
/flow-verifier verify "사용자 로그인"

# 한번에 (이미 다이어그램이 있을 때)
/flow-verifier verify docs/flow-diagrams/user-login.mmd

공식 호출명: /flow-verifier (별칭: 플로우 검증, 다이어그램 검증)

모드

plan — 다이어그램 생성

구현할 기능의 프로세스를 Mermaid flowchart로 그립니다.

절차:

1. 기능 분석: 사용자 설명 또는 SPEC 파일에서 핵심 흐름 추출
2. 노드 식별: 각 처리 단계를 노드로 정의
   • ([시작/끝]) — 시작/종료점
   • [처리] — 일반 처리 단계
   • {분기?} — 조건 분기 (if/else, switch)
   • [[서브루틴]] — 외부 함수/서비스 호출
3. 경로 매핑: 정상 경로(happy path) + 에러 경로 + 엣지 케이스
4. 파일 저장: docs/flow-diagrams/{feature-name}.mmd

출력 예시:

flowchart TD
    Start([로그인 요청]) --> Validate{입력값 유효?}
    Validate -->|No| Error400[400 Bad Request]
    Validate -->|Yes| FindUser[DB에서 사용자 조회]
    FindUser --> Exists{사용자 존재?}
    Exists -->|No| Error401[401 Unauthorized]
    Exists -->|Yes| CheckPwd[비밀번호 검증]
    CheckPwd --> PwdOk{비밀번호 일치?}
    PwdOk -->|No| Error401
    PwdOk -->|Yes| GenJWT[JWT 토큰 생성]
    GenJWT --> GenRefresh[리프레시 토큰 생성]
    GenRefresh --> SaveToken[DB에 리프레시 토큰 저장]
    SaveToken --> Response([200 OK + tokens])

규칙:

• mermaid-diagrams 스킬의 문법 가이드를 참조하여 정확한 Mermaid 문법 사용
• 노드 ID는 영문 camelCase (예: FindUser, CheckPwd)
• 노드 라벨은 한국어/영어 모두 가능
• 분기(decision)는 반드시 모든 경로(Yes/No, 에러 등) 포함
• 한 다이어그램에 노드 20개 이하 권장 (초과 시 서브 다이어그램으로 분리)

verify — 코드 흐름 검증

구현된 코드가 다이어그램의 흐름과 일치하는지 검증합니다.

절차:

1. 다이어그램 파싱: .mmd 파일에서 노드와 엣지(연결) 추출
2. 코드 추적: 관련 소스 파일에서 실제 실행 경로 분석
3. 매칭 검증: 다이어그램의 각 노드/분기가 코드에 존재하는지 확인
4. 리포트 생성: 일치/불일치 보고서 출력

검증 항목:

추적 전략:

1. 엔트리포인트 찾기
   - API: 라우터/컨트롤러에서 해당 엔드포인트 함수 찾기
   - UI: 이벤트 핸들러 또는 페이지 컴포넌트에서 시작점 찾기
   - 서비스: 해당 서비스 클래스/함수에서 public 메서드 찾기

2. 호출 체인 따라가기
   - 함수 → 함수 호출 추적 (Grep으로 함수명 검색)
   - 조건문 → 다이어그램 분기와 매칭
   - try-catch → 다이어그램 에러 경로와 매칭
   - return/throw → 다이어그램 종료 노드와 매칭

3. 결과 대조
   - 다이어그램 노드 ↔ 코드 위치 1:1 매핑 테이블 생성
   - 매핑 안 되는 노드 = 불일치

리포트 형식:

══ Flow Verification Report ══════════════
Feature: 사용자 로그인
Diagram: docs/flow-diagrams/user-login.mmd
Source:  src/auth/login.controller.ts
         src/auth/auth.service.ts
═══════════════════════════════════════════

## 노드 매칭 결과

| 다이어그램 노드 | 코드 위치 | 상태 |
|----------------|-----------|------|
| Start(로그인 요청) | login.controller.ts:15 `@Post('/login')` | ✅ Match |
| Validate(입력값 유효?) | login.controller.ts:18 `if (!dto.email)` | ✅ Match |
| Error400 | login.controller.ts:19 `throw new BadRequestException()` | ✅ Match |
| FindUser | auth.service.ts:32 `findByEmail()` | ✅ Match |
| CheckPwd | auth.service.ts:38 `bcrypt.compare()` | ✅ Match |
| GenRefresh | — | ❌ Missing |
| SaveToken | — | ❌ Missing |

## 분기 검증

| 분기 | Yes 경로 | No 경로 | 상태 |
|------|----------|---------|------|
| 입력값 유효? | ✅ | ✅ | Complete |
| 사용자 존재? | ✅ | ✅ | Complete |
| 비밀번호 일치? | ✅ | ✅ | Complete |

## 누락 경로 (코드에만 존재)

| 코드 경로 | 위치 | 제안 |
|-----------|------|------|
| Rate limit 체크 | login.controller.ts:12 | 다이어그램에 노드 추가 권장 |

## 요약

- 전체 노드: 10개
- 매칭: 8개 (80%)
- 누락: 2개 (GenRefresh, SaveToken)
- 추가 경로: 1개 (Rate limit)
- 판정: ⚠️ PARTIAL MATCH — 리프레시 토큰 관련 구현 누락
═══════════════════════════════════════════

Chronos 통합

Chronos(/chronos) 실행 시 --flow-verify 옵션으로 활성화:

/chronos 로그인 기능 구현해줘 --flow-verify

Chronos 내 동작:

Phase 0: 스코프 확인 (기존)
Phase 0.5: [NEW] 프로세스 다이어그램 생성
  → /flow-verifier plan "{기능 설명}"
  → docs/flow-diagrams/{feature}.mmd 저장
Phase 1: 루프 실행 — FIND → FIX → VERIFY (기존)
Phase 2: [NEW] 플로우 검증
  → /flow-verifier verify docs/flow-diagrams/{feature}.mmd
  → 불일치 발견 시 → 다음 사이클에서 수정 대상으로 승격
Phase 2: 최종 보고 (기존 + 플로우 검증 결과 포함)

Chronos 없이 단독 사용도 가능:

# 설계 단계에서 다이어그램만 그리기
/flow-verifier plan "결제 프로세스"

# 코드 리뷰 시 기존 다이어그램과 비교
/flow-verifier verify docs/flow-diagrams/payment.mmd

다이어그램 파일 관리

docs/
└── flow-diagrams/
    ├── user-login.mmd          # 사용자 로그인
    ├── payment-process.mmd     # 결제 프로세스
    └── order-lifecycle.mmd     # 주문 생명주기

규칙:

• 파일명: kebab-case + .mmd 확장자
• 위치: docs/flow-diagrams/ (프로젝트 루트 기준)
• 다이어그램 수정 시 verify 모드로 재검증 권장
• Git에 함께 커밋하여 코드와 다이어그램 버전 동기화

workpm 통합

workpm(/workpm) PM 모드에서 프로세스 도면(설계도)과 공정 점검(준공 검사)에 활용됩니다.

workpm 내 동작:

Phase 1:   리서치 & 제안 → 사용자 승인
Phase 2:   [도면 작성] /flow-verifier plan → .mmd 생성
Phase 3~4: 영향도 분석 → 구현 (도면의 노드별 태스크 배분)
Phase 5:   [공정 점검] /flow-verifier verify → 매칭 검증
           ├─ FULL MATCH → 최종 보고
           ├─ PARTIAL → 누락 노드 추가 구현 → 재검증
           └─ MISMATCH → 수정 후 재검증

Related Files