explain

Explain (Learning Harness)

코드를 읽고 3가지 모드로 설명합니다:

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

입력 판단

1. 파일 단위 (상세 설명)

@file 경로가 제공된 경우. 해당 파일의 핵심 로직을 설명.

/explain @src/auth/login.ts

2. 기능 단위

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

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

기능 단위인 경우 현재 CLI가 네이티브 위임을 제공하면 읽기 전용 탐색 역할에 관련 파일과 호출 흐름 조사를 맡깁니다. 이 역할은 파일을 수정하지 않고 근거 경로와 핵심 흐름만 반환합니다. 특정 에이전트 이름이나 spawn 인자 형식을 요구하지 않습니다. 위임 기능이 없거나 실패하면 메인 컨텍스트에서 rg/Read로 같은 탐색을 순차 수행합니다. 설명 작성과 최종 근거 확인은 메인 컨텍스트가 담당합니다.

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를 참조.

설명 프로세스

1. 코드 분석

파일 단위: 대상 파일을 읽고 구조 파악. 기능 단위: 읽기 전용 탐색 역할 또는 메인 컨텍스트 순차 탐색으로 관련 파일 확인 → 핵심 파일들을 읽고 흐름 파악.

2. 3단계 설명 작성

A. 한 줄 요약

이 코드가 하는 일을 한 문장으로.

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

B. 실제 비유

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

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

비유 작성 규칙:

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

C. 왜 필요한가

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

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

3. Mermaid 다이어그램

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

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