124 lines
6.2 KiB
Markdown
124 lines
6.2 KiB
Markdown
# Template 프로젝트 성숙도 리뷰 — 실행 체크리스트
|
|
|
|
이 문서는 `TEMPLATE-MATURITY-REVIEW-GUIDE.md`의 **실행용 요약본**이다. 상세 판정 근거와 예외는 정본 가이드를 따른다. 체크리스트 자체를 별도 점수 체계로 사용하지 않는다.
|
|
|
|
## 1. 리뷰 시작 전에 고정
|
|
|
|
- 대상 저장소, 브랜치·커밋, 작업 트리 상태, 확인 시점
|
|
- 템플릿/프로젝트의 사용 목적과 지원 실행 형태
|
|
- 필수 요구, 데이터·권한 범위, 의존 시스템
|
|
- 규모 목표와 운영 목표가 있는지 여부
|
|
- 지원 기능·선택 기능·의도적 비지원 범위
|
|
- 템플릿 책임과 사용 프로젝트 책임
|
|
- 이번에 읽을 코드·설정·테스트 범위와 확인하지 못할 범위
|
|
|
|
목표가 없는 항목은 임의로 만들지 않는다. 목표가 없어서 판단할 수 없으면 `미검증` 또는 `판단 보류`로 남긴다.
|
|
|
|
## 2. 대표 경로를 먼저 따라간다
|
|
|
|
전체 파일을 균등하게 훑기 전에 실제 사용 흐름과 고위험 흐름을 선택한다.
|
|
|
|
- 정상 사용자 흐름 1개 이상
|
|
- 실패 시 피해가 큰 흐름 1개 이상
|
|
- 기능 추가·변경·삭제 흐름 1개 이상
|
|
- 필요하면 배포·복구·동시성·인증 경계 흐름
|
|
|
|
각 흐름에서 입력 → 정책 → 상태 변화 → 외부 I/O → 실패 → 사용자/운영 결과를 연결한다.
|
|
|
|
## 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 → 선택 이유 → 재검토 조건`을 설명할 수 있는가?
|
|
- 수정하지 않는 것이 최선인 구조도 그렇게 기록했는가?
|
|
- 구현자가 “무엇을 바꾸면 끝나는지”와 “어떻게 다시 검증하는지”를 알 수 있는가?
|
|
|
|
충분한 근거가 모이면 리뷰를 끝낸다. 기준을 채우기 위해 새 프레임워크·불필요한 문서·장식성 메타데이터·중복 테스트를 추가하지 않는다.
|