genetics-mcp 2.0.0

package/skills/genetics-report/references/textbook-mode.md

@@ -0,0 +1,111 @@
+# 교과서 모드 — 가르치는 문서의 공식
+
+기술문서·인수인계·사후분석처럼 **독자가 배워야 하는** 문서의 구조 사양이다.
+검수 보고서(독자가 판정하는 문서)와는 뼈대가 다르다 — 같은 빌더, 다른 서사.
+
+## 0. 이 모드가 생긴 사건 (왜 공식이 필요한가)
+
+어느 기술보고서(2026-08-14)에서
+검수 보고서 뼈대(요약→판정표→건별 카드→확인 요청)에 타이포·여백·색만 갈아입힌 판을 냈다가
+반려됐다. 지적은 정확히 심슨의 역설이었다: **부분(활자·색·여백)마다 좋아졌는데 전체(문서가
+읽히는 방식)는 그대로였다.**
+
+> 베스트셀러 교과서는 같은 내용을 더 예쁘게 실어서 팔리는 게 아니다.
+> **가르치는 구조 자체가 다르다.** 구조가 제품이다.
+
+그러므로 이 모드에서 스타일 작업은 마지막이다. 먼저 물을 것: **이 문서는 무엇을 어떤
+순서로 가르치는가.** 그 답이 절 구성이 된다.
+
+## 1. 모드 판별 — 독자가 누구인가 (SKILL.md 0단계의 연장)
+
+| 독자의 일 | 모드 | 뼈대 |
+|---|---|---|
+| 판정한다 (검수·회신·결재) | 검수 보고서 | 요약 → 등급·판정표 → 건별 카드 → 확인 요청 |
+| 배운다 (유지보수·인수·온보딩) | **교과서** | 학습목표 → 원리 → 붕괴 → 처방 → 적용 → 연습 → 부록 대장 |
+
+트리거: 기술보고서, 인수인계, 온보딩 문서, 사후분석(포스트모템), "다음 사람이 읽고
+이해해야", "왜 이렇게 됐는지 설명하는 문서".
+
+## 2. 서사 공식 — 7단계 장 구성
+
+의존 순서로 가르친다. **각 장은 앞 장 없이는 성립하지 않아야 한다** — 그래야 스크롤이
+학습 곡선이 된다. 병렬 나열(어디서 읽어도 같은 문서)이 되는 순간 이 모드가 아니다.
+
+| 장 | 역할 | 규칙 |
+|---|---|---|
+| 01 학습목표 | "다 읽고 나면 할 수 있는 것" 2~4개 | **문서의 성패 기준**이라고 명시한다. recap 블록으로 |
+| 02 원리 | 시스템이 성립하는 핵심 명제 하나 | 개념 박스 하나로 압축될 것. 안 되면 아직 원리를 못 찾은 것 |
+| 03 붕괴 | 그 원리가 깨지는(깨졌던) 구조 | **실제 사건을 예제 풀이로.** 단계마다 "왜"를 단다 |
+| 04 처방 | 붕괴를 구조적으로 불가능하게 만든 결정 | "더 좋은 검사"가 아니라 "그 부류가 존재할 수 없게" 프레임 |
+| 05·06 적용 | 원리가 실제 작업에 적용된 사례들 | 각 적용이 02~04 를 콜백해야 한다. 독립 사례면 부록감이다 |
+| 07 연습 | 수정·운영 전 스스로 답할 물음 | 아래 4절 형식 |
+| 08+ 부록 대장 | 사실 원장 (문제·원인·구현·재현 명령) | 본문에서 뺀 건별 데이터가 전부 여기 산다 |
+
+**본문/대장 분리 원칙**: 본문은 가르치고, 대장은 참조를 받친다. 본문이 대장을 `§8.1`
+로 가리키면 재호출 팝오버(data-recall)가 그 자리에서 제목·등급을 되살린다 — 독자가
+본문 흐름을 잃지 않고 근거를 확인한다. 건별 카드를 본문에 두면 병렬 나열로 되돌아간다.
+
+**장 내부 리듬**: 도입 스트립(lede, "이 절에서") → 본문 → **정리(recap, 요점 3개 안팎)**.
+정리 박스가 장마다 누적되며 그 자체로 커리큘럼 요약이 된다. 리듬은 깨지 않는다 —
+독자가 장치 문법을 한 번 배우면 끝까지 통해야 한다(신호 이론).
+
+## 3. 장치 문법 — `kind:"lesson"` 블록 스키마
+
+```json
+{"no":"03","id":"sec-3","name":"불변식이 조용히 깨지는 구조","kind":"lesson",
+ "lede":"이 절에서 무엇을 왜 배우는지 한두 문장.",
+ "blocks":[
+   {"type":"p","text":"본문 문단. §8.1 참조 가능."},
+   {"type":"concept","title":"침묵 실패","text":"정의 한 문단.","label":"개념(선택)"},
+   {"type":"example","title":"치환표만 영어로 바꾸면",
+    "steps":[{"k":"원문","v":"It was pure goodwill.","note":"왜 이 단계가 이렇게 되는가"}],
+    "takeaway":"이 예제가 증명하는 것 한 문장 (굵게 렌더)"},
+   {"type":"recap","items":["요점 1","요점 2","요점 3"]},
+   {"type":"code","text":"재현 명령 또는 코드"},
+   {"type":"figure","path":"figure.html"}
+ ]}
+```
+
+| 블록 | 언제 | 어기면 생기는 일 |
+|---|---|---|
+| `concept` | 문서 전체가 기대는 명제. 장당 0~1개 | 남발하면 신호가 소음이 된다. 박스가 셋이면 원리가 아니라 목록이다 |
+| `example` | **실제 있었던 일**의 단계 풀이. 지어낸 예 금지 | note 없는 step 은 표다. 각 단계에 "왜"가 없으면 worked example 이 아니다 |
+| `recap` | 장 끝. 항목 2~4개 | 5개 넘으면 요점이 아니다. 본문에 없는 새 사실을 넣지 않는다 |
+| `figure` | 개념 직후, 그 개념의 구조를 그림으로 | SVG 색은 전부 var(--토큰) — design-system.md 규칙 그대로 |
+
+## 4. 연습문제 형식 (`kind:"asks"` 재해석)
+
+`open_items` 를 확인 요청이 아니라 **물음–답–복습 지침**으로 쓴다.
+
+```json
+{"title":"골든 지문이 어긋났을 때, 왜 Rust 쪽 결과로 갱신하면 안 됩니까?",
+ "body":"(답) … 참조 구조가 자기 인증이 되기 때문입니다. … 답이 바로 나오지
+         않으면 05를 다시 읽으십시오.",
+ "refs":["§9.1"]}
+```
+
+- `title` 은 **완전한 물음문**. "골든 지문 관리" 같은 명사구는 심각도를 감춘다.
+- `body` 는 답을 준다 — 시험이 아니라 자기 점검이다. 끝에 "N을 다시 읽으십시오" 복습 지침.
+- `cta` 는 이 문서 전체에서 독자가 지킬 단 하나의 행동 규칙 (게이트 재실행 등).
+
+## 5. 검수 기준 (기존 qa.py 에 더해 손으로 볼 것)
+
+- [ ] 장 순서를 뒤섞어도 문서가 성립하는가? **성립하면 실패다** (병렬 나열이라는 뜻)
+- [ ] 각 장의 recap 만 이어 읽어도 문서 요지가 재구성되는가?
+- [ ] 본문에 건별 사실(재현 명령·수치 표)이 남아 있는가? 대장으로 내릴 것
+- [ ] 예제의 모든 step 에 note("왜")가 있는가?
+- [ ] 연습문제 답에 복습 지침("N을 다시 읽으십시오")이 있는가?
+- [ ] 스타일부터 만지고 있지 않은가? 절 구성이 확정되기 전의 CSS 작업은 전부 낭비다
+
+## 6. 근거 (리서치 요약)
+
+- **신호 이론(SARA)** — 장치 문법을 일관되게 유지하면 독자가 레이아웃 해석을 멈추고
+  내용만 해석한다. explorersdesign.com/designing-signals
+- **Worked examples** — 완성된 풀이 제시가 실증적으로 기억을 향상. arxiv 2602.16806
+- **여백 노트** — 참조를 문서 끝이 아니라 참조된 자리 옆에. Tufte CSS, gwern.net/sidenote
+- **측정폭** — 본문 66ch 제한. 긴 행은 시선 복귀 비용. typographicwebdesign.com
+
+## 7. 표본
+
+그 프로젝트의 `docs/tech-report/` — report.json(교과서 서사)·cases.json(부록 대장)·
+figure.html(토큰 SVG). 새 기술문서는 이 셋을 복사해 내용만 갈아끼우는 것으로 시작한다.