6.2 KiB
6.2 KiB
Template 프로젝트 성숙도 리뷰 — 실행 체크리스트
이 문서는 TEMPLATE-MATURITY-REVIEW-GUIDE.md의 실행용 요약본이다. 상세 판정 근거와 예외는 정본 가이드를 따른다. 체크리스트 자체를 별도 점수 체계로 사용하지 않는다.
1. 리뷰 시작 전에 고정
- 대상 저장소, 브랜치·커밋, 작업 트리 상태, 확인 시점
- 템플릿/프로젝트의 사용 목적과 지원 실행 형태
- 필수 요구, 데이터·권한 범위, 의존 시스템
- 규모 목표와 운영 목표가 있는지 여부
- 지원 기능·선택 기능·의도적 비지원 범위
- 템플릿 책임과 사용 프로젝트 책임
- 이번에 읽을 코드·설정·테스트 범위와 확인하지 못할 범위
목표가 없는 항목은 임의로 만들지 않는다. 목표가 없어서 판단할 수 없으면 미검증 또는 판단 보류로 남긴다.
2. 대표 경로를 먼저 따라간다
전체 파일을 균등하게 훑기 전에 실제 사용 흐름과 고위험 흐름을 선택한다.
- 정상 사용자 흐름 1개 이상
- 실패 시 피해가 큰 흐름 1개 이상
- 기능 추가·변경·삭제 흐름 1개 이상
- 필요하면 배포·복구·동시성·인증 경계 흐름
각 흐름에서 입력 → 정책 → 상태 변화 → 외부 I/O → 실패 → 사용자/운영 결과를 연결한다.
3. 28개 관점은 적용되는 것만 판정
- 적용 여부와 이유를 먼저 적는다.
- 목표 통제와 현재 통제를 분리한다.
- 근거 수준(E0
E4)과 통제 수준(M0M4)을 혼동하지 않는다. - 하나의 결함이 여러 관점에 걸리면 Finding은 하나로 두고 관련 관점만 연결한다.
미검증을 완료율에서 빼지 않는다.
4. 먼저 찾을 고위험 문제
- 데이터 손상·권한 우회·민감정보 노출
- 결과 불명 쓰기와 잘못된 재시도·멱등성
- 동시성 경쟁·중복 처리·오래된 작업자의 쓰기
- 무제한 큐·병렬성·응답·메모리·재시도
- 배포·마이그레이션·복구 중 중간 상태
- CI/Guardrail이 있다고 문서에는 적혀 있지만 실제로 실행되지 않는 경우
5. 코드 품질은 “줄 수”보다 이해 부담과 보호 장치로 본다
대표 과제를 수행하면서 기록한다.
- 어디서 시작했는가?
- 반드시 알아야 하는 개념은 무엇인가?
- 이름과 실제 책임이 달라 다시 탐색한 곳은 어디인가?
- 숨은 등록 순서·전역 상태·문자열 키·설정 규약이 있는가?
- 중요한 위험과 실패 의미를 가까운 코드·타입·계약에서 찾을 수 있는가?
- 같은 사실을 annotation·descriptor·config·실행 코드에 반복한다면 각각 독립적인 역할과 불일치 검출이 있는가?
6. 추상화는 유지·내부화·통합·분리·제거 중에서 판단
각 추상화에 묻는다.
- 없으면 어떤 중복 지식·외부 결합·테스트 어려움이 생기는가?
- 호출자는 성공·실패·비용·수명주기를 추상화만 보고 이해할 수 있는가?
- 일반 사용자가 플랫폼 내부 개념까지 알아야 하는가?
- 더 작은 구조로 바꿨을 때 보호하던 계약을 그대로 유지할 수 있는가?
- 복잡하지만 현재 요구와 위험에 비해 정당하다면 현 상태 유지도 유효한 결론이다.
7. 중요한 설계 선택에는 Decision Explanation Test 적용
모든 한 줄에 적용하지 않는다. 객체 ownership, 공개 계약, 트랜잭션, 인가, retry/idempotency, cache, concurrency, module composition, template architecture처럼 계약·실패·유지비에 영향을 주는 선택에 적용한다.
- 무엇이 필요한가?
- 반드시 지킬 성질은 무엇인가?
- 현재 코드는 어떻게 보장하는가? 무엇은 보장하지 않는가?
- 현실적인 대안은 무엇인가?
- 각 대안의 정확성·복잡성·성능·실패 특성·변경/운영 비용은?
- 확인한 현재 조건에서는 왜 이 선택인가?
- 어떤 요구·측정·규모·의존 계약이 바뀌면 선택도 달라지는가?
작성 당시 의도가 기록에 없으면 만들어내지 않는다. 작성자가 이렇게 생각했다가 아니라 현재 조건에서 이 선택을 유지할 근거는 ...이라고 구분한다.
8. Finding 작성
필수:
- ID·제목
- 성격: 확인된 결함 / 구조적 위험 / 미검증 / 개선 제안
- 관련 관점
- 현재 근거와 발생 조건
- 영향
- 심각도와 우선순위
- 확실한 사실과 남은 가정
- 최소 개선 방향
- 비용·부작용
- 완료 기준
- 검증 방법
설계 선택·구조 변경이면 추가:
- 현재 제약과 보호할 규칙
- 이해 비용
- 현실적인 대안과 차이
- 단순화 후 보존해야 할 계약
- 재검토 조건
단순 구현 결함이면 위 설계 선택 필드는 적용 제외 가능하다. 빈칸 대신 적용 제외 이유를 한 문장으로 남긴다.
9. 제안보다 검증을 우선
- 구조적 위험은 가능한 경우 작은 변경·변이 실험으로 실제 검출 여부를 확인한다.
- 실제 DB·브라우저·CI·외부 의존성 동작이 필요한 주장은 가능한 환경에서 해당 수준까지 검증한다.
- 실행하지 못한 브라우저·CI·부하·복구 조건은 정적 근거만으로 검증 완료라고 쓰지 않는다.
- 문서의 “구현 완료” 표시는 증거가 아니라 주장으로 취급한다.
10. 리뷰 종료 전 확인
- 현재 사용 가능한 범위와 보류 범위를 구분했는가?
- 차단 항목과 미검증 목록이 따로 있는가?
- 가장 중요한 Finding의 재현·검출 근거가 있는가?
- 단순화 제안이 기존 안전장치를 잃지 않는가?
- 중요한 기술 선택에 대해
요구 → invariant → 현재 구현 → 대안 → trade-off → 선택 이유 → 재검토 조건을 설명할 수 있는가? - 수정하지 않는 것이 최선인 구조도 그렇게 기록했는가?
- 구현자가 “무엇을 바꾸면 끝나는지”와 “어떻게 다시 검증하는지”를 알 수 있는가?
충분한 근거가 모이면 리뷰를 끝낸다. 기준을 채우기 위해 새 프레임워크·불필요한 문서·장식성 메타데이터·중복 테스트를 추가하지 않는다.