init: document-haness 설계

skills/technical-doc-flow/references/section-playbook.md

@@ -0,0 +1,137 @@
+# 섹션 작성 지침
+
+한 섹션은 하나의 독자 질문을 닫는 최소 단위다. 모든 블록을 기계적으로 넣지 말고 질문에 필요한 블록만 선택한다.
+
+## 목차
+
+- 공통 section card와 block 순서
+- 역할별 pattern
+- example, code, validation 계약
+- 복잡도 제어와 완료 check
+
+## 공통 섹션 카드
+
+작성 전에 `04_logic_map.json.sections[]`에 다음을 고정한다.
+
+- 섹션 역할과 선행 섹션
+- 독자 질문과 쉬운 답 한 문장
+- 새 용어와 claim ID
+- 사용할 예시의 상태
+- 코드나 표가 필요한 이유
+- 검증과 한계
+- 다음 섹션으로 가는 이유
+
+## 기본 블록 순서
+
+1. **Orientation** — 지금 답할 질문과 왜 필요한지 말한다.
+2. **Plain answer** — 전문용어 없이 결론을 먼저 준다.
+3. **Definition** — 필요한 새 용어만 정의한다.
+4. **Example** — 하나의 사례로 개념을 고정한다.
+5. **Mechanism** — 책임, 순서, 상태, 의존을 설명한다.
+6. **Evidence/code** — 주장을 직접 지지하는 최소 절편을 둔다.
+7. **Table** — 산문으로 추적하기 어려운 반복 관계만 옮긴다.
+8. **Validation** — 무엇이 검사하고 어디서 실패하는지 밝힌다.
+9. **Boundary** — 비용, 예외, 증명하지 않는 것을 모은다.
+10. **Transition** — 다음 질문이 왜 생기는지 연결한다.
+
+## 역할별 패턴
+
+### 실패 장면
+
+- 한 가지 재현 가능한 증상이나 짧은 가정 코드를 보여 준다.
+- 독자가 스스로 실패를 판정할 질문 2~4개를 붙인다.
+- 용어 정의와 해결책을 먼저 쏟지 않는다.
+- 끝에서 원인 질문을 연다.
+
+### 원리
+
+- 혼동하기 쉬운 축을 먼저 분리한다.
+- 압축한 구조 설명보다 앞에서 일상어로 차이를 설명한다.
+- 원리 하나를 실제 코드 관계 하나에 대응한다.
+- 원리의 적용 한계와 흔한 과설계를 함께 둔다.
+
+### 결정
+
+- 제약→대안→평가 기준→선택→반대 조건 순서를 지킨다.
+- 채택안의 이점과 유지비를 같은 표나 문단에서 비교한다.
+- 외부 사례는 현재 구현의 증거가 아니라 대조인지 표시한다.
+
+### 전체 지도와 책임
+
+- 전체 구조는 세부보다 먼저 짧은 문단이나 목록으로 제공한다.
+- 컨텍스트, 논리 의존, 런타임 순서, 정책 상한을 한 단락에 섞지 않는다.
+- 책임 설명은 `owns`, `may_know`, `must_not_know`, `public_contract`, `enforcement` 순서를 권장한다.
+
+### 종단 흐름
+
+- 대표 요청이나 이벤트 하나를 고정한다.
+- 시작점, 상태 변화, 외부 경계, 성공, 실패, 재시도, 종료를 시간순으로 쓴다.
+- 다른 사례로 전환하면 비교 목적과 다시 사용할 용어를 한 문장으로 알린다.
+- 계약 존재와 실제 호출자 배선을 구분한다.
+
+### 강제와 break-it
+
+- 규칙의 이름보다 먼저 “무엇을 어디서 막는가”를 설명한다.
+- 위반→검사 장치→첫 실패 지점→관찰 결과 순서로 쓴다.
+- 테스트 자체가 검사 대상을 실제로 갖는지 비공허성 검증을 밝힌다.
+- 정적 분석이 놓치는 우회 하나 이상을 공개한다.
+
+### 비용과 한계
+
+- 모든 caveat를 본문 사이에 흩뿌리지 않는다.
+- `확실한 것`, `아직 아닌 것`, `도입 비용`, `반대 선택이 나은 조건`으로 묶는다.
+- 한계가 핵심 주장을 무효화하는지, 적용 범위만 좁히는지 구분한다.
+
+## 예시 상태
+
+예시는 다음 중 하나로 표시한다.
+
+- `hypothetical`: 문제를 설명하기 위해 가정한 예
+- `observed`: 고정된 소스나 실행에서 확인한 예
+- `derived`: 규칙과 설정에서 유도한 예상
+- `recommended`: 현재 배선이 아닌 권장 통합 형태
+- `counterexample`: 주장의 경계를 드러내는 반례
+
+“실제”, “현재”, “예시” 같은 표현만으로 상태를 암시하지 않는다.
+
+## 코드 블록
+
+각 코드 블록에는 다음 계약이 필요하다.
+
+- `purpose`: problem, mechanism, proof, break-it 중 하나
+- `source`: 원문 경로와 라인 또는 hypothetical
+- `focus_lines`: 독자가 볼 줄
+- `takeaway`: 코드 뒤 쉬운 한 문장
+
+설치 보일러플레이트와 관계없는 줄은 생략 표시로 줄인다. 코드가 주장을 증명하지 못하면 “모양을 설명하는 예”라고 쓴다.
+
+## 검증 블록
+
+행동 또는 구조 주장마다 가능하면 다음을 둔다.
+
+- `proves`: 직접 확인하는 성질
+- `does_not_prove`: 호출자 배선, 운영 효과 등 범위 밖 성질
+- `failure_stage`: compile, build, test, runtime, review
+- `claim_ids`
+
+테스트 개수만으로 보장 범위를 대신하지 않는다.
+
+quality rules가 evidence marker를 요구하면 factual passage 가까이에 허용 형식, 예를 들어 `<!-- claim:CLM-001 -->` 또는 `[근거: CLM-001]`를 사용한다. marker ID는 `03_evidence_map.json`과 같아야 하며 source citation을 대신하지 않는다.
+
+## 복잡도 제어
+
+- 문단은 질문 하나만 답한다.
+- 새 개념 예산은 문장 2개, 문단 2개, 절 7개를 기본으로 한다.
+- 절이 여러 상태기계, 세 개 이상의 독립 메커니즘, 두 개 이상의 주 사례를 포함하면 분할하거나 미니 로드맵을 둔다.
+- 정밀 식별자 목록은 본문 이해에 필요하지 않으면 표·근거 노트·부록으로 내린다.
+- 표의 결론을 산문에서 다시 장황하게 복제하지 않는다.
+
+## 섹션 완료 체크
+
+- 쉬운 답이 기술 세부보다 먼저 있는가.
+- claim과 근거가 연결됐는가.
+- 새 용어가 ledger와 예산을 지키는가.
+- 코드와 본문이 서로 다른 사실을 주장하지 않는가.
+- 현재 구현과 권장 미래가 구분됐는가.
+- 검증하지 못한 범위를 말했는가.
+- 다음 절이 단순 나열이 아니라 앞 답에서 생긴 질문인가.