Files
clean-architecture-frontend…/docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md
T

6.2 KiB

Template 프로젝트 성숙도 리뷰 — 실행 체크리스트

이 문서는 TEMPLATE-MATURITY-REVIEW-GUIDE.md의 실행용 요약본이다. 상세 판정 근거와 예외는 정본 가이드를 따른다. 체크리스트 자체를 별도 점수 체계로 사용하지 않는다.

1. 리뷰 시작 전에 고정

  • 대상 저장소, 브랜치·커밋, 작업 트리 상태, 확인 시점
  • 템플릿/프로젝트의 사용 목적과 지원 실행 형태
  • 필수 요구, 데이터·권한 범위, 의존 시스템
  • 규모 목표와 운영 목표가 있는지 여부
  • 지원 기능·선택 기능·의도적 비지원 범위
  • 템플릿 책임과 사용 프로젝트 책임
  • 이번에 읽을 코드·설정·테스트 범위와 확인하지 못할 범위

목표가 없는 항목은 임의로 만들지 않는다. 목표가 없어서 판단할 수 없으면 미검증 또는 판단 보류로 남긴다.

2. 대표 경로를 먼저 따라간다

전체 파일을 균등하게 훑기 전에 실제 사용 흐름과 고위험 흐름을 선택한다.

  • 정상 사용자 흐름 1개 이상
  • 실패 시 피해가 큰 흐름 1개 이상
  • 기능 추가·변경·삭제 흐름 1개 이상
  • 필요하면 배포·복구·동시성·인증 경계 흐름

각 흐름에서 입력 → 정책 → 상태 변화 → 외부 I/O → 실패 → 사용자/운영 결과를 연결한다.

3. 28개 관점은 적용되는 것만 판정

  • 적용 여부와 이유를 먼저 적는다.
  • 목표 통제와 현재 통제를 분리한다.
  • 근거 수준(E0E4)과 통제 수준(M0M4)을 혼동하지 않는다.
  • 하나의 결함이 여러 관점에 걸리면 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 → 선택 이유 → 재검토 조건을 설명할 수 있는가?
  • 수정하지 않는 것이 최선인 구조도 그렇게 기록했는가?
  • 구현자가 “무엇을 바꾸면 끝나는지”와 “어떻게 다시 검증하는지”를 알 수 있는가?

충분한 근거가 모이면 리뷰를 끝낸다. 기준을 채우기 위해 새 프레임워크·불필요한 문서·장식성 메타데이터·중복 테스트를 추가하지 않는다.