document-haness/skills/technical-doc-flow/references/reader-contract.md

독자 계약

작성 전에 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 최소 필드

{
  "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에도 같은 이름으로 기록한다.