Explain

---
name: explain
description: 'Use to explain concepts, code, plans, decisions, findings, or outcomes in the reader''s terms: "설명해줘", "쉽게 설명해줘", "어떤 근거야", "왜 이렇게 했어", "모르겠다", "explain how this works".'
---

# Explain

읽는 사람이 **무엇인지, 왜 그런지, 자신에게 어떤 의미인지** 이해하도록 설명한다.
개념·코드·계획·의사결정·조사 결과·진행 상황·완료 보고에 사용한다. IssueOps 사이클이나
특정 도구가 없어도 적용한다. 설명 요청만으로 구현·설정 변경·원격 게시를 시작하지 않는다.

## 설명할 질문과 독자를 먼저 정한다

사용자가 실제로 묻는 질문에 먼저 답한다. 대화에서 알 수 있는 배경은 활용하고,
이해 수준이나 대상이 답을 크게 바꾸는데 알아낼 수 없을 때만 짧게 묻는다.

| 요청 | 설명의 중심 |
|---|---|
| 개념·원리 | 무엇인지, 어떻게 작동하는지, 구체적인 예 |
| 코드·동작 | 입력, 처리 과정, 결과, 중요한 예외 |
| 계획·설계 | 해결할 문제, 선택한 방식, 선택 근거, 대안과 비용, 검증 방법 |
| 판단 근거 | 관찰한 사실, 그 사실에서 결론으로 이어지는 이유, 한계 |
| 작업 보고 | 바뀐 결과, 확인한 내용, 현재 상태, 남은 일 |

일반 독자에게는 익숙한 말부터 쓴다. 기술 독자나 내부 구조를 묻는 질문에는 필요한
용어·코드·경로를 유지하고 뜻을 연결해 설명한다. 쉽게 설명한다는 이유로 사용자가
요청한 근거나 동작 원리를 지우지 않는다.

## 설명을 구성하는 방법

1. **핵심 답부터 쓴다.** 개념이면 정의나 원리, 계획이면 접근 방식, 작업 보고면 결과를
   첫 문장에 둔다. 설명하겠다는 서론이나 수행 순서 나열로 시작하지 않는다.
2. **이유가 이어지게 쓴다.** 주장 뒤에 관찰·근거를 붙이고, 그 근거가 왜 결론을 뒷받침하는지
   설명한다. 계획은 해결하려는 문제 → 방법 → 기대 효과 → 확인 방법으로 연결한다.
3. **구체적인 예를 든다.** 실제 문제가 있으면 관찰한 증상이나 입력·출력을 보여준다.
   개념 설명에는 가상의 예를 써도 되지만 예시임을 밝힌다. 비유는 대응 관계와 한계를
   설명하고 실제 동작의 근거로 쓰지 않는다.
4. **사실과 기대를 구분한다.** 구현한 것, 테스트로 확인한 것, 예상하는 효과를 나눠 쓴다.
   테스트 통과를 실제 성능 향상이나 결함 발견률 향상의 증거로 바꾸지 않는다.
5. **중요한 조건과 한계를 남긴다.** 결론이나 사용자의 판단이 달라지는 조건은 본문에
   적는다. 개수를 제한해 중요한 위험을 숨기지 않는다. 부차적인 세부만 링크로 보낸다.
6. **필요할 때 다음 행동을 적는다.** 작업 보고에서는 완료·미완료와 사용자가 할 일을
   구분한다. 순수한 개념 질문에 불필요한 실행 계획이나 승인 질문을 붙이지 않는다.

짧은 질문에는 짧은 연결된 문장으로 답한다. 여러 대안을 비교하면 표, 병렬 항목이면
목록을 사용한다. 고정된 제목·순서·분량을 모든 답변에 강제하지 않는다. 자세한 설명을
요청받았다면 핵심 근거를 링크로만 돌리지 말고 본문에서 설명한다.

## 근거를 확인한다

대상에 맞는 원본을 읽는다. 도구로 확인할 수 있는 사실은 확인한 뒤 설명하고,
자료가 부족해 결론을 낼 수 없으면 빠진 자료와 확인한 범위를 구체적으로 적는다.
제공된 자료만으로 답할 수 있으면 불필요하게 다른 도구를 호출하지 않는다.

| 설명 대상 | 우선 확인할 근거 |
|---|---|
| 코드·현재 동작 | 소스, 설정, 실제 입력·출력, 관련 테스트 |
| 계획·선택 이유 | 사용자 요구, 계획서, 제약, 대안 비교, 관련 코드 |
| 오류·조사 결과 | 재현 조건, 로그, 원인으로 이어지는 호출 경로 |
| 작업 상태 | 실제 변경, 검증 결과, 게시·배포 상태 |
| 개념·외부 사실 | 제공된 자료, 필요한 경우 공식 문서나 1차 자료 |

수치·인용·링크·완료 여부를 만들어 내지 않는다. 중요한 주장 가까이에 근거를 연결한다.
수치는 판단이나 이해에 도움이 될 때 쓴다. 테스트·커밋·리뷰 횟수만 나열해 결과를 대신하지 않는다.
측정이 없으면 예상이라고 밝히고, 무엇을 비교해야 효과를 입증할 수 있는지 설명한다.

### IssueOps 사이클을 설명할 때

해당 사이클 ID가 있으면 현재 기록을 확인한다. 일반적인 설명에는 이 명령이나
IssueOps 설치를 요구하지 않는다. ID를 추측하거나 설명을 위해 새 사이클을 만들지 않는다.

```bash
issueops status --id "$ISSUEOPS_ID" --json
issueops next --id "$ISSUEOPS_ID" --json
```

사용자 요구·실제 변경·검증 결과·설정·원격 링크와 기록을 대조한다. 내부 단계 이름을
그대로 나열하기보다 “구현은 끝났고 테스트 중입니다”처럼 독자에게 필요한 상태로 풀어 쓴다.
사용자가 단계나 내부 구조 자체를 물으면 정확한 용어를 설명한다.

설명 작성은 원격 쓰기 권한을 부여하지 않는다. 이슈·PR/MR 게시 요청에는 해당 저장소의
게시 절차를 함께 따르고, 그 문서의 독자와 형식에 맞춰 설명한다.

## 되물어 오면

“뭔 소린지 모르겠다”는 질문에는 같은 문장을 줄여 반복하지 않는다. 낯선 용어를 풀고,
빠진 인과관계를 채우거나 구체적인 입력·출력 예로 다시 설명한다.
특정 문장을 물으면 그 부분에 집중한다. “왜?”에는 근거를, “어떻게?”에는 작동 과정을,
“무엇이 달라졌나?”에는 전후 차이를 답한다.

예를 들어 “검증을 병렬화해 효율을 높였습니다”를 되물으면:
“서로 영향을 주지 않는 테스트와 코드 검토를 동시에 진행하도록 바꿨습니다.
최종 통과는 둘 다 끝나야 결정합니다. 실제로 얼마나 빨라지는지는 같은 작업으로
변경 전후 시간을 비교해야 합니다.”

## 최종 확인

- 첫 문장이 사용자의 질문에 답하는가?
- 독자가 결론에 도달할 수 있도록 원인·근거·결과가 연결돼 있는가?
- 실제 관찰, 추론, 가상의 예, 기대 효과를 혼동하지 않았는가?
- 판단을 바꾸는 한계나 미완료 작업을 빠뜨리지 않았는가?
- 설명에 불필요한 내부 용어·수량·고정 형식을 덜어 냈는가?
- 한국어 설명은 `fluent-korean` 지침에 맞게 다듬었는가?