document-haness/skills/technical-doc-flow/references/logic-flow.md

논리 흐름

기술 문서의 구조를 장 수가 아니라 독자의 질문이 바뀌는 순서로 설계한다. 모든 실행은 하나의 주 문서 유형을 고르고 04_logic_map.json에 섹션 간 인과를 기록한다.

공통 불변식

1. 문서 전체를 지배하는 주장 또는 독자 결과를 하나만 둔다.
2. 각 섹션은 depends_on으로 선행 이해를 밝힌다. 근거 없는 점프와 고립 섹션을 허용하지 않는다.
3. 각 섹션은 question, answer_plain, reader_state_before, reader_state_after를 가진다.
4. 질문을 연 섹션은 뒤에서 답하고 최상위 closure에 회수 관계를 기록한다. 결론에서 미회수 질문을 나열하거나 제거한다.
5. 사실, 관찰, 해석, 권고, 미래 상태를 같은 인과 사슬로 섞지 않는다.
6. 상세 설명은 앞 절의 답을 구체화해야 한다. 새 논지를 몰래 시작하지 않는다.
7. 제목과 answer_plain만 순서대로 읽어도 이야기의 문제, 답, 근거, 한계가 이어져야 한다.
8. 장 번호는 렌더링 결과다. 특정 문서의 36장 구조를 템플릿으로 고정하지 않는다.

문서 유형 선택

02_reader_contract.json.document_kind에 주 유형 하나를 기록한다. 여러 유형이 섞이면 독자의 주된 과업을 기준으로 고르고, 부 유형은 명시적인 핸드오프로 분리한다.

설명문 (explanation)

기본 흐름은 다음과 같다. 소재가 없거나 합칠 수 있는 단계는 합치되 순서를 뒤집을 때는 04_logic_map.json에 이유를 기록한다.

1. 실패 장면 — 독자가 알아볼 수 있는 증상, 코드, 장애 또는 오해를 보여 준다.
2. 진짜 원인 — 제품명이나 유행어가 아니라 실패를 만드는 구조적 원인을 재정의한다.
3. 설계 요구 — 원인을 구현하거나 검증할 수 있는 요구사항으로 바꾼다.
4. 원리 — 뒤의 결정을 이해하는 데 필요한 최소 개념만 설명한다.
5. 결정 — 제약, 대안, 선택, 반대 조건과 비용을 함께 둔다.
6. 전체 지도 — 세부 전에 시스템 경계, 주요 책임, 의존 방향을 한 번에 보여 준다.
7. 책임 — 구성요소별 책임, 허용 지식, 금지 지식, 공개 계약을 설명한다.
8. 종단 흐름 — 대표 요청 또는 이벤트 하나를 입구부터 결과와 실패까지 따라간다.
9. 강제와 break-it — 규칙을 누가 검사하고, 일부러 깨뜨리면 어디서 멈추는지 보인다.
10. 비용과 한계 — 못 잡는 것, 운영 가정, 유지비, 반대 선택이 나은 조건을 공개한다.
11. 요구 회수 — 3단계의 요구를 구현, 근거 또는 미해결 한계와 다시 연결한다.

핵심 경로에서 실행 절차를 길게 복제하지 않는다. HOW가 필요하면 짧은 다음 단계와 정본 how-to를 연결한다.

의사결정문 (decision)

1. 결정이 필요한 상황과 마감 조건
2. 결정 질문과 평가 기준
3. 현실적으로 가능한 선택지
4. 선택지별 근거, 비용, 위험, 가역성
5. 선택과 선택하지 않은 이유
6. 구현 영향과 책임자
7. 검증 방법과 실패 시 대응
8. 재검토 신호와 만료 조건

결론을 먼저 정해 놓고 사례를 장식처럼 붙이지 않는다. 채택안과 반대편이 옳아지는 조건을 같은 깊이로 쓴다.

실행 절차 (how-to)

1. 완료 상태와 성공 기준
2. 적용 범위, 사전 조건, 권한, 위험
3. 안전한 준비와 백업 또는 롤백 지점
4. 번호가 있는 실행 단계
5. 중요한 단계 직후의 관찰 가능한 검증
6. 실패 증상별 분기와 복구
7. 최종 검증과 정리
8. 다음 운영 또는 유지보수 작업

명령은 실행 순서대로 두고 설명과 결과를 분리한다. 파괴적 작업은 대상 확인, 승인, 복구 가능성을 먼저 둔다.

참조 문서 (reference)

1. 범위와 제외 범위
2. 표기 규칙, 버전, 공통 개념 지도
3. 검색 가능한 색인
4. 동일한 필드 순서를 갖는 독립 항목
5. 각 항목의 구문, 의미, 기본값, 제약, 오류, 예시
6. 관련 항목과 상위 설명으로 가는 링크

Reference는 처음부터 끝까지 읽는 서사를 강제하지 않는다. 대신 항목 하나만 열어도 이해되도록 first-use 정의를 항목별로 재제공한다.

04_logic_map.json 의미 계약

필수 최상위 필드는 schema_version, title, document_kind, core_claim, sections, closure다. 각 sections[] 항목은 다음 필드를 가진다.

• id, heading, role, depends_on
• reader_state_before, question, answer_plain
• claim_ids, new_terms
• transition_to, reader_state_after

필요하면 required_markers, proves, does_not_prove를 추가한다. new_terms에는 05_term_ledger.json.terms[].id를, claim_ids에는 03_evidence_map.json.claims[].id를 넣는다. closure는 처음의 문제·요구·질문이 어느 섹션의 답과 한계로 회수되는지 기록한다.

depends_on 그래프는 순환하지 않아야 한다. 배열 순서는 표시 순서이며 인과를 대신하지 않는다.

논리 게이트

• 주 유형이 없거나 두 개 이상이면 실패한다.
• core_claim과 무관한 섹션은 제거, 부록 이동 또는 별도 문서로 분리한다.
• 존재하지 않는 선행 섹션, 자기 의존, 순환 의존은 실패한다.
• 정의 전에 필수 용어를 사용하는 섹션은 실패한다.
• 열린 핵심 질문 또는 요구가 closure에 없으면 실패한다.
• 종단 흐름이 현재 배선인지, 예시인지, 권장 미래 흐름인지 표시하지 않으면 실패한다.
• break-it 판정이 실제 실행 로그가 아니라 규칙에서 유도됐다면 derived로 표시한다.
• 설명 문서가 장황한 절차를 내장하거나 how-to가 긴 이론 설명으로 실행 단계를 끊으면 분리한다.