103 lines
5.8 KiB
Markdown
103 lines
5.8 KiB
Markdown
# 독자 계약
|
|
|
|
작성 전에 `02_reader_contract.json`으로 “누가, 무엇을 위해, 어디까지 알아야 하는가”를 고정한다. 독자 계약이 없으면 쉬운 설명과 충분한 설명을 판정할 기준도 없다.
|
|
|
|
## 필수 결정
|
|
|
|
- `primary_audience`: 역할과 경험 수준. “개발자”처럼 넓게만 쓰지 않는다.
|
|
- `purpose`: 이 문서가 존재하는 이유.
|
|
- `reader_question`: 문서가 답할 주된 질문 한 가지.
|
|
- `reader_outcome`: 읽은 직후 할 수 있어야 하는 판단 또는 행동 한 가지.
|
|
- `document_kind`: explanation, decision, how-to, reference 중 하나.
|
|
- `prerequisites`: 반드시 아는 개념. 본문에서 다시 설명할 개념과 구분한다.
|
|
- `assumed_known`: 설명 없이 사용해도 된다고 계약한 용어.
|
|
- `must_explain`: 본문에서 쉬운 말부터 설명해야 하는 개념.
|
|
- `non_goals`: 이 문서가 가르치거나 보장하지 않는 것.
|
|
|
|
현재 schema는 위 필수 필드 외의 임의 필드를 허용하지 않는다. 사용자에게 확인하지 못한 판단으로 진행할 때는 추정한 독자와 목적을 `primary_audience`와 `purpose`, 필요한 선수지식을 `prerequisites`와 `assumed_known`, 다루지 않을 범위와 보장하지 않는 내용을 `non_goals`에 구체적으로 반영한다.
|
|
|
|
빈값, `TBD`, `?`, “모든 독자”는 허용하지 않는다. 정보가 없으면 입력과 문서 목적에서 가장 보수적인 독자를 추정하고 위 기존 필드에서 추정의 범위가 드러나게 쓴다.
|
|
|
|
`assumed_known`과 `must_explain`은 정규화한 이름 기준으로 겹치면 안 된다. `assumed_known`은 `05_term_ledger.json.assumed_known`과 같은 목록을 유지한다. `must_explain`의 각 항목은 term ledger의 `canonical`, `aliases`, `english`, `abbreviation` 중 하나와 연결되는 실제 term이어야 하며, ledger에 없는 설명 대상을 계획만 해 두지 않는다. 설명이 필요하지만 term을 만들 근거가 부족하면 먼저 logic architect 단계에서 계약을 보완한다.
|
|
|
|
## 독자 수준
|
|
|
|
### 초급 독자 (`beginner`)
|
|
|
|
- 문제 영역은 알 수 있으나 주요 구현 용어는 모른다고 본다.
|
|
- 쉬운 설명, 일상적 예, 작은 개념 단계를 우선한다.
|
|
- 코드보다 결과와 책임을 먼저 설명한다.
|
|
|
|
### 실무 독자 (`practitioner`)
|
|
|
|
- 언어와 프레임워크의 기본 사용 경험은 있으나 해당 설계의 내부 계약은 모른다고 본다.
|
|
- 기본 프로필이다.
|
|
- 역할 설명 뒤 정확한 식별자와 검증 세부를 제공한다.
|
|
|
|
### 전문 독자 (`expert`)
|
|
|
|
- 표준 개념은 짧게 환기할 수 있다.
|
|
- 프로젝트 고유 용어, 상태, 제약, 예외는 여전히 first-use 정의가 필요하다.
|
|
- 익숙할 것이라는 이유로 구현 식별자의 역할 설명을 생략하지 않는다.
|
|
|
|
수준은 정확성의 차이가 아니라 설명 층의 차이다. Beginner 문서에서도 코드명과 수치를 바꾸지 않는다.
|
|
|
|
## 쉬운 설명의 순서
|
|
|
|
1. 독자가 관찰하는 현상
|
|
2. 그 현상이 중요한 이유
|
|
3. 쉬운 역할 또는 동작 설명
|
|
4. 정식 용어와 구현 식별자
|
|
5. 예외, 비용, 정확한 계약
|
|
|
|
첫 문단은 새 전문용어 없이 문제와 읽을 이유를 설명하는 것을 기본으로 한다. 제목에 낯선 용어가 필요하면 제목 바로 아래 첫 문장에서 뜻을 푼다.
|
|
|
|
## 독자 상태 계약
|
|
|
|
각 섹션은 다음 상태 전이를 가진다.
|
|
|
|
- `reader_state_before`: 독자가 아직 답하지 못하는 질문 하나
|
|
- `question`: 해당 절이 답할 질문
|
|
- `answer_plain`: 전문용어 없이 쓴 답 한 문장
|
|
- `reader_state_after`: 읽은 뒤 구분하거나 판단할 수 있는 것
|
|
|
|
`reader_state_after`가 다음 섹션의 `reader_state_before`를 준비하지 못하면 전환을 고치거나 순서를 바꾼다.
|
|
|
|
## 읽기 경로
|
|
|
|
- **빠른 경로**: 핵심 주장, 전체 지도, 결정, 비용·한계, 결론을 잇는다.
|
|
- **전체 경로**: 원리, 책임, 종단 흐름, 검증까지 포함한다.
|
|
- **전문가 경로**: 근거 절편, 규칙명, 전체 상태표, 부록을 추가한다.
|
|
|
|
빠른 경로만 읽어도 결론이 왜 나왔는지 이해할 수 있어야 한다. 세부 절을 건너뛰면 필수 전제가 사라지는 구조를 만들지 않는다.
|
|
|
|
## 이해도 자체검증
|
|
|
|
- 첫 두 문단을 구현 클래스명 없이 요약할 수 있는가.
|
|
- 한 문단이 동시에 답하는 질문이 하나인가.
|
|
- 사례가 바뀔 때 비교 목적을 명시했는가.
|
|
- “현재 구현”, “설명용 예”, “권장 패턴”, “미래 계획”을 구분했는가.
|
|
- 테스트가 증명하지 않는 범위를 독자가 찾을 수 있는가.
|
|
- 빠른 경로에 정의되지 않은 약어나 내부 코드명이 남지 않았는가.
|
|
- `assumed_known`과 `must_explain`이 서로 겹치지 않고, 모든 `must_explain`이 term ledger 항목에 연결되는가.
|
|
- reader contract와 term ledger의 `assumed_known` 목록이 같은가.
|
|
|
|
## `02_reader_contract.json` 최소 필드
|
|
|
|
```json
|
|
{
|
|
"schema_version": "1.0",
|
|
"document_kind": "explanation",
|
|
"primary_audience": "이 서비스의 구조를 처음 맡은 백엔드 실무자",
|
|
"purpose": "경계 규칙을 이해하고 변경 위치를 판단하게 한다.",
|
|
"reader_question": "변경 책임과 의존 방향을 어떻게 판단하는가?",
|
|
"reader_outcome": "변경 요구를 올바른 경계에 배치하고 검증 규칙을 찾을 수 있다.",
|
|
"prerequisites": ["기본적인 함수 호출과 모듈 개념"],
|
|
"assumed_known": ["HTTP 요청과 응답"],
|
|
"must_explain": ["의존 방향", "포트와 어댑터"],
|
|
"non_goals": ["특정 프레임워크 전체 사용법"]
|
|
}
|
|
```
|
|
|
|
위 예시의 `의존 방향`, `포트와 어댑터`는 `05_term_ledger.json`에 각각 등록되어야 한다. 독자가 이미 안다고 둔 `HTTP 요청과 응답`은 ledger의 `assumed_known`에도 같은 이름으로 기록한다.
|