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

섹션 작성 지침

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

목차

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