explainlisted

# Explain (Learning Harness) 코드를 읽고 3가지 모드로 설명합니다: - **파일/기능 모드**: 비유 + 3단계 설명 + Mermaid 다이어그램 (이게 무엇인지) - **줌아웃 모드**: 호출자/형제 모듈/상위 맵 (이게 어디에 속하는지) ## 입력 판단 ### 1. 파일 단위 (상세 설명) `@file` 경로가 제공된 경우. 해당 파일의 핵심 로직을 설명. ``` /explain @src/auth/login.ts ``` ### 2. 기능 단위 텍스트로 기능명이 제공된 경우. 코드베이스를 탐색하여 관련 파일들을 찾고 흐름을 설명. ``` /explain "로그인 기능" /explain "결제 흐름" ``` 기능 단위인 경우 현재 CLI의 background subagent/worker가 있으면 관련 파일을 먼저 탐색하게 하고, 없으면 메인 컨텍스트에서 `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](zoom-out.md)를 참조. ## 설명 프로세스 ### 1. 코드 분석 파일 단위: 대상 파일을 읽고 구조 파악. 기능 단위: Explore 서브에이전트로 관련 파일 탐색 → 핵심 파일들을 읽고 흐름 파악. ### 2. 3단계 설명 작성 #### A. 한 줄 요약 이 코드가 하는 일을 한 문장으로. ```markdown ## 한 줄 요약 이 파일은 사용자 인증 토큰을 발급하고 갱신하는 서비스입니다. ``` #### B. 실제 비유 비개발자도 이해할 수 있는 현실 세계 비유로 설명. ```markdown ## 비유로 이해하기 호텔 체크인 데스크와 같습니다: - **로그인** = 신분증(ID/PW)을 보여주고 룸키(토큰)를 받는 것 - **토큰 갱신** = 룸키 유효기간이 지나서 프론트에서 새 키를 받는 것 - **로그아웃** = 체크아웃하면서 룸키를 반납하는 것 ``` 비유 작성 규칙: - 일상에서 누구나 아는 상황 사용 (호텔, 도서관, 우체