Files
clean-architecture-frontend…/config/runbooks/runbooks.json
DongHyeonka 309631e419 docs(config): 설정 파일의 사람이 읽는 설명 칸을 한국어로 옮긴다
문제: recipe 카탈로그(config/recipes/frontend-capability-recipes.json),
runbook 등록(config/runbooks/runbooks.json), 규모 상한
(config/scale/feature-shape-ceilings.json), 짝 백엔드 pin의 `fact`,
secret scan 허용 이유의 설명 칸이 영어다. 소유자 결정(2026-11-07):
레지스트리의 설명 칸은 번역하되 그 칸을 읽는 테스트를 먼저 찾는다.

고른 방법: 칸마다 읽는 코드를 찾아, 비었는지만 보거나 자유 문자열로
산출물에 복사하는 칸만 옮긴다. 키, 배열 길이, 순서, 식별자·상태·경로·
명령·숫자는 그대로다.
- 옮기지 않은 칸: registry-baseline.json의 `trigger`·`compatibilityRole`
  (승인 파일이 그 사본의 digest를 고정한다), 승인·변경 증거 파일의
  `reason`(쓴 때의 기록), benchmark-baseline.json의 승인 이유,
  feature-shape-ceilings의 `axes[].axis`(테스트가 영어 리터럴로
  비교한다), 값이나 이름뿐인 칸. config/ci/는 정리 3단계·CI 세션
  범위라 보지 않았다.

위험: scripts/drill-runbook.ts의 복구 확인 항목 이름은 아직 영어라 설정과
코드의 언어가 다르다. 비교하지는 않는다.

검증: 다섯 파일 모두 HEAD와 키 경로·순서·배열 길이가 같다.
json-schema·runbook-contract·feature-shape-growth·backend-contract-pin
시험을 desktop에서 돌렸다.
2026-11-08 21:57:47 +09:00

94 lines
3.9 KiB
JSON

{
"schemaVersion": 1,
"runbooks": {
"FE-RB-001": {
"title": "boot 설정 실패",
"gateId": "FE-GATE-021",
"triggerKinds": ["BOOT_CONFIG_FAILURE"],
"containment": "제품 route mount를 멈추고, 안전한 지원 셸을 보여 주고, 다시 가져오기는 최대 한 번만 한다",
"window": "owner 분류(triage) 계획 기본값(planned-default) 5m",
"escalation": ["env-config owner", "release owner"],
"recoveryEvidence": [
"깨끗한 세션에서 boot",
"제품 root mount",
"config 검증",
"boot 오류 반복 없음"
],
"negativeFixture": "올바른 config 뒤에 mount 실패를 주입하면 복구가 실패해야 한다"
},
"FE-RB-002": {
"title": "chunk·manifest·배포 불일치",
"gateId": "FE-GATE-022",
"triggerKinds": [
"CHUNK_LOAD_FAILURE",
"RELEASE_MANIFEST_FAILURE",
"DEPLOY_MISMATCH"
],
"containment": "저장하지 않은 상태(dirty state)가 있으면 경고하고, manifest를 no-store로 한 번 가져오고, 보호된 reload를 한 번만 허용한다",
"window": "release owner 분류(triage) 계획 기본값(planned-default) 5m",
"escalation": ["release-cache owner", "hosting/CDN owner"],
"recoveryEvidence": [
"entry asset과 lazy asset에 접근 가능",
"release tuple 일치",
"두 번째 reload 차단",
"핵심 route smoke 시험"
],
"negativeFixture": "같은 release 쌍에서 두 번째 실패가 나면 reload하지 않아야 한다"
},
"FE-RB-003": {
"title": "백엔드 API 저하",
"gateId": "FE-GATE-023",
"triggerKinds": [
"TERMINAL_NETWORK_RATE",
"REQUEST_TIMEOUT_RATE",
"SERVER_FAILURE_RATE",
"SCHEMA_MISMATCH"
],
"containment": "재시도 상한을 늘리지 않고, 안전한 오래된(stale) 읽기를 보여 주고, 키 없는 mutation은 절대 재시도하지 않는다",
"window": "이동 구간(rolling) 5m trigger. 첫 분류 계획 기본값(planned-default) 10m",
"escalation": [
"api-client owner",
"백엔드 operation owner",
"release 호환성 owner"
],
"recoveryEvidence": [
"최종(terminal) 실패율이 기준선 수준",
"재시도 증폭 없음",
"핵심 읽기/쓰기 smoke 시험",
"스키마 fixture"
],
"negativeFixture": "키 없는 POST가 503을 받으면 재시도하지 않아야 한다"
},
"FE-RB-004": {
"title": "telemetry sink 실패",
"gateId": "FE-GATE-024",
"triggerKinds": ["TELEMETRY_FAILURE"],
"containment": "제품 흐름을 계속 쓸 수 있게 두고, queue에 상한을 두고, 실패하는 sink에 재귀로 보고하지 않는다",
"window": "platform 분류(triage) 계획 기본값(planned-default) 15m",
"escalation": ["관측(observability) owner", "telemetry platform owner"],
"recoveryEvidence": [
"제품 흐름 영향 없음",
"전송 자체 점검",
"queue가 상한 안에서 비워짐",
"금지 속성 없음"
],
"negativeFixture": "원본 URL과 query 데이터는 telemetry에서 지워져야 한다"
},
"FE-RB-005": {
"title": "일관된 release rollback",
"gateId": "FE-GATE-025",
"triggerKinds": ["RELEASE_BLOCKING_DEFECT"],
"containment": "이전의 불변 tuple을 고르고, asset/config/API 호환성을 확인하고, 원자적으로 바꾸고, smoke 시험을 한다",
"window": "provider 복구 목표 미정(TBD)",
"escalation": ["release-cache owner", "release 승인자/hosting owner"],
"recoveryEvidence": [
"호환성 gate",
"release 일관성 gate",
"핵심 smoke 시험",
"장애 타임라인에 release ID 기록"
],
"negativeFixture": "HTML build A와 asset manifest B 조합은 거절되어야 한다"
}
}
}