init: document-haness 하네스 설계

2026-07-24 13:58:08 +09:00
parent d6f78f92a0
commit c39406bbdd
219 changed files with 7010 additions and 20052 deletions
@@ -0,0 +1,58 @@
+{
+  "title": "API 재시도는 횟수가 아니라 부하 예산으로 설계한다",
+  "document_type": "technical_blog",
+  "language": "ko-KR",
+  "audience": {
+    "roles": [
+      "백엔드 개발자",
+      "플랫폼 엔지니어"
+    ],
+    "prior_knowledge": [
+      "HTTP 요청과 타임아웃의 기본 개념",
+      "분산 시스템의 부분 실패 경험"
+    ],
+    "needs": [
+      "재시도 정책을 설계할 때 확인할 판단 기준",
+      "운영 환경에서 검증할 지표"
+    ]
+  },
+  "reader_goal": "재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다",
+  "core_message": "재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.",
+  "scope": [
+    "서비스 간 동기 HTTP 호출의 클라이언트 재시도 정책",
+    "정책을 검증하는 운영 지표와 실패 실험"
+  ],
+  "non_scope": [
+    "메시지 큐의 전달 보장 전체 설계",
+    "특정 클라우드 SDK의 모든 기본값",
+    "정확히 한 번 처리 보장"
+  ],
+  "prerequisites": [
+    "HTTP 상태 코드와 타임아웃을 이해함",
+    "로그와 지표를 조회할 수 있음"
+  ],
+  "required_topics": [
+    "재시도의 부하 증폭",
+    "멱등성",
+    "지수 백오프",
+    "지터",
+    "재시도 한도",
+    "성공 및 중단 기준"
+  ],
+  "constraints": {
+    "target_words": 1200,
+    "tone": "운영 경험이 있는 엔지니어에게 설명하는 직접적이고 검증 가능한 문체",
+    "version_context": "HTTP 의미론은 RFC 9110, 예시는 2026-07-23 기준",
+    "max_heading_depth": 3,
+    "require_citations": true,
+    "allow_external_knowledge": false
+  },
+  "forbidden_claims": [
+    "재시도는 항상 안전하다"
+  ],
+  "metadata": {
+    "owner": "platform-engineering",
+    "risk": "high",
+    "review_cycle": "quarterly"
+  }
+}