---
name: e2e-sequence
description: 기능별 E2E 메시지 흐름을 분석하여 Mermaid 시퀀스 다이어그램(.md) 생성
argument-hint: "[기능명]"
---

# E2E Sequence Diagram Generator

사용자가 기능명을 지정하면 해당 기능의 코드를 직접 추적하여 E2E Mermaid 시퀀스 다이어그램을 생성한다.

## 사용법

```
/e2e-sequence 로그인
/e2e-sequence 주문생성
/e2e-sequence 헬스체크
```

## 아키텍처: 2단계 파이프라인

이 스킬은 **2단계 파이프라인**으로 동작한다. 코드 탐색과 다이어그램 생성을 분리하여 각 단계가 자신의 책임에만 집중한다.

```
Phase 1: 코드 추적 에이전트 (Explore)  →  구조화된 분석 결과 (중간 산출물)
                                              ↓
Phase 2: 메인 에이전트 (직접 수행)     →  Mermaid 다이어그램 + 최종 문서
```

**분리 이유**: 코드 탐색으로 컨텍스트가 채워진 상태에서 다이어그램 규칙(participant 통합, alt/deactivate, 외부 시스템 부재 표기 등)을 정확히 따르기 어렵다. Phase 1이 코드 사실만 수집하고, Phase 2가 규칙에만 집중하면 품질이 향상된다.

---

## Phase 1: 코드 추적 (Explore 에이전트에 위임)

Agent 도구로 **Explore 에이전트**를 호출하여 코드 추적을 위임한다.

### 에이전트 호출 방법

```
Agent(
  subagent_type: "Explore",
  model: "sonnet",
  description: "{기능명} 코드 추적",
  prompt: 아래 프롬프트 템플릿 사용
)
```

### 에이전트 프롬프트 템플릿

아래 내용을 Explore 에이전트에 전달한다. `{기능명}`을 실제 기능명으로 치환한다.

````
# 임무: "{기능명}" 기능의 E2E 코드 추적

프로젝트의 "{기능명}" 기능에 대해 코드를 직접 추적하여 아래 형식의 분석 결과를 출력하라.
**코드를 직접 Read하여 분석하며, 추측하지 않는다.**

## 사전 준비

1. `CLAUDE.md`가 있으면 읽어서 아키텍처, 서비스 목록, 기술 스택, API 엔드포인트를 파악한다.
2. 프로젝트 루트의 디렉토리 구조를 확인하여 레이어 구분을 식별한다.

## 진입점 판별

1. 기능 키워드로 전체 코드베이스를 검색한다 (테스트 제외).
2. 검색 결과에서 **호출 체인의 최상위**를 진입점으로 식별한다.
   - UI 코드가 있으면 반드시 UI부터 추적한다. Controller만 보고 끝내지 않는다.
   - 시작점 유형: UI/클라이언트, API Controller, 백그라운드 서비스, 메시지 구독, 이벤트 핸들러

## 호출 체인 순방향 추적

진입점에서 시작하여 호출 순서대로 레이어를 따라간다.
- 인터페이스를 Grep으로 찾아 구현체를 확인한다.
- 구현체를 Read하여 내부 로직과 다음 호출 대상을 파악한다.
- 외부 시스템 경계(HTTP, DB, 메시지 큐, WebSocket 등)에 도달할 때까지 반복한다.
- 외부 시스템 호출이 있으면 수신 측 코드도 추적한다.

## 출력 형식 (반드시 이 형식을 따른다)

```markdown
## 분석 결과: {기능명}

### 진입점
- 시작점 유형: {UI/API/Background/Message}
- 파일: {경로}
- 메서드: {이름}

### 호출 체인
| 순서 | 서비스/프로세스 | 클래스.메서드 | 역할 설명 |
|------|---------------|-------------|----------|
| 1 | {서비스명} | {클래스.메서드} | {역할} |
| 2 | ... | ... | ... |

### 서비스 간 통신
| From | To | 프로토콜 | 엔드포인트/경로 | Request 타입 | Response 타입 |
|------|----|---------|---------------|-------------|--------------|

### 외부 시스템
| 시스템 | 사용 여부 | 구현체/위치 | 비고 |
|--------|----------|-----------|------|
| DB (Oracle/SQL 등) | O/X | {구현체} | {비고} |
| 메시지 큐 (RabbitMQ 등) | O/X | {구현체} | {비고} |
| WebSocket | O/X | {구현체} | {비고} |
| 캐시 (Redis 등) | O/X | {구현체} | {비고} |
| 외부 HTTP 호출 | O/X | {구현체} | {비고} |

- 사용하지 않는 시스템도 X로 명시한다.
- 인메모리 자료구조(ConcurrentDictionary, Registry 등)로 대체되는 경우 비고에 명시한다.

### 메시지 타입
| 타입 | 클래스명 | 주요 필드 |
|------|----------|-----------|
| Request | {클래스명} | {필드 목록} |
| Response | {클래스명} | {필드 목록} |

### 조건 분기
| 조건 | 성공 경로 | 실패 경로 |
|------|----------|----------|

### 내부 처리 단계 (서비스별)
#### {서비스명}
1. {처리 단계 설명} (클래스: {클래스명})
2. ...

### 소스 파일 목록
#### {레이어/서비스}
- {파일 경로}
```

중요: Mermaid 문법을 출력하지 않는다. 코드 사실만 정확히 수집하여 위 형식으로 출력한다.
````

---

## Phase 2: 다이어그램 및 문서 생성 (메인 에이전트가 직접 수행)

Phase 1의 **구조화된 분석 결과**를 입력으로 받아 Mermaid 다이어그램과 최종 문서를 생성한다.

**핵심 원칙**: 이 단계에서는 코드를 Read하지 않는다. Phase 1의 분석 결과만을 기반으로 아래 규칙에 집중한다.

### 다이어그램 생성 규칙

#### 참여자 (Participants)

**해당 기능에 관여하는 컴포넌트만 포함한다.** 고정 목록 없이 Phase 1 분석 결과에서 도출한다.

참여자 도출 기준:
- **participant = 독립 프로세스 또는 서비스** (네트워크/IPC 경계가 있는 단위)
- 같은 프로세스 내 레이어(ViewModel, UseCase, Service, Adapter 등)는 **하나의 participant로 통합**한다
  - 내부 레이어 간 호출은 `Note over`로 표현한다
  - 예: WPF 클라이언트의 ViewModel → UseCase → HttpAdapter는 모두 "Client" 하나로 통합
- 외부 시스템(DB, 메시지 큐 등) → 별도 participant
- E2E 다이어그램의 목적은 **서비스 간 통신 흐름**을 보여주는 것이며, 한 프로세스 내부의 클래스 호출 관계는 범위 밖이다

#### 메시지 표현 규칙

| 유형 | Mermaid 문법 | 용도 |
|------|-------------|------|
| 요청 | `->>` (실선 화살표) | 컴포넌트 간 요청 전송 |
| 응답 | `-->>` (점선 화살표) | 요청에 대한 응답 |
| 내부 로직 | `Note over X` | 서비스 내부 처리 단계 설명 |
| 활성 구간 | `activate` / `deactivate` | 서비스가 처리 중인 구간 |
| 조건 분기 | `alt` / `else` / `end` | 성공/실패 경로 구분 |

#### activate/deactivate와 alt/else 병용 규칙

Mermaid는 `alt`/`else`를 실제 조건 분기가 아닌 **순차적으로 파싱**한다. 따라서 `alt` 분기와 `else` 분기 양쪽에서 같은 참여자를 `deactivate`하면 "Trying to inactivate an inactive participant" 오류가 발생한다.

**규칙:**
- `alt`/`else` 블록 **내부**에서는 `deactivate`를 사용하지 않는다
- `deactivate`는 `alt`/`else`/`end` 블록 **바깥**(이후)에서 수행하거나, `else`(정상 흐름) 분기 끝에서만 한 번 수행한다
- 응답 화살표(`-->>`)는 `alt`/`else` 내부에서 자유롭게 사용 가능하다

**잘못된 예시 (오류 발생):**
```
activate M
alt 실패
    M-->>GW: 401
    deactivate M    ← M 비활성화
else 성공
    M-->>GW: 200
    deactivate M    ← 오류! M은 이미 비활성
end
```

**올바른 예시:**
```
activate M
alt 실패
    M-->>GW: 401
else 성공
    M-->>GW: 200
    deactivate M    ← else 끝에서만 비활성화
end
```

#### 내부 로직 상세화 규칙

서비스 내부에서 수행하는 로직을 **번호 매기기**로 명시한다:

```
Note over M: 1. 요청 유효성 검증<br/>(UserId, Password null 체크)
Note over M: 2. 결과 판단<br/>(SUCCESS/FAIL)
```

- 각 단계는 Phase 1 분석 결과에서 확인된 로직만 기술한다
- 한국어로 설명한다
- `<br/>`로 줄바꿈하여 부가 설명을 추가한다

#### 메시지 레이블 규칙

- 컴포넌트 간 메시지에는 **프로토콜 정보**를 포함한다
  - HTTP: `POST /api/v1/auth/login (LoginRequest)`
  - WebSocket: `ws://host/path (메시지 타입)`
  - 메시지 큐: `publish/subscribe (큐/토픽명)`
  - 메서드 호출: `클래스.메서드명()`
- 요청/응답 DTO 이름을 괄호로 표기한다

### 출력 형식

아래 템플릿에 맞춰 Markdown 파일을 생성한다:

````markdown
# {기능명} E2E 시퀀스 다이어그램

## 개요
{기능에 대한 1-2줄 설명}

## 관련 엔드포인트

| Method | Route | Service | 설명 |
|--------|-------|---------|------|
| {METHOD} | {route} | {서비스명} | {설명} |

## 시퀀스 다이어그램

```mermaid
sequenceDiagram
    participant ...
    ...시퀀스 흐름...
```

## 주요 처리 로직

| 단계 | 서비스 | 클래스 | 설명 |
|------|--------|--------|------|
| 1 | {서비스명} | {클래스명} | {처리 내용} |

## 외부 시스템 의존성

| 시스템 | 사용 여부 | 비고 |
|--------|----------|------|
| DB (Oracle/SQL 등) | {O / X} | {사용 시: 테이블명·쿼리 유형 / 미사용 시: 대체 수단 (예: 인메모리 Registry)} |
| 메시지 큐 (RabbitMQ 등) | {O / X} | {사용 시: 큐·토픽명 / 미사용 시: 해당 없음} |
| WebSocket | {O / X} | {사용 시: 엔드포인트 / 미사용 시: 해당 없음} |
| 캐시 (Redis 등) | {O / X} | {사용 시: 키 패턴 / 미사용 시: 해당 없음} |
| 외부 HTTP 호출 | {O / X} | {사용 시: 대상 서비스·엔드포인트 / 미사용 시: 해당 없음} |

- **모든 항목을 빠짐없이 기재**한다. 사용하지 않는 시스템도 X로 명시하여 부재를 가시화한다.
- 인메모리 자료구조(ConcurrentDictionary, Registry 등)로 대체되는 경우 비고에 명시한다.

## 관련 메시지 타입

| 타입 | 클래스명 | 주요 필드 |
|------|----------|-----------|
| Request | {클래스명} | {필드 목록} |
| Response | {클래스명} | {필드 목록} |

## 특이 사항

{코드 추적 중 발견한 주목할 만한 설계 특성, Best-effort 처리, 역호출 패턴 등}

## 분석 소스 파일

{레이어별로 그룹핑하여 나열}
````

### 출력 경로

- **저장 위치**: `Docs/E2E-Sequence/{기능명}_Sequence.md`
- 기능명은 한국어 또는 영문 모두 가능 (사용자 지정 따름)

### Mermaid 검증

다이어그램 생성 후 MCP Mermaid Chart 도구로 렌더링 유효성을 검증한다:

1. `mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram` 호출
2. 문법 오류 시 수정 후 재검증
3. MCP 도구 오류 시 Mermaid 문법을 수동 점검하고 파일 생성 진행

---

## Quick Reference

| 항목 | 규칙 |
|------|------|
| 아키텍처 | 2단계 파이프라인 (코드 추적 → 문서 생성) |
| Phase 1 | Explore 에이전트에 위임, 코드 사실만 수집, Mermaid 문법 불필요 |
| Phase 2 | 메인 에이전트가 직접 수행, 코드 Read 없이 규칙에 집중 |
| 분석 방식 | 코드 직접 Read (Phase 1), 추측 금지 |
| 진입점 판별 | 전체 검색 후 호출 체인 최상위 식별 (Controller 고정 아님) |
| 추적 방향 | 진입점 → 순방향으로 호출 체인 따라감 |
| 참여자 | 독립 프로세스 단위로 통합, 고정 목록 없음 |
| 내부 로직 | 검증/조회/판단/생성/등록 단계 번호 매기기 |
| alt/deactivate | alt/else 내부에서 deactivate 금지, else 끝 또는 블록 바깥에서만 |
| 외부 시스템 | 모든 항목 기재, 미사용도 X로 명시, 인메모리 대체 시 비고 |
| 설명 언어 | 한국어 |
| 메시지 레이블 | 프로토콜 정보 + DTO명 |
| 저장 경로 | `Docs/E2E-Sequence/{기능명}_Sequence.md` |
| 검증 | Mermaid MCP 도구로 렌더링 테스트 |