fe-agent/docs/spec-review/04-flowchart-validation.md

플로우차트 검증 기준

AI가 생성하거나 직접 작성한 플로우차트가 올바른지 판단하는 기준입니다.

---

1. 구조적 완전성

1.1 필수 요소 포함 여부

요소	설명	확인
시작점	명확한 시작 노드 (원형/Stadium)	[ ]
종료점	모든 경로에 종료 노드가 있음	[ ]
분기 조건	모든 분기에 Yes/No 또는 조건 라벨이 있음	[ ]
처리 단계	주요 시스템/사용자 액션이 포함됨	[ ]
에러 경로	예외 상황 처리 흐름이 포함됨	[ ]

1.2 흐름 무결성

• 고아 노드가 없다 (연결되지 않은 노드)
• 무한 루프가 없다 (탈출 조건이 있는 경우만 루프 허용)
• 모든 분기가 다시 합류하거나 종료로 이어진다
• 화살표 방향이 일관적이다

---

2. 스펙 일치성

2.1 기능 요건과의 일치

• 스펙의 모든 주요 기능이 플로우차트에 반영되어 있다
• 플로우차트에 스펙에 없는 임의 로직이 추가되지 않았다
• 분기 조건이 스펙의 비즈니스 규칙과 일치한다
• API 호출 순서가 스펙의 API 요건과 일치한다

2.2 사용자 스토리와의 일치

• 사용자 스토리의 시작 조건이 플로우차트에 반영되어 있다
• 기대 결과(목표)가 플로우차트 종료 노드에 표현되어 있다

---

3. 가독성

3.1 노드 명명 규칙

노드 유형	명명 규칙	예시
사용자 액션	동사 + 목적어	"로그인 버튼 클릭"
시스템 처리	동사 + 결과	"토큰 발급"
분기 조건	조건문 형태	"토큰 유효한가?"
에러 상태	에러 + 설명	"인증 실패"
시작/종료	명사형	"시작", "완료", "종료"

3.2 복잡도 기준

기준	권장 값	초과 시 조치
노드 수	20개 이하	서브 플로우로 분리
분기 깊이	4단계 이하	조건 단순화 또는 분리
다이어그램 너비	7열 이하	방향 변경 또는 분리

3.3 시각적 기준

• 동일 레벨의 노드들이 정렬되어 있다
• 화살표가 교차하지 않는다 (불가피한 경우 최소화)
• 에러/예외 경로가 정상 경로와 시각적으로 구분된다 (점선 사용)
• subgraph로 역할이 구분된 경우 라벨이 명확하다

---

4. Mermaid 문법 검증

4.1 기본 문법 체크

flowchart TD
    %% 노드 유형 예시
    A([시작])           %% Stadium: 시작/종료
    B[처리 단계]         %% 직사각형: 처리
    C{조건 분기?}        %% 마름모: 분기
    D[(데이터베이스)]     %% 원통: DB
    E[[서브 루틴]]        %% 이중 직사각형: 서브 루틴

    %% 화살표 유형
    A --> B             %% 일반 화살표
    B -.-> C            %% 점선 화살표 (에러/예외)
    C -->|Yes| D
    C -->|No| E

4.2 자주 발생하는 오류

오류	원인	해결 방법
파싱 에러	노드명에 특수문자 포함	따옴표로 감싸기: ["노드명"]
화살표 미연결	노드 ID 오타	노드 ID 일치 여부 확인
마름모 문법 오류	중괄호 누락	{조건?} 형식 확인
subgraph 미닫힘	end 누락	subgraph 블록에 end 추가

4.3 검증 도구

• 온라인 검증: Mermaid Live Editor
• VSCode 플러그인: Mermaid Preview (Bierner)
• AI 검증: 02-ai-prompt-templates.md의 프롬프트 H 활용

---

5. 검증 프로세스

1단계: AI 생성
   └── 프롬프트 A~C 사용하여 초안 생성

2단계: 문법 검증
   └── Mermaid Live Editor에서 렌더링 확인

3단계: 구조 검증 (본 문서 1~2항 체크리스트)
   └── 필수 요소, 흐름 무결성, 스펙 일치 확인

4단계: 가독성 검토
   └── 복잡도, 노드 명명, 시각적 기준 확인

5단계: 스테이크홀더 검토
   └── 기획자/개발자 최종 승인

6단계: Confluence 등록
   └── Mermaid 매크로 또는 이미지로 삽입

---

6. 검증 결과 기록

항목	결과	수정 사항	검토자
구조적 완전성	Pass/Fail
스펙 일치성	Pass/Fail
가독성	Pass/Fail
문법 검증	Pass/Fail