From 21dd9dc96c6c3a38730d5439d88366660809d130 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 21:34:21 +0900 Subject: [PATCH] =?UTF-8?q?docs(reviews):=20=EA=B3=B5=EC=9A=A9=20=EB=A6=AC?= =?UTF-8?q?=EB=B7=B0=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=EB=91=90=20=ED=8C=8C?= =?UTF-8?q?=EC=9D=BC=EC=9D=84=20design-docs=20=EC=A0=95=EB=B3=B8=20?= =?UTF-8?q?=ED=8F=AC=EC=9D=B8=ED=84=B0=EB=A1=9C=20=EB=B0=94=EA=BE=BC?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 리뷰 가이드와 실행 체크리스트는 백엔드·프론트 두 템플릿이 함께 쓰는 리뷰 기준인데 프론트 repo의 docs/reviews/ 안에 있었다. 소유자가 2026-11-06 design-docs로 옮기기로 정했고(위임 루프 설계 결정 D13), 정본이 design-docs main 5f35810에 들어갔다. 이 repo의 사본이 그대로 남으면 두 곳에 본문이 생겨 서로 갈라진다. 고른 방법 - 두 파일을 정본 위치만 적은 포인터로 바꿨다. 정본 경로는 design-docs 저장소 기준(conventions/...)으로, 링크 없이 코드 표기로 적었다. 다른 저장소라 상대 링크는 이 checkout에서 따라갈 수 없다. - 포인터에 절 번호가 정본에서도 같다는 것과, 옮기기 전 마지막 판을 읽는 git show 명령(가이드 003832b6, 체크리스트 752a61f2)을 적었다. 정본과 이 repo 판의 차이는 맨 위 "옮긴 기록" 블록과 서로 가리키는 링크뿐이라 절 번호는 바뀌지 않았다. - 파일 이름과 위치는 그대로 뒀다. CLAUDE.md와 지난 리뷰 문서가 이 경로를 가리키므로 링크가 끊기지 않는다. - docs/README.md의 reviews/ 행을 "가이드는 design-docs로 옮겼고 여기에는 포인터만 있다"로 고쳤다. - 버린 대안: 두 파일 삭제. CLAUDE.md 링크와 지난 리뷰 문서의 가이드 경로가 끊긴다. CLAUDE.md는 소유자 승인 대상이라 이 커밋에서 바꾸지 않는다. 위험과 한계 - design-docs를 받지 않은 환경(다운스트림 복사본, CI)에서는 정본을 열 수 없다. 이력이 있는 checkout은 git show 명령으로 옛 판을 읽는다. - CLAUDE.md는 여전히 포인터 파일을 리뷰 기준으로 가리킨다. 링크를 design-docs로 바꿀지는 소유자가 정한다. - verify:documentation은 docs/README.md 1절에서 링크한 문서만 보므로 포인터 두 파일 안의 경로는 검사하지 않는다. 검증 - desktop에서 corepack pnpm verify:documentation, corepack pnpm test:unit 통과. 로그는 desktop ~/d13-review-guide-pointer-logs/. - 기준 브랜치: PR #8 끝 fix/maturity-review-2026-11-06(1141969f). --- docs/README.md | 2 +- ...ATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md | 129 +- .../reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md | 1949 +---------------- 3 files changed, 32 insertions(+), 2048 deletions(-) diff --git a/docs/README.md b/docs/README.md index 70eeed54..8ee965f4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -87,5 +87,5 @@ checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 | 경로 | 내용 | |---|---| | [`superpowers/`](superpowers/) | 과거 작업 계획과 스펙 | -| [`reviews/`](reviews/) | 리뷰 결과와 리뷰 가이드. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다. `reviews/adapters/`는 지우지 않는다: INVENTORY의 행과 `operations/adapter-remediation-ledger.md`가 그 안의 리뷰로 링크한다 | +| [`reviews/`](reviews/) | 리뷰 결과. 리뷰 가이드와 실행 체크리스트는 2026-11-06에 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 두 개만 있다. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다. `reviews/adapters/`는 지우지 않는다: INVENTORY의 행과 `operations/adapter-remediation-ledger.md`가 그 안의 리뷰로 링크한다 | | [`../SPEC.md`](../SPEC.md), [`../tasks/`](../tasks/) | 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 그 라운드는 0.2.0(`CHANGELOG.md`)으로 끝났다. 그때 리뷰 문서(`reviews/2026-09-25-maturity-review/`)가 이 경로(`SPEC.md:18` 등)로 가리키므로 옮기지 않는다 | diff --git a/docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md b/docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md index 932dd689..df5241e2 100644 --- a/docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md +++ b/docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md @@ -1,123 +1,26 @@ -# Template 프로젝트 성숙도 리뷰 — 실행 체크리스트 +# Template 프로젝트 성숙도 리뷰 실행 체크리스트 — 옮긴 곳 -이 문서는 `TEMPLATE-MATURITY-REVIEW-GUIDE.md`의 **실행용 요약본**이다. 상세 판정 근거와 예외는 정본 가이드를 따른다. 체크리스트 자체를 별도 점수 체계로 사용하지 않는다. +이 체크리스트는 2026-11-06에 design-docs 저장소로 옮겼다. 이 파일에는 본문이 없고 정본 위치만 적는다. -## 1. 리뷰 시작 전에 고정 +- 정본: design-docs 저장소의 `conventions/template-maturity-review-execution-checklist.md` +- 정본이 들어간 design-docs main 커밋: `5f35810` (옮긴 커밋은 `ec44d5a`) +- 옮긴 이유: 리뷰 가이드가 실행 순서로 가리키는 짝 문서다. 가이드와 함께 옮겼다. +- 리뷰 가이드의 정본 위치: [`TEMPLATE-MATURITY-REVIEW-GUIDE.md`](TEMPLATE-MATURITY-REVIEW-GUIDE.md) -- 대상 저장소, 브랜치·커밋, 작업 트리 상태, 확인 시점 -- 템플릿/프로젝트의 사용 목적과 지원 실행 형태 -- 필수 요구, 데이터·권한 범위, 의존 시스템 -- 규모 목표와 운영 목표가 있는지 여부 -- 지원 기능·선택 기능·의도적 비지원 범위 -- 템플릿 책임과 사용 프로젝트 책임 -- 이번에 읽을 코드·설정·테스트 범위와 확인하지 못할 범위 +## 절 번호 -목표가 없는 항목은 임의로 만들지 않는다. 목표가 없어서 판단할 수 없으면 `미검증` 또는 `판단 보류`로 남긴다. +정본의 절 번호(1~10절)는 이 파일에 있던 판과 같다. 짝인 리뷰 가이드의 절 번호(0.1·0.3, 35, 36.x 등)도 정본 가이드에서 그대로다. -## 2. 대표 경로를 먼저 따라간다 +정본에서 달라진 것은 맨 위 "옮긴 기록" 인용 블록과, 첫 문단에서 리뷰 가이드를 가리키는 링크뿐이다. -전체 파일을 균등하게 훑기 전에 실제 사용 흐름과 고위험 흐름을 선택한다. +## 옮기기 전 판 -- 정상 사용자 흐름 1개 이상 -- 실패 시 피해가 큰 흐름 1개 이상 -- 기능 추가·변경·삭제 흐름 1개 이상 -- 필요하면 배포·복구·동시성·인증 경계 흐름 +옮기기 전 마지막 판은 이 repo 이력에 있다. 이 파일을 마지막으로 바꾼 커밋은 `752a61f2`다. -각 흐름에서 입력 → 정책 → 상태 변화 → 외부 I/O → 실패 → 사용자/운영 결과를 연결한다. +```bash +git show 752a61f2:docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md +``` -## 3. 28개 관점은 적용되는 것만 판정 +## 고칠 때 -- 적용 여부와 이유를 먼저 적는다. -- 목표 통제와 현재 통제를 분리한다. -- 근거 수준(E0~E4)과 통제 수준(M0~M4)을 혼동하지 않는다. -- 하나의 결함이 여러 관점에 걸리면 Finding은 하나로 두고 관련 관점만 연결한다. -- `미검증`을 완료율에서 빼지 않는다. - -## 4. 먼저 찾을 고위험 문제 - -- 데이터 손상·권한 우회·민감정보 노출 -- 결과 불명 쓰기와 잘못된 재시도·멱등성 -- 동시성 경쟁·중복 처리·오래된 작업자의 쓰기 -- 무제한 큐·병렬성·응답·메모리·재시도 -- 배포·마이그레이션·복구 중 중간 상태 -- CI/Guardrail이 있다고 문서에는 적혀 있지만 실제로 실행되지 않는 경우 - -## 5. 코드 품질은 “줄 수”보다 이해 부담과 보호 장치로 본다 - -대표 과제를 수행하면서 기록한다. - -- 어디서 시작했는가? -- 반드시 알아야 하는 개념은 무엇인가? -- 이름과 실제 책임이 달라 다시 탐색한 곳은 어디인가? -- 숨은 등록 순서·전역 상태·문자열 키·설정 규약이 있는가? -- 중요한 위험과 실패 의미를 가까운 코드·타입·계약에서 찾을 수 있는가? -- 같은 사실을 annotation·descriptor·config·실행 코드에 반복한다면 각각 독립적인 역할과 불일치 검출이 있는가? - -## 6. 추상화는 유지·내부화·통합·분리·제거 중에서 판단 - -각 추상화에 묻는다. - -- 없으면 어떤 중복 지식·외부 결합·테스트 어려움이 생기는가? -- 호출자는 성공·실패·비용·수명주기를 추상화만 보고 이해할 수 있는가? -- 일반 사용자가 플랫폼 내부 개념까지 알아야 하는가? -- 더 작은 구조로 바꿨을 때 보호하던 계약을 그대로 유지할 수 있는가? -- 복잡하지만 현재 요구와 위험에 비해 정당하다면 **현 상태 유지**도 유효한 결론이다. - -## 7. 중요한 설계 선택에는 Decision Explanation Test 적용 - -모든 한 줄에 적용하지 않는다. 객체 ownership, 공개 계약, 트랜잭션, 인가, retry/idempotency, cache, concurrency, module composition, template architecture처럼 계약·실패·유지비에 영향을 주는 선택에 적용한다. - -1. 무엇이 필요한가? -2. 반드시 지킬 성질은 무엇인가? -3. 현재 코드는 어떻게 보장하는가? 무엇은 보장하지 않는가? -4. 현실적인 대안은 무엇인가? -5. 각 대안의 정확성·복잡성·성능·실패 특성·변경/운영 비용은? -6. 확인한 현재 조건에서는 왜 이 선택인가? -7. 어떤 요구·측정·규모·의존 계약이 바뀌면 선택도 달라지는가? - -작성 당시 의도가 기록에 없으면 만들어내지 않는다. `작성자가 이렇게 생각했다`가 아니라 `현재 조건에서 이 선택을 유지할 근거는 ...`이라고 구분한다. - -## 8. Finding 작성 - -필수: - -- ID·제목 -- 성격: 확인된 결함 / 구조적 위험 / 미검증 / 개선 제안 -- 관련 관점 -- 현재 근거와 발생 조건 -- 영향 -- 심각도와 우선순위 -- 확실한 사실과 남은 가정 -- 최소 개선 방향 -- 비용·부작용 -- 완료 기준 -- 검증 방법 - -설계 선택·구조 변경이면 추가: - -- 현재 제약과 보호할 규칙 -- 이해 비용 -- 현실적인 대안과 차이 -- 단순화 후 보존해야 할 계약 -- 재검토 조건 - -단순 구현 결함이면 위 설계 선택 필드는 `적용 제외` 가능하다. 빈칸 대신 적용 제외 이유를 한 문장으로 남긴다. - -## 9. 제안보다 검증을 우선 - -- 구조적 위험은 가능한 경우 작은 변경·변이 실험으로 실제 검출 여부를 확인한다. -- 실제 DB·브라우저·CI·외부 의존성 동작이 필요한 주장은 가능한 환경에서 해당 수준까지 검증한다. -- 실행하지 못한 브라우저·CI·부하·복구 조건은 정적 근거만으로 검증 완료라고 쓰지 않는다. -- 문서의 “구현 완료” 표시는 증거가 아니라 주장으로 취급한다. - -## 10. 리뷰 종료 전 확인 - -- 현재 사용 가능한 범위와 보류 범위를 구분했는가? -- 차단 항목과 미검증 목록이 따로 있는가? -- 가장 중요한 Finding의 재현·검출 근거가 있는가? -- 단순화 제안이 기존 안전장치를 잃지 않는가? -- 중요한 기술 선택에 대해 `요구 → invariant → 현재 구현 → 대안 → trade-off → 선택 이유 → 재검토 조건`을 설명할 수 있는가? -- 수정하지 않는 것이 최선인 구조도 그렇게 기록했는가? -- 구현자가 “무엇을 바꾸면 끝나는지”와 “어떻게 다시 검증하는지”를 알 수 있는가? - -충분한 근거가 모이면 리뷰를 끝낸다. 기준을 채우기 위해 새 프레임워크·불필요한 문서·장식성 메타데이터·중복 테스트를 추가하지 않는다. +체크리스트를 고칠 일이 생기면 design-docs의 정본을 고친다. 이 파일에 본문을 다시 넣지 않는다. 두 곳에 본문이 있으면 서로 갈라진다. diff --git a/docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md b/docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md index 55a702d3..947ed12c 100644 --- a/docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md +++ b/docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md @@ -1,1945 +1,26 @@ -# Template 프로젝트 성숙도 리뷰 가이드 — 상세 보강판 +# Template 프로젝트 성숙도 리뷰 가이드 — 옮긴 곳 -작성일: 2026-09-25 -수정일: 2026-09-28 — 설계 의도·코드 표현력과 설계 선택 설명 검증 기준 보강 -대상: Backend Template, Frontend Template, Platform Template 및 이를 사용하는 프로젝트 -기반 문서: 첨부된 `TEMPLATE-MATURITY-REVIEW-GUIDE(1).md` -목적: 코드의 정확성, 변경 비용, 위험의 가시성, 운영·복구 능력을 근거로 판단하는 리뷰 기준서 +이 가이드는 2026-11-06에 design-docs 저장소로 옮겼다. 이 파일에는 본문이 없고 정본 위치만 적는다. -이 문서는 원문의 **28개 관점과 번호를 유지**하면서 각 관점을 실제로 검토하고 판정하는 방법을 보강한 통합본이다. 원문 뒤에 체크리스트만 덧붙이지 않고, 과도하게 단정한 기준은 본문에서 바로잡았다. +- 정본: design-docs 저장소의 `conventions/template-maturity-review-guide.md` +- 정본이 들어간 design-docs main 커밋: `5f35810` (옮긴 커밋은 `ffbd902`) +- 옮긴 이유: 백엔드·프론트 두 템플릿이 함께 쓰는 리뷰 기준이다. 소유자가 2026-11-06에 design-docs로 옮기기로 정했다(design-docs `delegation-loop/02-design.md` 결정 D13). +- 짝 문서인 실행 체크리스트도 같이 옮겼다: [`TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`](TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md) -사용 중인 Backend·Frontend 템플릿의 현재 코드는 이 가이드 보강 작업에서 검사하지 않았다. 아래 코드·시나리오·수치는 설명용이며, 해당 템플릿에서 발견된 결함이나 측정 결과를 뜻하지 않는다. 2026-09-28에 추가한 오픈소스 사례는 GitHub 원문을 확인했으며 확인 범위와 한계를 40절에 적었다. 근거 자료는 38절에 정리했다. 평가 방식과 완료 기준은 이 가이드의 제안이며 공인 인증 체계가 아니다. +## 절 번호 -## 먼저 읽을 부분 +정본의 절 번호는 이 파일에 있던 판과 같다. 0.1·0.3, 28개 관점(1~28절), 35절, 36.1~36.5절 모두 같은 번호로 찾으면 된다. `CLAUDE.md`와 지난 리뷰 문서가 적은 절 번호도 정본에서 그대로 통한다. -- 전체 관점과 적용 범위: 0절 -- 원문과 같은 번호로 정리한 상세 기준: 1~28절 -- 코드에서 위험을 드러내는 구체적인 방법: 29절 -- 템플릿의 기본값·선택 기능·업데이트 전파: 30절 -- Backend / Frontend / Platform별 검증 시나리오: 31~33절 -- 실제 리뷰 순서와 측정 방법: 34절 -- 심각도·성숙도·증거 수준·완료 판정: 35절 -- 그대로 사용할 수 있는 리뷰 결과 양식: 36절 -- 원문에서 교정한 내용과 근거 자료: 37~38절 -- 설계 의도·코드 표현력과 안전한 단순화: 39절 -- 인용된 오픈소스에서 확인한 사실과 비교의 한계: 40절 -- 기초 코드부터 시스템 설계까지 선택의 이유를 설명하는 공통 검토 방식: 41절 -- 실제 리뷰 실행 순서만 빠르게 적용할 때: 동봉된 `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` +정본에서 달라진 것은 맨 위 "옮긴 기록" 인용 블록과, 실행 체크리스트를 가리키는 두 곳(「먼저 읽을 부분」, 36절 끝)의 링크뿐이다. -2026-09-28 보강은 평가 항목을 추가하는 대신 기존 관점을 연결한다. 39절은 4·5·9·10·21·22·24번을 연결해 **“중요한 동작과 선택 이유를 이해하는 데 필요한 부담이 줄었으며, 기존의 보호 장치는 유지되는가?”**를 묻는다. 41절은 모든 관점에 적용하는 설명 방식이다. **“현재 조건에서 왜 이 선택이 타당하며, 무엇을 보장하지 못하고, 어떤 조건이면 선택이 달라지는가?”**까지 근거를 들어 답할 수 있어야 한다. +## 옮기기 전 판 -## 0. 숙련된 리뷰어가 가장 먼저 확인하는 것 +옮기기 전 마지막 판은 이 repo 이력에 있다. 이 파일을 마지막으로 바꾼 커밋은 `003832b6`이다. -숙련된 리뷰어는 “이 패턴이 유행하는가”보다 **이 구조가 어떤 실수를 막고, 어떤 비용을 남기는가**를 묻는다. 메서드가 짧아도 중요한 부작용을 숨기면 읽기 어려운 코드다. 모듈이 많아도 한 기능을 바꿀 때 전부 알아야 한다면 변경 경계가 약하다. - -템플릿은 이 질문이 더 중요하다. 사용자는 샘플 코드와 기본값을 권장 방식으로 받아들이기 쉽다. 잘못된 재시도 정책이나 권한 처리 예제가 여러 프로젝트로 복제되면, 원본을 고친 뒤에도 사용 프로젝트에는 결함이 남을 수 있다. - -리뷰를 시작할 때 다음 다섯 질문에 답한다. - -1. **정확성:** 동시에 실행되거나 일부만 실패해도 지켜야 할 규칙은 무엇인가? -2. **이해 가능성:** 기능을 바꾸는 사람이 반드시 알아야 할 계약을 가까운 곳에서 찾을 수 있는가? -3. **변경·장애 범위:** 한 번의 실수로 어떤 데이터·사용자·프로젝트까지 영향을 받는가? -4. **운영·복구:** 문제가 생겼다는 사실을 발견하고, 원인을 좁히고, 정상 상태로 복구할 수 있는가? -5. **지속 비용:** 다음 기능 추가, 라이브러리 업그레이드, 담당자 교체 때도 이 구조의 비용을 감당할 수 있는가? - -### 0.1 평가 전에 고정할 전제 - -기준만 정하고 전제를 비워 두면 리뷰가 취향 경쟁으로 바뀐다. 다음 표부터 채운다. - -| 전제 | 기록할 내용 | 판정에 미치는 영향 | -| --- | --- | --- | -| 사용 목적 | 학습용, 사내 서비스 시작점, 외부 배포용 템플릿 등 | 요구할 운영 증거와 지원 범위가 달라진다. | -| 사용자와 팀 | 사용 프로젝트 수, 작성자 외 사용자, 예상 담당자 | 복제 범위와 인수인계 비용을 판단한다. | -| 지원 실행 형태 | 단일 프로세스, 다중 인스턴스, 브라우저, SSR 등 | 메모리 상태·락·세션의 안전 범위가 달라진다. | -| 데이터와 권한 | 공개·개인·민감 데이터, 관리자 기능, 테넌트 여부 | 정보 유출·오작동의 피해를 판단한다. | -| 규모 목표 | 요청량, 데이터량, 기능 수, 동시 개발자, 배포 빈도 | 부하와 구조 확장성을 따로 검증한다. | -| 의존 시스템 | DB, 캐시, 인증 서버, 외부 API, 메시지 시스템 | 실패·복구 시나리오를 선정한다. | -| 운영 목표 | 허용 실패율·지연, 허용 데이터 손실, 복구 시간 | 성능·가용성·복구의 합격 기준을 정한다. | -| 지원·비지원 | 필수 기능, 선택 기능, 의도적으로 제공하지 않는 기능 | 없는 기능을 모두 결함으로 평가하지 않게 한다. | - -합의된 목표가 없으면 “대규모 운영 준비 완료” 같은 판정은 보류한다. 그 대신 무엇까지 확인했고 어떤 전제가 비어 있는지 적는다. - -기술 선택에 대한 후속 질문에는 41절의 공통 질문을 적용한다. 요구와 규칙, 현재 구현, 현실적인 대안, 비용, 선택 이유, 재검토 조건을 연결한다. 모든 선택에 긴 문서를 요구하는 것은 아니며, 현재 코드의 효과와 작성 당시의 의도는 구분한다. - -### 0.2 템플릿 자체와 사용 프로젝트의 책임 - -| 항목 | 템플릿이 제공할 책임 | 사용 프로젝트가 결정·검증할 책임 | -| --- | --- | --- | -| 오류 처리 | 오류 분류·전달 방식과 안전한 기본 처리 | 도메인별 사용자 행동과 업무 보상 | -| 외부 호출 | 시간 제한·재시도 정책을 지정할 수 있는 계약 | 상대 API의 멱등성, 실제 지연에 맞춘 값 | -| 인증·인가 | 신뢰 경계, 확장 위치, 허용·거부 예제 | 역할·리소스 소유권·테넌트 정책 | -| DB 변경 | 마이그레이션 실행 방식과 호환성 지침 | 실제 데이터 규모에서의 락·백필 영향 | -| 관측 | 버전·요청 연결, 민감정보 보호, 수집 연결점 | 업무별 지표·알림 기준·대응 담당자 | -| 복구 | 선택한 구성의 복구 절차와 검증 예제 | 실제 인프라·데이터로 복구 시간·손실 검증 | -| 프론트 상태 | 요청 상태·캐시·세션 경계의 기본 계약 | 화면별 UX와 데이터 유효성 규칙 | - -책임을 나눈다고 템플릿의 위험한 기본값을 정당화할 수는 없다. 반대로 템플릿에 모든 서비스의 SLO나 복구 시간을 하드코딩할 필요도 없다. - -### 0.3 28개 관점의 관계 - -| 묶음 | 해당 관점 | 함께 답해야 할 질문 | -| --- | --- | --- | -| 정확성과 계약 | 1, 11, 12, 15, 17 | 무엇을 언제 누가 바꿀 수 있고, 실패 후 무엇이 남는가? | -| 구조와 이해 | 2, 3, 4, 5, 9, 22, 23, 24 | 읽는 사람이 변경 위치와 위험을 예측할 수 있는가? | -| 실패와 운영 | 6, 7, 8, 18, 19, 28 | 실패를 제한하고 발견·진단·복구할 수 있는가? | -| 성장과 비용 | 13, 14, 16, 25, 26, 27 | 규모와 시간이 늘 때 무엇이 병목이 되는가? | -| 재사용의 안전장치 | 10, 20, 21 | 다른 사람이 사용해도 실수를 빨리 발견하는가? | - -하나의 결함이 여러 관점에 걸칠 수 있다. 예를 들어 무제한 재시도는 실패 처리·성능·운영 문제를 함께 만든다. **발견 사항은 하나로 기록하고 관련 관점을 연결한다.** 같은 결함을 세 번 세어 심각성을 부풀리지 않는다. - -## 1. 코드 성숙도 — Code Maturity - -### 판단할 것 - -도메인의 중요한 규칙이 생성·변경 경로에서 실제로 지켜지는지 본다. 메서드 길이, `record` 사용 여부, setter 개수만으로 판정하지 않는다. 어떤 상태를 허용하며, 잘못된 상태가 저장되기 전에 어디서 차단되는지가 중심이다. - -예를 들어 주문의 `status`를 열거형으로 바꿔도 취소된 주문을 결제 완료로 바꿀 수 있다면 상태 전이 문제는 남아 있다. `markPaid()`라는 이름도 결제 확인·중복 처리·동시 변경을 저절로 보장하지 않는다. - -### 확인 질문과 증거 - -1. 지켜야 할 규칙을 먼저 문장으로 적을 수 있는가? 객체 생성자, 팩터리, 상태 변경 메서드와 대조한다. -2. HTTP 입력 외에 배치·메시지·테스트·관리자 도구에서도 같은 규칙이 유지되는가? 진입 경로를 따라간다. -3. 외부가 수정 가능한 컬렉션이나 공개 필드로 검증을 우회할 수 있는가? -4. `null`, 빈 값, 누락, 아직 계산되지 않은 값이 서로 다른 의미라면 구분되어 있는가? -5. 타입 단언·역직렬화·ORM 복원처럼 생성 규칙을 우회할 수 있는 경로가 있는가? - -**위험 신호:** UI 검증만 믿고 서버나 도메인에서 잘못된 값을 허용한다. 정상 생성 경로는 안전하지만 공개 setter로 불변식을 깨뜨릴 수 있다. - -**개선 완료 기준:** 허용·금지 상태 전이가 설명되고, 주요 변경 경로에서 같은 규칙을 지키며, 잘못된 입력과 상태 전이를 검증하는 테스트가 있다. 여러 요청 사이의 규칙은 12절의 DB 제약·동시성 검증까지 연결한다. - -**과도한 적용을 피할 점:** 전달용 DTO의 단순 필드를 모두 도메인 객체로 감싸거나, 의미가 없는 전용 예외를 필드마다 만들 필요는 없다. `IllegalArgumentException`도 내부 프로그래밍 계약 위반을 표현하는 데 적절할 수 있다. - -## 2. 구조적 성숙도 — Architectural Maturity - -### 판단할 것 - -폴더 배치와 실제 의존성·실행 경로가 일치하는지 본다. 소스 코드가 의존하는 방향과 런타임 호출 방향도 구분한다. 애플리케이션이 자신이 정의한 저장소 포트를 호출하고 외부 어댑터가 구현한다면, 런타임 호출은 바깥으로 나가도 소스 의존성을 안쪽에 둘 수 있다. - -### 확인 질문과 증거 - -1. 대표 기능 하나에서 UI·입력 처리, 정책, 저장·외부 호출의 책임을 구분할 수 있는가? -2. 다른 기능의 내부 파일을 직접 import하는가, 명시한 공개 계약을 사용하는가? -3. `common`, `shared`, 전역 registry가 사실상 모든 기능의 정책을 알고 있지 않은가? -4. 부트스트랩에서 구현체를 조립하는가, 업무 코드가 전역 컨테이너를 뒤져 의존성을 찾는가? -5. 금지 의존성을 실제로 한 번 넣으면 빌드·lint·아키텍처 검사가 실패하는가? - -증거는 디렉터리 그림보다 실제 import, 패키지 공개 범위, 모듈 의존성, 조립 코드, 위반 검출 결과다. - -**개선 완료 기준:** 지원하는 경계가 명시되어 있고, 핵심 경계를 우회하는 대표 경로를 검출한다. 기능 추가·제거 시 어디를 바꾸는지도 예측할 수 있다. - -**판정 주의:** 프레임워크 어노테이션이 도메인 안에 있다는 사실만으로 결함을 확정하지 않는다. 프레임워크와의 분리를 목표로 선언했는지, 결합 때문에 어떤 변경·테스트 비용이 생기는지 확인한다. 작은 CRUD 템플릿에 다층 구조를 강제하는 것이 더 비쌀 수 있다. - -TypeScript `paths`는 경로 해석을 돕는 설정이다. 그 자체를 접근 금지 규칙이나 런타임 경계로 취급하지 않는다. 경계 강제는 별도 검사·패키지 공개 범위와 실제 우회 검증으로 확인한다. [S4] - -## 3. 변경 용이성 — Changeability - -### 판단할 것 - -예상 가능한 변경을 실제로 따라가 보며, 바뀌어야 할 코드만 바뀌는지 본다. “확장 가능”이라는 선언보다 구체적인 변경 시나리오가 필요하다. - -### 확인할 변경 시나리오 - -- 오류 코드 하나를 추가한다. 서버 응답, 변환 계층, 화면 문구, 관측 정보가 어디서 연결되는가? -- 필터 조건 하나를 추가한다. 타입, API, 캐시 키, URL 상태에 중복 지식이 흩어져 있는가? -- 외부 API 제공자를 바꾼다. 제공자 고유 오류·시간 제한·인증 설정이 어디까지 전파되는가? -- 선택 기능 하나를 끈다. 관련 없는 앱이 설정 부족으로 시작하지 못하는가? - -파일 수뿐 아니라 **수정한 정책의 수, 깨지는 계약, 함께 배포할 단위, 필요한 팀 협의**를 기록한다. 파일 8개를 예측 가능하게 바꾸는 구조가 거대한 파일 1개에서 여러 정책을 함께 바꾸는 구조보다 안전할 수 있다. - -**위험 신호:** 같은 목록·분기·스키마를 여러 곳에서 손으로 맞춰야 한다. 기능 하나를 추가할 때 관계없는 기능의 초기화·테스트가 깨진다. - -**개선 완료 기준:** 변경 시나리오의 수정 위치와 확인할 테스트가 설명되며, 빠뜨린 계약 변경이 검출된다. 호환성을 깨는 변경에는 사용 프로젝트의 이행 방법이 있다. - -**과도한 적용을 피할 점:** 구현체가 하나인 인터페이스도 외부 I/O, 테스트 대역, 모듈 경계를 분리한다면 가치가 있다. 반대로 언젠가 쓸 것이라는 이유만 있는 factory·provider·strategy 연쇄는 현재 변경 사례로 효용을 입증해야 한다. - -## 4. 인지 부하 — Cognitive Load - -### 판단할 것 - -작업 하나를 끝내는 동안 사람이 동시에 기억해야 하는 **규칙과 예외의 수**를 본다. 파일 수와 호출 깊이는 보조 지표다. 이름이 명확한 여러 파일보다 전역 상태와 숨은 규약이 얽힌 한 파일이 더 어려울 수 있다. - -### 리뷰 방법 - -작성자에게 먼저 설명을 듣기 전에 대표 과제를 수행해 본다. 예를 들어 “목록 조회가 어느 API를 호출하고, 실패하면 어떤 화면을 보여 주는지 찾기”를 선택한다. - -| 관찰할 것 | 기록 예시 | -| --- | --- | -| 시작점 발견 | 어떤 검색어로 어디서 진입했는가? | -| 필수 지식 | 라우팅·DI·캐시·정책 중 무엇을 동시에 알아야 했는가? | -| 뜻밖의 이동 | 이름과 실제 책임이 달라 다시 찾은 곳은 어디인가? | -| 숨은 전제 | 등록 순서·문자열 키·전역 설정을 기억해야 했는가? | -| 오류 설명 | 실패 원인을 발견하는 데 어떤 정보가 부족했는가? | - -**위험 신호:** 타입을 따라가도 실제 구현체를 찾을 수 없다. 정상 흐름보다 설정 상속과 예외 규칙을 이해하는 시간이 길다. 핵심 위험은 공통 실행기 깊숙이 숨어 있다. - -**개선 완료 기준:** 대표 과제의 진입점·실행 흐름·실패 분기를 작성자의 구두 설명 없이 찾을 수 있다. 탐색이 반복해서 막힌 지점을 이름·배치·계약·진단 메시지로 줄인다. - -**측정 주의:** “5분 안에 못 찾으면 실패”, “파일 5개 이하면 우수” 같은 기준을 보편적으로 적용하지 않는다. 동일한 과제와 비슷한 숙련도의 사람을 기준으로 전후를 비교한다. [S1] - -**설계 의도 확인:** 독자가 입력·출력·상태·부작용뿐 아니라, 중요한 분기를 지우거나 순서를 바꾸면 왜 문제가 되는지도 가까운 코드와 계약에서 설명할 수 있는지 본다. 단순 위임 뒤의 전역 규약을 계속 추적해야 한다면 파일이 짧아져도 인지 부하는 줄지 않는다. 역할별 필수 개념과 국소적 이해의 검토 방법은 39절을 따른다. - -## 5. 위험 가시성 — Risk Visibility - -### 판단할 것 - -호출자가 결정을 내리는 데 필요한 비용과 실패 의미가 호출부 가까이에 드러나는지 본다. 라이브러리 내부 구현을 모두 노출하는 것이 목표는 아니다. - -예를 들어 `repository.save()`만 보고 실제 SQL·락 방식을 모두 알 필요는 없다. 다만 커밋 시점, 충돌 가능성, 외부 부작용과의 일관성에 영향을 받는 호출자는 그 계약을 찾을 수 있어야 한다. - -### 확인할 위험 - -| 위험 | 코드나 계약에서 확인할 정보 | -| --- | --- | -| 네트워크 I/O | 외부 대상, 시간 제한, 취소·실패 의미 | -| 재시도 | 책임 계층, 대상 오류, 최대 시도·총시간, 중복 처리 조건 | -| 트랜잭션 | 시작·종료, 락 보유 구간, 외부 호출과의 관계 | -| 캐시 | 키 범위, 신선도, 무효화, 사용자·테넌트 분리 | -| 비동기 처리 | 완료 의미, 실패 전달, 순서·중복, 종료 시 처리 | -| 권한·삭제 | 검증 주체, 대상 범위, 감사, 되돌릴 수 있는지 | -| 자원 사용 | 조회·업로드·병렬 처리·큐 크기의 상한 | - -**확인 방법:** 이름, 타입, 포트 계약, 설정 위치, 구현, 실패 테스트를 함께 본다. `dangerous` 같은 단어를 이름에 붙였다고 가시성이 확보된 것은 아니다. - -**개선 완료 기준:** 중요한 호출의 시간·상태·실패 계약을 가까운 위치에서 찾을 수 있고, 구현과 테스트가 그 계약을 뒷받침한다. 29절에 Backend와 Frontend 예시를 상세히 제시한다. - -**가시성과 중복 선언:** 같은 위험을 어노테이션·descriptor·실행 코드에 반복해서 적는다면 각각 누가 읽고 무엇을 보장하는지 확인한다. 실행에 쓰는 정책, 독립적인 검증 기준, 단순 설명을 구분한다. 선언과 실행의 불일치를 검출할 수 없는 장식성 메타데이터는 별도의 유지 비용이다. 구체적인 판정은 39.5절을 따른다. - -## 6. 실패 성숙도 — Failure Maturity - -### 판단할 것 - -실패를 종류별로 구분하고, 실패 후 남는 상태를 설명할 수 있는지 본다. 특히 **시간 초과는 상대 작업이 수행되지 않았다는 증거가 아니다.** 응답을 잃은 성공을 단순 실패로 처리하면 재시도에서 부작용이 반복될 수 있다. - -### 확인 질문과 증거 - -1. 연결 실패, 지연, 권한 거부, 유효성 오류, 자원 고갈, 결과 불명을 구분하는가? -2. 외부 호출의 시간 제한과 상위 요청의 총시간 제한이 맞물리는가? -3. SDK·어댑터·서비스·호출 클라이언트에 재시도가 중첩되는가? -4. 재시도해도 되는 작업인지 판단할 근거가 있는가? 동일 작업 식별과 중복 처리 범위를 확인한다. -5. 일부 단계만 성공했을 때 저장할 상태, 재처리 방법, 사람이 확인할 방법이 있는가? -6. 큐·동시 실행·대기 요청이 무제한으로 쌓이지 않는가? - -재시도 횟수·간격·총시간을 제한하고, 부하를 증폭시키는 중첩 재시도를 점검한다. 오류 종류를 가리지 않는 재시도는 일시적 장애와 영구적 실패를 모두 악화시킬 수 있다. [S3] - -**위험 신호:** 실패를 빈 목록·기본값·성공 응답으로 바꿔 데이터가 없는 것처럼 보이게 한다. 쓰기 요청의 결과가 불명인데 새 식별자로 다시 실행한다. - -**개선 완료 기준:** 선정한 실패 조건을 주입했을 때 상태·응답·자원 사용이 계약대로 유지되고, 결과 불명 상태가 조회·조정 가능하다. - -**과도한 적용을 피할 점:** 모든 템플릿에 circuit breaker, bulkhead, DLQ, saga를 한꺼번에 넣지 않는다. 실제 실패 경로와 운영할 능력에 맞는 수단을 선택한다. - -## 7. 운영 성숙도 — Operational Maturity - -### 판단할 것 - -운영자가 사용자 영향, 영향 범위, 현재 버전, 가능한 대응을 확인할 수 있는지 본다. 관측 도구를 설치했다는 사실은 충분한 증거가 아니다. - -### 확인 질문과 증거 - -1. 성공률·지연·처리량·포화 상태 중 해당 서비스의 건강을 설명할 지표가 있는가? -2. 알림에 영향, 확인할 화면, 대응 담당자, 첫 조치가 연결되는가? -3. 배포 버전·설정 변경·기능 활성화 시점과 이상 발생을 연결할 수 있는가? -4. 메트릭 라벨에 사용자 ID·요청 ID처럼 값 종류가 끝없이 늘어나는 값을 넣고 있지 않은가? -5. 로그·트레이스 수집이 느리거나 실패해도 서비스가 과도하게 영향을 받지 않는가? -6. readiness와 liveness가 각각 어떤 결정을 위한 신호인지 명확한가? - -**원문의 기준 교정:** 사용자에게 문제가 생겼다는 증상 기반 알림은 정상적인 설계다. 알림마다 근본 원인을 미리 맞힐 필요는 없다. 사용자 영향과 대응 필요성을 알리고, 원인 분석에 필요한 내부 지표·로그를 연결하는지 평가한다. [S2] - -**개선 완료 기준:** 대표 장애에서 영향 탐지부터 원인 범위 축소까지의 경로가 확인된다. 알림을 보낸 사실뿐 아니라 사람이 실행할 다음 행동이 설명된다. - -**적용 범위:** 템플릿은 지표 연결점과 예제를 제공할 수 있지만, 실제 SLO·알림 임계값은 서비스 목표에 맞춰 결정한다. 외부 의존성 하나의 실패를 모든 인스턴스 재시작 조건으로 연결하는 설계는 장애를 키울 수 있으므로 별도로 검증한다. [S5] - -## 8. 디버깅 가능성 — Debuggability - -### 판단할 것 - -관측된 문제를 재현하거나 원인을 좁히는 데 필요한 맥락이 남는지 본다. 오류 메시지가 길거나 모든 객체를 로그로 출력한다고 디버깅이 쉬워지는 것은 아니다. - -### 확인 질문과 증거 - -- 클라이언트의 문의와 서버의 처리 기록을 연결할 식별자가 있는가? -- 도메인 오류, 외부 시스템 오류, 내부 결함을 구분하면서 원래 원인을 보존하는가? -- 프론트 오류를 배포 버전·화면·사용자 행동과 연결할 수 있는가? -- 비동기 메시지·배치에는 요청이 끝난 뒤에도 원인을 잇는 작업·이벤트 식별자가 있는가? -- 사용한 설정·기능 플래그를 비밀값 없이 확인할 수 있는가? -- 시간·난수·외부 응답을 통제해 문제를 재현할 수 있는가? - -**위험 신호:** 모든 실패를 `UNKNOWN_ERROR`로 바꾸고 원인을 버린다. 반대로 토큰·쿠키·폼 원문을 통째로 수집한다. 여러 계층이 같은 예외를 반복 기록해 실제 사건 수를 부풀린다. - -**개선 완료 기준:** 대표 실패 하나에 대해 문의 식별자에서 관련 코드·버전·의존 호출·실패 분기로 이어지는 경로를 확인한다. 필요한 진단 정보와 사용자에게 보여 줄 정보를 구분한다. - -**판정 주의:** 사용자에게 일반적인 오류 문구를 보여 주는 것은 결함이 아닐 수 있다. 내부에는 원인과 연결 정보가 남고, 사용자에게는 안전한 안내와 문의 식별자가 제공되는지 본다. - -## 9. 유지보수 성숙도 — Maintainability - -### 판단할 것 - -3절이 개별 요구사항의 변경 비용을 본다면, 여기서는 **시간이 지나며 쌓이는 변경·업그레이드·인수인계 비용**을 본다. 최초 작성자만 구조를 이해하는 상태는 유지보수 증거가 약하다. - -### 확인 질문과 증거 - -1. 자주 바뀌는 코드와 장애가 자주 생기는 코드가 겹치는가? 변경 이력·결함 이력을 함께 본다. -2. 공통 모듈 변경 시 영향을 받는 소비자를 찾을 수 있는가? 공개 API와 실제 사용처를 확인한다. -3. 임시 우회·deprecated 경로·기능 플래그에 제거 조건과 담당자가 있는가? -4. 버전 업그레이드가 누적되어 작은 변경을 할 때도 한꺼번에 해결해야 하는가? -5. 설계 문서는 현재 선택의 이유·한계·변경 조건을 설명하는가, 코드 내용을 길게 반복하는가? -6. 담당자가 바뀌어도 대표 변경과 장애 대응을 수행할 수 있는가? - -**위험 신호:** 반복해서 바뀌는 전역 파일 하나에 여러 기능이 얽힌다. 잘못된 공통화를 유지하려고 기능별 예외 인자가 계속 늘어난다. 사용하지 않는 호환 코드의 제거 책임이 없다. - -**개선 완료 기준:** 주요 변경의 영향 소비자와 검증 범위를 찾을 수 있다. 오래된 경로를 정리할 수 있고, 다음 업그레이드 비용이 추정 가능하다. - -**판정 주의:** 코드가 비슷하다고 공통화하면 서로 다른 정책의 변경 시점까지 묶일 수 있다. 반대로 같은 권한·정산 규칙이 복제되어 따로 바뀌는 것은 중복 지식의 위험이다. 무엇을 함께 바꿔야 하는지를 기준으로 판단한다. - -**의사결정의 유지보수:** 현재 제약과 선택 이유를 Git 이력에서 매번 발굴해야 하는지도 본다. 과거 리뷰 번호만 남긴 주석은 이해를 돕기 어렵다. 반면 버그의 재발 조건이나 호환성 제약을 설명하는 주석과 원본 이슈·명세 링크는 유지할 이유가 있다. 주석의 수나 이력 링크의 유무로 품질을 판정하지 않는다. - -## 10. 테스트 성숙도 — Test Maturity - -### 판단할 것 - -테스트가 어떤 사고를 막고, 실패했을 때 무엇이 잘못됐는지 알려 주는지 본다. 테스트 수·커버리지·Given/When/Then 표기만으로 품질을 판정하지 않는다. - -| 검증 대상 | 적합한 증거의 예 | -| --- | --- | -| 규칙·상태 전이 | 유효·무효 경계값과 금지 전이 테스트 | -| DB 제약·트랜잭션 | 실제 DB 동작을 사용하는 통합 테스트 | -| 외부 계약 | 직렬화·필수 필드·오류·호환성 검증 | -| 의존성 경계 | 금지 import를 실제로 검출하는 검사 | -| 핵심 사용자 흐름 | 로그인·조회·저장·실패 복귀 등의 E2E | -| 경쟁·시간 | 동시 실행, 응답 순서 역전, 만료 경계 테스트 | -| 복구 | 중단된 작업의 재개·중복 억제·정합성 검증 | - -### 확인 질문 - -- 중요한 분기 하나를 잘못 바꾸면 관련 테스트가 실패하는가? -- 테스트가 실제 정책을 검증하는가, mock 호출 순서를 그대로 복사했는가? -- 테스트 간 시간·전역 상태·DB 데이터가 새어 실행 순서에 의존하는가? -- 실패 시 입력·기대 상태·실제 상태가 구분되는가? -- 재시도로 통과한 flaky test가 정상 통과로 숨겨지는가? -- 개발자가 자주 사용하는 빠른 검증과 배포 전 필요한 검증이 구분되는가? - -**개선 완료 기준:** 주요 위험마다 그것을 검출하는 검증이 연결되고, 실패 원인이 좁혀진다. 결함을 일부러 넣어 검출력을 확인할 때는 대표적인 고위험 규칙만 선정해 비용을 제한한다. - -**판정 주의:** 같은 기능을 단위·통합·E2E에서 다룬다고 무조건 중복은 아니다. 각 계층이 서로 다른 실패를 잡는다면 가치가 있다. 반대로 같은 구현 세부사항만 반복 검증하면 유지 비용만 늘어난다. [S1] - -**설계 결정을 보호하는 테스트:** 중요한 분기나 경계를 단순화한다면 그 결정이 막던 실패를 검증한다. 예를 들어 완료된 요청의 정리가 새 요청의 핸들을 지우지 않는지 확인한다. private helper 이름·정확한 호출 순서 같은 구현 세부사항을 그대로 고정하지 않고, 보호할 상태와 외부 동작을 검증한다. - -## 11. 데이터 성숙도 — Data Maturity - -### 판단할 것 - -데이터가 생성·변경·조회·이관·보관·삭제되는 전 과정에서 정확성과 접근 범위가 유지되는지 본다. 코드 롤백과 데이터 복구를 같은 일로 취급하지 않는다. - -### 확인 질문과 증거 - -1. 중요한 유일성·참조·범위 규칙이 동시 요청에서도 유지되는가? 애플리케이션 검사와 DB 제약을 함께 본다. -2. 신·구 애플리케이션이 공존할 때 스키마와 데이터 의미가 모두 호환되는가? -3. 백필을 나눠 실행하고, 중단 후 재개하며, 누락·불일치를 검출할 수 있는가? -4. 인덱스 생성·제약 추가·대량 수정의 락과 부하를 실제 DB 제품·버전·데이터 규모에서 확인했는가? -5. 페이지네이션에 안정된 정렬과 상한이 있는가? 데이터 변경 중 중복·누락 가능성을 계약으로 설명하는가? -6. 개인정보·로그·백업·파생 캐시의 보관과 삭제 범위가 연결되는가? -7. 백업을 복구한 뒤 업무상 정합성까지 확인하는가? - -### 마이그레이션에서 볼 순서 - -확장 가능한 스키마 준비, 호환되는 읽기·쓰기 배포, 이력 데이터 이관, 검증, 읽기 전환, 구버전 쓰기 종료 확인, 오래된 구조 제거의 순서를 검토한다. 실제 순서는 변경 유형에 따라 달라진다. - -**주의:** dual write는 필수 단계가 아니다. 두 쓰기의 불일치, 구버전 애플리케이션의 계속된 쓰기, 백필과 실시간 갱신의 경쟁을 해결할 수 있어야 한다. 코드만 이전 버전으로 돌려도 새로 기록한 데이터가 이해되지 않을 수 있다. - -**개선 완료 기준:** 전환 중간 상태와 중단·복구 방법이 정의되고, 실제 이관 결과를 확인할 수 있다. 오래된 열·데이터를 지울 때는 사용 중인 소비자와 복구 가능 기간을 확인한다. - -## 12. 동시성 성숙도 — Concurrency Maturity - -### 판단할 것 - -동시에 실행되는 주체와 공유 자원을 먼저 찾는다. 서버 요청뿐 아니라 배치·스케줄러·메시지 소비자·브라우저 탭·SSR 요청도 포함한다. - -### 확인 질문과 증거 - -- 두 요청이 같은 데이터를 읽은 뒤 각각 수정하면 갱신이 유실되는가? -- “존재 확인 후 생성” 사이에 다른 요청이 끼어들 수 있는가? -- 여러 인스턴스가 동일 예약 작업을 실행하거나 같은 세션을 갱신할 수 있는가? -- 락 범위·트랜잭션 격리 수준·유일성 제약·버전 검사의 역할이 구분되는가? -- 락을 잃었거나 작업 소유권이 바뀐 뒤 이전 작업자가 계속 쓰면 어떻게 되는가? -- 느린 과거 검색 응답이 더 최신 응답을 덮어쓸 수 있는가? - -**증거:** 공유 상태의 소유자, 원자적으로 처리되는 구간, 충돌 처리 계약, 동시 실행 테스트, 실제 저장소에서 확인한 최종 상태다. - -**위험 신호:** 다중 인스턴스를 지원하면서 정합성을 프로세스 내부 락 하나에 의존한다. 분산 락을 도입했지만 임대 만료 후의 오래된 작업자 쓰기를 고려하지 않는다. - -**개선 완료 기준:** 선정한 경쟁 조건에서 허용하는 최종 상태와 충돌 응답이 재현된다. 재시도가 필요한 경우 같은 논리적 작업인지 식별한다. - -**적용 범위:** 단일 프로세스로 범위를 제한한 기능에서는 로컬 락이 합리적일 수 있다. 무조건 분산 락을 추가하지 말고 DB 조건부 갱신·제약·소유권 모델로 충분한지 먼저 본다. 시간·TTL을 사용하는 규칙은 경계 시각과 시계 차이의 영향도 확인한다. - -## 13. 확장성 — Scalability - -### 판단할 것 - -무엇이 늘어나는지 나눠서 본다. 요청량을 견디는 능력과 기능·개발자 수를 견디는 능력은 다른 증거가 필요하다. - -| 증가하는 대상 | 살펴볼 병목 | 증거 | -| --- | --- | --- | -| 요청·사용자 | DB·외부 API·연결·큐·CPU 포화 | 부하별 처리량·지연·실패율·자원 | -| 데이터 | 쿼리 비용·인덱스·메모리·이관 시간 | 데이터량별 실행 계획·응답·복구 시간 | -| 기능·도메인 | 전역 등록·번들·타입 검사·탐색 | 기능 수별 빌드·시작·번들·변경 범위 | -| 개발자·팀 | 공통 파일 충돌·승인·릴리스 조율 | 변경 이력·대기·공동 변경 빈도 | -| 사용 프로젝트 | 패치 전파·버전 편차·지원 비용 | 버전 현황·이행 리허설·지원 기록 | - -### 확인 질문 - -기능 하나를 추가했을 때 모든 기능의 구현체를 로딩하는가? 전체 registry 순회가 요청마다 반복되는가? 한 사용자나 테넌트의 작업이 공유 자원을 독점하는가? 인스턴스를 늘려도 DB·락·중앙 조립 지점 하나가 한계를 결정하는가? - -**개선 완료 기준:** 목표 규모와 측정 환경을 명시하고, 어느 자원이 먼저 포화되는지와 그때의 동작을 설명한다. 기능 증가 시 변경 경계·빌드·번들 비용도 함께 확인한다. - -**과장 방지:** 이름만 다른 기능을 수천 개 생성한 실험은 구조적 증가 비용 일부를 보여 줄 뿐이다. 실제 정책 다양성·데이터·외부 의존성·사용자 흐름을 가진 수천 도메인의 운영 증거가 아니다. “1만 도메인 지원”보다 어떤 증가 축을 어떤 조건까지 확인했는지 기록한다. - -## 14. 성능 성숙도 — Performance Maturity - -### 판단할 것 - -빠르다는 주장보다 비용이 설명되고 한계가 통제되는지 본다. 한 번의 요청·화면 진입이 어떤 CPU, 메모리, DB 호출, 네트워크 호출을 발생시키는지 추적한다. - -### 확인 질문과 증거 - -1. 목록 한 번에 필요한 DB·외부 호출 수가 데이터 수에 비례해 늘어나는가? -2. 요청 크기·결과 개수·병렬 실행·큐 대기·캐시에 상한이 있는가? -3. 캐시가 차가울 때, 만료가 겹칠 때, 의존성이 느릴 때도 자원이 제한되는가? -4. 프론트엔드 초기 번들·경로별 로딩·렌더링·긴 작업의 비용을 측정했는가? -5. 평균 외에 지연 분포와 실패율을 함께 보는가? p95·p99를 해석할 표본과 부하 조건이 충분한가? -6. 단기 부하에서는 보이지 않는 메모리 누수·큐 증가·연결 누적이 있는가? - -### 측정 결과에 반드시 붙일 정보 - -하드웨어·런타임·버전·데이터량·요청 구성·동시성·캐시 상태·측정 시간·오류율을 기록한다. 부하 발생기가 목표 요청량을 실제로 전달했는지도 확인한다. 다른 조건의 평균값만 비교하지 않는다. - -**개선 완료 기준:** 목표 부하에서 합의한 지연·실패·자원 예산을 만족하고, 초과 시 무한 대기나 자원 고갈 대신 정의한 제한 동작을 보인다. - -**비용 관점:** 로그·트레이스 전송량, 외부 API 호출, 저장 공간, CI 실행 시간도 포함한다. 작은 지연 개선을 위해 운영비와 유지 비용이 크게 늘었다면 선택 이유가 필요하다. - -## 15. 보안 성숙도 — Security Maturity - -### 판단할 것 - -신뢰할 수 없는 입력이 들어오는 지점과 권한을 행사하는 지점을 찾는다. 인증 여부, 리소스 소유권, 테넌트, 관리자 권한을 구분한다. 내부 네트워크에 있다는 이유만으로 호출을 신뢰하지 않는다. - -### 확인 질문과 증거 - -- 인증한 사용자라도 다른 사용자의 ID로 조회·수정·다운로드할 수 있는가? -- 브라우저의 버튼 숨김·라우트 가드와 서버의 인가 검증이 구분되는가? -- 세션·토큰을 누가 보관하고 갱신·폐기하는가? 로그아웃 후 캐시·진행 중 요청에 이전 정보가 남는가? -- 쿠키 기반 흐름의 CSRF와 스크립트·HTML 처리의 XSS 위험을 각각 다루는가? -- CORS를 인증·인가 대신 사용하고 있지 않은가? -- 파일 경로·업로드·외부 URL 요청·동적 HTML처럼 입력이 다른 해석기에 전달되는 지점이 있는가? -- 브라우저 번들·오류 응답·진단 로그·저장소 이력에 비밀값이 포함되는가? -- 서비스 계정·CI·배포 도구의 권한이 필요한 범위로 제한되는가? - -**증거:** 데이터 흐름과 신뢰 경계, 인가 정책이 적용되는 코드, 금지된 접근의 거부 테스트, 비밀값 주입·교체·폐기 경로다. 객체 ID를 바꾸는 요청처럼 경계를 직접 확인하는 테스트가 필요하다. [S6] - -**개선 완료 기준:** 대표 허용·거부 시나리오가 서버에서 강제되고, 인증 상태·사용자·테넌트 변경 시 데이터가 섞이지 않는다. 수집·보관·공유하는 민감정보의 범위도 설명된다. [S9] - -**과도한 일반화 방지:** 인증 라이브러리를 썼다는 이유로 인가까지 검증됐다고 판단하지 않는다. 반대로 모든 템플릿에 특정 인증 서버나 비밀 관리 제품을 의무화하지 않는다. - -## 16. 의존성 성숙도 — Dependency Maturity - -### 판단할 것 - -의존성의 도입 이유, 유입 경로, 업데이트·교체 비용을 본다. 패키지 수만 세면 작지만 위험한 의존성과 크지만 잘 관리되는 의존성을 구분할 수 없다. - -### 확인 질문과 증거 - -1. 직접·전이 의존성과 실제 배포 산출물에 포함된 버전을 파악할 수 있는가? -2. 런타임·빌드 도구·패키지 관리자 버전과 잠금 정보가 일치하는가? -3. 보안 패치나 비호환 업그레이드를 소비자에게 전파할 담당자·절차가 있는가? -4. 외부 패키지의 타입·오류·데이터 모델이 핵심 정책까지 퍼져 교체 비용이 커졌는가? -5. 다운로드·설치·빌드 단계에서 실행되는 외부 코드와 권한을 파악하는가? -6. 라이선스 사용 조건과 유지 상태를 검토하는 책임자가 있는가? - -**공급망 증거:** 어떤 소스와 빌드 과정에서 배포물이 생성됐는지, 산출물 식별값과 출처 기록을 연결한다. SLSA의 provenance는 이처럼 산출물의 출처·생성과정을 추적하는 정보다. 출처 정보가 있다는 사실과 소프트웨어에 취약점이 없다는 주장은 별개다. [S8] - -**개선 완료 기준:** 대표 의존성 업데이트를 실제 빌드·테스트·배포 검증까지 수행할 경로가 있다. 탐지된 취약점의 영향·대응 여부와 지원 버전을 설명할 수 있다. - -**판정 주의:** 버전을 고정하는 것 자체는 위험 신호가 아니다. 재현 가능한 설치를 위해 필요할 수 있다. 문제는 고정 이유와 갱신 경로가 없거나, 잠금 정보가 실제 설치에서 무시되는 상태다. - -## 17. API / Contract 성숙도 — Contract Maturity - -### 판단할 것 - -HTTP API뿐 아니라 모듈 공개 타입, 이벤트, 설정, CLI, 생성 코드도 소비자가 의존하는 계약으로 본다. 문법상 호환과 의미상 호환을 구분한다. - -### 확인 질문과 증거 - -- 필드 누락·`null`·빈 값의 의미가 명확한가? -- 새 enum 값, 기본 정렬 변경, 오류 코드 변경을 기존 소비자가 견디는가? -- 페이지네이션의 정렬·커서 유효성·결과 변동 의미가 설명되어 있는가? -- 재전송한 쓰기 요청이 같은 작업인지 판단할 계약이 있는가? -- 이벤트의 순서·중복·스키마 변경·재처리 규칙이 정해져 있는가? -- 구버전 소비자와 신버전 제공자를 동시에 검증하는가? -- 폐기 예고 뒤 실제 사용자가 사라졌는지 확인하는가? - -**위험 신호:** 스키마에는 변화가 없지만 기본값이나 오류 의미가 바뀌어 클라이언트 동작이 달라진다. 생성된 타입만 믿고 신뢰 경계의 런타임 입력을 검증하지 않는다. - -**개선 완료 기준:** 공개 계약 변경이 리뷰에서 식별되고, 호환성 검사와 소비자 이행 방법이 연결된다. 깨지는 변경을 허용한다면 지원 버전·전환 기간·제거 조건을 명시한다. - -**판정 주의:** TypeScript 정적 타입이나 코드 생성은 외부 JSON의 런타임 유효성을 보장하지 않는다. 스키마 검사 역시 권한·상태 전이·업무 의미의 호환성까지 모두 증명하지는 않는다. - -## 18. 배포 성숙도 — Deployment Maturity - -### 판단할 것 - -빌드 성공 이후 실제 트래픽과 데이터가 안전하게 새 버전으로 이동하는지 본다. 배포는 코드·스키마·설정·정적 자산·캐시가 함께 바뀌는 과정이다. - -### 확인 질문과 증거 - -1. 검증한 산출물과 실제 배포한 산출물의 식별값이 같은가? -2. 신·구 서버, 오래 열린 브라우저, CDN의 이전 자산이 공존하는 동안 계약이 유지되는가? -3. 시작·준비 완료·트래픽 중단·종료의 순서가 정의되어 있는가? -4. 종료 중 요청·메시지·예약 작업이 완료·재전달·중단 중 무엇으로 처리되는가? -5. 마이그레이션과 애플리케이션 배포 순서가 서로의 전제를 만족하는가? -6. 이전 버전으로 돌릴 수 없는 데이터 변경이 있다면 전진 수정·보상·복구 계획이 있는가? -7. 배포 중단·되돌림 판단에 사용할 실제 사용자 영향 지표가 있는가? - -**위험 신호:** 롤백 명령은 있지만 새 버전이 쓴 데이터를 이전 버전이 읽지 못한다. 프론트 배포 후 기존 탭이 참조하던 청크 파일을 즉시 삭제해 화면 이동이 실패한다. - -**개선 완료 기준:** 지원하는 배포 방식의 중간 상태와 실패 복구를 확인한다. 코드 되돌림, 데이터 복구, 외부 부작용 조정의 차이를 운영 절차에서 구분한다. - -**적용 범위:** 모든 시스템이 rolling deployment를 지원해야 하는 것은 아니다. 계획된 중단이 허용된다면 중단 시간과 실행 절차를 검증한다. 여러 버전의 공존을 지원한다고 선언한 시스템에는 그 공존 검증이 필요하다. - -## 19. 설정 성숙도 — Configuration Maturity - -### 판단할 것 - -어떤 설정이 실제로 적용되고, 바뀌면 어떤 동작이 달라지는지 설명할 수 있는지 본다. 기본값·환경변수·파일·런타임 변경이 겹칠수록 우선순위가 중요하다. - -### 확인 질문과 증거 - -- 필수·선택·비밀·재시작 필요·실시간 적용 설정이 구분되는가? -- 잘못된 타입·범위·조합을 시작 시점이나 적용 시점에 검출하는가? -- 오타가 있는 키가 조용히 무시되는가? 검출 범위를 명시했는가? -- 선택하지 않은 기능의 설정까지 필수로 요구하는가? -- 보안상 위험한 개발 기본값이 운영 구성에 그대로 적용될 수 있는가? -- 현재 유효한 설정의 출처·버전·적용 시점을 비밀값 없이 확인할 수 있는가? -- 여러 인스턴스에 변경을 적용하는 중간 상태가 허용되는가? - -**개선 완료 기준:** 설정의 스키마·우선순위·기본값·검증 위치가 일치하고, 대표적인 잘못된 조합은 실행 전에 구체적인 오류로 드러난다. 설정 변경 실패 시 이전 상태 유지 여부도 정의한다. - -**판정 주의:** 모든 미설정 값을 오류로 처리하는 것이 안전한 것은 아니다. 선택 기능은 비활성화될 수 있어야 한다. 반대로 시간 제한을 무한대로 두거나 관리자 인증을 생략하는 식의 위험한 기본값은 명시적 선택과 제한이 필요하다. - -## 20. 개발자 경험 — Developer Experience - -### 판단할 것 - -템플릿 사용자가 처음 실행하고, 기능을 추가하고, 실패를 해결하는 과정을 본다. 작성자의 개발 환경에서 한 번 실행한 결과만으로 충분하지 않다. - -### 확인할 과제 - -1. 새 환경에서 필요한 런타임과 패키지 관리자를 확인한다. -2. 안내된 명령으로 의존성을 설치하고 샘플을 실행한다. -3. 테스트 하나를 실행하고 의도적인 입력 오류를 확인한다. -4. 작은 기능 하나를 권장 구조로 추가한다. -5. 기본 샘플이나 필요 없는 연동 하나를 제거한다. -6. 의존성 연결 실패·포트 충돌·필수 설정 누락에서 해결 방법을 찾는다. - -**문서에서 볼 것:** 명령은 한 줄에 한 목적을 두고, 작업 디렉터리·필요 조건·성공 시 보일 결과를 설명한다. 긴 합성 명령이나 숨은 전역 설치를 따라 해야 하는 구조는 시작 비용과 실패 비용을 높인다. 실제 제공되는 명령과 문서가 일치하는지도 확인한다. - -**개선 완료 기준:** 작성자 도움 없이 위 과제를 수행할 경로가 있고, 오류 메시지로 다음 행동을 결정할 수 있다. 생성물 중 사용자가 수정할 영역과 다시 생성될 영역을 구분한다. - -**과도한 적용을 피할 점:** 모든 개발 작업을 전용 CLI로 감쌀 필요는 없다. 이미 익숙한 빌드 도구의 명확한 명령으로 충분하다면 그 편이 유지 비용이 낮다. DX를 개선하려고 또 하나의 자체 프레임워크를 만들지 않는다. - -## 21. Guardrail 성숙도 — 실수 방지 장치 - -### 판단할 것 - -중요한 규칙 위반을 얼마나 이른 시점에, 이해 가능한 메시지로 잡는지 본다. 검사 도구의 개수보다 검출 범위와 우회 가능성이 중요하다. - -| 규칙 | 가능한 수단 | 확인할 우회 경로 | -| --- | --- | --- | -| 도메인 간 내부 import 금지 | lint·의존성 검사·공개 패키지 범위 | 상대 경로·재수출·생성 파일 | -| 잘못된 상태 생성 금지 | 생성·변경 API와 타입·런타임 검증 | 단언·역직렬화·직접 필드 변경 | -| 설정 범위 제한 | 스키마·시작 시 검증 | 다른 설정 소스·실시간 변경 | -| 중요한 정책 변경 검출 | 목적이 분명한 테스트·필수 CI 검사 | 검사 제외 경로·조건식·허용 목록 | -| 배포 권한 제한 | 계정 권한·배포 정책 | 다른 인증 정보·별도 배포 경로 | - -**확인 질문:** 규칙을 위반하는 작은 변경을 넣으면 실제로 실패하는가? CI 설정에 검사가 있어도 해당 변경에서 실행되는가? 실패를 무시하고 배포할 수 있다면 그 권한과 기록이 있는가? - -**개선 완료 기준:** 중요한 규칙의 대표 위반이 검출되고, 검사 메시지가 위반 위치와 해결 방향을 알려 준다. 예외에는 이유·범위·담당자·재검토 시점이 있다. - -**비용 기준:** 저위험 스타일 선호 때문에 복잡한 자체 검사기를 만들지 않는다. 표준 도구로 잡을 수 있는 규칙은 표준 도구에 맡기고, 사업 규칙은 코드와 의미 있는 테스트에 둔다. 빌드 스크립트에 모든 정책을 몰아넣는 것도 인지 부하를 높인다. - -**검사의 실제 효용:** 규칙을 위해 새 annotation이나 registry를 추가했다면 그것을 읽는 검사와 실제로 검출하는 위반 사례를 제시한다. 검사 통과만을 위해 같은 정보를 여러 곳에 적는 비용도 리뷰한다. 독립적인 요구 조건을 선언해 구현과 대조하는 검사는 가치가 있으므로 “중복 정보”라는 이유만으로 제거하지 않는다. - -## 22. 추상화 성숙도 — Abstraction Maturity - -### 판단할 것 - -추상화가 숨겨 주는 변동과 사용자가 추가로 배워야 하는 규칙을 비교한다. 구현체 수나 제네릭 매개변수 수로만 평가하지 않는다. - -### 확인 질문과 증거 - -1. 이 추상화가 없는 경우 어떤 중복 지식·외부 결합·테스트 어려움이 생기는가? -2. 호출자는 추상화만 보고 성공·실패·비용·수명주기를 이해할 수 있는가? -3. 구현체를 바꾸면 같은 계약을 지키는가? 예를 들어 로컬 메모리와 원격 저장소의 실패·일관성 차이를 숨기지 않았는가? -4. 기능별 예외를 처리하려고 boolean 인자, callback, 타입 단언이 계속 늘어나는가? -5. 추상화 일부를 제거하는 작은 실험에서 중요한 보호 기능을 잃지 않고 읽기가 쉬워지는가? - -**위험 신호:** 모든 업무를 범용 CRUD나 범용 executor에 맞추느라 도메인 의미가 문자열·맵·설정으로 이동한다. 타입을 이해하려면 관계없는 플러그인 체계까지 알아야 한다. - -**개선 완료 기준:** 추상화의 사용자가 알아야 할 계약이 짧고 안정적이며, 반복되는 실제 문제를 줄인다는 사례가 있다. 새로운 요구가 기존 추상화를 크게 비틀면 분리·단순화할 경로가 있다. - -**판정 주의:** 인터페이스 하나가 외부 네트워크·권한·저장 경계를 드러낸다면 구현체가 하나여도 충분한 이유가 된다. 반대로 구현체가 여러 개라는 사실만으로 잘된 추상화가 되지는 않는다. 상이한 실패 의미를 억지로 같은 성공 타입에 맞추고 있지 않은지 본다. [S1] - -**추가 완료 기준:** 추상화를 하나 줄이는 제안에는 실제 호출부의 변화, 없어지는 필수 개념, 유지해야 할 타입·실패·권한 계약을 붙인다. 제네릭 수를 줄이기 위해 `any`·강제 단언·느슨한 옵션 객체를 늘리거나, helper를 제거한 뒤 같은 정책을 여러 호출자가 구현한다면 개선으로 보지 않는다. 삭제 여부를 판단하는 질문은 39.6절에 정리했다. - -## 23. 일관성 — Consistency - -### 판단할 것 - -같은 의미가 같은 방식으로 표현되고, 다른 의미의 차이는 보존되는지 본다. 이름을 통일하는 과정에서 계약을 바꾸지 않아야 한다. - -### 구분해야 할 예 - -| 코드·패턴 | 확인할 의미 | -| --- | --- | -| `requireNonNull(value)` | 값이 null인지 검사한다. 빈 문자열이나 공백 검증과는 다르다. | -| `requireText(value)` | 프로젝트에서 정의한 계약을 읽어야 한다. null·빈 값·공백·정규화 중 무엇을 다루는지 확인한다. | -| 입력 검증 | 외부 요청을 받아들일 수 있는 형식·범위인가? | -| 도메인 검증 | 어떤 진입 경로에서도 지켜야 하는 업무 규칙인가? | -| 인가 검증 | 이 주체가 이 리소스에 이 작업을 수행해도 되는가? | - -### 확인 질문 - -오류 코드·날짜·시간대·금액·식별자·설정 이름이 기능마다 달라지는가? 같은 검증 이름이 다른 동작을 하는가? 테스트의 준비·실행·검증이 분리되어 읽히는가? 예외가 있다면 실제로 다른 문제를 풀기 때문인가? - -**개선 완료 기준:** 반복해서 만나는 계약과 작성 방식이 예측 가능하고, 예외는 이유를 설명할 수 있다. 공통 helper를 바꿀 때 기존 호출자의 계약 변화도 확인한다. - -**과도한 적용을 피할 점:** Given/When/Then 주석의 유무와 테스트 품질은 구분한다. 예외 검증처럼 실행을 callback에 넣는 라이브러리 관례도 있다. 팀이 명시한 형식을 지키면서 검증 책임이 흐려지지 않는지를 본다. 단순 표기 통일은 데이터·보안 결함과 같은 심각도로 취급하지 않는다. - -## 24. 네이밍 / 의미 성숙도 — Naming & Semantic Maturity - -### 판단할 것 - -이름을 읽은 사람이 예상한 동작과 실제 동작이 맞는지 본다. 긴 이름보다 의미의 일치가 중요하다. - -### 확인 질문과 증거 - -- `get`·`find`가 값이 없을 때 반환·예외·생성을 각각 어떻게 다루는가? -- `save`·`submit`·`publish`의 성공은 메모리 반영, DB 커밋, 큐 접수, 외부 처리 완료 중 무엇인가? -- `delete`가 논리 삭제인지 영구 삭제인지 구분되는가? -- `isAuthorized`가 로그인 여부만 검사하는 등 이름이 보장 범위를 과장하지 않는가? -- `timeoutMs`처럼 단위가 명확하고, `expiresAt`처럼 시각·기간이 구분되는가? -- 요청마다 다른 ID가 요청·업무 작업·이벤트 중 무엇을 식별하는지 알 수 있는가? - -**위험 신호:** `safe`, `validated`, `transactional`이라는 이름이 실제 보장을 뒷받침하지 않는다. `User`·`Account`·`Principal`을 구분 없이 섞어 소유권 판단이 어려워진다. - -**개선 완료 기준:** 중요한 업무 용어와 상태·실패 의미가 코드·계약·문서에서 일치한다. 이름으로 표현하기 어려운 보장은 짧은 계약 설명과 타입으로 보완한다. - -**판정 주의:** `execute()`, `handle()` 자체가 나쁜 이름은 아니다. `CancelReservationHandler.handle()`처럼 타입이 의미를 충분히 제공할 수 있다. 이름을 길게 만드는 것보다 호출 문맥까지 읽고 판단한다. - -**이름이 담을 수 없는 이유:** 이름과 타입은 동작·규칙을 표현하고, 짧은 주석은 예상 밖의 제약과 인과관계를 설명한다. 대안 비교가 길어지면 설계 기록으로 옮기고 코드 가까이에는 현재 선택의 이유와 링크를 남긴다. 모든 선택 이유를 클래스명이나 generic hierarchy로 표현하려 하지 않는다. - -## 25. 조직 확장성 — Organizational Scalability - -### 판단할 것 - -팀이 늘어날 때 변경·승인·배포를 얼마나 함께 맞춰야 하는지 본다. 독립 모듈과 독립 배포는 같은 개념이 아니다. - -### 확인 질문과 증거 - -1. 기능 팀이 작은 정책 변경을 할 때도 플랫폼 담당자에게 내부 구현 수정을 요청해야 하는가? -2. 전역 registry·공통 모델·번역 파일·부트스트랩 한곳에서 충돌이 반복되는가? -3. 공유 계약 변경은 사용처와 호환 범위를 확인하고 진행되는가? -4. 팀이 자율적으로 바꿀 수 있는 범위와 함께 합의해야 하는 범위가 명확한가? -5. 새 팀이 샘플과 공개 API만으로 기능을 추가할 수 있는가? -6. 승인·테스트·릴리스 대기 시간이 늘어나는 원인을 기록하는가? - -**증거:** 실제 공동 변경, 반복 충돌, 승인 대기, 함께 배포해야 하는 계약, 공통 모듈 수정 이력이다. 팀이 하나라면 실제 조직 확장 검증은 미확인으로 두고 구조적 준비만 평가한다. - -**개선 완료 기준:** 기능 변경의 책임과 공개 계약이 맞물리고, 공통 영역에 들어가는 이유를 설명할 수 있다. 긴급 패치 때 누가 무엇을 결정하는지 정해져 있다. - -**과도한 적용을 피할 점:** 팀 규모만 보고 마이크로서비스·멀티레포·독립 배포를 의무화하지 않는다. 하나의 배포물 안에서도 코드 소유권과 변경 경계를 나눌 수 있다. 분산으로 늘어나는 운영·계약 비용까지 비교한다. - -## 26. Ownership 성숙도 — 책임과 인수인계 - -### 판단할 것 - -문제가 생겼을 때 조사·수정·배포·복구·사용자 안내를 누가 맡는지 본다. 코드 소유자 파일에 이름이 있는 것과 실제 대응 책임이 연결되는 것은 다르다. - -### 확인 질문과 증거 - -- 템플릿 자체의 결함과 사용 프로젝트의 설정·업무 정책 결함을 누가 분류하는가? -- 공통 모듈의 패치를 누가 만들고 소비자에게 누가 적용하는가? -- 인증·배포·데이터 복구처럼 여러 책임이 겹칠 때 최종 결정자는 누구인가? -- 사용 중단·설정 제거·기능 플래그 회수·문서 갱신에도 담당자가 있는가? -- 주 담당자가 없을 때 필요한 접근 권한과 설명을 다른 사람이 확보할 수 있는가? - -**위험 신호:** 공유 코드는 모두가 수정하지만 사고 대응자는 없다. 플랫폼 팀은 라이브러리만 제공하고 서비스 팀은 내부를 몰라 장애가 서로에게 되돌아온다. - -**개선 완료 기준:** 주요 기능·공유 기반·운영 작업마다 책임과 지원 범위가 기록되고, 연락 대상과 실행 가능한 절차가 연결된다. 작성자 외 사람이 대표 작업을 수행한 기록이 있으면 인수인계 증거가 된다. - -**적용 범위:** 개인 프로젝트에 형식적인 대규모 조직표를 요구하지 않는다. “미래의 내가 이 장애를 다시 처리할 수 있는가”, “템플릿을 가져간 사람이 어디까지 책임져야 하는가”를 분명히 해도 가치가 있다. - -## 27. 삭제 가능성 — Deletability - -### 판단할 것 - -불필요한 기능을 제거했을 때 코드·설정·데이터·권한·운영 자원이 함께 정리되는지 본다. 소스 폴더 삭제만으로 끝나지 않는 경우가 많다. - -### 확인할 제거 범위 - -| 범위 | 남기기 쉬운 흔적 | -| --- | --- | -| 코드·빌드 | import·재수출·의존 패키지·생성기 등록 | -| 실행 구성 | 라우트·DI 등록·환경변수·기능 플래그 | -| 사용자 계약 | API·이벤트·URL·문서·번역 | -| 데이터 | 열·인덱스·백필·보관 데이터·파생 캐시 | -| 권한·운영 | 서비스 계정·배포 자원·대시보드·알림·비용 | - -**검증 방법:** 선택 기능 하나를 실제로 제거하거나 비활성화한 소비자 예제를 만들고, 최소 구성의 설치·빌드·시작·기본 흐름이 유지되는지 확인한다. 플래그를 껐어도 번들·백그라운드 작업·외부 연결이 남는지 본다. - -**개선 완료 기준:** 관련 없는 기능을 함께 뜯지 않고 제거할 수 있으며, 남는 계약·데이터의 보관 이유와 최종 제거 조건이 명확하다. - -**원문 보완:** 이미 적용된 마이그레이션 이력을 소스 기능과 함께 지워도 된다는 뜻이 아니다. 사용 중인 마이그레이션 도구의 이력 관리 방식과 기존 설치·새 설치 경로를 보존하면서 제거용 변경을 설계한다. - -## 28. 회복 가능성 — Recoverability - -### 판단할 것 - -장애를 멈추는 것과 올바른 상태로 되돌리는 것을 구분한다. 프로세스 재시작으로 응답이 돌아와도 중복 처리·누락·잘못된 권한이 남을 수 있다. - -### 확인 질문과 증거 - -1. 허용 가능한 데이터 손실 범위인 RPO와 목표 복구 시간인 RTO가 무엇인가? -2. 백업 파일뿐 아니라 복구에 필요한 설정·암호화 키·권한·외부 의존성을 확보할 수 있는가? -3. 빈 환경이나 지정한 복구 환경에서 실제 복원하고 시간을 측정했는가? -4. 메시지·이벤트를 다시 처리할 때 이미 발생한 외부 부작용이 반복되지 않는가? -5. 중복 방지 기록의 보관 기간보다 오래된 사건을 재처리하면 어떻게 되는가? -6. 복구 후 데이터 정합성·접근 권한·삭제 대상의 재등장 여부를 확인하는가? -7. 전체 복구가 어려울 때 영향 범위를 제한하거나 일부 기능부터 재개할 수 있는가? - -**위험 신호:** “백업 성공”만 확인한다. 복구 절차가 현재 버전과 맞지 않는다. 재실행할 수 있는 스크립트는 있지만 대상 범위·중복 실행·진행 상태를 알 수 없다. - -**개선 완료 기준:** 지정한 장애 시점에서 복구를 수행하고, 실제 소요 시간·확인한 데이터 범위·남은 손실을 기록한다. 재처리·수동 보정 도구에도 대상 확인, 범위 제한, 감사 기록, 중단·재개 방법을 둔다. - -**증거 한계:** 작은 실험 DB 복구 성공은 그 환경의 증거다. 실제 데이터량·외부 시스템·권한·운영 절차를 포함한 복구 완료로 확대하지 않는다. - -## 29. 코드에서 위험을 드러내는 방법 - -위험 가시성은 함수 이름 하나로 완성되지 않는다. **호출부의 의미, 경계의 계약, 실제 실행 정책, 검증 증거**가 이어져야 한다. - -### 29.1 무엇을 숨기고 무엇을 보여 줄 것인가 - -| 숨겨도 되는 구현 세부사항의 예 | 호출자가 알아야 할 계약의 예 | -| --- | --- | -| HTTP 라이브러리의 연결 생성 방식 | 외부 호출인지, 언제 포기하고 어떤 결과를 반환하는지 | -| SQL 문장의 구체적인 문자열 | 동시 갱신 충돌 여부, 커밋과 반환의 관계 | -| 캐시 저장 자료구조 | 사용자 범위, 신선도, 무효화, 원본 실패 시 동작 | -| 메시지 직렬화 라이브러리 | 접수와 처리 완료의 차이, 중복·순서·재처리 | -| 로깅 라이브러리의 구현 | 민감정보 처리와 오류를 기록하는 책임 | - -모든 함수 이름에 `WithTimeoutAndRetryAndTransaction`을 붙이면 핵심 동작이 오히려 안 보인다. 의미 있는 포트·타입·설정 위치에 계약을 두고, 호출부에서는 그 경계를 알아볼 수 있게 한다. - -### 29.2 Backend 예시: DB 변경과 외부 결제 호출 - -다음은 위험을 설명하기 위한 축약 코드다. 특정 프로젝트의 코드가 아니다. - -```java -@Transactional -public Receipt placeOrder(PlaceOrder command) { - Order order = orders.insertPending(command); - Approval approval = paymentClient.authorize(order); - orders.markPaid(order.id(), approval.id()); - return Receipt.from(order, approval); -} +```bash +git show 003832b6:docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md ``` -메서드가 짧고 순서가 읽힌다는 장점은 있다. 리뷰는 그다음 질문으로 넘어가야 한다. +## 고칠 때 -| 실패 조건 | 확인할 문제 | -| --- | --- | -| 결제사가 오래 응답하지 않는다. | DB 연결·락이 실제로 언제 확보되고 얼마나 유지되는가? | -| 결제는 승인됐지만 응답을 잃는다. | 실패로 단정하는가, 결과를 모르는 상태로 남기는가? | -| 승인 뒤 DB 반영이 실패한다. | 외부 승인과 내부 주문을 누가 다시 맞추는가? | -| 같은 주문 요청이 동시에 들어온다. | 논리적으로 같은 결제를 여러 번 실행할 수 있는가? | -| 프로세스가 중간에 종료된다. | 마지막으로 확인된 상태와 재개 지점을 찾을 수 있는가? | - -DB 연결·락 유지의 구체적 범위는 트랜잭션 매니저·ORM·flush 시점에 따라 확인해야 한다. 다만 로컬 DB 트랜잭션만으로 외부 결제의 원자성까지 보장하지 않는다는 경계는 분명히 설명되어야 한다. - -외부 호출을 트랜잭션 밖으로 옮기는 조치만으로 이 문제가 모두 해결되지는 않는다. 그 사이의 프로세스 종료·중복 호출·상태 경쟁이 새로 드러난다. - -**개선안을 리뷰할 때 확인할 계약** - -1. 같은 업무 시도에는 안정된 식별자를 사용한다. 재전송마다 새 키를 만들면 같은 작업을 구분하지 못한다. -2. 식별자의 사용자·테넌트·작업 범위, 동일 키와 다른 입력의 충돌 처리, 보관 기간을 정한다. -3. 로컬 상태 기록·외부 호출·결과 반영 각각의 경계를 정의한다. -4. 외부 시스템이 지원하는 중복 억제·결과 조회·취소 계약을 확인한다. -5. 응답을 잃은 경우 성공도 실패도 확정하지 않고 결과 조회·대사로 이어지게 한다. -6. 중단된 시도를 재개하거나 정리할 담당 흐름과 관측 정보를 둔다. - -멱등성 키의 저장과 업무 처리가 경쟁 조건에서 따로 움직이면 중복 억제가 깨질 수 있다. 키가 존재한다는 확인만으로 완료 처리하지 말고 진행 중·완료·실패·결과 불명 상태와 원자적 갱신 범위를 확인한다. [S10] - -반환 타입도 결과의 차이를 드러낼 수 있다. 아래는 언어 선택과 무관하게 계약을 보여 주기 위한 TypeScript 예시다. - -```typescript -type PaymentAttemptResult = - | { kind: "approved"; approvalId: string } - | { kind: "declined"; reasonCode: string } - | { kind: "outcome-unknown"; attemptId: string }; -``` - -이 타입 자체가 중복 결제를 방지하지는 않는다. 호출자가 “결과 불명”을 “결제 실패”로 오해하지 않게 돕는다. 실제 중복 억제와 복구는 저장소·외부 API 계약·경쟁 처리·검증이 맡는다. - -Outbox를 도입한다면 로컬 데이터와 이벤트 기록의 원자성을 어떻게 확보하는지, 전달 중복과 소비자 중복 처리를 어떻게 다루는지 본다. Outbox가 외부 시스템의 모든 부작용을 정확히 한 번만 실행하게 해 준다고 확대 해석하지 않는다. - -### 29.3 Frontend 예시: 비동기 응답과 사용자 범위 - -```typescript -async function refreshOrders() { - const orders = await api.getOrders(); - store.setOrders(orders); -} -``` - -이 코드도 짧지만 다음 조건이 보이지 않는다. - -- 호출 중 사용자가 로그아웃하거나 다른 계정으로 로그인하면? -- 더 최신 필터의 요청이 먼저 끝나고 과거 요청이 나중에 끝나면? -- 화면을 떠난 뒤 응답이 도착하면? -- API 실패를 빈 배열로 바꿔 “주문 없음”으로 표시하면? -- SSR에서 여러 사용자의 요청이 같은 저장소 인스턴스를 공유하면? - -**개선안을 리뷰할 때 확인할 계약** - -| 경계 | 드러나야 할 정보 | 확인할 행동 | -| --- | --- | --- | -| 요청 수명 | 시작·취소·완료와 소유 화면 | 화면 이동 후 불필요한 작업과 상태 반영 | -| 응답 순서 | 어떤 요청의 결과가 유효한가 | 응답 순서를 뒤집어 최신 상태 유지 | -| 인증 범위 | 현재 사용자·테넌트·인증 세대 | 로그아웃 전 요청이 후속 상태를 바꾸지 않음 | -| 캐시 | 키·유효 기간·공유 범위·초기화 | 다른 사용자나 필터의 결과 혼입 방지 | -| 실패 의미 | 오류·빈 결과·결과 불명 | 상태별 문구와 가능한 행동 | -| 실행 환경 | 브라우저 앱·SSR 요청별 소유권 | 서로 다른 서버 요청의 상태 격리 | - -인증 세대는 로그인 상태가 바뀌기 전후를 구분하는 클라이언트 내부 표식 같은 방법을 뜻한다. 이것을 서버 인가의 근거로 사용해서는 안 된다. - -`AbortController` 등으로 요청을 취소해도 서버의 처리가 없었다는 뜻은 아니다. 쓰기 요청의 중복 억제는 서버 계약으로 다룬다. 클라이언트에서도 취소만 믿지 말고, 이미 완료된 응답이나 다른 비동기 단계가 현재 화면 상태를 덮어쓰지 않는지 확인한다. - -UI 상태를 타입으로 표현하는 것은 이런 구분을 보존하는 한 방법이다. - -```typescript -type LoadState = - | { kind: "idle" } - | { kind: "loading" } - | { kind: "success"; data: T } - | { kind: "empty" } - | { kind: "error"; errorCode: string; retryAllowed: boolean }; -``` - -화면이 기존 데이터를 유지하며 새로 고치는 UX라면 `refreshing`·이전 데이터 같은 상태가 더 필요할 수 있다. 이 예시 타입을 모든 화면에 그대로 강제하기보다 실제 사용자 흐름의 불가능한 조합을 줄이는지 판단한다. - -### 29.4 위험 가시성의 완료 기준 - -중요한 동작 하나를 골라 다음 문장을 코드와 증거로 채울 수 있어야 한다. - -> 이 호출은 어디에 어떤 부작용을 만들며, 언제까지 기다리고, 어떤 조건에서 다시 시도하며, 동시에 실행되거나 응답을 잃으면 어떤 상태가 남는다. 그 상태는 어디서 확인하고 어떻게 조정한다. - -계약이 없으면 먼저 계약을 정한다. 계약은 있는데 호출부에서 찾기 어렵다면 이름·배치·타입을 고친다. 계약과 구현이 다르면 실제 동작을 고치고 실패 조건을 검증한다. 세 문제를 전부 “네이밍 개선”으로 처리하지 않는다. - -## 30. 템플릿을 하나의 제품으로 보는 추가 기준 - -원문의 28개 관점은 일반 서비스에도 적용된다. 템플릿에는 **재사용·복제·조합·업데이트·제거** 때문에 생기는 추가 책임이 있다. - -### 30.1 최소 구성과 안전한 기본값 - -사용자가 기본 명령으로 시작했을 때 어떤 구성인지 명확해야 한다. 테스트용 인증 우회, 메모리 저장소, 가짜 결제 어댑터가 있다면 용도와 제한을 드러낸다. 운영 프로필이 이를 실수로 채택하지 않게 한다. - -DB·캐시·인증·메시지 시스템을 모두 띄워야 빈 화면 하나를 실행할 수 있다면 최소 구성을 다시 검토한다. 선택 기능을 위한 확장 위치와 운영상 필수 기능은 구분한다. - -**검증:** 최소 구성, 대표 확장 구성, 지원하지 않는 잘못된 조합을 각각 실행한다. 마지막 조합은 조용히 잘못 동작하는 대신 이해할 수 있는 오류로 거부되어야 한다. - -### 30.2 옵션 조합의 수와 검증 책임 - -옵션이 늘면 지원할 조합도 늘어난다. 저장소 3개와 인증 방식 4개를 제공한다는 이유로 모든 조합이 검증된 것은 아니다. - -| 옵션 상태 | 필요한 설명 | -| --- | --- | -| 기본 지원 | 기본값, 동작, 자동 검증 범위 | -| 선택 지원 | 추가 전제, 조합 제약, 운영 책임 | -| 실험 | 확인한 범위와 미검증 조건 | -| 비지원 | 왜 비지원인지, 잘못 선택했을 때의 오류 | - -위험이 높은 조합은 직접 검증하고, 나머지는 선정 원칙을 기록한다. 일부 조합 테스트로 모든 조합의 안전성을 주장하지 않는다. - -### 30.3 생성·복사 후 수정 권한 - -생성 파일 중 사용자가 수정할 부분, 다시 생성될 부분, 공통으로 관리하는 부분을 구분한다. 코드 생성기가 있으면 재실행 시 사용자의 수정이 덮어써지는지 확인한다. - -모든 파일에 “수정 금지”를 붙여 사용자 변경을 막는 방식도 비용이 크다. 사용자가 실제로 바꾸는 정책은 안정된 수정 지점으로 제공한다. - -### 30.4 버전과 업데이트 전파 - -템플릿 원본의 버전과 사용 프로젝트가 출발한 버전을 식별할 수 있어야 한다. 복사된 프로젝트는 원본 패치를 자동으로 받지 않는 경우가 많다. - -| 제공 방식 | 리뷰에서 확인할 업데이트 문제 | -| --- | --- | -| 저장소 복사 | 원본 변경을 어떻게 찾아 선택적으로 반영하는가? | -| 코드 생성 | 재생성 시 사용자 수정과 충돌을 어떻게 처리하는가? | -| 공통 라이브러리 | 공개 계약·지원 버전·업그레이드 순서를 어떻게 관리하는가? | -| 혼합 방식 | 어떤 코드가 어디서 관리되며 중복 패치를 어떻게 피하는가? | - -**검증:** 사용자 수정이 들어간 대표 소비자에 템플릿의 작은 보안·계약 패치를 반영해 본다. 수정 보존, 충돌 설명, 테스트, 되돌림·재적용 경로를 확인한다. - -### 30.5 샘플 코드의 대표성 - -샘플은 가장 많이 복제되는 설명서다. 성공 경로만 보여 주고 실패·권한·설정 누락을 숨기면 사용자가 그 빈칸을 프로젝트마다 다시 채운다. - -복제할 샘플에는 해당 기능에 필요한 최소 실패 처리와 검증을 넣고, 설명을 위해 생략한 부분은 표시한다. 데모 편의를 위한 우회가 권장 운영 코드처럼 보이지 않게 한다. - -### 30.6 도입·유지 비용 - -기본 실행의 메모리·외부 서비스·설정 수, 첫 기능 추가의 필수 개념, CI 시간, 업그레이드·패치 작업을 본다. 팀이 사용하지 않는 기능을 이해·운영해야 한다면 재사용 이익이 줄어든다. - -“도메인을 더 추가해도 된다”는 선언만으로 비용을 평가하지 않는다. 기본 기능을 끄거나 삭제할 때의 비용도 함께 잰다. - -### 30.7 템플릿에서 졸업할 수 있는가 - -사용 프로젝트가 커지면서 기본 구조를 바꿀 수 있어야 한다. 데이터·도메인 정책이 템플릿 고유 registry나 설정 언어에 갇혀 있는지, 일반 코드로 이동할 경로가 있는지 본다. - -안전한 기본 흐름은 제공하되, 변경할 수 있는 경계와 변경 후 사용자가 맡는 책임을 명시한다. 모든 변경을 금지하는 것이 장기 유지보수성은 아니다. - -### 30.8 배포 판단에 필요한 최소 증거 - -| 배포하려는 주장 | 그 주장에 필요한 증거 | -| --- | --- | -| 새 프로젝트를 시작할 수 있다. | 깨끗한 환경의 설치·실행·기본 테스트 | -| 기본 패턴을 복제해 기능을 만들 수 있다. | 작성자 외 사용자의 대표 기능 추가 | -| 선택 기능을 분리할 수 있다. | 최소·선택 구성의 동작과 제거 확인 | -| 패치를 사용 프로젝트에 전달할 수 있다. | 사용자 수정이 있는 소비자의 업데이트 검증 | -| 특정 운영 구성을 지원한다. | 그 구성의 장애·배포·복구 조건에 맞는 증거 | - -지원하지 않는 기능을 명시적으로 제외하는 것도 성숙한 선택이다. 없는 기능을 안전하다고 주장하지 않고, 사용자가 잘못된 전제로 도입하지 않게 한다. - -## 31. Backend Template에서 깊게 볼 시나리오 - -아래 표는 실제 코드 리뷰에서 선택할 시나리오다. 기능이 없는 경우 적용 제외 사유를 적는다. 모든 템플릿에 모든 기술을 추가하라는 뜻은 아니다. - -| 시나리오 | 따라갈 경계 | 확인할 결과 | -| --- | --- | --- | -| 정상 쓰기 요청 | 입력·인가·정책·트랜잭션·저장·응답 | 규칙과 커밋 의미가 일치하고 민감정보가 새지 않는다. | -| 중복·동시 요청 | 요청 식별·DB 제약·외부 부작용 | 같은 논리적 작업의 중복 효과를 계약대로 처리한다. | -| 외부 응답 지연·유실 | 시간 제한·재시도·결과 저장 | 대기와 자원이 제한되고 결과 불명을 조회·조정할 수 있다. | -| DB 오류·경쟁 | 트랜잭션·충돌·오류 변환 | 잘못된 일부 상태가 남지 않거나 남은 상태가 설명된다. | -| 메시지 중복·역순 | 발행·소비·중복 기록·버전 | 지원하는 전달 조건에서 규칙이 유지된다. | -| 신·구 버전 공존 | API·스키마·이벤트 | 선언한 지원 기간 동안 읽기·쓰기가 호환된다. | -| 여러 서버의 작업 실행 | 스케줄러·작업 소유권·저장소 | 중복 실행·중단·재개를 정의한 규칙으로 처리한다. | -| 세션·토큰 갱신 경쟁 | 세션·인증 클라이언트·토큰 저장·락 | 지원하는 인증 구조에서 사용자 상태가 섞이지 않고 경쟁을 처리한다. | -| 다른 사용자 리소스 접근 | 인증·리소스 조회·인가 | 객체 ID를 바꿔도 권한 없는 조회·수정이 거부된다. | -| 큰 입력·목록 조회 | 입력 상한·쿼리·페이지·직렬화 | 메모리·호출 수·응답 크기의 제한이 유지된다. | -| 종료·재시작 | 신규 요청 차단·진행 작업·메시지 확인 | 완료·재전달·재개 조건이 설명되고 실제로 확인된다. | -| 선택 어댑터 제거 | 조립·의존성·설정·테스트 | 최소 구성이 불필요한 연결·설정 없이 동작한다. | - -### 리뷰어가 요청 하나를 따라가며 적을 것 - -입력의 신뢰 수준, 권한 판단 위치, 규칙을 소유한 객체, 트랜잭션 시작·종료, 외부 부작용, 성공의 의미, 오류 변환, 연결 가능한 진단 정보를 적는다. 이 흐름을 설명하지 못한 상태에서 패키지 이름만 보고 구조를 평가하지 않는다. - -예를 들어 세션 저장소와 OAuth 인가 클라이언트 저장소가 모두 등장한다면 각각 무엇을 키로 어떤 상태를 저장하는지 확인한다. 같은 저장소 제품을 사용한다고 두 상태의 수명과 책임이 같은 것은 아니다. 실제 인증 구성과 사용 라이브러리의 계약을 읽고 판단한다. - -### 비용이 작은 개선부터 비교 - -중복 생성을 막는 요구라면 DB 유일성 제약과 충돌 처리가 충분한지 먼저 본다. 원격 부작용과의 조정이 필요할 때 멱등성·결과 조회·이벤트 기록 같은 추가 수단을 검토한다. 모든 위험의 해결책을 분산 락·사가·새로운 인프라 도입으로 고정하지 않는다. - -## 32. Frontend Template에서 깊게 볼 시나리오 - -프론트엔드는 폴더 구조와 컴포넌트 분리만으로 평가하기 쉽지만, 실제 결함은 상태 수명·사용자 경계·비동기 경쟁·배포 호환에서 드러나는 경우가 많다. - -| 시나리오 | 따라갈 경계 | 확인할 결과 | -| --- | --- | --- | -| 목록 최초 진입 | route·기능 조립·조회·렌더링 | loading·success·empty·error가 의미에 맞게 구분된다. | -| 상세 URL 직접 접속·새로고침 | URL·서버 제공·라우터·권한 | 지원 경로가 직접 진입에서도 동작하고 잘못된 경로를 처리한다. | -| 빠른 필터 변경 | URL/폼 상태·요청 식별·캐시 | 과거 응답이 최신 화면을 덮지 않는다. | -| 화면 이동·언마운트 | 요청·구독·타이머·캐시 수명 | 불필요한 작업·리스너·상태 반영이 누적되지 않는다. | -| 로그아웃 중 응답 도착 | 인증 상태·요청·캐시·전역 store | 이전 사용자 응답이 다음 세션 상태에 들어가지 않는다. | -| 사용자·테넌트 전환 | 캐시 키·초기화·서버 인가 | 데이터 범위가 분리되고 UI 제한과 서버 권한이 구분된다. | -| 저장 버튼 중복 클릭 | UI pending·작업 식별·서버 계약 | 화면의 중복 클릭 방지와 서버의 중복 처리 책임이 연결된다. | -| 낙관적 갱신 실패 | 임시 상태·오류·재조회·롤백 | 잘못된 성공 상태가 남지 않고 최신 변경을 덮어 되돌리지 않는다. | -| 세션 만료 | API 오류·갱신·재로그인·이동 | 무한 갱신·리다이렉트·재시도 없이 다음 행동을 제공한다. | -| 공통 HTTP 설정 변경 | API 바인딩·base URL·헤더·시간 제한 | 각 기능이 상충하는 전송 정책을 따로 구현하지 않는다. | -| 새 배포 후 기존 탭 사용 | HTML·청크·CDN·라우트 | 자산 부재·버전 불일치에서 복구 경로가 있다. | -| 다국어 전환 | 화면·행동·오류·빈 상태·접근성 이름 | 주요 사용자 문구가 빠지지 않고 날짜·숫자 표시가 맞는다. | -| 키보드·보조기술 사용 | 포커스·라벨·다이얼로그·상태 변경 | 핵심 흐름을 조작하고 현재 상태를 이해할 수 있다. | -| 여러 SSR 요청 | 요청별 인증·캐시·store·조립 | 요청 간 사용자 상태가 공유되지 않는다. | -| 기능 추가·삭제 | 공개 API·route·조립·번들 | 다른 기능 내부 변경 없이 예측한 범위에서 작업한다. | - -### 32.1 상태의 소유권 - -서버 원본 데이터, URL 상태, 폼 초안, 일시적 UI 상태, 인증 상태가 어디에 속하는지 구분한다. 같은 값을 여러 저장소에 복제했다면 어느 값이 기준이며 언제 맞춰지는지 설명해야 한다. - -전역 store는 그 자체로 문제도 해법도 아니다. 수명과 공유 범위가 맞는지가 중요하다. 화면 하나의 임시 상태를 앱 전체가 공유하거나, SSR 요청별 정보가 프로세스 전역에 남는 상황을 특히 본다. - -### 32.2 UI에 필요한 계약과 내부 계약 - -컴포넌트가 HTTP 상태 코드·토큰·재시도 엔진을 모두 알아야 하면 경계가 약할 수 있다. 반대로 공통 어댑터가 모든 실패를 `false`로 바꾸면 화면이 사용자에게 필요한 행동을 선택할 수 없다. - -사용자 취소, 입력 오류, 권한 부족, 재로그인 필요, 일시 장애, 처리 결과 불명을 필요한 범위에서 구분한다. “다시 시도” 버튼이 실제로 안전한지도 서버 계약과 함께 검토한다. - -### 32.3 접근성과 국제화 - -접근성을 자동 스캔 통과로만 판정하지 않는다. 키보드 순서·포커스 복귀·오류와 입력의 연결·로딩 및 완료 상태 전달을 실제 화면에서 확인한다. WCAG는 이런 검토에 사용할 기준을 제공하지만, 일부 검사항목 통과만으로 전체 준수를 선언하지 않는다. [S7] - -국제화는 메뉴 이름 교체에서 끝나지 않는다. 버튼·검증 오류·empty·loading·알림·접근성 이름·날짜·숫자의 범위와 누락 시 동작을 본다. 아직 한 언어만 지원한다면 실제 요구와 확장 계획을 기준으로 범위를 정한다. - -### 32.4 대규모 기능 증가 - -기능 수가 늘어날 때 라우팅·초기화·번들·타입 검사·공통 파일 충돌이 어떻게 늘어나는지 본다. 각 도메인을 디렉터리로 나눴다는 사실만으로 독립성이 증명되지는 않는다. - -특히 앱 부트스트랩이 기능의 공개 계약만 조합하는지, 기능 내부의 세부 오류·상태·API까지 알고 있는지 확인한다. 조립 지점이 존재한다는 이유만으로 결함은 아니며, 거기에 모인 지식의 성격과 변경 비용을 본다. - -## 33. Platform / 배포 기반 템플릿에서 깊게 볼 시나리오 - -플랫폼 구성을 제공하는 템플릿에 적용한다. 일반 애플리케이션 템플릿에 Kubernetes·고가용성 구성을 반드시 추가하라는 뜻은 아니다. - -| 시나리오 | 확인할 대상 | 확인할 결과 | -| --- | --- | --- | -| 새 환경 생성 | 구성 원본·권한·버전·네트워크·비밀값 | 숨은 수동 상태 없이 지원 환경을 재구성한다. | -| 인스턴스·노드 중단 | 트래픽·복제·상태 저장·작업 재개 | 선언한 장애 범위에서 업무 규칙과 복구 목표를 지킨다. | -| 공통 의존성 장애 | DB·인증·DNS·외부 저장소 | 재시작·재시도 연쇄로 장애가 확대되지 않는다. | -| readiness·liveness 실패 | 검사 의미·임계값·라우팅·재시작 | 재시작으로 해결할 장애와 트래픽 제외가 필요한 상태를 구분한다. | -| 백업·복구 | 데이터·키·설정·권한·복구 순서 | 실제 복원과 정합성 확인이 가능하다. | -| 비밀값·인증서 교체 | 발급·주입·반영·폐기·재연결 | 교체 중간 상태와 실패 복귀를 설명한다. | -| 자원 압박 | CPU·메모리·저장 공간·연결·큐 | 과부하 감지·제한과 복구 동작이 검증된다. | -| 공급망·배포 권한 | 빌드 출처·산출물·계정·환경 | 검증한 산출물을 권한 있는 경로로 배포한다. | -| 구성 차이 누적 | 선언한 설정·실제 적용 상태 | 수동 변경을 식별하고 유지·원복 결정을 기록한다. | -| 기반 제거·이전 | 데이터·DNS·인증서·비밀·계정·비용 | 필요한 이력을 남기고 불필요한 자원과 권한을 회수한다. | - -### 고가용성 주장에 필요한 추가 질문 - -두 인스턴스가 같은 호스트·디스크·전원·네트워크·DB를 공유한다면 어떤 장애가 여전히 공통 장애인지 적는다. 인스턴스 수만으로 독립된 장애 영역이 확보됐다고 판단하지 않는다. - -데이터 복제와 백업도 구분한다. 잘못된 삭제나 손상이 복제될 수 있다면 복제만으로 복구할 수 있는 범위를 설명해야 한다. - -Kubernetes를 사용할 경우 잘못된 liveness 설정은 부하가 높은 인스턴스를 반복 재시작해 남은 인스턴스의 부담을 키울 수 있다. 검사 경로·빈도·실패 임계값을 실제 장애 시나리오와 연결한다. [S5] - -## 34. 실제 리뷰를 수행하는 순서 - -### 34.1 리뷰 대상과 증거 시점을 고정한다 - -저장소, 브랜치·커밋, 미커밋 변경의 유무, 확인 날짜, 실행 환경, 리뷰 목적을 기록한다. 기존 변경을 보존하고 무엇을 읽고 실행했는지 구분한다. - -README·설계 문서는 **주장과 의도를 찾는 자료**다. 실제 동작의 증거는 코드·구성·현재 실행 결과에서 찾는다. 이전 버전의 테스트 결과를 현재 코드의 증거로 그대로 재사용하지 않는다. - -### 34.2 핵심 주장과 적용 범위를 적는다 - -“다중 인스턴스 지원”, “기능별 경계 강제”, “선택 연동 제거 가능”, “안전한 재시도”처럼 검증 가능한 문장으로 바꾼다. 적용하지 않는 기능과 그 이유도 함께 기록한다. - -예를 들어 “확장성 우수”라는 주장은 “기능을 추가할 때 다른 기능 내부를 수정하지 않으며, 정한 규모에서 빌드·초기화 비용이 예산을 넘지 않는다”처럼 나눠야 확인할 수 있다. - -### 34.3 실행 경로와 신뢰 경계를 지도처럼 정리한다 - -입력·권한·정책·상태 저장·외부 I/O·오류·관측·복구의 연결을 대표 경로로 확인한다. 정확한 관계를 보여 주는 간단한 표나 다이어그램을 사용한다. - -정상 조회 하나, 상태를 바꾸는 요청 하나, 인증·권한 경로 하나, 외부 호출 또는 비동기 경로 하나를 우선 선정할 수 있다. 이것은 시작 표본이며 저장소 전체 검토를 대체하지 않는다. - -### 34.4 중요한 실패와 경계를 먼저 검증한다 - -데이터 손상·권한 우회·결과 불명·무제한 자원 사용·복구 불가처럼 피해가 큰 경로부터 본다. 위험이 없는 단순 스타일 항목에 먼저 시간을 쓰지 않는다. - -대표 위반이나 실패를 재현할 때는 격리된 검증 환경을 사용한다. 운영 데이터 삭제·실제 결제·외부 전송을 발생시키는 검증은 별도 실행 범위와 승인이 필요한 작업이다. - -### 34.5 변경·삭제·업데이트를 한 번 따라간다 - -기능 추가, 정책 변경, 선택 기능 제거, 소비자 패치 반영을 실제 diff나 구체적인 작업 경로로 확인한다. 미래 가능성을 추측하는 설명보다 비용을 더 잘 보여 준다. - -### 34.6 반복되는 패턴을 확인하며 범위를 넓힌다 - -좋은 샘플 하나만 보고 모든 기능이 같다고 판단하지 않는다. 다른 작성 시기·규모·도메인·예외 경로의 표본도 확인한다. - -검색 결과 개수는 위치를 찾는 데 쓴다. `catch`, `any`, `common`, `@Transactional`이 몇 번 나오는지만으로 결함 수를 세지 않는다. 해당 맥락과 도달 가능한 실행 경로를 확인한다. - -### 34.7 발견 사항과 미검증을 분리한다 - -확인된 결함, 조건부 구조적 위험, 아직 확인하지 못한 항목을 나눠 적는다. 각각 근거·발생 조건·영향·최소 개선 방향·완료 검증을 연결한다. - -같은 원인을 여러 관점에서 다시 발견했다면 하나의 항목에 관련 관점을 연결한다. 증거가 없는 결론은 질문이나 미검증 항목으로 남긴다. - -### 34.8 필요한 검증까지만 수행한다 - -먼저 읽어서 확인할 수 있는 계약을 확인하고, 남은 위험을 해결할 실험만 실행한다. 작은 스타일 변경에 대규모 E2E나 부하 테스트를 붙이지 않는다. 반대로 동시성 문제를 단일 요청 테스트로 닫지 않는다. - -충분한 증거가 모이면 다음 위험으로 이동한다. 검사를 많이 실행했다는 사실을 리뷰의 깊이로 대신하지 않는다. - -### 34.9 결과를 사용 결정으로 연결한다 - -“좋다/나쁘다” 대신 어떤 용도에서 지금 사용할 수 있고, 무엇을 고쳐야 하며, 어떤 주장은 검증이 필요한지 적는다. 범위가 제한된 합격도 유효한 결과다. - -### 34.10 안전성과 코드 이해를 함께 재검토한다 - -리팩터링 결과에서는 중요한 보호 장치가 유지됐는지와 사용·수정 과정의 부담이 줄었는지를 함께 확인한다. 대표 과제를 그대로 다시 수행해 필수 개념, 수동 동기화 지점, 실행 흐름의 이동, 오류 원인 파악이 어떻게 바뀌었는지 기록한다. 줄 수 감소만으로 완료 처리하지 않는다. - -### 34.11 대표적인 선택을 후속 질문으로 검토한다 - -핵심 계약에 영향을 주거나 대안이 논쟁이 되는 선택을 골라 “왜 이 방식인가?”, “더 단순한 방식으로 바꾸면 무엇이 달라지는가?”, “어떤 조건이면 결론이 바뀌는가?”를 묻는다. 41절에 따라 코드·계약·검증 근거를 연결하고, 근거가 없으면 설명을 만들어 채우지 않는다. - -개발자를 시험하거나 기술 지식을 과시하기 위한 절차가 아니다. 유지할 이유가 있는 코드, 실제 결함, 설명 부족, 미확인 요구를 구분해 다음 수정자가 판단할 수 있게 한다. 모든 줄에 질문표를 작성하거나 별도 CI 검사를 추가하지 않는다. - -### 비교에 유용한 측정 항목 - -| 측정 | 활용 | 오해하지 말 것 | -| --- | --- | --- | -| 대표 과제의 탐색·변경 시간 | 인지 부하·DX 개선 전후 | 사람·과제 차이를 무시한 절대 등급 | -| 함께 바뀌는 정책·모듈·계약 | 변경 범위와 조율 비용 | 파일 수만으로 계산한 품질 | -| 필요한 CI의 시간·실패 설명·불안정성 | 피드백 비용 | 테스트 수가 많을수록 안전하다는 주장 | -| 부하별 지연·오류·포화 자원 | 용량과 제한 동작 | 다른 조건의 평균값 비교 | -| 복구 시간·손실·정합성 확인 범위 | 회복 가능성 | 백업 성공을 복구 성공으로 간주 | -| 소비자 패치 적용의 수정·충돌 | 템플릿 업데이트 비용 | 원본 패치 완료를 모든 소비자 완료로 간주 | - -측정값에는 비교 기준과 조건을 붙인다. 이 가이드는 업계 공통의 합격 시간·최대 파일 수·최소 커버리지 비율을 제시하지 않는다. - -## 35. 심각도·성숙도·증거·완료를 구분하는 판정 체계 - -원문의 단계 체계는 출발점으로 쓸 수 있지만, 통제 장치의 강도와 검증 환경이 한 줄에 섞여 있었다. 여기서는 다음 네 가지를 따로 기록한다. - -1. **문제의 심각도:** 발생하면 얼마나 큰 피해가 생기는가? -2. **통제 수준:** 중요한 규칙을 어떤 수단으로 보호하는가? -3. **검증 증거:** 어떤 버전·조건·환경에서 무엇을 확인했는가? -4. **조치 상태:** 합의한 개선과 검증이 끝났는가? - -### 35.1 발견 사항의 성격 - -| 분류 | 기준 | 표현 예시 | -| --- | --- | --- | -| 확인된 결함 | 현재 코드·구성 또는 실행 결과로 계약 위반을 입증 | “권한 검사를 거치지 않는 이 경로에서 다른 사용자 리소스를 반환한다.” | -| 구조적 위험 | 지원 조건에서 문제가 될 인과 경로가 있으며 영향 확인이 남음 | “외부 지연 동안 자원을 점유하는 구조다. 목표 부하에서 고갈되는지는 미확인이다.” | -| 미검증 | 관련 자료·실행 결과가 부족해 판단할 수 없음 | “복구 스크립트는 있으나 실제 복구 결과를 확인하지 못했다.” | -| 개선 제안 | 확인된 계약 위반 없이 이해·비용을 개선할 여지 | “같은 역할의 이름을 통일하면 탐색 부담을 줄일 수 있다.” | - -실행 재현이 없어도 충분한 정적 증거로 결함을 확정할 수 있다. 반대로 테스트를 한 번 실행했다는 사실만으로 원인과 영향이 입증되는 것도 아니다. - -### 35.2 심각도 - -다음은 이 문서의 판정 예시다. 조직의 사고 등급과 연결할 때는 정의를 맞춘다. - -| 등급 | 판단 기준 | 예시와 조건 | -| --- | --- | --- | -| Critical | 심각한 보안·데이터·금전 피해 또는 광범위한 서비스 상실로 이어지는 도달 가능한 경로 | 인증 없이 민감정보 접근, 실제 데이터의 비가역적 대량 손상 등 | -| High | 지원하는 사용·배포·장애 조건에서 중요한 기능 실패나 큰 피해를 유발 | 다중 서버에서 업무 중복 실행, 결과 불명 작업의 무방비 재실행 등 | -| Medium | 피해 범위가 제한되거나 변경·운영 비용을 반복해서 높임 | 정책 중복으로 변경 누락이 반복됨, 주요 진단 정보 부족 등 | -| Low | 계약 위반과 직접적인 운영 피해가 작고 주로 가독성·편의에 영향 | 모호한 지역 변수명, 제한된 문서 불일치 등 | - -같은 구조도 데이터·권한·발생 조건에 따라 등급이 달라진다. 아키텍처 경계가 없다는 사실, 인터페이스가 많다는 사실, `common`이 크다는 사실만으로 Critical을 부여하지 않는다. - -다음 정보를 함께 적는다. - -- 발생 조건과 도달 가능성 -- 영향을 받는 사용자·데이터·서비스 -- 탐지와 복구의 난이도 -- 기본 설정·샘플을 통해 다른 프로젝트로 복제되는 범위 -- 근거의 확실성과 아직 확인할 가정 - -불확실성은 별도로 표시한다. 증거가 부족한데 “높은 확률” 같은 표현을 임의로 붙이지 않는다. - -### 35.3 조치 우선순위 - -| 우선순위 | 처리 기준 | -| --- | --- | -| P0 | 현재 심각한 피해가 발생하거나 노출된 경로의 즉시 차단·완화가 필요 | -| P1 | 해당 용도의 도입·출시·확대 전에 해결할 차단 항목 | -| P2 | 현재 사용 범위에서 조건을 관리하며 계획적으로 개선 | -| P3 | 효과와 비용을 비교해 선택할 개선 | - -이 분류는 관점별 고정 순위가 아니다. 데이터 복구가 없는 서비스에서는 회복 가능성이 최우선이 될 수 있고, 배포할 수 없는 템플릿에서는 개발자 경험의 실행 경로가 도입 차단 항목이 될 수 있다. - -예방 비용과 피해·복제 범위를 함께 고려하되, 낮은 비용의 스타일 개선으로 심각한 미해결 위험을 가리지 않는다. - -### 35.4 통제 수준 - -원문의 Level 0~4 취지를 다음처럼 좁혀 사용한다. 프로젝트 전체가 아니라 **선정한 규칙**에 부여한다. - -| 수준 | 의미 | 필요한 근거 | -| --- | --- | --- | -| M0 — 통제 부재 확인 | 필요한 규칙을 지킬 수단이 없다. | 관련 경로를 확인한 결과 | -| M1 — 명시 | 규칙·책임·제약이 적혀 있다. | 현재 계약·설정 설명·문서 | -| M2 — 구현·일관 적용 | 필요한 코드 경로에 규칙이 구현되어 있다. | 대표·예외 경로의 실제 구현 | -| M3 — 위반 검출 | 의미 있는 자동 검증이 위반을 검출한다. | 검사 구성과 관련 실패·통과 증거 | -| M4 — 경계에서 강제 | 타입·공개 범위·DB 제약·권한 등으로 규칙 위반을 직접 제한한다. | 적용 경계와 우회 검증 | - -**미확인은 M0가 아니다.** 필요한 경로를 읽지 못했다면 `미평가` 또는 `미확인`으로 남긴다. 문서만 존재하는 상태와 문서에 적힌 구현이 실제로 확인된 상태도 구분한다. - -모든 규칙에 M4가 필요하거나 가능한 것은 아니다. 낮은 피해의 표기 규칙과 금전·인가 규칙에 같은 통제 비용을 쓰지 않는다. 강한 통제가 일부 경로에만 적용되면 그 범위만 기록한다. - -### 35.5 검증 증거 - -| 표기 | 확인한 것 | 확대해서 주장할 수 없는 것 | -| --- | --- | --- | -| E0 — 설명·주장 | 문서·설계 의도가 있다. | 실제 구현·동작 | -| E1 — 정적 확인 | 코드·설정에서 구현과 경로를 확인했다. | 실행 환경의 전체 동작 | -| E2 — 테스트 실행 | 명시한 테스트가 해당 버전에서 통과했다. | 테스트하지 않은 실패·규모 | -| E3 — 통합·실험 확인 | 실제 의존성, 선택한 부하·장애·배포·복구 조건에서 확인했다. | 다른 구성·데이터량·실제 운영 기간 | -| E4 — 실제 운영 관찰 | 정한 기간·사용량·환경에서 운영 결과와 대응 기록을 확보했다. | 모든 장애·미래 규모의 안전성 | - -이 표는 모든 성질에 적용되는 단일 사다리가 아니다. 높은 번호의 증거 하나가 낮은 번호의 모든 검증을 대신하지 않는다. 실제 운영에서 정상 요청을 처리했다는 증거와 복구 실험의 증거는 별도로 필요할 수 있다. - -예를 들어 “통제 M3, 단위 테스트 E2, 다중 인스턴스 경쟁 미검증”처럼 적는다. 코드에 강제 장치가 있어도 운영 복구를 검증했다는 뜻은 아니다. - -**실험은 실험으로 기록한다.** 장애 주입·부하·복구를 수행한 환경이 실험실이라면 E3 범위다. 원문의 “Level 5 — 운영 검증”처럼 실험과 실제 운영을 하나의 표현으로 합치지 않는다. - -### 35.6 항목 상태와 완료의 정의 - -| 상태 | 의미 | -| --- | --- | -| 충족 | 합의한 범위·목표와 필요한 검증을 만족한다. | -| 부분 충족 | 일부 경로·구성·검증이 남아 있다. | -| 미충족 | 필요한 계약·구현·통제가 없거나 확인된 결함이 남아 있다. | -| 미검증 | 현재 증거로 충족 여부를 판단할 수 없다. | -| 적용 제외 | 이 사용 범위에 해당하지 않으며 이유가 있다. | - -“검토 중”, “조치 중”, “보류”, “위험 수용”은 별도의 작업 상태로 관리한다. 위험을 수용했다고 기술적으로 충족한 것은 아니다. 수용 이유·책임자·보완 수단·재검토 조건을 적는다. - -개선 항목을 닫으려면 다음이 연결되어야 한다. - -1. 원래 위험과 발생 조건 -2. 변경한 코드·구성·계약 -3. 문제를 검출하거나 남은 위험을 확인하는 검증 -4. 검증한 버전·환경·실행 결과 -5. 남아 있는 제한과 후속 책임 - -문서의 체크 표시나 구현자의 “완료” 설명만으로 닫지 않는다. 수정 후 현재 상태를 확인한다. - -### 35.7 전체 성숙도를 요약하는 방법 - -기본 보고는 **관점별 목표 대비 상태, 도입·출시 차단 항목, 미검증 목록**으로 한다. 28개 관점의 단순 평균으로 인증 우회나 복구 불가를 상쇄하지 않는다. - -통제 수준이 높다는 이유로 코드 이해까지 우수하다고 추론하지 않는다. “핵심 규칙은 M4로 강제되지만 일반 기능 작성자가 여러 등록 규약을 알아야 한다”는 판정도 가능하다. 이 경우 4번 인지 부하·22번 추상화의 개선이 남는다. 39·41절의 질문을 별도 점수로 중복 집계하지 않는다. - -진행률이 필요하면 먼저 독립적으로 검증 가능한 세부 기준을 고정한다. 적용 항목 중 충족·부분 충족·미충족·미검증 수를 각각 보고하고, 적용 제외는 사유와 함께 분리한다. 미검증 항목을 분모에서 빼서 완료율을 높이지 않는다. - -점수를 꼭 사용한다면 가중치·배점·합격 조건·미검증 처리·차단 규칙을 사전에 합의한다. 기준이 바뀌면 이전 점수와 직접 비교하지 않는다. 서로 목적이 다른 Backend와 Frontend 템플릿의 단일 점수 경쟁은 피한다. - -### 35.8 사용 결정의 표현 - -| 결정 | 뜻 | -| --- | --- | -| 지정 범위에서 사용 가능 | 선언한 범위의 필수 기준과 검증을 충족 | -| 조건부 사용 가능 | 사용 조건·제외 기능·보완 책임을 구체적으로 제한 | -| 해당 용도의 사용 보류 | 필수 계약의 결함이나 중요한 검증 공백이 남음 | -| 판단 보류 | 범위·목표·증거가 부족해 결정할 수 없음 | - -새 템플릿에 실제 운영 이력이 없다는 이유만으로 영구적으로 사용을 막는 것은 적절하지 않다. 도입 전에 필요한 실험·제한을 정하고, 사용 범위를 넓히면서 운영 증거를 축적한다. - -## 36. 실제 리뷰 결과에 사용할 양식 - -아래 양식의 빈칸은 실제 리뷰에서 채울 항목이다. 현재 프로젝트의 평가 결과가 아니다. - -### 36.1 리뷰 범위 - -| 항목 | 기록 | -| --- | --- | -| 대상 저장소·프로젝트 | 기재 | -| 커밋·작업 상태·확인 시점 | 기재 | -| 목적과 지원 실행 구성 | 기재 | -| 필수 요구와 규모·운영 목표 | 기재 | -| 읽은 코드·구성 범위 | 기재 | -| 수행한 테스트·실험 | 기재 | -| 확인하지 못한 범위·이유 | 기재 | -| 이전 리뷰와 비교 가능한 범위 | 기재 | - -### 36.2 28개 관점 판정표 - -목표 통제와 확인 통제는 동일한 범위에서 비교한다. 구체적인 규칙이 여러 개면 관점 아래 세부 행을 추가한다. - -| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 | -| --- | --- | --- | --- | --- | --- | -| 1 | 코드 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 2 | 구조적 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 3 | 변경 용이성 | 미평가 | 미평가 | 미확인 | 미검증 | -| 4 | 인지 부하 | 미평가 | 미평가 | 미확인 | 미검증 | -| 5 | 위험 가시성 | 미평가 | 미평가 | 미확인 | 미검증 | -| 6 | 실패 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 7 | 운영 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 8 | 디버깅 가능성 | 미평가 | 미평가 | 미확인 | 미검증 | -| 9 | 유지보수 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 10 | 테스트 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 11 | 데이터 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 12 | 동시성 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 13 | 확장성 | 미평가 | 미평가 | 미확인 | 미검증 | -| 14 | 성능 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 15 | 보안 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 16 | 의존성 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 17 | API / Contract 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 18 | 배포 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 19 | 설정 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 20 | 개발자 경험 | 미평가 | 미평가 | 미확인 | 미검증 | -| 21 | Guardrail 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 22 | 추상화 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 23 | 일관성 | 미평가 | 미평가 | 미확인 | 미검증 | -| 24 | 네이밍 / 의미 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 25 | 조직 확장성 | 미평가 | 미평가 | 미확인 | 미검증 | -| 26 | Ownership 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 | -| 27 | 삭제 가능성 | 미평가 | 미평가 | 미확인 | 미검증 | -| 28 | 회복 가능성 | 미평가 | 미평가 | 미확인 | 미검증 | - -### 36.3 발견 사항 양식 - -아래 필드는 모든 발견 사항을 장황한 설계 문서로 만들기 위한 것이 아니다. **단순한 구현 결함, 오탈자, 누락된 null 검사, 실행되어야 할 gate의 단순 누락처럼 선택 비교가 실질적으로 필요하지 않은 항목에는 설계 선택 관련 필드를 `적용 제외`로 둘 수 있다.** 그때는 왜 적용 제외인지 한 문장으로 적는다. 반대로 구조 변경·추상화·기술 선택·정책 변경처럼 여러 타당한 선택지가 있는 항목은 41절을 적용해 현재 선택과 대안을 비교한다. - -| 필드 | 작성할 내용 | -| --- | --- | -| ID·제목 | 다른 항목과 구분되는 ID와 구체적인 문제. ID는 라운드 안에서 `NN-MM`(영역 번호-순번)이다. 라운드 밖(CHANGELOG, 코드 주석, 커밋 제목, 다른 라운드의 문서)에서 가리킬 때는 리뷰 폴더 날짜의 월일을 붙여 `MMDD/NN-MM`(예: `0925/14-02`)으로 쓴다. 라운드마다 `NN-MM`을 새로 매기므로 접두어가 없으면 어느 결함인지 알 수 없다. 이미 있는 주석은 고치지 않고 새로 쓰는 것부터 붙인다 | -| 성격 | 확인된 결함 / 구조적 위험 / 미검증 / 개선 제안 | -| 관련 관점 | 28개 관점 중 해당 번호 | -| 근거 | 현재 파일·심볼·설정, 필요한 코드 범위, 실행 결과 | -| 발생 조건 | 어떤 입력·순서·장애·배포·규모에서 문제가 되는가? | -| 영향 | 어떤 사용자·데이터·자원·소비자에 무엇이 발생하는가? | -| 심각도·우선순위 | 등급과 해당 판단의 이유 | -| 확실성과 남은 가정 | 직접 확인한 사실과 추론의 경계 | -| 결정의 근거 | **설계 선택·구조 변경과 관련된 경우** 현재 제약·보호할 규칙·선택 이유를 적고, 확인된 사실·기록된 의도·리뷰어의 추론을 구분한다. 단순 결함이면 `적용 제외 — 선택 비교가 필요한 문제가 아님`처럼 적을 수 있다. | -| 이해 비용 | 누가 어떤 과제를 하며, 무엇을 읽고 수동으로 맞춰야 하는가? 단순 지역 결함이면 필요한 범위만 기록한다. | -| 최소 개선 방향 | 위험을 줄이는 가장 작은 변경. 설계 선택이면 비교할 대안을 함께 적는다. | -| 대안 비교 | **여러 타당한 선택지가 있는 경우** 현상 유지·더 단순한 대안·다른 접근의 차이를 비교한다. 명백한 계약 위반을 바로잡는 단순 수정이면 적용 제외할 수 있다. | -| 단순화의 보존 조건 | 제거·통합·비공개화처럼 단순화를 제안할 때 지켜야 할 동작·타입·실패·진단 계약. 단순 결함 수정이면 적용 제외할 수 있다. | -| 비용·부작용 | 추가 복잡성·운영 책임·호환성·이행 비용 | -| 재검토 조건 | **현재 선택을 유지하거나 새 선택으로 바꾸는 판단이 있는 경우** 어떤 요구·규모·측정 결과·의존 계약 변화가 결론을 바꾸는지 적는다. 단순 결함 수정이면 적용 제외할 수 있다. | -| 완료 기준 | 구현자가 끝났는지 판단할 관찰 가능한 조건 | -| 검증 방법 | 그 위험을 직접 다루는 테스트·실험·정적 검사 | -| 담당·기한·상태 | 실제 조치 책임과 진행 상태 | -| 재검증 결과 | 변경 버전·실행 결과·잔여 위험 | - -`적용 제외`는 빈칸을 허용한다는 뜻이 아니다. **왜 선택 비교가 필요하지 않은지 짧게 남겨야 한다.** 예를 들어 `CI workflow에서 필수 gate ID 한 개가 단순 누락됨 — 기대 계약이 이미 고정되어 있어 대안 비교 적용 제외`처럼 기록한다. 반대로 “복잡해 보여서 단순화한다”, “다른 라이브러리로 바꾼다”, “추상화를 합친다”처럼 선택을 바꾸는 제안은 단순 결함으로 축소하지 않고 41절의 비교를 수행한다. - -### 36.4 부정확한 리뷰와 실행 가능한 리뷰의 차이 - -다음은 작성 방식의 예시다. 실제 저장소에서 발견한 문제를 뜻하지 않는다. - -| 부정확한 표현 | 실행 가능한 표현 | -| --- | --- | -| “추상화가 너무 많다.” | “목록 조회 경로에서 세 wrapper가 같은 입력을 그대로 전달한다. 각 wrapper가 보호하는 계약을 확인하고, 역할이 없는 단계를 제거한 뒤 오류·취소 동작이 유지되는지 검증한다.” | -| “분산 락을 도입하라.” | “지원하는 다중 인스턴스에서 같은 작업의 중복 실행을 막아야 한다. DB 조건부 갱신·제약·작업 소유권으로 해결 가능한지 비교하고 중단·재개까지 검증한다.” | -| “운영 준비가 안 됐다.” | “복구 절차 문서는 있으나 현재 버전과 데이터 규모로 실행한 증거가 없다. 복구 시간·손실·정합성 기준을 정하고 해당 환경에서 검증해야 한다.” | -| “캐시를 지우면 된다.” | “로그아웃 시 캐시 제거뿐 아니라 이전 세션의 진행 중 요청이 캐시를 다시 채우지 않는지 확인한다. 늦은 응답을 의도적으로 전달하는 시나리오로 검증한다.” | -| “아키텍처 90점이다.” | “공개 경계는 구현되어 있으나 상대 경로를 통한 우회 검출이 미확인이다. 대표 위반이 CI에서 차단되는지 확인해야 한다.” | - -### 36.5 최종 리뷰 요약 양식 - -1. **사용 결정:** 어느 구성·용도에서 사용 가능·조건부 가능·보류인가? -2. **확인된 강점:** 어떤 위험을 실제로 막고 있으며 근거는 무엇인가? -3. **차단 항목:** 도입·배포·규모 확대 전에 무엇을 해결해야 하는가? -4. **주요 구조적 위험:** 어떤 조건에서 나타나며 어떻게 확인할 것인가? -5. **미검증:** 실행·자료·환경이 부족한 범위는 어디인가? -6. **개선 순서:** 먼저 고칠 이유, 최소 변경, 비용, 완료 기준은 무엇인가? -7. **재검토 조건:** 규모·버전·의존성·인증·배포 방식이 어떻게 바뀌면 다시 봐야 하는가? - -설계 선택의 상세 설명이 필요한 경우 41.10절의 답변 양식을 사용한다. 이미 코드·공개 계약·기존 기록에 있는 설명은 연결해서 쓰며, 모든 발견 사항에 같은 내용을 중복 작성하지 않는다. -실제 리뷰를 수행할 때는 동봉된 `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md`를 실행 순서로 사용하고, 상세 판단이 필요한 지점에서 이 기준서의 해당 절로 돌아온다. - -## 37. 원문에서 보강·교정한 주요 내용 - -원문의 범위는 넓고 유용하다. 다음은 실제 리뷰에 적용할 때 오해를 줄이기 위해 바꾼 지점이다. - -| 원문의 표현·구성 | 보강판의 처리 | -| --- | --- | -| 관점별 P0~P3 고정 분류 | 실제 피해·발생 조건·복제 범위·현재 목표를 기준으로 우선순위를 정한다. | -| 아키텍처 경계 부재를 Critical 예시에 포함 | 경계 위반이 어떤 피해로 이어지는지 확인한 뒤 심각도를 정한다. | -| “알림이 원인보다 증상만 알리는가?”라는 질문 | 증상 기반 알림을 정상적인 접근으로 인정하고 대응 가능성과 원인 조사 경로를 본다. [S2] | -| 문서화부터 운영 검증까지 하나의 성숙도 단계 | 통제 수준과 검증 환경을 분리한다. | -| 장애 주입·부하·복구 실험을 운영 검증에 묶음 | 실험에서 확인한 범위와 실제 운영 관찰을 별도로 기록한다. | -| 구현체 하나인 추상화를 과설계 신호로 제시 | 외부 경계·테스트·변경 격리의 가치와 학습 비용을 비교한다. [S1] | -| 파일 수·호출 깊이·5분 추적 등을 인지 부하 지표로 제시 | 보조 지표로 사용하고 실제 과제에서 숨은 규칙과 탐색 실패를 관찰한다. | -| 프레임워크 의존을 위험 신호로 제시 | 선언한 분리 목표와 실제 결합 비용을 기준으로 판단한다. | -| TypeScript 경로 관련 규칙을 guardrail 예시에 포함 | `paths` 설정과 실제 의존성 금지 검사를 구분한다. [S4] | -| 같은 검증의 다양한 이름을 일관성 문제로 제시 | null·blank·입력·도메인·인가의 의미를 먼저 구분한다. | -| 일반적인 오류 문구를 디버깅 위험 신호로 제시 | 외부의 안전한 안내와 내부 원인·연결 정보의 보존을 구분한다. | -| 테스트 계층 간 중복 검증을 피하도록 표현 | 같은 기능이어도 계층별 실패를 다루면 가치가 있음을 반영한다. | -| dual write를 포함한 마이그레이션 순서 예시 | 적용 조건·불일치·구버전 쓰기·백필 경쟁을 함께 평가한다. | -| feature 제거 시 migration 정리를 간단히 표현 | 이미 적용한 이력을 임의로 지우지 않고 안전한 제거 경로를 설계한다. | -| Backend·Frontend의 항목 목록 중심 | 실제 입력·경쟁·실패·배포 시나리오와 확인할 결과를 추가한다. | -| 템플릿 재사용의 장기 비용이 여러 관점에 분산 | 옵션 조합·기본값·샘플·소비자 업데이트·졸업 경로를 별도로 다룬다. | -| 점수·등급 중심으로 읽힐 가능성 | 적용 제외·미검증·목표 수준·증거 범위·차단 항목을 명시한다. | - -## 38. 참고한 공식 자료와 사용 범위 - -기존 원칙 자료 S1~S10 확인일: 2026-09-25. 추가 코드·문서 자료 S11~S24 확인일: 2026-09-28. S3·S10은 41절 보강 때 다시 확인했다. 아래 자료는 각각의 원칙과 사례를 확인하는 근거다. 이 문서의 28개 분류, 평가표, 예시 시나리오 전체가 해당 기관의 공식 기준이라는 뜻은 아니다. - -| 표기 | 자료 | 이 문서에서 참고한 내용 | -| --- | --- | --- | -| S1 | [Google Engineering Practices — What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html) | 설계·복잡성·불필요한 일반화·테스트의 유효성·명명·리뷰 범위 | -| S2 | [Google SRE — Monitoring Distributed Systems](https://sre.google/sre-book/monitoring-distributed-systems/) | 증상과 원인 구분, 이해 가능하고 대응할 수 있는 알림 | -| S3 | [AWS Well-Architected — Control and limit retry calls](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_mitigate_interaction_failure_limit_retries.html) | 재시도 상한·간격·jitter, 중첩 재시도와 부작용 위험 | -| S4 | [TypeScript — TSConfig paths](https://www.typescriptlang.org/tsconfig/paths.html) | 경로 해석 설정의 역할과 출력 import 경로를 변경하지 않는다는 제한 | -| S5 | [Kubernetes — Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/concepts/workloads/pods/probes/) | 검사 목적의 구분과 잘못된 liveness가 만드는 연쇄 장애 | -| S6 | [OWASP — Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html) | 최소 권한·기본 거부·요청별 권한 검증·클라이언트 검사 한계 | -| S7 | [W3C — Web Content Accessibility Guidelines 2.2](https://www.w3.org/TR/WCAG22/) | 키보드·포커스·오류 식별·상태 메시지 등 접근성 검토의 기준 | -| S8 | [SLSA v1.2 — Provenance](https://slsa.dev/spec/v1.2/provenance) | 산출물의 출처와 생성 과정을 추적하는 검증 가능한 정보 | -| S9 | [OWASP ASVS 5.0 — General Data Protection](https://cornucopia.owasp.org/taxonomy/asvs-5.0/14-data-protection/02-general-data-protection) | 민감정보 전송·캐시·수집·보호 정책의 확인 | -| S10 | [AWS Well-Architected — Make mutating operations idempotent](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_prevent_interaction_failure_idempotent.html) | 작업 식별·중복 억제·상태 추적·원자성·보관 기간의 검토 | -| S11 | [TanStack Query — React Quick Start](https://github.com/TanStack/query/blob/2e1ad64b525f6ff2034f169ab9c2f48f82f17296/docs/framework/react/quick-start.md) | 입문 문서에서 강조하는 Query·Mutation·Invalidation | -| S12 | [TanStack Query — query.ts](https://github.com/TanStack/query/blob/2e1ad64b525f6ff2034f169ab9c2f48f82f17296/packages/query-core/src/query.ts) | 내부 타입·상태·Action·retryer 위임과 완료 후 참조 정리 | -| S13 | [Spring Framework — TransactionTemplate.java](https://github.com/spring-projects/spring-framework/blob/93ff61fb1ff9b30654d5b44f488887ce100974f1/spring-tx/src/main/java/org/springframework/transaction/support/TransactionTemplate.java) | callback 실행·transaction manager 위임·rollback 실패 처리 | -| S14 | [Spring Security — AuthenticationManager.java](https://github.com/spring-projects/spring-security/blob/c09729200b15acac8ac53bd7f30646d4e81cfb36/core/src/main/java/org/springframework/security/authentication/AuthenticationManager.java) | 단일 메서드 계약에 담긴 성공·실패 의미와 조건부 상태 검사 | -| S15 | [Debezium — README](https://github.com/debezium/debezium/blob/main/README.md) | 공통 모듈과 DB 특화 모듈의 기능·성능 차이를 설명하는 범위 | -| S16 | [React Router — README](https://github.com/remix-run/react-router/blob/main/README.md) | framework 또는 library로 사용하는 범위의 구분 | -| S17 | [Java SE 21 — List](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/List.html#copyOf(java.util.Collection)) | `copyOf`의 수정 불가·후속 원본 변경과의 분리·null 제한·요소 가변성·반환 객체 재사용 가능성 | -| S18 | [Java SE 21 — Collections.unmodifiableList](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Collections.html#unmodifiableList(java.util.List)) | 원본 목록을 읽는 수정 불가능한 view의 계약 | -| S19 | [Java SE 21 — ArrayList](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/ArrayList.html) | 컬렉션을 받는 생성자와 목록 변경 연산 | -| S20 | [Java Language Specification 21 — §4.12.4 final Variables](https://docs.oracle.com/javase/specs/jls/se21/html/jls-4.html#jls-4.12.4) | 참조 재대입 제한과 참조 대상의 가변성 구분 | -| S21 | [Jakarta Persistence 3.2 — §2.1·§2.2](https://jakarta.ee/specifications/persistence/3.2/jakarta-persistence-spec-3.2) | Entity의 non-final 요구, 영속 필드·컬렉션의 접근 계약 | -| S22 | [AWS Prescriptive Guidance — Transactional outbox pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html) | 로컬 DB 변경과 발행 의도의 원자적 기록, 중복 전달·순서·후속 처리의 고려 사항 | -| S23 | [RFC 9110 — §9.2.1·§9.2.2·§10.2.3](https://www.rfc-editor.org/rfc/rfc9110.html) | HTTP의 safe·idempotent 의미, 비멱등 요청의 자동 재시도 조건, Retry-After | -| S24 | [Microsoft Azure Architecture Center — Cache-Aside](https://learn.microsoft.com/en-us/azure/architecture/patterns/cache-aside) | 캐시 적용 조건·만료·무효화·데이터 원본과의 정합성 한계 | - -## 39. 설계 의도와 코드 표현력 — 보호 장치를 유지하며 이해 부담 줄이기 - -이 절은 4번 인지 부하, 5번 위험 가시성, 9번 유지보수, 10번 테스트, 21번 Guardrail, 22번 추상화, 24번 의미 표현을 함께 검토하는 방법이다. 새로운 상위 성숙도 항목이나 점수를 추가하지 않는다. - -리뷰에서 묻는 것은 **“왜 이 코드가 이런 모양이어야 하는지 다음 수정자가 설명할 수 있는가?”**다. 안전장치가 많다는 사실과 코드가 잘 읽힌다는 사실은 각각 확인해야 한다. - -### 39.1 “고민과 결정이 드러나는 코드”의 의미 - -개발 당시의 모든 고민이 코드에 남을 필요는 없다. 다음 수정에 영향을 주는 제약과 결정은 현재 코드에서 찾을 수 있어야 한다. - -| 확인할 것 | 독자가 설명할 수 있어야 할 내용 | -| --- | --- | -| 해결할 문제 | 어떤 상황에서 어떤 잘못된 동작을 막는가? | -| 보호할 규칙 | 어떤 입력·실패·경쟁에서도 무엇을 유지해야 하는가? | -| 선택한 경계 | 왜 이 객체·함수·타입·트랜잭션이 이 일을 맡는가? | -| 선택 이유 | 더 단순해 보이는 대안을 쓰면 어떤 요구가 깨지는가? | -| 감수한 비용 | 이 선택이 만드는 지연·중복·메모리·학습 비용은 무엇인가? | -| 재검토 조건 | 어떤 요구나 환경이 바뀌면 이 선택을 다시 보아야 하는가? | - -예를 들어 완료된 비동기 작업의 핸들을 지우는 코드에서는 “핸들을 비운다”는 동작만 읽혀서는 부족할 수 있다. 오래 살아 있는 객체가 완료 결과를 계속 참조하지 않게 하려는 이유와, 새 작업이 시작됐다면 그 핸들은 보존해야 한다는 규칙을 확인할 수 있어야 한다. - -이 정도 이유가 코드의 조건·상태 소유권·짧은 주석·실패 테스트에서 드러나면 설계의 판단이 남아 있는 것이다. 새 인터페이스나 정책 객체를 추가해야만 의도를 표현할 수 있는 것은 아니다. - -이유의 타당성을 검토하는 공통 질문과 후속 답변 예시는 41절에 정리했다. 설득력 있는 설명만으로 현재 구현이 그 이유를 충족한다고 판정하지 않는다. - -### 39.2 결정의 이유를 어디에 남길 것인가 - -| 내용 | 우선 둘 위치 | 남길 정보 | -| --- | --- | --- | -| 업무 행위와 경계 | 함수·객체 이름과 호출 순서 | 무엇을 언제 수행하는가? | -| 허용 상태와 결과 | 타입·생성/변경 API·계약 | 어떤 상태와 실패를 구분하는가? | -| 예상 밖의 분기·순서 | 해당 코드 가까이의 짧은 주석 | 이 조건을 없애거나 순서를 바꾸면 왜 문제가 되는가? | -| 중요한 재발 조건 | 동작을 검증하는 테스트 | 어떤 입력·경쟁에서 어떤 결과를 지켜야 하는가? | -| 여러 대안과 비용 비교 | 설계 결정 기록(ADR) 또는 기존 설계 문서 | 선택 근거·포기한 대안·한계·재검토 조건 | -| 변경 과정과 상세 토론 | Git 이력·PR·이슈 | 누가 언제 무엇을 시도하고 바꿨는가? | - -한 줄의 조건식만으로 모든 선택 이유를 증명할 수는 없다. 코드가 동작과 규칙을 표현하고, 가까운 설명이 독자의 잘못된 추론을 막으며, 긴 비교는 별도 기록으로 이어지면 된다. - -설계 기록을 남기기 위해 모든 helper에 문서를 만들 필요는 없다. 대안을 다시 검토할 가능성이 높거나 선택의 비용이 큰 결정에 집중한다. - -“history는 Git에 있다”는 말은 변경 과정을 코드 주석에 길게 복사하지 말라는 취지로 사용한다. **현재도 유효한 선택 이유까지 Git 이력으로 밀어내지 않는다.** - -### 39.3 국소적 이해 — 필요한 범위에서 행동을 예측할 수 있는가 - -국소적 이해는 파일 하나만 읽고 시스템 전체를 이해한다는 뜻이 아니다. 대표 과제의 진입점과 공개 계약, 필요한 정책을 읽으면 해당 동작을 예측할 수 있어야 한다는 뜻이다. - -다음 과제를 하나 골라 작성자의 구두 설명 없이 따라간다. - -> “이 요청을 취소하면 어떤 처리가 중단되고, 어떤 데이터와 외부 부작용이 남는가?” - -읽은 파일 수와 함께 다음을 기록한다. - -- 이름과 타입만으로 알 수 있었던 것 -- 반드시 구현 안쪽까지 들어가야 했던 것과 이유 -- 전역 registry·설정 우선순위·호출 순서를 암기해야 했던 것 -- 다른 곳의 정보를 수동으로 맞춰야 했던 것 -- 실패 결과와 자원 정리의 소유자를 찾을 수 있었는지 - -**좋은 신호:** 구현은 여러 파일이어도 공개 계약이 안정되어 불필요한 내부 지식을 요구하지 않는다. - -**나쁜 신호:** 함수는 짧아졌지만 의미 없는 전달 계층을 계속 넘나들며, 중요한 실패 의미는 전역 실행 정책을 읽어야만 알 수 있다. - -“파일 2~3개면 합격” 같은 절대 기준을 만들지 않는다. 이전과 같은 과제를 다시 수행해 뜻밖의 이동과 숨은 전제가 줄었는지 비교한다. 설정·보안 정책을 모든 호출부에 복사해 넣는 것도 해결책이 아니다. - -### 39.4 내부 복잡성과 사용자가 알아야 할 개념을 분리한다 - -템플릿에서는 누가 코드를 읽고 바꾸는지에 따라 필요한 지식이 다르다. - -| 역할 | 주로 알아야 할 것 | 자동으로 떠안기지 않을 것 | -| --- | --- | --- | -| 제품 기능 작성자 | 기능의 입력·출력·경로·상태·필요 capability | 플랫폼의 모든 타입 조합·설치 registry 내부 | -| 앱을 조립하는 사람 | 기능 설치·환경별 구현·충돌·필수 의존성 | 각 기능의 내부 상태 전이 | -| 플랫폼 유지보수자 | capability 검증·타입 추론·수명·교체 경계 | 모든 제품 기능의 업무 정책 | - -예를 들어 `FeatureModule`에 제네릭 축이 여섯 개 있다는 사실만으로 복잡하다고 판정하지 않는다. 다음을 실제 호출부에서 확인한다. - -1. 기능 작성자가 여섯 타입을 직접 고르고 연결해야 하는가, 입력으로부터 추론되는가? -2. 각 축은 다른 잘못된 조합을 막는가, 같은 정보를 여러 형태로 전달하는가? -3. 기본 기능을 만들 때도 고급 확장 규칙을 모두 알아야 하는가? -4. 오류가 났을 때 부족한 입력과 해결 위치가 보이는가, 거대한 내부 타입만 나오는가? -5. 공개하지 않아도 될 구현 타입을 사용자 계약으로 노출했는가? - -`EmptyFeatureContract`, `AnyFeatureModule`, capability 관련 타입 등이 내부에서 정확성을 지키는 데 쓰이고 사용자에게 추론된다면 유지할 근거가 있다. 반대로 일반 기능 하나를 만들기 위해 모두 이해·작성해야 한다면 노출 범위를 줄일 후보가 된다. - -**완료 기준:** 같은 기능을 작성할 때 필요한 결정과 수동 연결이 줄며, 잘못된 capability·계약 조합은 이전과 같은 단계 또는 더 이른 단계에 이해 가능한 오류로 검출된다. - -제네릭 여섯 개를 거대한 설정 객체 하나로 감싸거나, 또 하나의 등록 DSL을 도입하는 것만으로 개선됐다고 보지 않는다. 실제 사용자의 작업을 기준으로 비교한다. - -### 39.5 선언·실행·검증이 같은 정보를 반복하는가 - -다음은 전달받은 평가에서 제시한 형태를 설명용으로 축약한 것이다. 현재 프로젝트의 실제 실행 방식은 확인하지 않았다. - -```java -@UseCaseCapability(transactionMode = WRITE) -public Result execute(Command command) { - return tx.inWrite(() -> perform(command)); -} -``` - -겉모습만 보면 두 곳에서 쓰기 트랜잭션을 말한다. 그러나 무엇이 원본 정책이며 각각 누가 읽는지에 따라 판단은 달라진다. - -| 상황 | 판단 | -| --- | --- | -| annotation을 런타임이 소비해 실제 경계를 구성한다. | 실행 경로와 중첩·충돌을 확인한다. 단순 설명 메타데이터로 취급하지 않는다. | -| annotation은 독립적인 허용 조건이고 검사가 실제 실행과 대조한다. | 검출하는 위반 사례와 검사 한계가 분명하면 가치가 있다. | -| 한쪽은 다른 쪽에서 생성되거나 추론되며 사람이 두 곳을 맞추지 않는다. | 생성·추론의 원본과 검증 범위를 확인한다. | -| 어느 도구도 읽지 않고 개발자가 두 곳을 항상 맞춰야 한다. | 중복 유지 비용이다. 삭제·통합·계약 설명으로 대체할 후보가 된다. | -| 검사도 선언값만 다시 읽고 실제 동작은 확인하지 않는다. | 검사 통과를 선언·실행 일치의 증거로 사용할 수 없다. | - -**확인할 네 가지:** 정보의 원본, 실제 소비자, 불일치 시 검출 지점, 그 검사가 놓치는 실행 경로다. - -독립적인 기대값과 실제 구현을 비교하는 것은 유용한 중복이다. 테스트의 기대값까지 구현에서 그대로 생성하면 독립적인 검증을 잃을 수 있다. 따라서 “한 사실은 한 번만 적는다”는 원칙을 기계적으로 적용하지 않는다. - -`@RequiresPermission`처럼 권한에 관련된 annotation은 실제 인가를 수행할 수 있다. 선언처럼 보인다는 이유로 제거하지 않고 interceptor·필터·검증기의 실제 사용을 확인한다. 제거 제안에는 동등한 권한 통제가 어디에 남는지 적는다. - -### 39.6 추상화의 필요성을 입증하는 질문 - -삭제 후보마다 다음 정보를 간단히 적는다. 프로젝트 전체에 새로운 registry나 자동화 시스템을 만들 필요는 없다. 실제로 논쟁이 있는 몇 개만 검토한다. - -| 질문 | 확인할 증거 | -| --- | --- | -| 누가 사용하는가? | 실제 호출부와 사용자의 역할 | -| 무엇을 대신 책임지는가? | 실패·수명·권한·변경 경계와 계약 | -| 없으면 무엇이 깨지거나 반복되는가? | 도달 가능한 실패 또는 호출자에 복제될 정책 | -| 어떤 차이를 표현하는가? | 실제 구현·설정·소비자의 차이 | -| 왜 지금 필요한가? | 현재 요구 또는 명시된 지원 범위 | -| 사용자가 지불하는 비용은 무엇인가? | 필수 개념·등록·타입 지정·탐색·오류 해석 | -| 더 작은 수단으로 충분한가? | 함수·모듈 비공개화·기본값·기존 라이브러리·부분 중복과의 비교 | - -판정은 유지, 내부로 감추기, 합치기, 나누기, 제거 중에서 고른다. 모든 복잡성 문제의 답이 제거는 아니다. - -**단일 소비자도 충분한 이유가 될 수 있다.** 외부 결제 호출, 단일 DB 구현, 인가 경계를 격리하는 포트는 소비자가 하나여도 의미가 있다. 두 번째 소비자 유무는 재사용 가능성의 증거 중 하나다. - -**함께 바뀌는 이유를 본다.** 변경 이력에서 자주 같이 수정됐다는 사실만으로 공통화하지 않는다. 대규모 포맷 수정이나 일괄 마이그레이션으로 함께 바뀌었을 수도 있다. 같은 정책 때문에 함께 바뀌는지, 차이가 생겼을 때 예외 인자가 계속 늘어나는지를 확인한다. - -**코드 경제성은 줄 수의 최소화가 아니다.** 같은 계약을 제공하는 데 필요한 개념·수동 연결·변경 지점과 유지 비용을 줄이는 것이다. 조금의 중복이 서로 다른 정책을 독립적으로 이해하게 한다면 허용할 수 있다. - -### 39.7 큰 실행기를 나눌 때는 상태와 정책의 소유권을 본다 - -HTTP 실행기에 deadline, retry, auth, cancellation, idempotency, 응답 크기 제한, schema 검증, 관측이 모여 있다고 해서 전부 분리해야 하는 것은 아니다. 같은 요청의 시간·시도 횟수·취소 상태를 조율해야 하므로 함께 판단할 부분이 있다. - -| 확인 질문 | 유지·분리 판단에 주는 정보 | -| --- | --- | -| 같은 상태와 수명을 공유하는가? | 같은 상태 전이를 소유하는 핵심 조율부가 필요한가? | -| 정책을 바꿀 때 함께 바뀌어야 하는가? | 독립적인 변화 이유가 섞였는가? | -| 순서가 정확성에 영향을 주는가? | 분리하면 호출자가 순서를 외워야 하는가? | -| 외부 I/O 없이 판단할 수 있는가? | 순수한 판정 함수로 좁힐 수 있는가? | -| 오류·취소·정리의 책임이 이어지는가? | 분리 뒤 누가 최종 상태와 자원을 책임지는가? | -| 테스트가 어느 경계를 검증하는가? | 의미 있는 경계인가, 같은 상태를 나눠 숨긴 것인가? | - -예를 들어 재시도 가능 여부를 계산하는 함수는 분리할 수 있어도, 전체 deadline에서 남은 시간을 계산하고 실제 재시도를 예약하는 주체는 일관된 상태를 알아야 한다. 취소와 재시도를 서로 모르는 실행기로 옮기면 정합성을 오히려 해칠 수 있다. - -분리한다면 정상 흐름과 중요한 실패 분기를 조율부에서 읽을 수 있게 하고, 별도 함수가 맡는 판단을 이름과 계약으로 설명한다. 여러 개의 `*Policy`, `*Context`, `*Descriptor`로 파일만 나눈 뒤 더 많은 규약을 요구하는 구조는 개선으로 판정하지 않는다. - -**완료 기준:** 독립적인 정책 변경의 영향 범위가 줄고, 요청의 시간·취소·시도·자원 정리 순서를 여전히 설명할 수 있다. 파일 길이는 결과로 기록할 수 있지만 합격 조건으로 고정하지 않는다. - -### 39.8 주석·조건·테스트가 하나의 결정을 설명하는 예 - -다음은 설명용 TypeScript 축약 예시다. 생략한 타입·주변 구현을 포함하는 제품 코드나 그대로 실행할 완성 예제가 아니다. - -결정의 이유를 알기 어려운 형태: - -```typescript -finally { - // Q-6.9-7 반영 - releaseAttempt(attempt); -} -``` - -독자는 리뷰 문서에서 번호를 찾고, helper 구현을 열고, 어떤 상태를 보호하는지 다시 추론해야 한다. helper가 실제 책임을 캡슐화한다면 유지할 수 있지만 주석은 그 책임을 설명하지 못한다. - -선택 이유가 가까이 드러나는 형태: - -```typescript -finally { - // 완료된 작업의 결과를 계속 붙잡지 않도록 참조를 해제한다. - // 그사이 새 작업이 시작됐다면 새 작업의 핸들은 유지한다. - if (activeAttempt === attempt) { - activeAttempt = undefined; - } -} -``` - -여기서 조건은 어떤 핸들을 지울 수 있는지 제한하고, 주석은 참조 해제와 소유권 검사의 이유를 설명한다. 이 형태가 실제 제품의 상태 소유권에 맞는지는 별도로 확인해야 한다. - -중요한 경쟁을 검증하는 예시는 다음과 같다. - -1. 작업 A를 시작한다. -2. A의 정리 전에 작업 B가 현재 작업이 되도록 한다. -3. A의 정리를 실행한다. -4. B가 여전히 현재 작업인지 확인한다. - -테스트는 private 필드명이나 helper의 모양을 고정하기보다, B의 취소·조회·진행 관리가 계속 올바르게 동작하는지를 확인한다. - -같은 원칙으로 owner signal에서 listener를 떼는 코드에는 “리뷰 지적 반영”보다 **owner가 더 오래 살아도 완료된 작업을 listener가 계속 참조하지 않게 한다는 이유**를 남긴다. 실제로 어떤 참조가 객체 수명을 늘리는지는 구현에서 확인한다. - -**이슈·명세 링크는 삭제 대상이 아니다.** 브라우저 버그, 프로토콜 규칙, 보안 제약, 호환성 우회처럼 원본 근거가 중요한 경우 짧은 설명 뒤에 링크나 식별자를 남긴다. “Spec §10”만 있고 현재 코드와의 관계가 설명되지 않는 상태를 개선한다. - -### 39.9 단순화 전후에 지켜야 할 조건 - -줄 수나 공개 타입이 줄어들었더라도 다음 계약을 잃으면 단순화에 성공한 것이 아니다. 변경한 경계에 관련된 항목만 선정해 검증한다. - -| 보존할 성질 | 확인할 회귀 | -| --- | --- | -| 중요한 상태 구분 | 결과 불명·거부·일시 실패를 같은 값으로 합치지 않았는가? | -| 타입 안전성 | 잘못된 기능 조합을 `any`·단언·느슨한 옵션으로 허용하지 않았는가? | -| 권한·데이터 범위 | 내부화하거나 공통화한 상태가 사용자·테넌트 사이에 섞이지 않는가? | -| 부작용 계약 | 시간 제한·재시도·취소·멱등성 의미가 유지되는가? | -| 자원 수명 | listener·timer·연결·완료 결과를 적절한 주체가 정리하는가? | -| 진단 가능성 | 오류의 원인·작업 식별·적용 정책을 찾을 수 있는가? | -| 변경 경계 | 없앤 helper의 정책을 여러 호출자가 각자 구현하게 되지 않았는가? | -| 사용·오류 설명 | 정상 과제는 쉬워졌지만 실패 시 내부 전체를 알아야 하는 구조가 되지 않았는가? | - -제네릭이나 schema 경계를 바꿨다면 대표적인 금지 조합이 여전히 검출되는지 확인한다. 수명주기를 바꿨다면 취소·경쟁·정리 조건을 확인한다. 설명 주석만 고쳤다면 실행 동작이 바뀌지 않았는지와 사실이 맞는지를 확인한다. - -이 검토 때문에 모든 변경에 대규모 테스트를 요구하지 않는다. 줄이려는 복잡성이 무엇을 보호했는지 파악하고, 그 보호가 사라질 구체적인 위험을 검증한다. - -### 39.10 리뷰 결과를 리팩터링 작업으로 바꾸는 방법 - -대상 하나마다 다음 내용을 기록한다. - -> 대표 과제와 사용자 → 현재 알아야 할 개념 → 보호할 규칙 → 불필요한 부담의 근거 → 비교한 작은 대안 → 유지할 계약 → 확인할 결과 - -예를 들어 “capability 관련 타입이 많으니 삭제”라는 지시는 부족하다. 다음처럼 작성한다. - -> 일반 기능 작성자가 실제로 지정하는 타입·등록값을 확인한다. 입력으로 추론할 수 있는 정보와 플랫폼 내부에서만 필요한 타입을 분리한다. 선언하지 않은 capability 사용과 host 제공 누락의 검출을 유지하면서, 기능 작성 시 필요한 수동 연결을 줄인다. 기존 구현이 이미 이 조건을 만족하면 변경하지 않는다. - -다음 질문에도 답해야 한다. - -- 분리·통합·삭제 외에 이름이나 주석을 고치는 것으로 충분한가? -- 기존 라이브러리가 맡을 수 있는 책임을 자체 framework로 다시 만들었는가? -- 단순화를 위해 추가한 facade가 실제 사용 계약을 좁혔는가, 전달 계층만 하나 늘렸는가? -- 바꾼 뒤 같은 대표 과제를 수행하면 무엇이 실제로 쉬워지는가? - -이 기준은 “초보·중급·고수”라는 등급을 부여하기 위한 것이 아니다. 리뷰어의 취향을 검증 가능한 변경 제안으로 바꾸기 위한 것이다. - -## 40. 오픈소스 비교에서 확인한 사실과 평가의 한계 - -이 절은 전달받은 비교 글을 그대로 채택하지 않고, 확인한 코드와 문서에서 어떤 원칙을 가져올 수 있는지 정리한다. 오픈소스의 인지도나 규모가 모든 설계 선택의 정답을 보장하는 것은 아니다. - -### 40.1 확인된 내용과 가이드에 적용할 해석 - -| 대상 | 원문에서 확인한 내용 | 이 가이드의 해석과 한계 | -| --- | --- | --- | -| TanStack Query 입문 문서 | Query·Mutation·Invalidation을 핵심 입문 개념으로 제시한다. [S11] | 입문 경로를 좁힌 사례다. 사용자가 항상 세 개만 알면 충분하다는 증거는 아니다. | -| TanStack Query 내부 | `Query`에 여러 제네릭·상태가 있으며 `Action`과 `retryer` 등을 사용한다. 완료 후 참조를 정리하는 코드와 이유 설명도 있다. [S12] | 내부 타입 수와 일반 사용자에게 노출되는 필수 개념 수를 구분한다. | -| Spring TransactionTemplate | callback 수행과 transaction manager 위임이 보인다. rollback 실패 종류에 따라 원래 예외를 연결하거나 로그에 남기는 처리도 있다. [S13] | 의미 있는 책임을 한곳에서 읽는 사례다. 하위 manager와 기반 클래스의 복잡성까지 파일 길이에 포함된 것은 아니다. | -| Spring AuthenticationManager | 단일 인증 메서드에 반환·예외 계약을 설명한다. disabled·locked 검사는 해당 상태를 확인할 수 있는 경우라는 조건이 붙는다. [S14] | 짧은 API도 정밀한 계약이 필요하다. 인터페이스만 읽고 모든 구현이 계약을 지킨다고 결론내릴 수는 없다. | -| Debezium README | 여러 DB에 적용하는 모듈과 특정 DB 기능을 활용하는 모듈의 차이를 설명한다. [S15] | 공통화에 따른 제약을 읽을 수 있다. README만으로 전체 구현의 응집도나 변경 비용을 판정하지 않는다. | -| React Router README | framework 또는 library로 사용할 수 있다고 설명한다. [S16] | 사용 범위의 차이를 확인했다. 핵심 상태 머신의 응집도·파일 길이·flag별 테스트 범위는 이 README로 입증하지 못한다. | - -TanStack Query의 완료 처리에서는 결과 참조가 남는 이유를 주석으로 설명하고, 현재 `retryer`가 정리 대상과 같은지 확인한 뒤 참조를 해제한다. 이 조건이 다른 작업의 핸들을 지우지 않도록 제한한다는 해석은 코드에서 도출한 것이다. 39.8절의 예시는 이와 같은 판단을 설명하기 위해 별도로 작성했다. [S12] - -실행 테스트나 저장소 전체 리뷰를 수행한 것은 아니다. 이 사례들은 특정한 설계 판단을 읽는 근거로만 사용한다. - -### 40.2 확인한 버전 - -| 자료 | 확인 기준 | -| --- | --- | -| S11·S12 TanStack Query | 커밋 `2e1ad64b525f6ff2034f169ab9c2f48f82f17296`; `query.ts` 파일 blob `fad5c2067a1e1bb3b8d644abc76267b59f6a5e28` | -| S13 Spring Framework | 커밋 `93ff61fb1ff9b30654d5b44f488887ce100974f1`; 파일 blob `475994bd3136da0030fb0482bdab0057b822a061` | -| S14 Spring Security | 커밋 `c09729200b15acac8ac53bd7f30646d4e81cfb36`; 파일 blob `b95d8c4f0789cb647273657b6e8913fc328e95c6` | -| S15 Debezium README | 2026-09-28 조회한 main 파일 blob `6bb1276d5f7a898980cc8623646555e59a86aaab` | -| S16 React Router README | 2026-09-28 조회한 main 파일 blob `8e1210841f3febba5009b0a1f7c3e33ce1d051f1` | - -blob은 파일 내용의 식별자이며 저장소 커밋과 다르다. S15·S16의 main 링크는 이후 내용이 바뀔 수 있다. - -### 40.3 그대로 받아들이지 않을 평가 - -- **“현재 두 템플릿의 아키텍처·안전성은 매우 강하다.”** 현재 코드·검사·실행 결과를 확인한 뒤 부여할 평가다. 복잡하고 정교해 보인다는 사실만으로 안전성이 입증되지는 않는다. -- **“제네릭 여섯 개, 타입 여러 개이므로 사용자가 알아야 할 개념이 많다.”** 실제 작성 지점·추론·오류 경험과 사용자 역할을 확인해야 한다. -- **“리뷰·명세 번호가 없는 코드가 더 성숙하다.”** 현재 제약과 원본 근거의 연결이 유용하다면 남긴다. 설명 없이 번호만 있는 상태가 문제다. -- **“고수 코드는 줄 수와 추상화가 적다.”** 비교 대상의 책임 범위와 위임한 하위 구현을 맞추지 않으면 성립하지 않는 평가다. -- **“두 번째 소비자가 없는 추상화는 삭제한다.”** 재사용 외에 경계·정확성·테스트 대역을 위한 이유가 있을 수 있다. -- **“일단 안전성이 완성됐으니 다음은 취향만 다듬으면 된다.”** 단순화 중에 보호 장치가 약해질 수 있다. 정확성과 이해 비용을 함께 확인한다. - -전달받은 글에 등장하는 `FeatureModule`, `feature-adapter-contribution.ts`, `http-execution-v3.ts`, `CreateWorkLogUseCase`의 구체적인 상태와 파일 길이·변경 수·브랜치·커밋은 이번 가이드 보강에서 재확인하지 않았다. 코드 리뷰를 시작할 때 최신 상태와 적용 범위를 고정한다. 이를 현재 프로젝트의 확정된 결함이나 등급으로 기록하지 않는다. - -### 40.4 비교할 때 책임 범위부터 맞춘다 - -비교 단위를 “파일 하나 대 파일 하나”로 고정하지 않는다. 같은 사용자 과제와 실패 책임을 수행하는 코드 범위를 비교한다. - -| 먼저 맞출 조건 | 확인할 질문 | -| --- | --- | -| 사용자 역할 | 라이브러리 사용자와 내부 유지보수자를 섞어 비교하지 않았는가? | -| 책임 범위 | 한쪽이 직접 처리하고 다른 쪽이 아래로 위임한 책임은 무엇인가? | -| 지원 조건 | 버전 호환·실행 환경·취소·재시도·데이터 범위가 같은가? | -| 관찰 과제 | 정상 사용·변경·오류 해결 중 무엇을 비교하는가? | -| 보호할 성질 | 같은 위험을 통제한 상태에서 비교하는가? | - -좋은 비교는 “저쪽에는 이 타입이 없으니 삭제하자”에서 끝나지 않는다. **“저쪽은 이 책임을 어디에서 해결하며, 우리도 그 방법을 적용하면 어떤 계약과 비용이 달라지는가?”**까지 확인한다. - -리뷰 결과에는 남겨야 할 복잡성과 없앨 수 있는 부담을 함께 적는다. 다른 사람이 코드와 근거를 읽고 같은 결정을 검토할 수 있을 때, 설계 의도가 코드에 드러난다고 평가할 수 있다. - -## 41. 설계 선택 설명 검증 — Decision Explanation Test - -리뷰 후 “왜 여기서 이 방법을 썼는가?”라는 질문에 **요구와 코드 근거, 현실적인 대안, 감수한 비용, 선택이 달라질 조건**을 연결해 답할 수 있는지 확인한다. 설명을 잘하는 능력만 평가하는 절차가 아니다. 설명한 성질을 현재 코드가 실제로 보장하는지까지 검토한다. - -39절은 선택 이유를 코드와 주변 기록에 어떻게 드러낼지 다뤘다. 이 절은 그 이유가 타당한지 판단하고, 후속 질문에 답하는 공통 방식이다. 언어 기능부터 분산 처리·템플릿 구조까지 적용하되 새로운 성숙도 점수나 필수 문서 체계를 만들지 않는다. - -아래 사례의 요구조건과 답변은 설명용 가정이다. 실제 프로젝트의 요구, 선택 이력, 동작을 확인했다는 뜻이 아니다. 기술 계약은 38절의 자료와 연결하고, 해당 계약에서 도출한 설계 판단은 이 가이드의 제안으로 제시한다. - -### 41.1 어떤 선택에 적용할 것인가 - -계약·실패·유지보수 비용에 영향을 주는 대표적인 선택에 적용한다. - -- 가변 상태를 공유하거나 복사하는 지점 -- 객체가 생성·변경될 때 지켜야 하는 업무 규칙 -- 공개 API의 입력·결과·오류·호환성 계약 -- 트랜잭션, 인가, 외부 부작용, 취소·재시도 경계 -- 캐시·동시성·배포·복구 방식 -- 모듈·플러그인·기능 조립·템플릿 업데이트 구조 -- 단순화 과정에서 제거하려는 보호 장치나 추상화 - -명백한 지역 계산까지 대안표를 만들지는 않는다. `Math.max(a, b)`처럼 의미가 충분히 드러나면 코드로 설명을 마칠 수 있다. 다만 같은 계산이라도 금액 상한이나 권한 범위를 결정한다면 주변 계약을 확인한다. 설명의 깊이는 문법의 난이도보다 영향 범위와 오해했을 때의 피해에 맞춘다. - -### 41.2 일곱 가지 공통 질문 - -| 질문 | 답변에 포함할 내용 | -| --- | --- | -| 1. 무엇이 필요한가? | 사용자·호출자, 현재 지원 환경, 정확성·성능·운영 요구, 확인되지 않은 전제 | -| 2. 반드시 지킬 성질은 무엇인가? | 어떤 입력·순서·부분 실패에서도 유지해야 할 규칙과 책임 주체 | -| 3. 현재 코드는 어떻게 보장하는가? | 실제 파일·심볼·실행 경계·타입·제약·검증 근거와 보장하지 않는 범위 | -| 4. 현실적인 대안은 무엇인가? | 현상 유지, 기능을 추가하지 않기, 더 작은 수단, 현재 요구에 맞는 다른 접근 | -| 5. 대안마다 무엇을 얻고 지불하는가? | 정확성, 이해 부담, 성능, 실패 특성, 변경·이행 비용, 운영 책임 중 관련 항목 | -| 6. 현재 조건에서 왜 이 선택인가? | 요구를 충족하는 후보 사이에서 선택한 이유와 받아들인 제한 | -| 7. 어떤 조건이면 선택이 달라지는가? | 새 요구, 의존 계약 변화, 측정 결과, 규모·팀·배포 변화와 다시 비교할 대안 | - -필수 계약을 위반하는 대안은 비용이 낮다는 이유만으로 동등한 후보가 되지 않는다. 반대로 현재 요구에 없는 가상 미래를 위해 복잡한 선택을 자동으로 정당화하지 않는다. - -대안을 많이 나열하는 것도 목표가 아니다. 실제 판단을 바꿀 수 있는 후보와 가장 단순한 후보를 비교한다. 대안이 사실상 하나뿐인 경우에는 그 제약을 설명하면 된다. 상충하는 요구를 동시에 만족할 수 없다면 무엇을 완화해야 하는지 드러낸다. - -“가장 좋은 방법”이라는 표현에는 비교 범위가 필요하다. 측정하지 않은 성능 우위나 모든 대안을 검토했다는 주장을 피하고, **“확인한 조건과 비교한 후보에서는 이 선택이 타당하다”**고 설명한다. - -### 41.3 확인한 사실·기록된 의도·추론을 구분한다 - -현재 코드가 어떤 효과를 낸다는 사실만으로 작성자가 그 효과를 의도했다고 단정할 수는 없다. - -| 구분 | 근거 | 적절한 답변 | -| --- | --- | --- | -| 현재 동작·계약 | 코드·명세·실행 결과 | “이 생성자는 입력 목록의 후속 변경이 저장된 목록에 반영되지 않도록 합니다.” | -| 기록된 결정 | 현재 코드와 연결되는 ADR·PR·이슈·주석 | “당시 기록에는 외부 변경으로 규칙이 깨지는 문제를 막기 위한 선택이라고 설명돼 있습니다.” | -| 현재 조건에서의 해석 | 확인한 요구와 코드 효과의 비교 | “선택 이력은 없지만, 생성 후 목록 고정이 요구라면 이 구현은 그 요구와 맞습니다.” | -| 미확인 | 요구·호출부·의존 계약·측정 부재 | “내부에서 목록을 변경해야 하는지는 확인하지 못해 최종 선택은 조건부입니다.” | - -과거 결정 기록도 현재 코드와 다르면 그대로 답에 사용하지 않는다. 작성자의 동기는 미확인이어도 현재 선택의 효과와 타당성은 분석할 수 있다. - -리뷰어는 현재 구현을 방어하기 위해 요구를 만들어내지 않는다. 요구가 없으면 필요한 확인을 좁히고, 그동안 가능한 조건별 판단을 제시한다. 성능 수치, 장애 경험, 두 번째 소비자, 운영 규모를 근거 없이 보충하지 않는다. - -**말로 설명할 수 있는 것과 코드에 표현되어 있는 것도 다르다.** 작성자만 아는 전제가 긴 구두 설명에만 존재한다면 4번 인지 부하·9번 유지보수의 개선 후보다. 다음 수정자가 필요한 근거를 코드·계약·짧은 설명·연결된 기록에서 찾을 수 있어야 한다. - -### 41.4 다섯 범위에서 같은 질문을 적용한다 - -다음은 개발자의 등급이나 성숙도 단계가 아니라 서로 다른 검토 범위다. 작은 언어 선택이 시스템 계약에 영향을 줄 수 있고, 플랫폼 구조가 지역 코드의 이해 부담을 늘릴 수도 있다. - -| 범위 | 대표 대상 | 중심 질문 | 관련 범위로 이어지는 질문 | -| --- | --- | --- | --- | -| 1. 언어·자료구조 | null, Optional, record, equals/hashCode, 예외, 방어적 복사 | 허용하는 값·상태는 무엇이며, 누가 변경할 수 있는가? | 가변 요소·키가 외부로 노출되거나 동시 접근되면 계약이 유지되는가? | -| 2. 객체·도메인 | Entity, Value Object, Aggregate, Factory, 상태 전이 | 업무 규칙을 누가 생성·변경 경계에서 지키는가? | 재구성·역직렬화·동시 갱신이 그 경계를 우회하는가? | -| 3. 애플리케이션·아키텍처 | UseCase, Port, Adapter, Repository, Transaction, Event, 인가 | 어떤 변화와 실패를 이 경계가 격리하는가? | 경계 밖 부작용과 안쪽 상태가 어긋나면 누가 복구하는가? | -| 4. 분산 처리·운영 | 재시도, 멱등성, 캐시, 락, 전달, 마이그레이션, 배포 | 부분 실패와 동시 실행에서도 어떤 계약을 유지하는가? | 결과 불명·중복·구버전 공존을 관찰하고 수습할 수 있는가? | -| 5. 시스템·플랫폼 | 모듈 구성, 플러그인, 기능 조립, CI, 팀 책임, 템플릿 진화 | 사용자가 알아야 할 개념과 변경 범위를 통제하는가? | 사용 프로젝트에 수정이 전파되고, 지원하지 않는 조합이 드러나는가? | - -넓은 시야는 모든 리뷰에서 다섯 범위를 전부 조사한다는 뜻이 아니다. **현재 선택의 보장이 어디까지 유효하며, 다음 경계에서 무엇이 추가로 필요한지** 아는 것이다. - -예를 들어 결제 요청 객체의 목록을 불변으로 만들면 그 객체의 상태 변경을 제한할 수 있다. 그것만으로 중복 요청의 결제 실행까지 막지는 못한다. 같은 업무 작업을 식별하는 계약과 서버의 중복 처리 방식을 별도로 확인해야 한다. - -반대로 단일 객체 내부의 변경 문제를 해결하는 데 분산 락·이벤트 플랫폼부터 제안하는 것도 범위를 잘못 잡은 판단이다. - -### 41.5 언어·자료구조 예시 — 왜 List.copyOf인가 - -다음 코드만으로는 요구를 확정할 수 없다. - -```java -class Sample { - private final List values; - - Sample(List values) { - this.values = values; - } -} -``` - -`final`은 필드에 다른 참조를 대입하지 못하게 한다. 참조 대상 목록의 변경까지 막지는 않는다. 호출자가 같은 가변 목록을 가지고 있다면 생성 이후에도 그 내용을 바꿀 수 있다. 이것이 이 예시에서 확인할 **가변 객체의 공유 참조, 즉 mutable aliasing**이다. [S20] - -먼저 다음을 확인한다. - -- 생성 이후 목록의 항목·순서가 고정되어야 하는가? -- 클래스 내부에서 추가·삭제·교체해야 하는가? -- 호출자와 변경을 공유하는 것이 의도된 계약인가? -- null 입력·null 요소를 허용하는가? -- 요소 자체도 가변인가? 반환 경로를 통해 내부 상태를 바꿀 수 있는가? -- 입력 크기와 복사 빈도가 실제 비용인가? 입력을 읽는 동안 동시 변경이 가능한가? - -**대안 비교** - -| 선택 | 원본 목록의 후속 변경 | 보관한 목록 변경 | 적합한 조건과 한계 | -| --- | --- | --- | --- | -| `this.values = values` | 공유한다. | 입력 구현에 달려 있다. | 공유가 의도되거나 별도 소유권 계약이 보장될 때 가능하다. 다른 참조의 변경을 이 코드가 제한하지는 않는다. | -| `Collections.unmodifiableList(values)` | view에 반영된다. | view를 통한 수정은 거부한다. | 읽기 전용 접근을 제공하면서 소유자의 변경은 보여줘야 할 때 적합하다. 스냅샷은 아니다. [S18] | -| `new ArrayList<>(values)` | 목록 상태를 분리한다. | 클래스 안에서 변경할 수 있다. | 내부 변경이 필요한 객체에 맞는다. 내부 목록을 그대로 반환하면 다시 외부 변경을 허용한다. [S19] | -| `List.copyOf(values)` | 반환 목록에 반영되지 않는다. | 추가·삭제·요소 교체를 거부한다. | 목록 구성을 고정할 때 맞는다. null 입력·요소를 거부하며, 요소 객체까지 복제하지는 않는다. [S17] | - -네 선택 모두 같은 목적의 우열 관계는 아니다. 실시간 view와 고정된 스냅샷은 서로 다른 계약이다. `Collections.unmodifiableList(new ArrayList<>(values))`도 복사본을 외부에 따로 노출하지 않으면 목록 상태를 분리하는 선택이다. null 허용·지원 Java 버전 등 관련 조건이 있을 때 비교한다. - -**조건을 붙인 답변 예시** - -> 이 객체는 생성 이후 저장된 목록 구성이 바뀌지 않아야 한다고 가정했습니다. 참조를 그대로 보관하면 호출자가 항목을 추가·삭제·교체할 수 있고, 원본을 감싼 읽기 전용 view도 그 변경을 보여줍니다. 내부 변경 역시 필요 없고 null을 허용하지 않는 계약이어서, 이 조건에서는 `List.copyOf`가 적합합니다. 내부 추가·삭제가 필요해지면 방어적 가변 복사와 변경 메서드의 규칙을 다시 검토하겠습니다. - -여기서 “소유권을 가져온다”는 표현은 주의해서 쓴다. Java에서 이 호출이 원본에 대한 호출자의 권한을 회수하는 것은 아니다. **저장할 목록 상태를 원본의 후속 변경과 분리하는 것**이다. - -**보장 범위를 넘겨 설명하지 않을 것** - -- `List`의 요소가 가변이라면 요소 상태의 공유는 남는다. 객체 전체의 불변성이 요구되면 요소의 소유권·불변 모델·필요한 복사 범위도 검토한다. 원래 예시의 `String`과 가변 도메인 객체를 동일하게 취급하지 않는다. [S17] -- `List.copyOf`가 언제나 새 목록을 할당한다고 가정하지 않는다. 구현은 적합한 수정 불가능 목록을 재사용할 수 있다. 비용은 실제 입력 구현·크기·호출 빈도를 기준으로 판단한다. [S17] -- 복사 호출 자체를 동시 변경 중인 입력의 일관된 스냅샷 보장으로 해석하지 않는다. 필요한 일관성은 입력 자료구조와 동기화 계약에서 별도로 확인한다. -- 가변 목록을 반환할 때 view를 줄지 스냅샷을 줄지도 계약이다. `unmodifiableList(internal)`은 내부의 후속 변경을 보여주며, 목록을 복사해 반환하는 방식은 복사 시점의 구성을 제공한다. 요소 가변성은 어느 쪽에서도 따로 살핀다. - -**JPA Entity에는 그대로 적용하지 않는다.** 영속 컬렉션의 변경·관계 동기화·provider 접근 방식을 확인한다. Jakarta Persistence 3.2는 Entity의 영속 인스턴스 변수가 non-final이어야 한다고 규정하므로, `@OneToMany private final List<...>` 자체도 이식 가능한 명세 준수 예제로 볼 수 없다. 특정 provider에서 돌아간다는 사실과 표준 계약을 구분한다. 불변 목록을 사용했을 때의 구체적인 실패 여부는 provider 버전·매핑·persist/merge/관계 변경 경로로 확인한다. [S21] - -검증이 필요한 변경이라면 JDK 구현을 다시 테스트하기보다 **우리 객체의 계약**을 확인한다. 생성 후 호출자의 입력 변경이 업무 결과를 바꾸는지, 공개 변경 메서드가 규칙을 지키는지, 반환한 값으로 내부 상태를 우회 변경할 수 있는지 중 변경과 관련된 시나리오를 고른다. - -### 41.6 트랜잭션·분산 처리 예시 — 왜 Outbox인가 - -다음은 일반적인 로컬 DB 트랜잭션과 별개의 외부 API를 사용하는 설명용 코드다. 외부 서비스가 같은 분산 트랜잭션에 참여한다는 전제는 두지 않는다. - -```java -tx.inWrite(() -> { - repository.save(order); - externalApi.charge(); -}); -``` - -호출 순서만 읽어서는 원자성을 설명할 수 없다. 외부 호출 성공 후 DB commit이 실패하거나, 외부에서 처리했지만 응답이 유실될 수 있다. 트랜잭션 블록 안에 있다는 이유만으로 외부 결제가 DB rollback과 함께 취소되지는 않는다. - -먼저 확정해야 할 것은 “주문을 접수할 때 결제 완료가 필수인가?”, “결제 대기 상태를 허용하는가?”, “결과 불명을 조회·대사할 방법이 있는가?”다. 이 답이 대안의 적합성을 바꾼다. - -| 선택 | 해결하는 부분 | 남는 문제와 비용 | -| --- | --- | --- | -| DB 트랜잭션 안에서 외부 호출 | 한 실행 흐름에서 결과를 받아 분기한다. | 일반적인 외부 API와 로컬 DB의 공동 원자성은 없다. 외부 지연 중 DB 자원·획득한 락을 오래 보유할 수 있다. | -| 로컬 commit 후 직접 호출 | 외부 대기 시간을 DB 트랜잭션 밖으로 옮긴다. | commit 직후 중단되면 호출 누락이 생길 수 있다. 별도의 지속 가능한 작업·복구 수단이 필요할 수 있다. | -| 로컬 상태와 Outbox 레코드를 함께 기록 | DB 변경과 후속 전달 의도를 같은 로컬 트랜잭션에 남긴다. | 전달 지연·중복, relay 운영, 후속 처리 결과 반영을 다뤄야 한다. [S22] | -| 예약 후 확정, 또는 Saga·보상 절차 | 여러 단계의 업무 상태와 복구 경로를 명시한다. | 외부 API의 지원 계약, 만료·보상 실패·결과 불명 처리가 필요하다. 보상은 과거 효과를 완전히 없애는 rollback과 같지 않다. | - -이 대안들은 모두 상호 배타적이지 않다. Outbox로 Saga의 명령·이벤트를 전달할 수도 있다. 패턴 하나가 다른 모든 책임을 대신한다고 비교하지 않는다. - -**조건을 붙인 답변 예시** - -> 이 흐름에서는 주문을 결제 대기 상태로 접수할 수 있고, 접수한 주문의 결제 작업 의도가 프로세스 중단 때문에 사라지지 않아야 한다고 가정했습니다. commit 후 즉시 호출만 하는 방식에는 그 사이의 중단 구간이 남습니다. 따라서 주문과 작업 의도를 같은 DB 트랜잭션에 기록하는 Outbox를 선택할 수 있습니다. 다만 외부 결제까지 원자적으로 완료되거나 정확히 한 번만 실행된다는 보장은 아닙니다. 중복 실행 방지, 결과 조회·대사, 전달 지연과 적체 처리 책임이 함께 필요합니다. [S22][S10] - -위 설명을 실제 프로젝트에 적용하려면 같은 트랜잭션·DB에 기록되는지와 relay의 읽기·전송·완료 처리 경계를 확인한다. 전송 성공 뒤 완료 표시 전에 중단되는 경우도 살핀다. `outbox.append()` 호출 하나가 있다는 사실로 전체 계약을 충족했다고 판단하지 않는다. - -요청 응답 전에 결제 확정이 반드시 필요해지면 비동기 접수만으로는 요구가 충족되지 않는다. 그렇다고 외부 호출을 DB 트랜잭션 안으로 옮기면 해결된다고 결론내리지 않는다. 동기 응답 계약과 외부 작업 식별·복구 프로토콜을 함께 다시 설계한다. - -업무 상태만으로 누락된 후속 작업을 확실히 재구성할 수 있고 그 지연·중복·비용이 허용된다면, 별도 Outbox 대신 그 상태를 이용하는 지속 가능한 작업 방식도 비교할 수 있다. 핵심은 패턴 이름보다 **중단 뒤 어떤 근거로 무엇을 복구하는가**다. - -### 41.7 성능·운영 예시 — 왜 캐시인가 - -캐시는 측정된 문제와 허용할 데이터 계약을 먼저 설명해야 한다. - -| 후보 | 비교할 조건 | -| --- | --- | -| 캐시 없이 유지 | 현재 목표를 충족하는지, 추가 상태·장애 지점을 만들 이익이 있는지 | -| 쿼리·인덱스·조회량 개선 | 중복 요청·N+1·불필요한 데이터 읽기가 비용의 원인인지 | -| 프로세스 내부 캐시 | 인스턴스별 데이터 차이·메모리 사용·재시작을 허용하는지 | -| 공유 캐시 | 여러 인스턴스의 재사용 이익이 네트워크 지연·의존 장애·운영 비용보다 큰지 | -| CDN 등 전달 경로의 캐시 | 응답의 공개 범위·개인화·캐시 키·무효화 계약이 맞는지 | -| 사전 계산·별도 조회 모델 | 읽기 비용을 줄이는 대신 갱신 지연·재구축·저장 비용을 감당할 수 있는지 | - -단일 조회가 1ms라는 사실만으로 캐시가 불필요하다고 결론내리지 않는다. 요청 빈도·전체 DB 비용·혼잡 시 지연·목표를 함께 본다. 반대로 인스턴스가 다섯 개라는 이유만으로 Redis가 필요한 것도 아니다. - -공유 캐시도 원본 DB와의 강한 정합성을 자동으로 제공하지 않는다. cache-aside에서는 갱신·무효화·재적재 사이의 경쟁과 오래된 값의 노출을 설계해야 한다. 허용할 오래된 값의 범위, 캐시 키의 사용자·테넌트 구분, 캐시 장애 때 원본이 감당할 부하를 확인한다. [S24] - -**조건을 붙인 답변 예시** - -> 같은 조회의 반복 비용이 목표를 넘고, 이 데이터에는 합의된 범위의 오래된 값을 허용한다고 가정했습니다. 여러 인스턴스가 같은 결과를 반복 계산하므로 공유 캐시를 비교할 이유가 있습니다. 다만 적중률과 전체 지연의 개선을 확인하고, 무효화 경쟁·장애 시 원본 부하·운영 비용을 포함해 선택해야 합니다. 강한 정합성이 필수로 바뀌거나 실제 재사용 이익이 작다면 캐시 제거 또는 다른 조회 방식도 다시 비교하겠습니다. - -“트래픽이 늘면 재검토”보다 “목표 지연을 넘는 원인이 반복 조회인지, 캐시 적중 이익이 비용을 상쇄하는지 확인되면 재검토”가 더 유효한 조건이다. 합의하지 않은 숫자를 일반적인 합격선으로 만들지 않는다. - -### 41.8 경계·추상화 예시 — 구현체가 하나인데 왜 Interface인가 - -`UserRepository`가 하나의 JPA 구현만 가져도 애플리케이션이 의존할 계약과 영속 구현을 분리할 이유는 있을 수 있다. 구현체 수보다 **실제로 무엇을 격리하는지** 확인한다. - -- 애플리케이션에 필요한 업무 계약을 정의하는가? -- 반환 타입·예외·지연 로딩·트랜잭션 전제가 구현 기술을 그대로 노출하는가? -- 실제 변경을 격리하거나 필요한 테스트 대역을 제공하는가? -- 중복 선언·매핑·탐색 비용에 비해 이득이 있는가? - -**조건을 붙인 답변 예시** - -> 이 인터페이스는 구현체 교체 가능성을 막연히 대비하기보다, 애플리케이션이 사용할 저장 계약을 영속 기술과 분리하기 위한 경계로 해석할 수 있습니다. 그 해석이 맞으려면 호출부가 JPA의 타입·예외·세션 수명에 계속 의존하는지도 확인해야 합니다. 실제 격리 가치가 없고 같은 호출을 전달하는 선언만 늘어난다면 경계를 좁히거나 제거하는 대안이 있습니다. - -순수한 `NameFormatter`라도 구현 교체·정책 주입 계약이 실제로 필요하면 인터페이스가 의미 있을 수 있다. 반대로 그런 경계가 없으면 함수나 구체 클래스만으로 충분할 수 있다. “외부 I/O가 없으니 무조건 삭제”와 “아키텍처 패턴이니 무조건 유지” 모두 근거가 부족하다. - -### 41.9 실패·운영 예시 — 왜 이 재시도 정책인가 - -`retry(3)`에서는 먼저 최초 시도를 포함한 총 세 번인지, 최초 이후 재시도 세 번인지 확인한다. 횟수 외에도 다시 수행해도 되는 작업인지, 실패 원인이 회복 가능한지, 응답을 기다릴 시간이 남았는지가 중요하다. - -| 확인할 조건 | 판단에 미치는 영향 | -| --- | --- | -| 실제 작업 의미 | GET·POST라는 이름만으로 사용자 정의 API의 모든 부작용을 추정하지 않는다. HTTP의 표준 의미와 실제 서버 계약을 함께 확인한다. [S23] | -| 실패·결과 불명 | 응답을 못 받았다는 사실과 서버에서 적용하지 않았다는 사실을 구분한다. | -| 멱등 처리 계약 | 헤더 존재뿐 아니라 서버의 키 범위·유효 기간·입력 일치·동시 요청 처리·결과 재현을 확인한다. [S10] | -| 실패 원인 | 일시 장애와 잘못된 입력·권한·영구 실패를 구분한다. 다시 호출해도 나아지지 않는 실패는 반복하지 않는다. | -| 시간·횟수·부하 | 전체 deadline, 요청별 timeout, 상한, 간격, jitter, 여러 계층의 중복 재시도를 함께 본다. [S3] | -| 서버의 대기 안내 | 적용되는 Retry-After와 남은 시간 예산을 함께 판단한다. 기다릴 여유가 없으면 현재 요청 안의 재시도를 종료한다. [S23] | -| 취소·요청 재생 | 취소 이후 예약이 남는지, body 등을 같은 의미로 다시 보낼 수 있는지 확인한다. | - -**조건을 붙인 답변 예시** - -> 이 작업은 서버가 동일 업무 키에 대해 중복 효과를 억제하고, 같은 입력의 결과를 다시 확인할 수 있다는 전제에서만 재시도합니다. 일시 실패에는 정한 시간·횟수 예산 안에서 간격을 두되, 결제 응답이 유실된 경우를 곧바로 결제 실패로 바꾸지는 않습니다. 키가 만료됐거나 중복 방지 계약을 확인할 수 없으면 새 키로 다시 결제하는 대신 상태 조회·대사 경로를 검토합니다. - -멱등키를 붙이는 것과 안전한 재시도가 같은 말은 아니다. key와 업무 효과를 따로 저장해 중간에 중단될 수 있다면 보호가 깨질 수 있다. 외부 제공자의 멱등 계약과 로컬 처리의 보장 범위를 연결해서 확인한다. [S10] - -전송 재시도와 업무 재시작도 구분한다. 일정 시간 뒤 업무를 다시 시도해야 한다면 호출 스택 안의 재시도 횟수를 늘리는 대신, 지속 가능한 작업 상태와 재개 정책이 필요한지 검토한다. 이것도 현재 요구가 있을 때의 대안이다. - -### 41.10 설명의 깊이와 후속 답변 양식 - -| 선택의 영향 | 보통 충분한 표현 위치 | 설명할 핵심 | -| --- | --- | --- | -| 지역적이고 명백한 계산 | 이름·표현식·작은 함수 | 입력과 결과 | -| 객체의 상태·소유권 | 타입·생성자·변경/반환 API, 필요한 짧은 주석 | 변경 권한, 공유 참조, 보호할 규칙 | -| 공개 API·모듈 계약 | 계약 문서와 필요한 경계 검증 | 허용 입력·결과·오류·호환성 | -| 트랜잭션·재시도·인가 | 실행 경계, 중요한 실패 검증, 짧은 근거 | 부분 실패·우회·동시성·남는 책임 | -| 여러 팀·프로젝트에 영향을 주는 구조 | 기존 설계 기록 또는 ADR와 코드 연결 | 후보 비교, 비용, 이행·철회·재검토 조건 | - -표는 새로운 문서의 필수 목록이 아니다. 기존 자료로 충분하면 연결해서 사용한다. 모든 메서드에 annotation이나 결정 ID를 붙이지 않고, 같은 설명을 코드·문서·표에 반복해 수동으로 맞추게 만들지 않는다. - -후속 질문에는 먼저 결론을 짧게 답한 뒤 필요한 근거를 펼친다. 다음 양식은 긴 설명이 필요한 경우에 쓰며 항목 수를 채우기 위해 내용을 늘리지 않는다. - -> **판단:** 현재의 [확인된 조건]에서는 [선택 유지/변경/조건부 판단]가 타당합니다. -> **보호할 성질:** [누가 어떤 상황에서도 무엇을 지켜야 하는가]. -> **현재 근거:** [코드·계약·기록·검증]에서 [보장]을 확인했습니다. [남은 범위]는 확인하지 못했습니다. -> **대안과 차이:** [단순한 대안]은 [장점]이 있지만 [필수 요구 미충족 또는 추가 비용]이 있습니다. -> **감수한 비용과 한계:** 현재 선택에는 [비용]이 남으며 [보장하지 않는 것]은 별도 책임입니다. -> **재검토 조건:** [구체적인 요구·측정·계약 변화]가 생기면 [대안]을 다시 비교합니다. - -작성 이력 없이 선택 이유를 설명할 때는 “작성자가 이렇게 생각했다” 대신 **“현재 조건에서 이 선택을 유지할 근거는 다음과 같다”**고 말한다. 리뷰 과정에서 새로 정한 결정이라면 새 결정이라는 사실을 남긴다. - -대안의 장점도 공정하게 설명한다. `unmodifiableList`는 스냅샷에는 부족하지만 live view가 필요한 계약에는 적합하다. 어떤 대안도 통과할 수 없도록 현재 구현에 유리한 요구를 뒤늦게 만드는 설명은 검증으로 인정하지 않는다. - -### 41.11 통과 여부와 리뷰를 끝내는 기준 - -중요한 선택 하나를 놓고 다음 후속 질문을 해본다. - -1. 가장 단순한 대안으로 바꾸면 구체적으로 무엇이 달라지는가? -2. 그 문제가 발생하는 입력·순서·실패 조건 또는 변경 과제는 무엇인가? -3. 지금 구현에서 그 문제를 막는 경계는 어디인가? -4. 무엇은 여전히 보장하지 못하며, 누가 그 책임을 갖는가? -5. 어떤 조건이나 증거가 나오면 지금 결론을 바꾸겠는가? - -| 검토 결과 | 처리 | -| --- | --- | -| 요구·현재 구현·대안 비교가 맞고 제한이 허용된다. | 선택을 유지할 수 있다. 수정하지 않는 것도 유효한 결과다. | -| 선택은 타당하지만 중요한 이유가 작성자의 설명에만 있다. | 이름·계약·가까운 주석·기존 기록 연결 중 가장 작은 보강을 한다. | -| 이유는 타당하지만 현재 구현이 그 보장을 하지 못한다. | 설명 개선으로 닫지 않고 구현·검증의 문제로 기록한다. | -| 현재 코드가 맞을 수 있지만 핵심 요구나 계약을 모른다. | 미확인 전제와 필요한 확인을 남긴다. 결함이나 합격으로 단정하지 않는다. | -| 같은 요구를 더 적은 비용으로 충족하는 대안의 근거가 있다. | 이행 비용과 보호할 계약을 포함해 변경을 제안한다. | - -리뷰어에게 필요한 것은 모든 기술의 대안을 즉시 암기해 말하는 능력이 아니다. 모르는 계약을 식별하고, 해당 버전의 1차 자료와 실제 코드·실험으로 확인한 뒤 판단을 갱신하는 능력이다. - -대표 선택의 판단에 충분한 근거가 모였으면 검토를 마친다. 선택 이유를 설명하기 위해 새 프레임워크·대규모 문서 체계·관성적인 테스트를 추가하지 않는다. **다음 수정자가 같은 근거로 선택을 유지하거나 바꿀 수 있으면 이 검토의 목적을 달성한 것이다.** +리뷰 기준을 고칠 일이 생기면 design-docs의 정본을 고친다. 이 파일에 본문을 다시 넣지 않는다. 두 곳에 본문이 있으면 서로 갈라진다. -- 2.54.0