docs(reviews): 공용 리뷰 가이드 두 파일을 design-docs 정본 포인터로 바꾼다 #10

Closed
donghyeon.kang wants to merge 1 commits from docs/review-guide-pointer into fix/maturity-review-2026-11-06
3 changed files with 32 additions and 2048 deletions
+1 -1
View File
@@ -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` 등)로 가리키므로 옮기지 않는다 |
@@ -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의 정본을 고친다. 이 파일에 본문을 다시 넣지 않는다. 두 곳에 본문이 있으면 서로 갈라진다.
File diff suppressed because it is too large Load Diff