explain git:20260428.672e0cdA

Immutable. This exact content is served forever at /api/v1/blob/b635d8f363caed7b.

---
name: explain
description: 코드를 비유 기반으로 설명하고 Mermaid 다이어그램을 생성합니다. 파일/기능/줌아웃 3가지 모드 지원. /explain @file.ts (상세 설명), /explain "로그인 기능" (기능 단위), /explain --zoom-out @file.ts (한 단계 위 맵).
---

# Explain (Learning Harness)

코드를 읽고 3가지 모드로 설명합니다:
- **파일/기능 모드**: 비유 + 3단계 설명 + Mermaid 다이어그램 (이게 무엇인지)
- **줌아웃 모드**: 호출자/형제 모듈/상위 맵 (이게 어디에 속하는지)

## 입력 판단

### 1. 파일 단위 (상세 설명)
`@file` 경로가 제공된 경우. 해당 파일의 핵심 로직을 설명.

```
/explain @src/auth/login.ts
```

### 2. 기능 단위
텍스트로 기능명이 제공된 경우. 코드베이스를 탐색하여 관련 파일들을 찾고 흐름을 설명.

```
/explain "로그인 기능"
/explain "결제 흐름"
```

기능 단위인 경우 Task(subagent_type="Explore")로 관련 파일을 먼저 탐색.

### 3. 줌아웃 모드 (Zoom-out)
"이게 뭘 하는지"가 아니라 "이게 **어디에 속하는지**"가 궁금할 때.

```
/explain --zoom-out @src/auth/middleware.ts
/explain --map @src/auth/middleware.ts
/explain @src/auth/middleware.ts 줌아웃
```

**트리거 표현**: "줌아웃", "한 단계 위", "전체 구조에서 어디", "위에서 보여줘", "맵", "zoom out", "broader context".

**출력**: 비유 X, 상세 설명 X. 다음 4가지만:
1. **호출자(Callers)** — 이 모듈을 부르는 곳 (Grep으로 import/usage 찾기)
2. **형제(Siblings)** — 같은 디렉토리/모듈의 다른 파일들과 각자의 역할
3. **상위 맵** — 한 단계 위(부모 디렉토리 또는 기능 묶음) 구조
4. **추천 다음 행동** — "이 코드를 이해하려면 X부터 읽으세요"

자세한 줌아웃 모드 워크플로우는 [zoom-out.md](zoom-out.md)를 참조.

## 설명 프로세스

### 1. 코드 분석

파일 단위: 대상 파일을 읽고 구조 파악.
기능 단위: Explore 서브에이전트로 관련 파일 탐색 → 핵심 파일들을 읽고 흐름 파악.

### 2. 3단계 설명 작성

#### A. 한 줄 요약
이 코드가 하는 일을 한 문장으로.

```markdown
## 한 줄 요약
이 파일은 사용자 인증 토큰을 발급하고 갱신하는 서비스입니다.
```

#### B. 실제 비유
비개발자도 이해할 수 있는 현실 세계 비유로 설명.

```markdown
## 비유로 이해하기
호텔 체크인 데스크와 같습니다:
- **로그인** = 신분증(ID/PW)을 보여주고 룸키(토큰)를 받는 것
- **토큰 갱신** = 룸키 유효기간이 지나서 프론트에서 새 키를 받는 것
- **로그아웃** = 체크아웃하면서 룸키를 반납하는 것
```

비유 작성 규칙:
- 일상에서 누구나 아는 상황 사용 (호텔, 도서관, 우체국 등)
- 코드의 각 핵심 요소를 비유의 요소에 1:1 매핑
- 비유가 깨지는 부분이 있으면 솔직히 "여기서 비유는 한계가 있습니다" 명시

#### C. 왜 필요한가
이 코드가 시스템에서 어떤 역할을 하는지, 없으면 어떤 문제가 생기는지.

```markdown
## 왜 필요한가
- 인증 없이는 누구나 다른 사용자의 데이터에 접근 가능
- 토큰 갱신 없으면 사용자가 매번 로그인해야 함
- 이 서비스가 모든 API 요청의 관문 역할
```

### 3. Mermaid 다이어그램

코드의 핵심 흐름을 Mermaid 다이어그램으로 시각화.

파일 단위: 주요 함수 간 호출 흐름 또는 상태 변화.
기능 단위: 파일/모듈 간 데이터 흐름.

적절한 다이어그램 타입 선택:
- **흐름도 (flowchart)**: 의사결정, 분기 로직
- **시퀀스 (sequence)**: API 호출, 요청-응답 흐름
- **상태도 (stateDiagram)**: 상태 변화 (주문 상태, 인증 상태 등)
- **클래스 (classDiagram)**: 객체 관계, 의존성

```markdown
## 흐름도

```mermaid
sequenceDiagram
    participant U as 사용자
    participant C as AuthController
    participant S as AuthService
    participant D as DB

    U->>C: POST /login (id, pw)
    C->>S: authenticate(id, pw)
    S->>D: findUser(id)
    D-->>S: User
    S-->>C: JWT Token
    C-->>U: 200 OK + Token
`` `
```

### 4. 출력

대상 파일과 같은 디렉토리에 `EXPLANATION.md`로 저장.
기능 단위인 경우 프로젝트 루트에 `EXPLANATION-{기능명}.md`로 저장.

```markdown
# {대상} 설명

> 생성일: {날짜}
> 대상: {파일 경로 또는 기능명}

## 한 줄 요약
...

## 비유로 이해하기
...

## 왜 필요한가
...

## 흐름도
...

## 관련 파일
- `src/auth/login.ts` — 로그인 엔드포인트
- `src/auth/token.ts` — 토큰 발급/갱신
- ...
```

## 제약사항

### 공통
- 설명은 한국어로 작성
- 다이어그램은 핵심 흐름만 (모든 함수를 다 그리지 않음)
- 핵심 흐름 중심으로 간결하게 유지

### 파일/기능 모드 전용
- 비유는 반드시 일상 사물/상황 사용 (기술 용어로 비유 금지)
- 비유의 한계가 있으면 솔직히 명시

### 줌아웃 모드 전용
- 비유 X, 상세 설명 X (구조와 관계만)
- 호출자/형제는 각각 5개 이하 (많으면 "총 N개 중 대표 5개"로 요약)
- 상위 맵은 현재 파일과 직접 관련된 것만 (전체 디렉토리 덤프 금지)
- 자세한 워크플로우는 [zoom-out.md](zoom-out.md) 참조