docs(reviews): 공용 리뷰 가이드 두 파일을 design-docs 정본 포인터로 바꾼다
문제 리뷰 가이드와 실행 체크리스트는 백엔드·프론트 두 템플릿이 함께 쓰는 리뷰 기준인데 프론트 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).
This commit is contained in:
+1
-1
@@ -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
Reference in New Issue
Block a user