코드를 비유·다이어그램·단계별 설명·함정 포인트 네 가지로 구성해 설명한다.
$ARGUMENTS에 파일 경로나 함수명이 주어지면 해당 코드를 먼저 Read/Grep으로 읽는다.
주어지지 않으면 사용자가 붙여넣거나 언급한 코드를 대상으로 한다.
STEP 1 — 코드 파악
대상 코드를 읽고 아래를 정리한다.
- 이 코드가 무엇을 하는가 (한 줄 요약)
- 입력 → 처리 → 출력 흐름
- 외부 의존성 (함수 호출, 모듈, API 등)
- 복잡도가 높은 부분 (조건 분기, 재귀, 비동기 등)
STEP 2 — 비유로 시작
일상 생활 속 사물·상황에 빗대어 코드의 역할을 1~3문장으로 설명한다.
- 복잡할수록 비유를 여러 개 사용한다
- 추상적인 개념(캐시, 큐, 재귀 등)은 특히 비유가 효과적이다
- 예: “이 함수는 우체국 분류기와 같습니다. 편지(요청)가 들어오면 주소(조건)를 보고 해당 창구(핸들러)로 보냅니다.”
STEP 3 — 다이어그램
ASCII art로 코드의 흐름·구조·관계를 시각화한다.
상황별 추천 다이어그램 형태:
// 흐름도
[입력] → [검증] → [처리] → [출력]
↓
[에러 처리]
// 계층 구조
Router
├── /users → UserController
├── /posts → PostController
└── /auth → AuthController
// 상태 변화
[idle] --요청--> [loading] --성공--> [success]
└----실패-----> [error]
// 함수 호출 스택
main()
└── fetchData()
└── parseResponse()
└── validateSchema()
복잡도가 낮으면 간단한 한 줄 화살표로 충분하다. 과하게 그리지 않는다.
STEP 4 — 단계별 설명
코드를 논리적 블록 단위로 나눠 순서대로 설명한다.
- 각 블록: 무엇을 하는가 + 왜 이렇게 했는가
- 변수명·함수명은 코드 그대로 인용 (
`변수명`형식) - 기술 용어는 처음 등장 시 한 번 풀어서 설명
STEP 5 — 함정 포인트
이 코드에서 흔히 오해하거나 실수하기 쉬운 부분을 1~3개 짚는다.
- 예: “여기서
===와==의 차이를 모르면 예상치 못한 버그가 생깁니다” - 예: “이 함수는 비동기라서 결과를 바로 쓰면
undefined가 나옵니다” - 없으면 생략해도 된다
출력 형식
## 한 줄 요약
{코드가 하는 일}
## 비유
{일상 비유 1~3문장}
## 흐름 다이어그램
{ASCII art}
## 단계별 설명
**1단계 — {블록 설명}**
{설명}
**2단계 — {블록 설명}**
{설명}
...
## 함정 포인트
- {주의사항 1}
- {주의사항 2}
설명은 대화체로 작성한다. 딱딱한 기술 문서 말투보다 “이 부분은 ~입니다”, “여기서 ~를 주의하세요” 같은 자연스러운 어투를 사용한다.