donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

chore: 문서를 작성할 때 한국어의 표현 작성 스킬 추가 및 1인칭 관점의 글 작성 검증 테스트 추가

Browse Source
This commit is contained in:
DongHyeonka
2026-07-29 16:48:03 +09:00
parent c39406bbdd
commit 41501b5d06
520 changed files with 95494 additions and 2231 deletions
Download Patch File Download Diff File Expand all files Collapse all files
examples/output/retry-policy-demo/final/document.md
+29 -54
View File
@@ -1,73 +1,48 @@
# API 재시도는 횟수가 아니라 부하 예산으로 설계한다
## 먼저 결론: 무엇을 해결하는가
## 코드보다 먼저 드러난 문제
이 글의 독자는 백엔드 개발자, 플랫폼 엔지니어이다. 읽고 나면 **재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다**할 수 있어야 한다. 먼저 결론부터 말하면, 재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.
범위는 서비스 간 동기 HTTP 호출의 클라이언트 재시도 정책, 정책을 검증하는 운영 지표와 실패 실험이다. 합리적으로 기대할 수 있지만 이 글에서 다루지 않는 범위는 메시지 큐의 전달 보장 전체 설계, 특정 클라우드 SDK의 모든 기본값, 정확히 한 번 처리 보장이다. 적용 맥락은 HTTP 의미론은 RFC 9110, 예시는 2026-07-23 기준이다.
제공된 근거 팩은 다음 사실을 확인 대상으로 제시한다: Retries can increase load on a dependency that is already failing. [S1]
작은 구현 선택처럼 보였던 문제가 실제 흐름을 따라가자 여러 경계에 걸쳐 있었다. 재시도의 부하 증폭, 멱등성, 지수 백오프, 지터, 재시도 한도, 성공 및 중단 기준 가운데 하나만 고치면 다른 지점에서 부하, 중복, 조립 비용, 복구 비용이 커질 수 있었다. 이 글은 다음 질문을 다룬다. **재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다**
핵심 판단은 명확하다. **재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.** 여기서는 서비스 간 동기 HTTP 호출의 클라이언트 재시도 정책, 정책을 검증하는 운영 지표와 실패 실험에 집중하며, 메시지 큐의 전달 보장 전체 설계, 특정 클라우드 SDK의 모든 기본값, 정확히 한 번 처리 보장까지 보편적인 결론으로 확대하지 않는다.
## 문제가 생기는 맥락과 제약
## 문제를 어렵게 만든 제약
이 절은 ‘왜 이 문제가 실제 시스템에서 어려워지는가?’에 답한다. 판단의 기준은 **재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.**이다. 다룰 핵심 항목은 현상, 원인 후보, 제약, 재시도의 부하 증폭, 멱등성이며, 설명은 독자의 목표인 “재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다”에 필요한 범위로 제한한다.
현실의 문제는 재시도의 부하 증폭, 멱등성, 지수 백오프, 지터, 재시도 한도, 성공 및 중단 기준가 독립적으로 움직이지 않는다는 점이다. 입력, 상태, 시간, 실패 복구가 연결되므로 한 요소만 최적화하면 다른 경로에서 비용이 나타날 수 있다.
제공된 근거 팩은 다음 사실을 확인 대상으로 제시한다: A client can automatically retry an idempotent request after a communication failure before reading the response, subject to the specification's conditions. [S2]
재시도의 부하 증폭, 멱등성, 지수 백오프, 지터, 재시도 한도, 성공 및 중단 기준는 입력과 상태, 실패와 복구를 통해 서로 연결된다. 한 부분의 편의를 높이면 다른 경계로 부하나 중복, 복구 비용이 이동할 수 있어서 각 요소를 독립적으로 바꾸기 어려웠다.
근거의 역할도 서로 달랐다. 현재 구현, 결정 기록, 공식 동작, 다른 회사의 사례는 같은 단어를 사용하더라도 같은 사실을 증명하지 않는다. 프로젝트의 선택 이유는 그 이유를 직접 기록한 자료가 있을 때만 설명할 수 있다.
## 핵심 판단 기준과 멘털 모델
## 검토한 선택지와 막힌 지점
이 절은 ‘뒤의 세부사항을 이해하려면 어떤 모델이 필요한가?’에 답한다. 판단의 기준은 **재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.**이다. 다룰 핵심 항목은 용어 정의, 인과 관계, 판단 기준이며, 설명은 독자의 목표인 “재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다”에 필요한 범위로 제한한다.
멘털 모델은 ‘입력 → 판단 기준 → 상태 변화 → 관측 결과’의 네 칸으로 잡는다. 재시도의 부하 증폭, 멱등성, 지수 백오프, 지터, 재시도 한도, 성공 및 중단 기준를 이 흐름에 배치하면 구현 세부사항이 바뀌어도 인과 관계를 추적할 수 있다.
제공된 근거 팩은 다음 사실을 확인 대상으로 제시한다: Retry behavior should consider whether the operation is idempotent. [S3]
검토할 선택지는 최소 두 가지다. 첫째, 현재 방식을 유지하고 문제가 드러난 지점만 보완한다. 변경 범위는 작지만 상호작용을 놓치기 쉽다. 둘째, 관련 요소를 하나의 정책 경계로 묶는다. 초기 설계와 검증 비용은 늘지만 판단 기준과 실패 범위를 함께 관리할 수 있다.
비교 기준은 구현량이 아니라 실패 시 부하가 어디로 이동하는지, 중복 부작용을 막을 수 있는지, 검증 결과를 관측할 수 있는지, 잘못됐을 때 되돌릴 수 있는지다. 실패한 시도나 제외한 대안도 같은 기준으로 설명해야 독자가 선택을 재현할 수 있다.
## 해결 방식이 동작하는 과정
## 선택의 이유와 지킨 경계
이 절은 ‘구성요소와 데이터 흐름은 어떻게 연결되는가?’에 답한다. 판단의 기준은 **재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.**이다. 다룰 핵심 항목은 구성요소, 데이터 또는 제어 흐름, 불변조건, 재시도의 부하 증폭, 멱등성이며, 설명은 독자의 목표인 “재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다”에 필요한 범위로 제한한다.
동작은 다음 인과 순서로 이해할 수 있다.
1. 입력과 사전 조건을 검증하고 처리 가능한 상태인지 확인한다.
2. 명시된 판단 기준으로 경로를 선택하고 상태 변경 범위를 제한한다.
3. 결과를 기록한 뒤 성공 기준과 비교해 다음 행동을 결정한다.
제공된 근거 팩은 다음 사실을 확인 대상으로 제시한다: Retries can increase load on a dependency that is already failing. [S1]
이 글이 선택한 방향은 **재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.** 여러 설정을 함께 다루기로 한 이유는 각각의 값이 서로의 안전 조건을 바꾸기 때문이다. 한 항목만 최적화하면 전체 요청 경로나 모듈 경계에서 예상하지 못한 비용이 발생한다.
대안은 설정을 완전히 분리하거나 편의를 위해 관련 경계를 넓게 허용하는 방식이다. 전자는 상호작용을 운영자에게 떠넘기고, 후자는 정책이 코어 안으로 번질 위험을 키운다. 따라서 초기 설계와 테스트 비용을 수용하되, 허용 범위와 금지 범위를 자동 검사하는 가드레일을 함께 둔다.
## 끝까지 따라가는 구현 예시
## 선택이 코드와 흐름에 반영되는 방식
이 절은 ‘구체적인 입력이 어떻게 결과로 바뀌는가?’에 답한다. 판단의 기준은 **재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.**이다. 다룰 핵심 항목은 초기 조건, 단계별 변화, 최종 결과, 재시도의 부하 증폭, 멱등성이며, 설명은 독자의 목표인 “재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다”에 필요한 범위로 제한한다.
아래는 특정 제품의 실제 측정값이 아니라 판단 흐름을 드러내기 위한 예시다.
결정은 입력에서 관측까지 끊기지 않는 흐름으로 반영한다. 요청이나 변경이 들어오면 사전 조건을 확인하고, 같은 기준에서 실행 경로와 상태 변경 범위를 정한다. 실행 뒤에는 결과와 실패 신호를 기록해 성공, 중단, 복구 중 하나를 결정한다.
```text
입력: 변경 요청과 현재 상태
판단: 사전 조건 충족 여부 → 안전한 실행 경로 선택
실행: 최소 범위 변경
관측: 예상 상태와 실제 상태 비교
결과: 성공이면 확정, 불일치면 중단 후 복구
입력과 현재 상태
→ 안전 조건 확인
→ 한정된 실행 경로 선택
→ 상태 변경 또는 호출
→ 로그·지표·테스트 결과 관측
→ 확정 / 중단 / 복구
```
예시의 핵심은 명령 자체가 아니라 각 단계의 입력, 판단, 관측이 끊기지 않는다는 점이다.
제공된 근거 팩은 다음 사실을 확인 대상으로 제시한다: A request method is idempotent when multiple identical requests have the same intended effect as one request. [S2]
이 흐름의 불변조건은 실패한 작업이 성공으로 기록되지 않고, 같은 입력을 다시 처리했을 때 허용하지 않은 부작용이 늘어나지 않는 것이다. 실제 글에서는 일반 명칭 대신 프로젝트의 모듈, 인터페이스, 테스트 이름을 사용한다.
## 어떻게 검증할 것인가
## 결정이 지켜지는지 확인하는 방법
이 절은 ‘주장이 맞고 구현이 동작한다는 것을 어떻게 확인하는가?’에 답한다. 판단의 기준은 **재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.**이다. 다룰 핵심 항목은 검증 절차, 성공 기준, 관측 지표, 재시도의 부하 증폭, 멱등성이며, 설명은 독자의 목표인 “재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다”에 필요한 범위로 제한한다.
검증 계획은 주장과 관측을 일대일로 연결한다.
1. 핵심 주장마다 확인 가능한 로그, 테스트, 상태 또는 출처를 지정한다.
2. 정상 경로뿐 아니라 실패 경로와 복구 경로를 실행한다.
3. 성공 기준과 중단 기준을 실행 전에 고정한다.
제공된 근거 팩은 다음 사실을 확인 대상으로 제시한다: Exponential backoff increases the delay between retry attempts and should use bounded limits. [S3]
검증은 주장마다 관측 가능한 증거를 붙이는 방식으로 설계한다. 구조적 경계는 빌드 규칙이나 정적 분석으로, 런타임 동작은 단위·통합 테스트와 로그·지표로, 실패 복구는 의도된 오류 주입과 롤백 확인으로 검증한다.
성공 기준은 독자가 다음 목표를 반복 가능한 결과로 확인할 수 있는지다. **재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다** 반대로 운영 배포, 장기 부하, 특정 장애 조합을 검증하지 않았다면 그 범위는 명시적으로 남겨야 한다. 로컬 테스트 통과를 운영 검증으로 확대해 쓰지 않는다.
## 대안, 트레이드오프, 실패 조건
## 얻은 것, 잃은 것, 적용하지 않을 때
이 절은 ‘언제 이 접근법을 선택하지 말아야 하는가?’에 답한다. 판단의 기준은 **재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.**이다. 다룰 핵심 항목은 대안, 얻는 것과 잃는 것, 적용 한계이며, 설명은 독자의 목표인 “재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다”에 필요한 범위로 제한한다.
이 접근은 구조와 검증 가능성을 얻는 대신 초기 설계와 근거 정리에 비용이 든다. 빠른 초안만 필요한 상황에서는 과할 수 있고, 규제·운영 위험이 큰 문서에서는 더 강한 사실 검증이 필요하다.
대안은 더 자유로운 서술, 단일 모델 작성, 수동 리뷰다. 선택 기준은 문서의 위험도, 변경 빈도, 독자의 숙련도, 검증 비용이다.
제공된 근거 팩은 다음 사실을 확인 대상으로 제시한다: Retries can increase load on a dependency that is already failing. [S1]
얻는 것은 판단 기준의 일관성, 실패 범위의 가시성, 자동 검증 가능성이다. 잃는 것은 초기 설계 시간과 정책을 유지하는 비용이다. 작은 실험이나 폐기 예정 코드에서는 이 구조가 과할 수 있지만, 반복 사용되거나 장애 시 비용이 큰 경로에서는 그 비용이 가드레일로 작동한다.
이 선택은 보편 법칙이 아니다. 성공 기준을 관측할 수 없거나 관련 요소의 소유권이 분리돼 있다면 더 작은 경계가 나을 수 있다. 남은 위험은 자동 검사가 잡지 못하는 런타임 우회와 문서·구현 간 시차이며, 코드 리뷰와 주기적인 근거 재검증으로 보완한다.
## 실무 적용 체크리스트
## 결국 지키려던 것은 무엇이었나
실무 적용 전 다음을 확인한다.
- 독자 목표와 비범위를 한 문장으로 고정했는가?
- 판단 기준과 근거가 연결되어 있는가?
- 예시가 시작 상태부터 검증 결과까지 이어지는가?
- 실패 조건, 중단 기준, 롤백이 있는가?
- 버전 또는 시점이 드러나는가?
제공된 근거 팩은 다음 사실을 확인 대상으로 제시한다: A client can automatically retry an idempotent request after a communication failure before reading the response, subject to the specification's conditions. [S2]
## 결론
기억해야 할 판단은 하나다. **재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.** 독자의 다음 행동은 자신의 환경에서 재시도가 장애를 증폭하지 않도록 타임아웃, 재시도 횟수, 백오프, 지터, 멱등성을 함께 설계한다을 검증 가능한 기준으로 바꾸는 것이다.
제공된 근거 팩은 다음 사실을 확인 대상으로 제시한다: Retry behavior should consider whether the operation is idempotent. [S3]
결국 지키려던 것은 특정 도구가 아니라 판단 가능한 경계다. **재시도는 성공 확률을 높이는 무료 기능이 아니라 실패 중인 의존성에 추가 부하를 보내는 예산이므로, 멱등성·한도·백오프·지터·관측성을 하나의 정책으로 묶어야 한다.** 자신의 환경에서는 ‘왜 이 선택이 필요한가’, ‘대안보다 어떤 비용을 덜어 주는가’, ‘그 대가를 어떤 테스트가 제한하는가’를 연속해서 답할 수 있어야 한다.
examples/output/retry-policy-demo/final/evidence-map.json
+470
View File
@@ -0,0 +1,470 @@
{
"schema_version": 2,
"document": "API 재시도는 횟수가 아니라 부하 예산으로 설계한다",
"citation_style": "hidden",
"reader_document_contains_internal_source_ids": false,
"sections": [
{
"section_id": "01-problem-scene",
"intent": "problem_scene",
"title": "코드보다 먼저 드러난 문제",
"reader_question": "독자가 공감할 수 있는 구체적인 상황에서 어떤 문제가 드러났는가?",
"decision_requirements": [],
"evidence": [
{
"id": "S1",
"title": "Timeouts, retries, and backoff with jitter",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S2",
"title": "RFC 9110, HTTP Semantics — Idempotent Methods",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S3",
"title": "Retry strategy",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://cloud.google.com/storage/docs/retry-strategy",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
}
],
"evidence_gap": false
},
{
"section_id": "02-constraints",
"intent": "constraints",
"title": "문제를 어렵게 만든 제약",
"reader_question": "단순한 해법을 막은 프로젝트 제약은 무엇이었는가?",
"decision_requirements": [],
"evidence": [
{
"id": "S1",
"title": "Timeouts, retries, and backoff with jitter",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S2",
"title": "RFC 9110, HTTP Semantics — Idempotent Methods",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S3",
"title": "Retry strategy",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://cloud.google.com/storage/docs/retry-strategy",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
}
],
"evidence_gap": false
},
{
"section_id": "03-options",
"intent": "options",
"title": "검토한 선택지와 막힌 지점",
"reader_question": "어떤 대안들을 검토했고 각각 어디에서 비용이 생겼는가?",
"decision_requirements": [
"상황·제약",
"선택",
"선택 이유",
"검토한 대안",
"수용한 비용",
"보완 가드레일"
],
"evidence": [
{
"id": "S1",
"title": "Timeouts, retries, and backoff with jitter",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S2",
"title": "RFC 9110, HTTP Semantics — Idempotent Methods",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S3",
"title": "Retry strategy",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://cloud.google.com/storage/docs/retry-strategy",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
}
],
"evidence_gap": false
},
{
"section_id": "04-decision-rationale",
"intent": "decision_rationale",
"title": "선택의 이유와 지킨 경계",
"reader_question": "왜 이 선택을 했으며 무엇을 일부러 포기하거나 금지했는가?",
"decision_requirements": [
"상황·제약",
"선택",
"선택 이유",
"검토한 대안",
"수용한 비용",
"보완 가드레일"
],
"evidence": [
{
"id": "S1",
"title": "Timeouts, retries, and backoff with jitter",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S2",
"title": "RFC 9110, HTTP Semantics — Idempotent Methods",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S3",
"title": "Retry strategy",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://cloud.google.com/storage/docs/retry-strategy",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
}
],
"evidence_gap": false
},
{
"section_id": "05-mechanism",
"intent": "mechanism",
"title": "선택이 코드와 흐름에 반영되는 방식",
"reader_question": "결정이 모듈, 인터페이스, 제어 흐름에 어떻게 반영되는가?",
"decision_requirements": [],
"evidence": [
{
"id": "S1",
"title": "Timeouts, retries, and backoff with jitter",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S2",
"title": "RFC 9110, HTTP Semantics — Idempotent Methods",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S3",
"title": "Retry strategy",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://cloud.google.com/storage/docs/retry-strategy",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
}
],
"evidence_gap": false
},
{
"section_id": "06-evidence-verification",
"intent": "evidence_verification",
"title": "결정이 지켜지는지 확인하는 방법",
"reader_question": "설명한 경계와 결과가 실제로 유지되는지 어떻게 확인하는가?",
"decision_requirements": [],
"evidence": [
{
"id": "S1",
"title": "Timeouts, retries, and backoff with jitter",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S2",
"title": "RFC 9110, HTTP Semantics — Idempotent Methods",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S3",
"title": "Retry strategy",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://cloud.google.com/storage/docs/retry-strategy",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
}
],
"evidence_gap": false
},
{
"section_id": "07-tradeoffs",
"intent": "tradeoffs",
"title": "얻은 것, 잃은 것, 적용하지 않을 때",
"reader_question": "이 선택의 비용과 한계는 무엇이며 언제 다른 선택이 나은가?",
"decision_requirements": [
"상황·제약",
"선택",
"선택 이유",
"검토한 대안",
"수용한 비용",
"보완 가드레일"
],
"evidence": [
{
"id": "S1",
"title": "Timeouts, retries, and backoff with jitter",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S2",
"title": "RFC 9110, HTTP Semantics — Idempotent Methods",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S3",
"title": "Retry strategy",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://cloud.google.com/storage/docs/retry-strategy",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
}
],
"evidence_gap": false
},
{
"section_id": "08-conclusion",
"intent": "conclusion",
"title": "결국 지키려던 것은 무엇이었나",
"reader_question": "세부 기술을 걷어냈을 때 남는 판단은 무엇인가?",
"decision_requirements": [],
"evidence": [],
"evidence_gap": false
}
],
"sources": [
{
"id": "S1",
"title": "Timeouts, retries, and backoff with jitter",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S2",
"title": "RFC 9110, HTTP Semantics — Idempotent Methods",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
},
{
"id": "S3",
"title": "Retry strategy",
"source_type": "external",
"status": "",
"path": "",
"heading": "",
"line_start": null,
"line_end": null,
"url": "https://cloud.google.com/storage/docs/retry-strategy",
"accessed": "2026-07-23",
"claim_ids": [],
"decision_ids": [],
"priority": 0.0
}
]
}
examples/output/retry-policy-demo/final/provenance.md
+67
View File
@@ -0,0 +1,67 @@
# Evidence and decision provenance
> This is an internal sidecar. It is not reader-facing article content.
> Source IDs, repository paths, line ranges, status labels, and access dates belong here—not in `document.md`.
- Document: **API 재시도는 횟수가 아니라 부하 예산으로 설계한다**
- Citation rendering: `hidden`
- Evidence sources: **3**
## Section evidence map
| Section | Decision contract | Evidence | Status / location |
|---|---|---|---|
| 코드보다 먼저 드러난 문제 | — | `S1` Timeouts, retries, and backoff with jitter | `unspecified` · https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/ |
| ↳ | — | `S2` RFC 9110, HTTP Semantics — Idempotent Methods | `unspecified` · https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2 |
| ↳ | — | `S3` Retry strategy | `unspecified` · https://cloud.google.com/storage/docs/retry-strategy |
| 문제를 어렵게 만든 제약 | — | `S1` Timeouts, retries, and backoff with jitter | `unspecified` · https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/ |
| ↳ | — | `S2` RFC 9110, HTTP Semantics — Idempotent Methods | `unspecified` · https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2 |
| ↳ | — | `S3` Retry strategy | `unspecified` · https://cloud.google.com/storage/docs/retry-strategy |
| 검토한 선택지와 막힌 지점 | 상황·제약, 선택, 선택 이유, 검토한 대안, 수용한 비용, 보완 가드레일 | `S1` Timeouts, retries, and backoff with jitter | `unspecified` · https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/ |
| ↳ | — | `S2` RFC 9110, HTTP Semantics — Idempotent Methods | `unspecified` · https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2 |
| ↳ | — | `S3` Retry strategy | `unspecified` · https://cloud.google.com/storage/docs/retry-strategy |
| 선택의 이유와 지킨 경계 | 상황·제약, 선택, 선택 이유, 검토한 대안, 수용한 비용, 보완 가드레일 | `S1` Timeouts, retries, and backoff with jitter | `unspecified` · https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/ |
| ↳ | — | `S2` RFC 9110, HTTP Semantics — Idempotent Methods | `unspecified` · https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2 |
| ↳ | — | `S3` Retry strategy | `unspecified` · https://cloud.google.com/storage/docs/retry-strategy |
| 선택이 코드와 흐름에 반영되는 방식 | — | `S1` Timeouts, retries, and backoff with jitter | `unspecified` · https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/ |
| ↳ | — | `S2` RFC 9110, HTTP Semantics — Idempotent Methods | `unspecified` · https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2 |
| ↳ | — | `S3` Retry strategy | `unspecified` · https://cloud.google.com/storage/docs/retry-strategy |
| 결정이 지켜지는지 확인하는 방법 | — | `S1` Timeouts, retries, and backoff with jitter | `unspecified` · https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/ |
| ↳ | — | `S2` RFC 9110, HTTP Semantics — Idempotent Methods | `unspecified` · https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2 |
| ↳ | — | `S3` Retry strategy | `unspecified` · https://cloud.google.com/storage/docs/retry-strategy |
| 얻은 것, 잃은 것, 적용하지 않을 때 | 상황·제약, 선택, 선택 이유, 검토한 대안, 수용한 비용, 보완 가드레일 | `S1` Timeouts, retries, and backoff with jitter | `unspecified` · https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/ |
| ↳ | — | `S2` RFC 9110, HTTP Semantics — Idempotent Methods | `unspecified` · https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2 |
| ↳ | — | `S3` Retry strategy | `unspecified` · https://cloud.google.com/storage/docs/retry-strategy |
| 결국 지키려던 것은 무엇이었나 | — | **GAP** | No allocated evidence |
## Source details
### `S1` Timeouts, retries, and backoff with jitter
- Type: `external`
- Status: `unspecified`
- Location: `https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/`
- Public/reference URL: `https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/`
- Claim IDs: —
- Decision IDs: —
- Retrieval priority: `0.0000`
### `S2` RFC 9110, HTTP Semantics — Idempotent Methods
- Type: `external`
- Status: `unspecified`
- Location: `https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2`
- Public/reference URL: `https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2`
- Claim IDs: —
- Decision IDs: —
- Retrieval priority: `0.0000`
### `S3` Retry strategy
- Type: `external`
- Status: `unspecified`
- Location: `https://cloud.google.com/storage/docs/retry-strategy`
- Public/reference URL: `https://cloud.google.com/storage/docs/retry-strategy`
- Claim IDs: —
- Decision IDs: —
- Retrieval priority: `0.0000`
examples/output/retry-policy-demo/final/quality-report.md
+30 -17
View File
@@ -4,7 +4,7 @@
- Type: `technical_blog`
- Language: `ko-KR`
- Gate: **PASS**
- Final composite score: **89.3/100**
- Final composite score: **95.6/100**
- Rounds: **1**
## Provider topology
@@ -12,7 +12,7 @@
- Planner: `mock`
- Writer: `mock`
- Reviser: `mock`
- Reviewers: `logic` → `mock`, `reader` → `mock`, `evidence` → `mock`, `operations` → `mock`
- Reviewers: `logic` → `mock`, `decision` → `mock`, `reader` → `mock`, `editor` → `mock`, `evidence` → `mock`, `operations` → `mock`
## Quality-gate configuration
@@ -26,51 +26,64 @@
| Round | Deterministic | Model mean | Composite | Blockers | Errors | Gate |
|---:|---:|---:|---:|---:|---:|---|
| 1 | 87.5 | 90.5 | 89.3 | 0 | 0 | PASS |
| 1 | 95.0 | 96.0 | 95.6 | 0 | 0 | PASS |
## Final deterministic findings
blocker: 0, error: 0, warning: 5, info: 0
blocker: 0, error: 0, warning: 2, info: 0
| Severity | Code | Location | Finding |
|---|---|---|---|
| warning | `READ002` | line 5 | Paragraph contains 8 sentences. |
| warning | `READ002` | line 11 | Paragraph contains 8 sentences. |
| warning | `READ002` | line 17 | Paragraph contains 8 sentences. |
| warning | `READ002` | line 23 | Paragraph contains 13 sentences. |
| warning | `READ002` | line 40 | Paragraph contains 13 sentences. |
| warning | `READ002` | line 15 | Paragraph contains 7 sentences. |
| warning | `LEN002` | — | Document is under target (667/1200 words). |
## Final independent reviews
### logic — mock
Score: **90.5/100**
Score: **96.0/100**
Strengths: The logic review found the document contract explicit and inspectable.
Strengths: The deterministic logic fixture found the document contract inspectable.
No material issues reported.
### decision — mock
Score: **96.0/100**
Strengths: The deterministic decision fixture found the document contract inspectable.
No material issues reported.
### reader — mock
Score: **90.5/100**
Score: **96.0/100**
Strengths: The reader review found the document contract explicit and inspectable.
Strengths: The deterministic reader fixture found the document contract inspectable.
No material issues reported.
### editor — mock
Score: **96.0/100**
Strengths: The deterministic editor fixture found the document contract inspectable.
No material issues reported.
### evidence — mock
Score: **90.5/100**
Score: **96.0/100**
Strengths: The evidence review found the document contract explicit and inspectable.
Strengths: The deterministic evidence fixture found the document contract inspectable.
No material issues reported.
### operations — mock
Score: **90.5/100**
Score: **96.0/100**
Strengths: The operations review found the document contract explicit and inspectable.
Strengths: The deterministic operations fixture found the document contract inspectable.
No material issues reported.