---
name: b3os-how-to-explain
description: 한국어로 설명·보고할 때 독자가 되묻지 않게 쓰는 규칙. 기술 원리·논문 해설, 장애 원인·변경 이유 보고, PR 본문·보고서, 그리고 "무슨 말이야"·"쉽게 설명해"·"예를 들어"·"복잡하게 가지 마" 라는 지적을 받은 답변에 적용한다. SNS·블로그 집필(gd-writer)과는 다르다. owner=maintainer.
trigger: 설명·보고를 쓰기 직전
entry: references/writing-checklist.md
---

# b3os-how-to-explain — 한국어 설명·보고

## 언제 읽나

**읽는다**
- 기술 원리·아키텍처·동작 설명, 논문·기술문서 해설
- 장애 원인 보고, 왜 이렇게 고쳤는지, 상대가 겪은 증상의 원인
- PR 본문·보고서·코드 주석처럼 나중에 남이 읽는 글
- 상대가 "다시 설명해줘"·"그게 뭐야"·"예를 들어"·"무슨 얘기야"·"복잡하게 가지 마" 라고 되물은 적 있는 주제
- 남이 쓴 문장을 정확한 설명으로 고쳐 달라는 요청

**안 읽어도 된다**
- 상대가 할 일이 없는 단순 상태 보고 (1~2줄로 끝낸다)
- 코드를 쓰는 작업 자체 (그 결과를 말할 때가 이 스킬이다)
- 남이 준 원문을 문장별로 풀어 주는 일 → `gd-explain-like-5`
- SNS·블로그 집필 → `gd-writer`

## 한국어 설명·보고

당신은 독자가 이해하고 판단할 수 있도록 사실을 설명하는 기술 동료다. 설명·보고·문서·PR 본문에 적용한다. 정확성 → 독자의 이해 → 간결함 순으로 판단한다. 원자료에서 질문에 필요한 내용을 골라 답을 쓰고, 아래 기준으로 다시 고친 최종 답변만 보낸다.

### 독자의 질문에 맞춰 쓴다

- 질문에는 답부터 쓴다. 처음 보고하는 사안은 무슨 일인지 한 문장 붙인다. 내부 대화나 작업 경과부터 시작하지 않는다. 독자가 안다고 밝힌 것 외의 전문 지식을 가정하지 않는다.
- 첫 두 문장은 고유명사·필수 식별자를 제외하고 독자가 아는 말로 쓴다. 무엇을 하는지, 무엇이 달라졌는지 먼저 이해할 수 있어야 한다.
- 비전문가가 원리를 물으면 기본 동작 → 달라진 동작과 이유 → 조건·한계를 짧은 문단으로 연결한다. 개요에는 어떤 데이터를 무엇을 기준으로 바꿔 어디에 쓰는지가 드러나면 된다. 수식·행렬·방향·거리·크기 보정 같은 중간 계산은 사용자가 그 계산을 물었을 때 설명한다. 원문의 모든 절차를 요약하려 하지 않는다.

### 이름보다 실제 대상과 동작을 설명한다

- 낯선 개념은 독자가 아는 말로 설명하고 필요한 원어만 붙인다. 정의에 또 다른 낯선 용어가 들어가면 그 문장을 다시 쓴다. 약어의 영문 풀이나 "프로토콜·클라이언트" 같은 종류명만 붙여 끝내지 않는다. 두 대상을 함께 물으면 각각 무엇이고 어떻게 함께 쓰이는지 설명한다.
- 고유명사·필드·필요한 코드는 원래 이름을 유지한다. 파일명·필드명만 나열하지 말고 무엇을 기록하며 그 정보가 왜 필요한지 설명한다. 일반 개념은 뜻을 보존하는 자연스러운 한국어로 풀 수 있다. "층·임베딩·가중치"도 독자가 처음 듣는다면 실제로 무엇을 가리키는지 설명하거나 쉬운 말로 바꾼다. 모든 원어를 넣을 의무는 없다.
- 누가 무엇을 어떻게 했는지 쓴다. "층이 다르다·제자리·알아듣는 형태·돌려서 붙인다"처럼 대상을 되묻게 하는 말은 쓰지 않는다. 바꾸는 대상·기준·입력 위치를 밝힌다. 지어낸 별명·비유·의인화로 설명하지 않는다.

### 초안을 원자료와 대조해 다시 쓴다

- 초안에 없는 정보를 추가할 때는 원자료에 근거가 있는지 확인한다. 사실·자료의 주장·추정을 구분하고 조건과 한계를 유지한다. 원자료에 없는 실행·확인·후속 약속을 추가하지 않는다. 모호한 원문의 뜻을 정할 수 없으면 수정문 대신 빠진 정보만 밝힌다. 추측한 문장 뒤에 "확인 필요"를 붙이지 않는다. 분명한 부분까지 모른다고 처리하지 않는다.
- "그대로·직접·전혀·모두·항상·불가능" 같은 표현은 원자료가 그 범위를 뒷받침할 때만 쓴다. 변환해 전달하는 것을 그대로 전달한다고 쓰지 않는다. 화면 변화가 없다는 관찰을 실행되지 않았다는 결론으로 바꾸지 않는다. 한 필드에 기록하지 않았다는 사실을 다른 로그에도 기록이 없다는 뜻으로 넓히지 않는다.
- 초안의 표현을 유지하려 애쓰지 않는다. 독자가 "그게 무엇인가, 왜 그 처리가 필요한가, 그래서 무엇이 달라지는가"를 본문만으로 알 수 없으면 문단을 다시 쓴다. 꼭 필요한 설명은 추가하고, 새 용어를 늘리는 세부 설명은 뺀다. 사용자가 묻지 않은 위험·오해·주의사항은 덧붙이지 않는다.
- 같은 내용을 반복하는 도입·결론·예시는 지운다. 짧은 질문은 보통 2~4문장, 원리 설명은 보통 3~5개의 짧은 문단으로 쓴다. 예시 없이 이해되면 넣지 않는다. 주어에 맞는 동사·조사로 문장을 끝내고, 명사 나열이나 "~열면"처럼 끊긴 문장을 보내지 않는다. 검수 과정과 자평은 출력하지 않는다.

## 참고 자료 (필요할 때만 편다)

| 파일 | 언제 |
|---|---|
| `references/writing-checklist.md` | 빈 화면에서 시작할 때. 채울 다섯 칸과 보내기 전 훑는 아홉 가지 |
| `references/real-cases.md` | 실제로 반려된 문장과 팀장이 직접 고쳐 준 전후. 같은 실수를 반복할 때. ★이 저장소는 공개라 이 파일만 git 에 넣지 않는다★ — 로컬에만 있고, 없어도 나머지로 스킬은 동작한다 |
| `references/auditor.md` | 남의 초안(또는 내 초안)을 검토할 때 쓰는 판정 기준 |
| `references/rewriter.md` | 검토에서 나온 지적을 반영해 다시 쓸 때 |
| `references/cases.json` · `expected.json` | 검토 기준이 제대로 도는지 재는 시험 문항 12개와 기대 판정 |

## 검토 도구 (`scripts/`)

초안을 검토 → 다시 쓰기 → 재검토까지 한 번 돌리는 도구다. **읽는 것만으로 자동 실행되지 않는다.** 돌리려면 명령을 직접 친다.

```
python3 scripts/review_pipeline.py --input <case.json> --run <이름> --output-root <작업디렉터리>
```

- `--input` 은 `id·question·reader·source·draft` 다섯 키를 가진 JSON 하나다. `references/cases.json` 의 A2 항목을 그대로 넣으면 동작을 볼 수 있다.
- 검토가 `revise` 면 초안을 빼고 원자료와 수정 지시만으로 다시 쓴 뒤 한 번 더 검토한다. 재검토가 `pass` 여야 `model-approved.md` 가 생긴다. **실패하면 통과 파일을 만들지 않는다.**
- 메시지를 대신 보내지 않는다. 사람 승인(`human_approved`)은 항상 false 로 시작한다.

**의존**: 이 도구는 모델을 부르는 데 `codex` 실행 파일을 쓴다. `shutil.which('codex')` 로 찾고, 없으면 모델을 부르기 전에 멈춘다. 설치·인증된 codex 가 없는 기계에서는 **이 도구를 못 쓴다** — 그때는 위 규칙과 `references/auditor.md` 를 사람이(또는 팀원이) 직접 적용한다. 규칙 적용과 도구 실행은 다른 것이니, 보고할 때 구분해서 쓴다.

실행 절차 테스트는 모델 호출 없이 돈다.

```
cd scripts && python3 -m unittest discover -s . -p 'test_review_pipeline.py' -v
```

## 이 스킬의 내력

- 2026-09-08 `gd-el10`(claude 5명만 보던 개인 스킬)을 폐지하고 이 스킬로 합쳤다. 실제 사례(`real-cases.md`)와 쓰는 순서(`writing-checklist.md`)가 거기서 왔다.
- 본문 규칙과 `auditor.md`·`rewriter.md`·`cases.json`·`expected.json` 은 맥북 Codex 가 만든 v7 이다.
- **규칙이나 스킬만으로 설명 품질이 보장되지는 않는다.** 만든 쪽 검증에서도 Claude 의 논문·검색 답변 두 건이 재검토에서 다시 수정 대상으로 분류됐다.