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,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)을 함께 정하면 오래된 값이 남는 시간을 제한할 수 있다."
+    }
+  ]
+}