init: document-haness 설계

2026-07-23 17:52:22 +09:00
parent 993788c14e
commit d6f78f92a0
127 changed files with 20099 additions and 1 deletions
@@ -0,0 +1,16 @@
+# 실패 문서
+
+# 또 다른 제목
+
+중복 방지는 먼저 쓰였고 TTL도 설명 없이 등장한다. 멱등성, 유효 기간, 캐시 관통을 한 문장에 몰아넣는다. RetryStorm과 HTTPX도 장부에 없다. `cacheStore` 역시 등록되지 않았다. TODO 내용을 보강해야 한다. [없는 절](#missing-section)
+
+### 원리
+
+이 절은 순서가 뒤집혔다.
+
+## 문제
+
+첫 문장이다. 둘째 문장이다. 셋째 문장이다. 넷째 문장이다. 다섯째 문장이다. 여섯째 문장이다. 일곱째 문장이다. 여덟째 문장이다. 이 문단은 독자가 한 번에 따라가기 어렵도록 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다. 같은 설명을 매우 길게 반복한다.
+
+```python
+print("닫히지 않은 fence")
@@ -0,0 +1,19 @@
+[
+  "DOC-H001",
+  "DOC-H002",
+  "DOC-M001",
+  "DOC-M002",
+  "DOC-M003",
+  "DOC-L001",
+  "DOC-L002",
+  "DOC-L003",
+  "DOC-T001",
+  "DOC-T002",
+  "DOC-T003",
+  "DOC-T004",
+  "DOC-T005",
+  "DOC-T007",
+  "DOC-T009",
+  "DOC-P001",
+  "DOC-P002"
+]
@@ -0,0 +1,35 @@
+{
+  "schema_version": "1.0",
+  "title": "실패 문서",
+  "document_kind": "explanation",
+  "core_claim": "이 핵심 주장은 문서에 존재하지 않는다.",
+  "sections": [
+    {
+      "id": "problem",
+      "heading": "문제",
+      "role": "problem",
+      "depends_on": [],
+      "reader_state_before": "모른다.",
+      "question": "문제는 무엇인가?",
+      "answer_plain": "문제가 있다.",
+      "claim_ids": ["C1"],
+      "new_terms": [],
+      "transition_to": "principle",
+      "reader_state_after": "문제를 안다."
+    },
+    {
+      "id": "principle",
+      "heading": "원리",
+      "role": "mechanism",
+      "depends_on": ["problem"],
+      "reader_state_before": "원리를 모른다.",
+      "question": "원리는 무엇인가?",
+      "answer_plain": "원리가 있다.",
+      "claim_ids": ["C2"],
+      "new_terms": ["t1", "t2", "t3"],
+      "transition_to": null,
+      "reader_state_after": "원리를 안다."
+    }
+  ],
+  "closure": "실패를 확인한다."
+}
@@ -0,0 +1,12 @@
+{
+  "schema_version": "1.0",
+  "document_kind": "explanation",
+  "primary_audience": "초급 개발자",
+  "purpose": "실패 fixture",
+  "reader_question": "무엇이 잘못됐는가?",
+  "reader_outcome": "실패를 확인한다.",
+  "prerequisites": [],
+  "assumed_known": [],
+  "must_explain": ["멱등성", "유효 기간", "캐시 관통"],
+  "non_goals": []
+}
@@ -0,0 +1,40 @@
+{
+  "schema_version": "1.0",
+  "assumed_known": ["HTTP"],
+  "budgets": {
+    "per_sentence": 2,
+    "per_paragraph": 2,
+    "per_section": 7
+  },
+  "terms": [
+    {
+      "id": "t1",
+      "canonical": "멱등성",
+      "plain_definition": "여러 번 처리해도 결과가 같은 성질",
+      "why_needed": "재시도를 설명한다.",
+      "aliases": ["중복 방지"],
+      "first_section": "principle",
+      "first_use": "여러 번 처리해도 결과가 같은 성질을 멱등성이라고 한다."
+    },
+    {
+      "id": "t2",
+      "canonical": "유효 기간",
+      "english": "time to live",
+      "abbreviation": "TTL",
+      "plain_definition": "데이터가 남는 시간",
+      "why_needed": "만료를 설명한다.",
+      "aliases": [],
+      "first_section": "principle",
+      "first_use": "데이터가 남는 시간인 유효 기간(time to live, TTL)을 정한다."
+    },
+    {
+      "id": "t3",
+      "canonical": "캐시 관통",
+      "plain_definition": "없는 키 요청이 저장소까지 계속 내려가는 현상",
+      "why_needed": "실패를 설명한다.",
+      "aliases": [],
+      "first_section": "principle",
+      "first_use": "없는 키 요청이 저장소까지 계속 내려가는 현상을 캐시 관통이라고 한다."
+    }
+  ]
+}
@@ -0,0 +1,19 @@
+# 캐시 실패를 줄이는 설명
+
+캐시 장애를 줄이려면 재시도 규칙과 만료 시간을 함께 설계하고 각각의 한계를 검증해야 한다.
+
+## 문제
+
+요청이 한꺼번에 몰릴 때 모든 호출자가 같은 데이터를 다시 계산하면 원래 장애보다 더 큰 부하가 생긴다. 이 절에서는 그 실패 장면을 먼저 확인한다. <!-- claim:C1 -->
+
+다음 [원리](#원리)는 중복 계산과 오래된 데이터라는 두 문제를 나눠 다룬다.
+
+## 원리
+
+같은 요청을 여러 번 처리해도 결과가 한 번 처리한 것과 같게 되는 성질을 멱등성이라고 한다. 이 성질이 있으면 안전한 재시도 범위를 설명할 수 있다. <!-- claim:C1 -->
+
+데이터가 자동으로 사라지기까지의 시간인 유효 기간(time to live, TTL)을 함께 정하면 오래된 값이 남는 시간을 제한할 수 있다.
+
+## 검증과 한계
+
+재시도 횟수와 TTL을 바꿔 부하와 오래된 값의 비율을 각각 측정한다. 이 검증은 두 설정의 상호작용을 보여 주지만 실제 장애가 모두 사라진다는 사실까지 증명하지는 않는다. <!-- claim:C2 -->
@@ -0,0 +1,50 @@
+{
+  "schema_version": "1.0",
+  "title": "캐시 실패를 줄이는 설명",
+  "document_kind": "explanation",
+  "core_claim": "캐시 장애를 줄이려면 재시도 규칙과 만료 시간을 함께 설계하고 각각의 한계를 검증해야 한다.",
+  "sections": [
+    {
+      "id": "problem",
+      "heading": "문제",
+      "role": "problem",
+      "depends_on": [],
+      "reader_state_before": "캐시 장애가 왜 커지는지 모른다.",
+      "question": "어떤 실패가 부하를 키우는가?",
+      "answer_plain": "동시에 같은 데이터를 다시 계산하는 요청이 부하를 키운다.",
+      "claim_ids": ["C1"],
+      "new_terms": [],
+      "transition_to": "principle",
+      "reader_state_after": "중복 계산이 문제임을 안다."
+    },
+    {
+      "id": "principle",
+      "heading": "원리",
+      "role": "mechanism",
+      "depends_on": ["problem"],
+      "reader_state_before": "문제는 알지만 설정의 역할을 구분하지 못한다.",
+      "question": "재시도와 만료 시간은 각각 무엇을 제한하는가?",
+      "answer_plain": "재시도는 중복 실행을, 만료 시간은 오래된 값의 수명을 제한한다.",
+      "claim_ids": ["C1"],
+      "new_terms": ["term-idempotency", "term-ttl"],
+      "transition_to": "limits",
+      "reader_state_after": "두 설정의 역할을 구분한다."
+    },
+    {
+      "id": "limits",
+      "heading": "검증과 한계",
+      "role": "verification",
+      "depends_on": ["principle"],
+      "reader_state_before": "설정은 알지만 검증 범위는 모른다.",
+      "question": "무엇을 측정하고 무엇은 단정하지 않아야 하는가?",
+      "answer_plain": "부하와 오래된 값은 측정하되 모든 장애 제거를 단정하지 않는다.",
+      "claim_ids": ["C2"],
+      "new_terms": [],
+      "transition_to": null,
+      "reader_state_after": "검증 범위와 한계를 설명할 수 있다.",
+      "proves": ["설정 변화와 측정값의 관계"],
+      "does_not_prove": ["모든 운영 장애의 제거"]
+    }
+  ],
+  "closure": "처음의 장애 문제를 두 설정과 검증 한계로 다시 연결한다."
+}
@@ -0,0 +1,12 @@
+{
+  "schema_version": "1.0",
+  "document_kind": "explanation",
+  "primary_audience": "캐시 운영 경험이 적은 백엔드 개발자",
+  "purpose": "캐시 재시도와 만료 시간의 관계를 설명한다.",
+  "reader_question": "캐시 장애가 커지는 이유와 줄이는 방법은 무엇인가?",
+  "reader_outcome": "재시도와 만료 시간을 함께 검증할 수 있다.",
+  "prerequisites": ["웹 요청의 기본 흐름을 안다."],
+  "assumed_known": ["HTTP"],
+  "must_explain": ["멱등성", "유효 기간"],
+  "non_goals": ["특정 캐시 제품의 설치법"]
+}
@@ -0,0 +1,32 @@
+{
+  "schema_version": "1.0",
+  "assumed_known": ["HTTP"],
+  "budgets": {
+    "per_sentence": 2,
+    "per_paragraph": 2,
+    "per_section": 7
+  },
+  "terms": [
+    {
+      "id": "term-idempotency",
+      "canonical": "멱등성",
+      "english": "idempotency",
+      "plain_definition": "같은 요청을 여러 번 처리해도 결과가 한 번 처리한 것과 같게 되는 성질",
+      "why_needed": "안전한 재시도 범위를 설명하기 위해 필요하다.",
+      "aliases": [],
+      "first_section": "principle",
+      "first_use": "같은 요청을 여러 번 처리해도 결과가 한 번 처리한 것과 같게 되는 성질을 멱등성이라고 한다."
+    },
+    {
+      "id": "term-ttl",
+      "canonical": "유효 기간",
+      "english": "time to live",
+      "abbreviation": "TTL",
+      "plain_definition": "데이터가 자동으로 사라지기까지의 시간",
+      "why_needed": "오래된 값이 남는 시간을 설명하기 위해 필요하다.",
+      "aliases": [],
+      "first_section": "principle",
+      "first_use": "데이터가 자동으로 사라지기까지의 시간인 유효 기간(time to live, TTL)을 함께 정하면 오래된 값이 남는 시간을 제한할 수 있다."
+    }
+  ]
+}