# 섹션 작성 지침

한 섹션은 하나의 독자 질문을 닫는 최소 단위다. 모든 블록을 기계적으로 넣지 말고 질문에 필요한 블록만 선택한다.

## 목차

- 공통 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와 예산을 지키는가.
- 코드와 본문이 서로 다른 사실을 주장하지 않는가.
- 현재 구현과 권장 미래가 구분됐는가.
- 검증하지 못한 범위를 말했는가.
- 다음 절이 단순 나열이 아니라 앞 답에서 생긴 질문인가.