98 lines
5.9 KiB
Markdown
98 lines
5.9 KiB
Markdown
# 논리 흐름
|
|
|
|
기술 문서의 구조를 장 수가 아니라 **독자의 질문이 바뀌는 순서**로 설계한다. 모든 실행은 하나의 주 문서 유형을 고르고 `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가 긴 이론 설명으로 실행 단계를 끊으면 분리한다.
|