CLAUDE.md makes the guide the standing review standard for this repo. The review folder holds 14 area reports and the summary with the 28-perspective table and the finding index. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
103 KiB
Template 프로젝트 성숙도 리뷰 가이드
작성일: 2026-09-25
대상: Backend Template, Frontend Template, Platform Template 및 이를 사용하는 프로젝트
기반 문서: 첨부된 TEMPLATE-MATURITY-REVIEW-GUIDE(1).md
목적: 코드의 정확성, 변경 비용, 위험의 가시성, 운영·복구 능력을 근거로 판단하는 리뷰 기준서
이 문서는 원문의 28개 관점과 번호를 유지하면서 각 관점을 실제로 검토하고 판정하는 방법을 보강한 통합본이다. 원문 뒤에 체크리스트만 덧붙이지 않고, 과도하게 단정한 기준은 본문에서 바로잡았다.
실제 프로젝트의 코드는 이번 작업에서 검사하지 않았다. 아래 코드·시나리오·수치는 설명용이며, 사용 중인 템플릿에서 발견된 결함이나 측정 결과를 뜻하지 않는다. 참고한 공식 자료는 문서 끝에 정리했다. 평가 방식과 완료 기준은 이 가이드의 제안이며 공인 인증 체계가 아니다.
먼저 읽을 부분
- 전체 관점과 적용 범위: 0절
- 원문과 같은 번호로 정리한 상세 기준: 1~28절
- 코드에서 위험을 드러내는 구체적인 방법: 29절
- 템플릿의 기본값·선택 기능·업데이트 전파: 30절
- Backend / Frontend / Platform별 검증 시나리오: 31~33절
- 실제 리뷰 순서와 측정 방법: 34절
- 심각도·성숙도·증거 수준·완료 판정: 35절
- 그대로 사용할 수 있는 리뷰 결과 양식: 36절
- 원문에서 교정한 내용과 근거 자료: 37~38절
0. 숙련된 리뷰어가 가장 먼저 확인하는 것
숙련된 리뷰어는 “이 패턴이 유행하는가”보다 이 구조가 어떤 실수를 막고, 어떤 비용을 남기는가를 묻는다. 메서드가 짧아도 중요한 부작용을 숨기면 읽기 어려운 코드다. 모듈이 많아도 한 기능을 바꿀 때 전부 알아야 한다면 변경 경계가 약하다.
템플릿은 이 질문이 더 중요하다. 사용자는 샘플 코드와 기본값을 권장 방식으로 받아들이기 쉽다. 잘못된 재시도 정책이나 권한 처리 예제가 여러 프로젝트로 복제되면, 원본을 고친 뒤에도 사용 프로젝트에는 결함이 남을 수 있다.
리뷰를 시작할 때 다음 다섯 질문에 답한다.
- 정확성: 동시에 실행되거나 일부만 실패해도 지켜야 할 규칙은 무엇인가?
- 이해 가능성: 기능을 바꾸는 사람이 반드시 알아야 할 계약을 가까운 곳에서 찾을 수 있는가?
- 변경·장애 범위: 한 번의 실수로 어떤 데이터·사용자·프로젝트까지 영향을 받는가?
- 운영·복구: 문제가 생겼다는 사실을 발견하고, 원인을 좁히고, 정상 상태로 복구할 수 있는가?
- 지속 비용: 다음 기능 추가, 라이브러리 업그레이드, 담당자 교체 때도 이 구조의 비용을 감당할 수 있는가?
0.1 평가 전에 고정할 전제
기준만 정하고 전제를 비워 두면 리뷰가 취향 경쟁으로 바뀐다. 다음 표부터 채운다.
| 전제 | 기록할 내용 | 판정에 미치는 영향 |
|---|---|---|
| 사용 목적 | 학습용, 사내 서비스 시작점, 외부 배포용 템플릿 등 | 요구할 운영 증거와 지원 범위가 달라진다. |
| 사용자와 팀 | 사용 프로젝트 수, 작성자 외 사용자, 예상 담당자 | 복제 범위와 인수인계 비용을 판단한다. |
| 지원 실행 형태 | 단일 프로세스, 다중 인스턴스, 브라우저, SSR 등 | 메모리 상태·락·세션의 안전 범위가 달라진다. |
| 데이터와 권한 | 공개·개인·민감 데이터, 관리자 기능, 테넌트 여부 | 정보 유출·오작동의 피해를 판단한다. |
| 규모 목표 | 요청량, 데이터량, 기능 수, 동시 개발자, 배포 빈도 | 부하와 구조 확장성을 따로 검증한다. |
| 의존 시스템 | DB, 캐시, 인증 서버, 외부 API, 메시지 시스템 | 실패·복구 시나리오를 선정한다. |
| 운영 목표 | 허용 실패율·지연, 허용 데이터 손실, 복구 시간 | 성능·가용성·복구의 합격 기준을 정한다. |
| 지원·비지원 | 필수 기능, 선택 기능, 의도적으로 제공하지 않는 기능 | 없는 기능을 모두 결함으로 평가하지 않게 한다. |
합의된 목표가 없으면 “대규모 운영 준비 완료” 같은 판정은 보류한다. 그 대신 무엇까지 확인했고 어떤 전제가 비어 있는지 적는다.
0.2 템플릿 자체와 사용 프로젝트의 책임
| 항목 | 템플릿이 제공할 책임 | 사용 프로젝트가 결정·검증할 책임 |
|---|---|---|
| 오류 처리 | 오류 분류·전달 방식과 안전한 기본 처리 | 도메인별 사용자 행동과 업무 보상 |
| 외부 호출 | 시간 제한·재시도 정책을 지정할 수 있는 계약 | 상대 API의 멱등성, 실제 지연에 맞춘 값 |
| 인증·인가 | 신뢰 경계, 확장 위치, 허용·거부 예제 | 역할·리소스 소유권·테넌트 정책 |
| DB 변경 | 마이그레이션 실행 방식과 호환성 지침 | 실제 데이터 규모에서의 락·백필 영향 |
| 관측 | 버전·요청 연결, 민감정보 보호, 수집 연결점 | 업무별 지표·알림 기준·대응 담당자 |
| 복구 | 선택한 구성의 복구 절차와 검증 예제 | 실제 인프라·데이터로 복구 시간·손실 검증 |
| 프론트 상태 | 요청 상태·캐시·세션 경계의 기본 계약 | 화면별 UX와 데이터 유효성 규칙 |
책임을 나눈다고 템플릿의 위험한 기본값을 정당화할 수는 없다. 반대로 템플릿에 모든 서비스의 SLO나 복구 시간을 하드코딩할 필요도 없다.
0.3 28개 관점의 관계
| 묶음 | 해당 관점 | 함께 답해야 할 질문 |
|---|---|---|
| 정확성과 계약 | 1, 11, 12, 15, 17 | 무엇을 언제 누가 바꿀 수 있고, 실패 후 무엇이 남는가? |
| 구조와 이해 | 2, 3, 4, 5, 9, 22, 23, 24 | 읽는 사람이 변경 위치와 위험을 예측할 수 있는가? |
| 실패와 운영 | 6, 7, 8, 18, 19, 28 | 실패를 제한하고 발견·진단·복구할 수 있는가? |
| 성장과 비용 | 13, 14, 16, 25, 26, 27 | 규모와 시간이 늘 때 무엇이 병목이 되는가? |
| 재사용의 안전장치 | 10, 20, 21 | 다른 사람이 사용해도 실수를 빨리 발견하는가? |
하나의 결함이 여러 관점에 걸칠 수 있다. 예를 들어 무제한 재시도는 실패 처리·성능·운영 문제를 함께 만든다. 발견 사항은 하나로 기록하고 관련 관점을 연결한다. 같은 결함을 세 번 세어 심각성을 부풀리지 않는다.
1. 코드 성숙도 — Code Maturity
판단할 것
도메인의 중요한 규칙이 생성·변경 경로에서 실제로 지켜지는지 본다. 메서드 길이, record 사용 여부, setter 개수만으로 판정하지 않는다. 어떤 상태를 허용하며, 잘못된 상태가 저장되기 전에 어디서 차단되는지가 중심이다.
예를 들어 주문의 status를 열거형으로 바꿔도 취소된 주문을 결제 완료로 바꿀 수 있다면 상태 전이 문제는 남아 있다. markPaid()라는 이름도 결제 확인·중복 처리·동시 변경을 저절로 보장하지 않는다.
확인 질문과 증거
- 지켜야 할 규칙을 먼저 문장으로 적을 수 있는가? 객체 생성자, 팩터리, 상태 변경 메서드와 대조한다.
- HTTP 입력 외에 배치·메시지·테스트·관리자 도구에서도 같은 규칙이 유지되는가? 진입 경로를 따라간다.
- 외부가 수정 가능한 컬렉션이나 공개 필드로 검증을 우회할 수 있는가?
null, 빈 값, 누락, 아직 계산되지 않은 값이 서로 다른 의미라면 구분되어 있는가?- 타입 단언·역직렬화·ORM 복원처럼 생성 규칙을 우회할 수 있는 경로가 있는가?
위험 신호: UI 검증만 믿고 서버나 도메인에서 잘못된 값을 허용한다. 정상 생성 경로는 안전하지만 공개 setter로 불변식을 깨뜨릴 수 있다.
개선 완료 기준: 허용·금지 상태 전이가 설명되고, 주요 변경 경로에서 같은 규칙을 지키며, 잘못된 입력과 상태 전이를 검증하는 테스트가 있다. 여러 요청 사이의 규칙은 12절의 DB 제약·동시성 검증까지 연결한다.
과도한 적용을 피할 점: 전달용 DTO의 단순 필드를 모두 도메인 객체로 감싸거나, 의미가 없는 전용 예외를 필드마다 만들 필요는 없다. IllegalArgumentException도 내부 프로그래밍 계약 위반을 표현하는 데 적절할 수 있다.
2. 구조적 성숙도 — Architectural Maturity
판단할 것
폴더 배치와 실제 의존성·실행 경로가 일치하는지 본다. 소스 코드가 의존하는 방향과 런타임 호출 방향도 구분한다. 애플리케이션이 자신이 정의한 저장소 포트를 호출하고 외부 어댑터가 구현한다면, 런타임 호출은 바깥으로 나가도 소스 의존성을 안쪽에 둘 수 있다.
확인 질문과 증거
- 대표 기능 하나에서 UI·입력 처리, 정책, 저장·외부 호출의 책임을 구분할 수 있는가?
- 다른 기능의 내부 파일을 직접 import하는가, 명시한 공개 계약을 사용하는가?
common,shared, 전역 registry가 사실상 모든 기능의 정책을 알고 있지 않은가?- 부트스트랩에서 구현체를 조립하는가, 업무 코드가 전역 컨테이너를 뒤져 의존성을 찾는가?
- 금지 의존성을 실제로 한 번 넣으면 빌드·lint·아키텍처 검사가 실패하는가?
증거는 디렉터리 그림보다 실제 import, 패키지 공개 범위, 모듈 의존성, 조립 코드, 위반 검출 결과다.
개선 완료 기준: 지원하는 경계가 명시되어 있고, 핵심 경계를 우회하는 대표 경로를 검출한다. 기능 추가·제거 시 어디를 바꾸는지도 예측할 수 있다.
판정 주의: 프레임워크 어노테이션이 도메인 안에 있다는 사실만으로 결함을 확정하지 않는다. 프레임워크와의 분리를 목표로 선언했는지, 결합 때문에 어떤 변경·테스트 비용이 생기는지 확인한다. 작은 CRUD 템플릿에 다층 구조를 강제하는 것이 더 비쌀 수 있다.
TypeScript paths는 경로 해석을 돕는 설정이다. 그 자체를 접근 금지 규칙이나 런타임 경계로 취급하지 않는다. 경계 강제는 별도 검사·패키지 공개 범위와 실제 우회 검증으로 확인한다. [S4]
3. 변경 용이성 — Changeability
판단할 것
예상 가능한 변경을 실제로 따라가 보며, 바뀌어야 할 코드만 바뀌는지 본다. “확장 가능”이라는 선언보다 구체적인 변경 시나리오가 필요하다.
확인할 변경 시나리오
- 오류 코드 하나를 추가한다. 서버 응답, 변환 계층, 화면 문구, 관측 정보가 어디서 연결되는가?
- 필터 조건 하나를 추가한다. 타입, API, 캐시 키, URL 상태에 중복 지식이 흩어져 있는가?
- 외부 API 제공자를 바꾼다. 제공자 고유 오류·시간 제한·인증 설정이 어디까지 전파되는가?
- 선택 기능 하나를 끈다. 관련 없는 앱이 설정 부족으로 시작하지 못하는가?
파일 수뿐 아니라 수정한 정책의 수, 깨지는 계약, 함께 배포할 단위, 필요한 팀 협의를 기록한다. 파일 8개를 예측 가능하게 바꾸는 구조가 거대한 파일 1개에서 여러 정책을 함께 바꾸는 구조보다 안전할 수 있다.
위험 신호: 같은 목록·분기·스키마를 여러 곳에서 손으로 맞춰야 한다. 기능 하나를 추가할 때 관계없는 기능의 초기화·테스트가 깨진다.
개선 완료 기준: 변경 시나리오의 수정 위치와 확인할 테스트가 설명되며, 빠뜨린 계약 변경이 검출된다. 호환성을 깨는 변경에는 사용 프로젝트의 이행 방법이 있다.
과도한 적용을 피할 점: 구현체가 하나인 인터페이스도 외부 I/O, 테스트 대역, 모듈 경계를 분리한다면 가치가 있다. 반대로 언젠가 쓸 것이라는 이유만 있는 factory·provider·strategy 연쇄는 현재 변경 사례로 효용을 입증해야 한다.
4. 인지 부하 — Cognitive Load
판단할 것
작업 하나를 끝내는 동안 사람이 동시에 기억해야 하는 규칙과 예외의 수를 본다. 파일 수와 호출 깊이는 보조 지표다. 이름이 명확한 여러 파일보다 전역 상태와 숨은 규약이 얽힌 한 파일이 더 어려울 수 있다.
리뷰 방법
작성자에게 먼저 설명을 듣기 전에 대표 과제를 수행해 본다. 예를 들어 “목록 조회가 어느 API를 호출하고, 실패하면 어떤 화면을 보여 주는지 찾기”를 선택한다.
| 관찰할 것 | 기록 예시 |
|---|---|
| 시작점 발견 | 어떤 검색어로 어디서 진입했는가? |
| 필수 지식 | 라우팅·DI·캐시·정책 중 무엇을 동시에 알아야 했는가? |
| 뜻밖의 이동 | 이름과 실제 책임이 달라 다시 찾은 곳은 어디인가? |
| 숨은 전제 | 등록 순서·문자열 키·전역 설정을 기억해야 했는가? |
| 오류 설명 | 실패 원인을 발견하는 데 어떤 정보가 부족했는가? |
위험 신호: 타입을 따라가도 실제 구현체를 찾을 수 없다. 정상 흐름보다 설정 상속과 예외 규칙을 이해하는 시간이 길다. 핵심 위험은 공통 실행기 깊숙이 숨어 있다.
개선 완료 기준: 대표 과제의 진입점·실행 흐름·실패 분기를 작성자의 구두 설명 없이 찾을 수 있다. 탐색이 반복해서 막힌 지점을 이름·배치·계약·진단 메시지로 줄인다.
측정 주의: “5분 안에 못 찾으면 실패”, “파일 5개 이하면 우수” 같은 기준을 보편적으로 적용하지 않는다. 동일한 과제와 비슷한 숙련도의 사람을 기준으로 전후를 비교한다. [S1]
5. 위험 가시성 — Risk Visibility
판단할 것
호출자가 결정을 내리는 데 필요한 비용과 실패 의미가 호출부 가까이에 드러나는지 본다. 라이브러리 내부 구현을 모두 노출하는 것이 목표는 아니다.
예를 들어 repository.save()만 보고 실제 SQL·락 방식을 모두 알 필요는 없다. 다만 커밋 시점, 충돌 가능성, 외부 부작용과의 일관성에 영향을 받는 호출자는 그 계약을 찾을 수 있어야 한다.
확인할 위험
| 위험 | 코드나 계약에서 확인할 정보 |
|---|---|
| 네트워크 I/O | 외부 대상, 시간 제한, 취소·실패 의미 |
| 재시도 | 책임 계층, 대상 오류, 최대 시도·총시간, 중복 처리 조건 |
| 트랜잭션 | 시작·종료, 락 보유 구간, 외부 호출과의 관계 |
| 캐시 | 키 범위, 신선도, 무효화, 사용자·테넌트 분리 |
| 비동기 처리 | 완료 의미, 실패 전달, 순서·중복, 종료 시 처리 |
| 권한·삭제 | 검증 주체, 대상 범위, 감사, 되돌릴 수 있는지 |
| 자원 사용 | 조회·업로드·병렬 처리·큐 크기의 상한 |
확인 방법: 이름, 타입, 포트 계약, 설정 위치, 구현, 실패 테스트를 함께 본다. dangerous 같은 단어를 이름에 붙였다고 가시성이 확보된 것은 아니다.
개선 완료 기준: 중요한 호출의 시간·상태·실패 계약을 가까운 위치에서 찾을 수 있고, 구현과 테스트가 그 계약을 뒷받침한다. 29절에 Backend와 Frontend 예시를 상세히 제시한다.
6. 실패 성숙도 — Failure Maturity
판단할 것
실패를 종류별로 구분하고, 실패 후 남는 상태를 설명할 수 있는지 본다. 특히 시간 초과는 상대 작업이 수행되지 않았다는 증거가 아니다. 응답을 잃은 성공을 단순 실패로 처리하면 재시도에서 부작용이 반복될 수 있다.
확인 질문과 증거
- 연결 실패, 지연, 권한 거부, 유효성 오류, 자원 고갈, 결과 불명을 구분하는가?
- 외부 호출의 시간 제한과 상위 요청의 총시간 제한이 맞물리는가?
- SDK·어댑터·서비스·호출 클라이언트에 재시도가 중첩되는가?
- 재시도해도 되는 작업인지 판단할 근거가 있는가? 동일 작업 식별과 중복 처리 범위를 확인한다.
- 일부 단계만 성공했을 때 저장할 상태, 재처리 방법, 사람이 확인할 방법이 있는가?
- 큐·동시 실행·대기 요청이 무제한으로 쌓이지 않는가?
재시도 횟수·간격·총시간을 제한하고, 부하를 증폭시키는 중첩 재시도를 점검한다. 오류 종류를 가리지 않는 재시도는 일시적 장애와 영구적 실패를 모두 악화시킬 수 있다. [S3]
위험 신호: 실패를 빈 목록·기본값·성공 응답으로 바꿔 데이터가 없는 것처럼 보이게 한다. 쓰기 요청의 결과가 불명인데 새 식별자로 다시 실행한다.
개선 완료 기준: 선정한 실패 조건을 주입했을 때 상태·응답·자원 사용이 계약대로 유지되고, 결과 불명 상태가 조회·조정 가능하다.
과도한 적용을 피할 점: 모든 템플릿에 circuit breaker, bulkhead, DLQ, saga를 한꺼번에 넣지 않는다. 실제 실패 경로와 운영할 능력에 맞는 수단을 선택한다.
7. 운영 성숙도 — Operational Maturity
판단할 것
운영자가 사용자 영향, 영향 범위, 현재 버전, 가능한 대응을 확인할 수 있는지 본다. 관측 도구를 설치했다는 사실은 충분한 증거가 아니다.
확인 질문과 증거
- 성공률·지연·처리량·포화 상태 중 해당 서비스의 건강을 설명할 지표가 있는가?
- 알림에 영향, 확인할 화면, 대응 담당자, 첫 조치가 연결되는가?
- 배포 버전·설정 변경·기능 활성화 시점과 이상 발생을 연결할 수 있는가?
- 메트릭 라벨에 사용자 ID·요청 ID처럼 값 종류가 끝없이 늘어나는 값을 넣고 있지 않은가?
- 로그·트레이스 수집이 느리거나 실패해도 서비스가 과도하게 영향을 받지 않는가?
- readiness와 liveness가 각각 어떤 결정을 위한 신호인지 명확한가?
원문의 기준 교정: 사용자에게 문제가 생겼다는 증상 기반 알림은 정상적인 설계다. 알림마다 근본 원인을 미리 맞힐 필요는 없다. 사용자 영향과 대응 필요성을 알리고, 원인 분석에 필요한 내부 지표·로그를 연결하는지 평가한다. [S2]
개선 완료 기준: 대표 장애에서 영향 탐지부터 원인 범위 축소까지의 경로가 확인된다. 알림을 보낸 사실뿐 아니라 사람이 실행할 다음 행동이 설명된다.
적용 범위: 템플릿은 지표 연결점과 예제를 제공할 수 있지만, 실제 SLO·알림 임계값은 서비스 목표에 맞춰 결정한다. 외부 의존성 하나의 실패를 모든 인스턴스 재시작 조건으로 연결하는 설계는 장애를 키울 수 있으므로 별도로 검증한다. [S5]
8. 디버깅 가능성 — Debuggability
판단할 것
관측된 문제를 재현하거나 원인을 좁히는 데 필요한 맥락이 남는지 본다. 오류 메시지가 길거나 모든 객체를 로그로 출력한다고 디버깅이 쉬워지는 것은 아니다.
확인 질문과 증거
- 클라이언트의 문의와 서버의 처리 기록을 연결할 식별자가 있는가?
- 도메인 오류, 외부 시스템 오류, 내부 결함을 구분하면서 원래 원인을 보존하는가?
- 프론트 오류를 배포 버전·화면·사용자 행동과 연결할 수 있는가?
- 비동기 메시지·배치에는 요청이 끝난 뒤에도 원인을 잇는 작업·이벤트 식별자가 있는가?
- 사용한 설정·기능 플래그를 비밀값 없이 확인할 수 있는가?
- 시간·난수·외부 응답을 통제해 문제를 재현할 수 있는가?
위험 신호: 모든 실패를 UNKNOWN_ERROR로 바꾸고 원인을 버린다. 반대로 토큰·쿠키·폼 원문을 통째로 수집한다. 여러 계층이 같은 예외를 반복 기록해 실제 사건 수를 부풀린다.
개선 완료 기준: 대표 실패 하나에 대해 문의 식별자에서 관련 코드·버전·의존 호출·실패 분기로 이어지는 경로를 확인한다. 필요한 진단 정보와 사용자에게 보여 줄 정보를 구분한다.
판정 주의: 사용자에게 일반적인 오류 문구를 보여 주는 것은 결함이 아닐 수 있다. 내부에는 원인과 연결 정보가 남고, 사용자에게는 안전한 안내와 문의 식별자가 제공되는지 본다.
9. 유지보수 성숙도 — Maintainability
판단할 것
3절이 개별 요구사항의 변경 비용을 본다면, 여기서는 시간이 지나며 쌓이는 변경·업그레이드·인수인계 비용을 본다. 최초 작성자만 구조를 이해하는 상태는 유지보수 증거가 약하다.
확인 질문과 증거
- 자주 바뀌는 코드와 장애가 자주 생기는 코드가 겹치는가? 변경 이력·결함 이력을 함께 본다.
- 공통 모듈 변경 시 영향을 받는 소비자를 찾을 수 있는가? 공개 API와 실제 사용처를 확인한다.
- 임시 우회·deprecated 경로·기능 플래그에 제거 조건과 담당자가 있는가?
- 버전 업그레이드가 누적되어 작은 변경을 할 때도 한꺼번에 해결해야 하는가?
- 설계 문서는 현재 선택의 이유·한계·변경 조건을 설명하는가, 코드 내용을 길게 반복하는가?
- 담당자가 바뀌어도 대표 변경과 장애 대응을 수행할 수 있는가?
위험 신호: 반복해서 바뀌는 전역 파일 하나에 여러 기능이 얽힌다. 잘못된 공통화를 유지하려고 기능별 예외 인자가 계속 늘어난다. 사용하지 않는 호환 코드의 제거 책임이 없다.
개선 완료 기준: 주요 변경의 영향 소비자와 검증 범위를 찾을 수 있다. 오래된 경로를 정리할 수 있고, 다음 업그레이드 비용이 추정 가능하다.
판정 주의: 코드가 비슷하다고 공통화하면 서로 다른 정책의 변경 시점까지 묶일 수 있다. 반대로 같은 권한·정산 규칙이 복제되어 따로 바뀌는 것은 중복 지식의 위험이다. 무엇을 함께 바꿔야 하는지를 기준으로 판단한다.
10. 테스트 성숙도 — Test Maturity
판단할 것
테스트가 어떤 사고를 막고, 실패했을 때 무엇이 잘못됐는지 알려 주는지 본다. 테스트 수·커버리지·Given/When/Then 표기만으로 품질을 판정하지 않는다.
| 검증 대상 | 적합한 증거의 예 |
|---|---|
| 규칙·상태 전이 | 유효·무효 경계값과 금지 전이 테스트 |
| DB 제약·트랜잭션 | 실제 DB 동작을 사용하는 통합 테스트 |
| 외부 계약 | 직렬화·필수 필드·오류·호환성 검증 |
| 의존성 경계 | 금지 import를 실제로 검출하는 검사 |
| 핵심 사용자 흐름 | 로그인·조회·저장·실패 복귀 등의 E2E |
| 경쟁·시간 | 동시 실행, 응답 순서 역전, 만료 경계 테스트 |
| 복구 | 중단된 작업의 재개·중복 억제·정합성 검증 |
확인 질문
- 중요한 분기 하나를 잘못 바꾸면 관련 테스트가 실패하는가?
- 테스트가 실제 정책을 검증하는가, mock 호출 순서를 그대로 복사했는가?
- 테스트 간 시간·전역 상태·DB 데이터가 새어 실행 순서에 의존하는가?
- 실패 시 입력·기대 상태·실제 상태가 구분되는가?
- 재시도로 통과한 flaky test가 정상 통과로 숨겨지는가?
- 개발자가 자주 사용하는 빠른 검증과 배포 전 필요한 검증이 구분되는가?
개선 완료 기준: 주요 위험마다 그것을 검출하는 검증이 연결되고, 실패 원인이 좁혀진다. 결함을 일부러 넣어 검출력을 확인할 때는 대표적인 고위험 규칙만 선정해 비용을 제한한다.
판정 주의: 같은 기능을 단위·통합·E2E에서 다룬다고 무조건 중복은 아니다. 각 계층이 서로 다른 실패를 잡는다면 가치가 있다. 반대로 같은 구현 세부사항만 반복 검증하면 유지 비용만 늘어난다. [S1]
11. 데이터 성숙도 — Data Maturity
판단할 것
데이터가 생성·변경·조회·이관·보관·삭제되는 전 과정에서 정확성과 접근 범위가 유지되는지 본다. 코드 롤백과 데이터 복구를 같은 일로 취급하지 않는다.
확인 질문과 증거
- 중요한 유일성·참조·범위 규칙이 동시 요청에서도 유지되는가? 애플리케이션 검사와 DB 제약을 함께 본다.
- 신·구 애플리케이션이 공존할 때 스키마와 데이터 의미가 모두 호환되는가?
- 백필을 나눠 실행하고, 중단 후 재개하며, 누락·불일치를 검출할 수 있는가?
- 인덱스 생성·제약 추가·대량 수정의 락과 부하를 실제 DB 제품·버전·데이터 규모에서 확인했는가?
- 페이지네이션에 안정된 정렬과 상한이 있는가? 데이터 변경 중 중복·누락 가능성을 계약으로 설명하는가?
- 개인정보·로그·백업·파생 캐시의 보관과 삭제 범위가 연결되는가?
- 백업을 복구한 뒤 업무상 정합성까지 확인하는가?
마이그레이션에서 볼 순서
확장 가능한 스키마 준비, 호환되는 읽기·쓰기 배포, 이력 데이터 이관, 검증, 읽기 전환, 구버전 쓰기 종료 확인, 오래된 구조 제거의 순서를 검토한다. 실제 순서는 변경 유형에 따라 달라진다.
주의: dual write는 필수 단계가 아니다. 두 쓰기의 불일치, 구버전 애플리케이션의 계속된 쓰기, 백필과 실시간 갱신의 경쟁을 해결할 수 있어야 한다. 코드만 이전 버전으로 돌려도 새로 기록한 데이터가 이해되지 않을 수 있다.
개선 완료 기준: 전환 중간 상태와 중단·복구 방법이 정의되고, 실제 이관 결과를 확인할 수 있다. 오래된 열·데이터를 지울 때는 사용 중인 소비자와 복구 가능 기간을 확인한다.
12. 동시성 성숙도 — Concurrency Maturity
판단할 것
동시에 실행되는 주체와 공유 자원을 먼저 찾는다. 서버 요청뿐 아니라 배치·스케줄러·메시지 소비자·브라우저 탭·SSR 요청도 포함한다.
확인 질문과 증거
- 두 요청이 같은 데이터를 읽은 뒤 각각 수정하면 갱신이 유실되는가?
- “존재 확인 후 생성” 사이에 다른 요청이 끼어들 수 있는가?
- 여러 인스턴스가 동일 예약 작업을 실행하거나 같은 세션을 갱신할 수 있는가?
- 락 범위·트랜잭션 격리 수준·유일성 제약·버전 검사의 역할이 구분되는가?
- 락을 잃었거나 작업 소유권이 바뀐 뒤 이전 작업자가 계속 쓰면 어떻게 되는가?
- 느린 과거 검색 응답이 더 최신 응답을 덮어쓸 수 있는가?
증거: 공유 상태의 소유자, 원자적으로 처리되는 구간, 충돌 처리 계약, 동시 실행 테스트, 실제 저장소에서 확인한 최종 상태다.
위험 신호: 다중 인스턴스를 지원하면서 정합성을 프로세스 내부 락 하나에 의존한다. 분산 락을 도입했지만 임대 만료 후의 오래된 작업자 쓰기를 고려하지 않는다.
개선 완료 기준: 선정한 경쟁 조건에서 허용하는 최종 상태와 충돌 응답이 재현된다. 재시도가 필요한 경우 같은 논리적 작업인지 식별한다.
적용 범위: 단일 프로세스로 범위를 제한한 기능에서는 로컬 락이 합리적일 수 있다. 무조건 분산 락을 추가하지 말고 DB 조건부 갱신·제약·소유권 모델로 충분한지 먼저 본다. 시간·TTL을 사용하는 규칙은 경계 시각과 시계 차이의 영향도 확인한다.
13. 확장성 — Scalability
판단할 것
무엇이 늘어나는지 나눠서 본다. 요청량을 견디는 능력과 기능·개발자 수를 견디는 능력은 다른 증거가 필요하다.
| 증가하는 대상 | 살펴볼 병목 | 증거 |
|---|---|---|
| 요청·사용자 | DB·외부 API·연결·큐·CPU 포화 | 부하별 처리량·지연·실패율·자원 |
| 데이터 | 쿼리 비용·인덱스·메모리·이관 시간 | 데이터량별 실행 계획·응답·복구 시간 |
| 기능·도메인 | 전역 등록·번들·타입 검사·탐색 | 기능 수별 빌드·시작·번들·변경 범위 |
| 개발자·팀 | 공통 파일 충돌·승인·릴리스 조율 | 변경 이력·대기·공동 변경 빈도 |
| 사용 프로젝트 | 패치 전파·버전 편차·지원 비용 | 버전 현황·이행 리허설·지원 기록 |
확인 질문
기능 하나를 추가했을 때 모든 기능의 구현체를 로딩하는가? 전체 registry 순회가 요청마다 반복되는가? 한 사용자나 테넌트의 작업이 공유 자원을 독점하는가? 인스턴스를 늘려도 DB·락·중앙 조립 지점 하나가 한계를 결정하는가?
개선 완료 기준: 목표 규모와 측정 환경을 명시하고, 어느 자원이 먼저 포화되는지와 그때의 동작을 설명한다. 기능 증가 시 변경 경계·빌드·번들 비용도 함께 확인한다.
과장 방지: 이름만 다른 기능을 수천 개 생성한 실험은 구조적 증가 비용 일부를 보여 줄 뿐이다. 실제 정책 다양성·데이터·외부 의존성·사용자 흐름을 가진 수천 도메인의 운영 증거가 아니다. “1만 도메인 지원”보다 어떤 증가 축을 어떤 조건까지 확인했는지 기록한다.
14. 성능 성숙도 — Performance Maturity
판단할 것
빠르다는 주장보다 비용이 설명되고 한계가 통제되는지 본다. 한 번의 요청·화면 진입이 어떤 CPU, 메모리, DB 호출, 네트워크 호출을 발생시키는지 추적한다.
확인 질문과 증거
- 목록 한 번에 필요한 DB·외부 호출 수가 데이터 수에 비례해 늘어나는가?
- 요청 크기·결과 개수·병렬 실행·큐 대기·캐시에 상한이 있는가?
- 캐시가 차가울 때, 만료가 겹칠 때, 의존성이 느릴 때도 자원이 제한되는가?
- 프론트엔드 초기 번들·경로별 로딩·렌더링·긴 작업의 비용을 측정했는가?
- 평균 외에 지연 분포와 실패율을 함께 보는가? p95·p99를 해석할 표본과 부하 조건이 충분한가?
- 단기 부하에서는 보이지 않는 메모리 누수·큐 증가·연결 누적이 있는가?
측정 결과에 반드시 붙일 정보
하드웨어·런타임·버전·데이터량·요청 구성·동시성·캐시 상태·측정 시간·오류율을 기록한다. 부하 발생기가 목표 요청량을 실제로 전달했는지도 확인한다. 다른 조건의 평균값만 비교하지 않는다.
개선 완료 기준: 목표 부하에서 합의한 지연·실패·자원 예산을 만족하고, 초과 시 무한 대기나 자원 고갈 대신 정의한 제한 동작을 보인다.
비용 관점: 로그·트레이스 전송량, 외부 API 호출, 저장 공간, CI 실행 시간도 포함한다. 작은 지연 개선을 위해 운영비와 유지 비용이 크게 늘었다면 선택 이유가 필요하다.
15. 보안 성숙도 — Security Maturity
판단할 것
신뢰할 수 없는 입력이 들어오는 지점과 권한을 행사하는 지점을 찾는다. 인증 여부, 리소스 소유권, 테넌트, 관리자 권한을 구분한다. 내부 네트워크에 있다는 이유만으로 호출을 신뢰하지 않는다.
확인 질문과 증거
- 인증한 사용자라도 다른 사용자의 ID로 조회·수정·다운로드할 수 있는가?
- 브라우저의 버튼 숨김·라우트 가드와 서버의 인가 검증이 구분되는가?
- 세션·토큰을 누가 보관하고 갱신·폐기하는가? 로그아웃 후 캐시·진행 중 요청에 이전 정보가 남는가?
- 쿠키 기반 흐름의 CSRF와 스크립트·HTML 처리의 XSS 위험을 각각 다루는가?
- CORS를 인증·인가 대신 사용하고 있지 않은가?
- 파일 경로·업로드·외부 URL 요청·동적 HTML처럼 입력이 다른 해석기에 전달되는 지점이 있는가?
- 브라우저 번들·오류 응답·진단 로그·저장소 이력에 비밀값이 포함되는가?
- 서비스 계정·CI·배포 도구의 권한이 필요한 범위로 제한되는가?
증거: 데이터 흐름과 신뢰 경계, 인가 정책이 적용되는 코드, 금지된 접근의 거부 테스트, 비밀값 주입·교체·폐기 경로다. 객체 ID를 바꾸는 요청처럼 경계를 직접 확인하는 테스트가 필요하다. [S6]
개선 완료 기준: 대표 허용·거부 시나리오가 서버에서 강제되고, 인증 상태·사용자·테넌트 변경 시 데이터가 섞이지 않는다. 수집·보관·공유하는 민감정보의 범위도 설명된다. [S9]
과도한 일반화 방지: 인증 라이브러리를 썼다는 이유로 인가까지 검증됐다고 판단하지 않는다. 반대로 모든 템플릿에 특정 인증 서버나 비밀 관리 제품을 의무화하지 않는다.
16. 의존성 성숙도 — Dependency Maturity
판단할 것
의존성의 도입 이유, 유입 경로, 업데이트·교체 비용을 본다. 패키지 수만 세면 작지만 위험한 의존성과 크지만 잘 관리되는 의존성을 구분할 수 없다.
확인 질문과 증거
- 직접·전이 의존성과 실제 배포 산출물에 포함된 버전을 파악할 수 있는가?
- 런타임·빌드 도구·패키지 관리자 버전과 잠금 정보가 일치하는가?
- 보안 패치나 비호환 업그레이드를 소비자에게 전파할 담당자·절차가 있는가?
- 외부 패키지의 타입·오류·데이터 모델이 핵심 정책까지 퍼져 교체 비용이 커졌는가?
- 다운로드·설치·빌드 단계에서 실행되는 외부 코드와 권한을 파악하는가?
- 라이선스 사용 조건과 유지 상태를 검토하는 책임자가 있는가?
공급망 증거: 어떤 소스와 빌드 과정에서 배포물이 생성됐는지, 산출물 식별값과 출처 기록을 연결한다. SLSA의 provenance는 이처럼 산출물의 출처·생성과정을 추적하는 정보다. 출처 정보가 있다는 사실과 소프트웨어에 취약점이 없다는 주장은 별개다. [S8]
개선 완료 기준: 대표 의존성 업데이트를 실제 빌드·테스트·배포 검증까지 수행할 경로가 있다. 탐지된 취약점의 영향·대응 여부와 지원 버전을 설명할 수 있다.
판정 주의: 버전을 고정하는 것 자체는 위험 신호가 아니다. 재현 가능한 설치를 위해 필요할 수 있다. 문제는 고정 이유와 갱신 경로가 없거나, 잠금 정보가 실제 설치에서 무시되는 상태다.
17. API / Contract 성숙도 — Contract Maturity
판단할 것
HTTP API뿐 아니라 모듈 공개 타입, 이벤트, 설정, CLI, 생성 코드도 소비자가 의존하는 계약으로 본다. 문법상 호환과 의미상 호환을 구분한다.
확인 질문과 증거
- 필드 누락·
null·빈 값의 의미가 명확한가? - 새 enum 값, 기본 정렬 변경, 오류 코드 변경을 기존 소비자가 견디는가?
- 페이지네이션의 정렬·커서 유효성·결과 변동 의미가 설명되어 있는가?
- 재전송한 쓰기 요청이 같은 작업인지 판단할 계약이 있는가?
- 이벤트의 순서·중복·스키마 변경·재처리 규칙이 정해져 있는가?
- 구버전 소비자와 신버전 제공자를 동시에 검증하는가?
- 폐기 예고 뒤 실제 사용자가 사라졌는지 확인하는가?
위험 신호: 스키마에는 변화가 없지만 기본값이나 오류 의미가 바뀌어 클라이언트 동작이 달라진다. 생성된 타입만 믿고 신뢰 경계의 런타임 입력을 검증하지 않는다.
개선 완료 기준: 공개 계약 변경이 리뷰에서 식별되고, 호환성 검사와 소비자 이행 방법이 연결된다. 깨지는 변경을 허용한다면 지원 버전·전환 기간·제거 조건을 명시한다.
판정 주의: TypeScript 정적 타입이나 코드 생성은 외부 JSON의 런타임 유효성을 보장하지 않는다. 스키마 검사 역시 권한·상태 전이·업무 의미의 호환성까지 모두 증명하지는 않는다.
18. 배포 성숙도 — Deployment Maturity
판단할 것
빌드 성공 이후 실제 트래픽과 데이터가 안전하게 새 버전으로 이동하는지 본다. 배포는 코드·스키마·설정·정적 자산·캐시가 함께 바뀌는 과정이다.
확인 질문과 증거
- 검증한 산출물과 실제 배포한 산출물의 식별값이 같은가?
- 신·구 서버, 오래 열린 브라우저, CDN의 이전 자산이 공존하는 동안 계약이 유지되는가?
- 시작·준비 완료·트래픽 중단·종료의 순서가 정의되어 있는가?
- 종료 중 요청·메시지·예약 작업이 완료·재전달·중단 중 무엇으로 처리되는가?
- 마이그레이션과 애플리케이션 배포 순서가 서로의 전제를 만족하는가?
- 이전 버전으로 돌릴 수 없는 데이터 변경이 있다면 전진 수정·보상·복구 계획이 있는가?
- 배포 중단·되돌림 판단에 사용할 실제 사용자 영향 지표가 있는가?
위험 신호: 롤백 명령은 있지만 새 버전이 쓴 데이터를 이전 버전이 읽지 못한다. 프론트 배포 후 기존 탭이 참조하던 청크 파일을 즉시 삭제해 화면 이동이 실패한다.
개선 완료 기준: 지원하는 배포 방식의 중간 상태와 실패 복구를 확인한다. 코드 되돌림, 데이터 복구, 외부 부작용 조정의 차이를 운영 절차에서 구분한다.
적용 범위: 모든 시스템이 rolling deployment를 지원해야 하는 것은 아니다. 계획된 중단이 허용된다면 중단 시간과 실행 절차를 검증한다. 여러 버전의 공존을 지원한다고 선언한 시스템에는 그 공존 검증이 필요하다.
19. 설정 성숙도 — Configuration Maturity
판단할 것
어떤 설정이 실제로 적용되고, 바뀌면 어떤 동작이 달라지는지 설명할 수 있는지 본다. 기본값·환경변수·파일·런타임 변경이 겹칠수록 우선순위가 중요하다.
확인 질문과 증거
- 필수·선택·비밀·재시작 필요·실시간 적용 설정이 구분되는가?
- 잘못된 타입·범위·조합을 시작 시점이나 적용 시점에 검출하는가?
- 오타가 있는 키가 조용히 무시되는가? 검출 범위를 명시했는가?
- 선택하지 않은 기능의 설정까지 필수로 요구하는가?
- 보안상 위험한 개발 기본값이 운영 구성에 그대로 적용될 수 있는가?
- 현재 유효한 설정의 출처·버전·적용 시점을 비밀값 없이 확인할 수 있는가?
- 여러 인스턴스에 변경을 적용하는 중간 상태가 허용되는가?
개선 완료 기준: 설정의 스키마·우선순위·기본값·검증 위치가 일치하고, 대표적인 잘못된 조합은 실행 전에 구체적인 오류로 드러난다. 설정 변경 실패 시 이전 상태 유지 여부도 정의한다.
판정 주의: 모든 미설정 값을 오류로 처리하는 것이 안전한 것은 아니다. 선택 기능은 비활성화될 수 있어야 한다. 반대로 시간 제한을 무한대로 두거나 관리자 인증을 생략하는 식의 위험한 기본값은 명시적 선택과 제한이 필요하다.
20. 개발자 경험 — Developer Experience
판단할 것
템플릿 사용자가 처음 실행하고, 기능을 추가하고, 실패를 해결하는 과정을 본다. 작성자의 개발 환경에서 한 번 실행한 결과만으로 충분하지 않다.
확인할 과제
- 새 환경에서 필요한 런타임과 패키지 관리자를 확인한다.
- 안내된 명령으로 의존성을 설치하고 샘플을 실행한다.
- 테스트 하나를 실행하고 의도적인 입력 오류를 확인한다.
- 작은 기능 하나를 권장 구조로 추가한다.
- 기본 샘플이나 필요 없는 연동 하나를 제거한다.
- 의존성 연결 실패·포트 충돌·필수 설정 누락에서 해결 방법을 찾는다.
문서에서 볼 것: 명령은 한 줄에 한 목적을 두고, 작업 디렉터리·필요 조건·성공 시 보일 결과를 설명한다. 긴 합성 명령이나 숨은 전역 설치를 따라 해야 하는 구조는 시작 비용과 실패 비용을 높인다. 실제 제공되는 명령과 문서가 일치하는지도 확인한다.
개선 완료 기준: 작성자 도움 없이 위 과제를 수행할 경로가 있고, 오류 메시지로 다음 행동을 결정할 수 있다. 생성물 중 사용자가 수정할 영역과 다시 생성될 영역을 구분한다.
과도한 적용을 피할 점: 모든 개발 작업을 전용 CLI로 감쌀 필요는 없다. 이미 익숙한 빌드 도구의 명확한 명령으로 충분하다면 그 편이 유지 비용이 낮다. DX를 개선하려고 또 하나의 자체 프레임워크를 만들지 않는다.
21. Guardrail 성숙도 — 실수 방지 장치
판단할 것
중요한 규칙 위반을 얼마나 이른 시점에, 이해 가능한 메시지로 잡는지 본다. 검사 도구의 개수보다 검출 범위와 우회 가능성이 중요하다.
| 규칙 | 가능한 수단 | 확인할 우회 경로 |
|---|---|---|
| 도메인 간 내부 import 금지 | lint·의존성 검사·공개 패키지 범위 | 상대 경로·재수출·생성 파일 |
| 잘못된 상태 생성 금지 | 생성·변경 API와 타입·런타임 검증 | 단언·역직렬화·직접 필드 변경 |
| 설정 범위 제한 | 스키마·시작 시 검증 | 다른 설정 소스·실시간 변경 |
| 중요한 정책 변경 검출 | 목적이 분명한 테스트·필수 CI 검사 | 검사 제외 경로·조건식·허용 목록 |
| 배포 권한 제한 | 계정 권한·배포 정책 | 다른 인증 정보·별도 배포 경로 |
확인 질문: 규칙을 위반하는 작은 변경을 넣으면 실제로 실패하는가? CI 설정에 검사가 있어도 해당 변경에서 실행되는가? 실패를 무시하고 배포할 수 있다면 그 권한과 기록이 있는가?
개선 완료 기준: 중요한 규칙의 대표 위반이 검출되고, 검사 메시지가 위반 위치와 해결 방향을 알려 준다. 예외에는 이유·범위·담당자·재검토 시점이 있다.
비용 기준: 저위험 스타일 선호 때문에 복잡한 자체 검사기를 만들지 않는다. 표준 도구로 잡을 수 있는 규칙은 표준 도구에 맡기고, 사업 규칙은 코드와 의미 있는 테스트에 둔다. 빌드 스크립트에 모든 정책을 몰아넣는 것도 인지 부하를 높인다.
22. 추상화 성숙도 — Abstraction Maturity
판단할 것
추상화가 숨겨 주는 변동과 사용자가 추가로 배워야 하는 규칙을 비교한다. 구현체 수나 제네릭 매개변수 수로만 평가하지 않는다.
확인 질문과 증거
- 이 추상화가 없는 경우 어떤 중복 지식·외부 결합·테스트 어려움이 생기는가?
- 호출자는 추상화만 보고 성공·실패·비용·수명주기를 이해할 수 있는가?
- 구현체를 바꾸면 같은 계약을 지키는가? 예를 들어 로컬 메모리와 원격 저장소의 실패·일관성 차이를 숨기지 않았는가?
- 기능별 예외를 처리하려고 boolean 인자, callback, 타입 단언이 계속 늘어나는가?
- 추상화 일부를 제거하는 작은 실험에서 중요한 보호 기능을 잃지 않고 읽기가 쉬워지는가?
위험 신호: 모든 업무를 범용 CRUD나 범용 executor에 맞추느라 도메인 의미가 문자열·맵·설정으로 이동한다. 타입을 이해하려면 관계없는 플러그인 체계까지 알아야 한다.
개선 완료 기준: 추상화의 사용자가 알아야 할 계약이 짧고 안정적이며, 반복되는 실제 문제를 줄인다는 사례가 있다. 새로운 요구가 기존 추상화를 크게 비틀면 분리·단순화할 경로가 있다.
판정 주의: 인터페이스 하나가 외부 네트워크·권한·저장 경계를 드러낸다면 구현체가 하나여도 충분한 이유가 된다. 반대로 구현체가 여러 개라는 사실만으로 잘된 추상화가 되지는 않는다. 상이한 실패 의미를 억지로 같은 성공 타입에 맞추고 있지 않은지 본다. [S1]
23. 일관성 — Consistency
판단할 것
같은 의미가 같은 방식으로 표현되고, 다른 의미의 차이는 보존되는지 본다. 이름을 통일하는 과정에서 계약을 바꾸지 않아야 한다.
구분해야 할 예
| 코드·패턴 | 확인할 의미 |
|---|---|
requireNonNull(value) |
값이 null인지 검사한다. 빈 문자열이나 공백 검증과는 다르다. |
requireText(value) |
프로젝트에서 정의한 계약을 읽어야 한다. null·빈 값·공백·정규화 중 무엇을 다루는지 확인한다. |
| 입력 검증 | 외부 요청을 받아들일 수 있는 형식·범위인가? |
| 도메인 검증 | 어떤 진입 경로에서도 지켜야 하는 업무 규칙인가? |
| 인가 검증 | 이 주체가 이 리소스에 이 작업을 수행해도 되는가? |
확인 질문
오류 코드·날짜·시간대·금액·식별자·설정 이름이 기능마다 달라지는가? 같은 검증 이름이 다른 동작을 하는가? 테스트의 준비·실행·검증이 분리되어 읽히는가? 예외가 있다면 실제로 다른 문제를 풀기 때문인가?
개선 완료 기준: 반복해서 만나는 계약과 작성 방식이 예측 가능하고, 예외는 이유를 설명할 수 있다. 공통 helper를 바꿀 때 기존 호출자의 계약 변화도 확인한다.
과도한 적용을 피할 점: Given/When/Then 주석의 유무와 테스트 품질은 구분한다. 예외 검증처럼 실행을 callback에 넣는 라이브러리 관례도 있다. 팀이 명시한 형식을 지키면서 검증 책임이 흐려지지 않는지를 본다. 단순 표기 통일은 데이터·보안 결함과 같은 심각도로 취급하지 않는다.
24. 네이밍 / 의미 성숙도 — Naming & Semantic Maturity
판단할 것
이름을 읽은 사람이 예상한 동작과 실제 동작이 맞는지 본다. 긴 이름보다 의미의 일치가 중요하다.
확인 질문과 증거
get·find가 값이 없을 때 반환·예외·생성을 각각 어떻게 다루는가?save·submit·publish의 성공은 메모리 반영, DB 커밋, 큐 접수, 외부 처리 완료 중 무엇인가?delete가 논리 삭제인지 영구 삭제인지 구분되는가?isAuthorized가 로그인 여부만 검사하는 등 이름이 보장 범위를 과장하지 않는가?timeoutMs처럼 단위가 명확하고,expiresAt처럼 시각·기간이 구분되는가?- 요청마다 다른 ID가 요청·업무 작업·이벤트 중 무엇을 식별하는지 알 수 있는가?
위험 신호: safe, validated, transactional이라는 이름이 실제 보장을 뒷받침하지 않는다. User·Account·Principal을 구분 없이 섞어 소유권 판단이 어려워진다.
개선 완료 기준: 중요한 업무 용어와 상태·실패 의미가 코드·계약·문서에서 일치한다. 이름으로 표현하기 어려운 보장은 짧은 계약 설명과 타입으로 보완한다.
판정 주의: execute(), handle() 자체가 나쁜 이름은 아니다. CancelReservationHandler.handle()처럼 타입이 의미를 충분히 제공할 수 있다. 이름을 길게 만드는 것보다 호출 문맥까지 읽고 판단한다.
25. 조직 확장성 — Organizational Scalability
판단할 것
팀이 늘어날 때 변경·승인·배포를 얼마나 함께 맞춰야 하는지 본다. 독립 모듈과 독립 배포는 같은 개념이 아니다.
확인 질문과 증거
- 기능 팀이 작은 정책 변경을 할 때도 플랫폼 담당자에게 내부 구현 수정을 요청해야 하는가?
- 전역 registry·공통 모델·번역 파일·부트스트랩 한곳에서 충돌이 반복되는가?
- 공유 계약 변경은 사용처와 호환 범위를 확인하고 진행되는가?
- 팀이 자율적으로 바꿀 수 있는 범위와 함께 합의해야 하는 범위가 명확한가?
- 새 팀이 샘플과 공개 API만으로 기능을 추가할 수 있는가?
- 승인·테스트·릴리스 대기 시간이 늘어나는 원인을 기록하는가?
증거: 실제 공동 변경, 반복 충돌, 승인 대기, 함께 배포해야 하는 계약, 공통 모듈 수정 이력이다. 팀이 하나라면 실제 조직 확장 검증은 미확인으로 두고 구조적 준비만 평가한다.
개선 완료 기준: 기능 변경의 책임과 공개 계약이 맞물리고, 공통 영역에 들어가는 이유를 설명할 수 있다. 긴급 패치 때 누가 무엇을 결정하는지 정해져 있다.
과도한 적용을 피할 점: 팀 규모만 보고 마이크로서비스·멀티레포·독립 배포를 의무화하지 않는다. 하나의 배포물 안에서도 코드 소유권과 변경 경계를 나눌 수 있다. 분산으로 늘어나는 운영·계약 비용까지 비교한다.
26. Ownership 성숙도 — 책임과 인수인계
판단할 것
문제가 생겼을 때 조사·수정·배포·복구·사용자 안내를 누가 맡는지 본다. 코드 소유자 파일에 이름이 있는 것과 실제 대응 책임이 연결되는 것은 다르다.
확인 질문과 증거
- 템플릿 자체의 결함과 사용 프로젝트의 설정·업무 정책 결함을 누가 분류하는가?
- 공통 모듈의 패치를 누가 만들고 소비자에게 누가 적용하는가?
- 인증·배포·데이터 복구처럼 여러 책임이 겹칠 때 최종 결정자는 누구인가?
- 사용 중단·설정 제거·기능 플래그 회수·문서 갱신에도 담당자가 있는가?
- 주 담당자가 없을 때 필요한 접근 권한과 설명을 다른 사람이 확보할 수 있는가?
위험 신호: 공유 코드는 모두가 수정하지만 사고 대응자는 없다. 플랫폼 팀은 라이브러리만 제공하고 서비스 팀은 내부를 몰라 장애가 서로에게 되돌아온다.
개선 완료 기준: 주요 기능·공유 기반·운영 작업마다 책임과 지원 범위가 기록되고, 연락 대상과 실행 가능한 절차가 연결된다. 작성자 외 사람이 대표 작업을 수행한 기록이 있으면 인수인계 증거가 된다.
적용 범위: 개인 프로젝트에 형식적인 대규모 조직표를 요구하지 않는다. “미래의 내가 이 장애를 다시 처리할 수 있는가”, “템플릿을 가져간 사람이 어디까지 책임져야 하는가”를 분명히 해도 가치가 있다.
27. 삭제 가능성 — Deletability
판단할 것
불필요한 기능을 제거했을 때 코드·설정·데이터·권한·운영 자원이 함께 정리되는지 본다. 소스 폴더 삭제만으로 끝나지 않는 경우가 많다.
확인할 제거 범위
| 범위 | 남기기 쉬운 흔적 |
|---|---|
| 코드·빌드 | import·재수출·의존 패키지·생성기 등록 |
| 실행 구성 | 라우트·DI 등록·환경변수·기능 플래그 |
| 사용자 계약 | API·이벤트·URL·문서·번역 |
| 데이터 | 열·인덱스·백필·보관 데이터·파생 캐시 |
| 권한·운영 | 서비스 계정·배포 자원·대시보드·알림·비용 |
검증 방법: 선택 기능 하나를 실제로 제거하거나 비활성화한 소비자 예제를 만들고, 최소 구성의 설치·빌드·시작·기본 흐름이 유지되는지 확인한다. 플래그를 껐어도 번들·백그라운드 작업·외부 연결이 남는지 본다.
개선 완료 기준: 관련 없는 기능을 함께 뜯지 않고 제거할 수 있으며, 남는 계약·데이터의 보관 이유와 최종 제거 조건이 명확하다.
원문 보완: 이미 적용된 마이그레이션 이력을 소스 기능과 함께 지워도 된다는 뜻이 아니다. 사용 중인 마이그레이션 도구의 이력 관리 방식과 기존 설치·새 설치 경로를 보존하면서 제거용 변경을 설계한다.
28. 회복 가능성 — Recoverability
판단할 것
장애를 멈추는 것과 올바른 상태로 되돌리는 것을 구분한다. 프로세스 재시작으로 응답이 돌아와도 중복 처리·누락·잘못된 권한이 남을 수 있다.
확인 질문과 증거
- 허용 가능한 데이터 손실 범위인 RPO와 목표 복구 시간인 RTO가 무엇인가?
- 백업 파일뿐 아니라 복구에 필요한 설정·암호화 키·권한·외부 의존성을 확보할 수 있는가?
- 빈 환경이나 지정한 복구 환경에서 실제 복원하고 시간을 측정했는가?
- 메시지·이벤트를 다시 처리할 때 이미 발생한 외부 부작용이 반복되지 않는가?
- 중복 방지 기록의 보관 기간보다 오래된 사건을 재처리하면 어떻게 되는가?
- 복구 후 데이터 정합성·접근 권한·삭제 대상의 재등장 여부를 확인하는가?
- 전체 복구가 어려울 때 영향 범위를 제한하거나 일부 기능부터 재개할 수 있는가?
위험 신호: “백업 성공”만 확인한다. 복구 절차가 현재 버전과 맞지 않는다. 재실행할 수 있는 스크립트는 있지만 대상 범위·중복 실행·진행 상태를 알 수 없다.
개선 완료 기준: 지정한 장애 시점에서 복구를 수행하고, 실제 소요 시간·확인한 데이터 범위·남은 손실을 기록한다. 재처리·수동 보정 도구에도 대상 확인, 범위 제한, 감사 기록, 중단·재개 방법을 둔다.
증거 한계: 작은 실험 DB 복구 성공은 그 환경의 증거다. 실제 데이터량·외부 시스템·권한·운영 절차를 포함한 복구 완료로 확대하지 않는다.
29. 코드에서 위험을 드러내는 방법
위험 가시성은 함수 이름 하나로 완성되지 않는다. 호출부의 의미, 경계의 계약, 실제 실행 정책, 검증 증거가 이어져야 한다.
29.1 무엇을 숨기고 무엇을 보여 줄 것인가
| 숨겨도 되는 구현 세부사항의 예 | 호출자가 알아야 할 계약의 예 |
|---|---|
| HTTP 라이브러리의 연결 생성 방식 | 외부 호출인지, 언제 포기하고 어떤 결과를 반환하는지 |
| SQL 문장의 구체적인 문자열 | 동시 갱신 충돌 여부, 커밋과 반환의 관계 |
| 캐시 저장 자료구조 | 사용자 범위, 신선도, 무효화, 원본 실패 시 동작 |
| 메시지 직렬화 라이브러리 | 접수와 처리 완료의 차이, 중복·순서·재처리 |
| 로깅 라이브러리의 구현 | 민감정보 처리와 오류를 기록하는 책임 |
모든 함수 이름에 WithTimeoutAndRetryAndTransaction을 붙이면 핵심 동작이 오히려 안 보인다. 의미 있는 포트·타입·설정 위치에 계약을 두고, 호출부에서는 그 경계를 알아볼 수 있게 한다.
29.2 Backend 예시: DB 변경과 외부 결제 호출
다음은 위험을 설명하기 위한 축약 코드다. 특정 프로젝트의 코드가 아니다.
@Transactional
public Receipt placeOrder(PlaceOrder command) {
Order order = orders.insertPending(command);
Approval approval = paymentClient.authorize(order);
orders.markPaid(order.id(), approval.id());
return Receipt.from(order, approval);
}
메서드가 짧고 순서가 읽힌다는 장점은 있다. 리뷰는 그다음 질문으로 넘어가야 한다.
| 실패 조건 | 확인할 문제 |
|---|---|
| 결제사가 오래 응답하지 않는다. | DB 연결·락이 실제로 언제 확보되고 얼마나 유지되는가? |
| 결제는 승인됐지만 응답을 잃는다. | 실패로 단정하는가, 결과를 모르는 상태로 남기는가? |
| 승인 뒤 DB 반영이 실패한다. | 외부 승인과 내부 주문을 누가 다시 맞추는가? |
| 같은 주문 요청이 동시에 들어온다. | 논리적으로 같은 결제를 여러 번 실행할 수 있는가? |
| 프로세스가 중간에 종료된다. | 마지막으로 확인된 상태와 재개 지점을 찾을 수 있는가? |
DB 연결·락 유지의 구체적 범위는 트랜잭션 매니저·ORM·flush 시점에 따라 확인해야 한다. 다만 로컬 DB 트랜잭션만으로 외부 결제의 원자성까지 보장하지 않는다는 경계는 분명히 설명되어야 한다.
외부 호출을 트랜잭션 밖으로 옮기는 조치만으로 이 문제가 모두 해결되지는 않는다. 그 사이의 프로세스 종료·중복 호출·상태 경쟁이 새로 드러난다.
개선안을 리뷰할 때 확인할 계약
- 같은 업무 시도에는 안정된 식별자를 사용한다. 재전송마다 새 키를 만들면 같은 작업을 구분하지 못한다.
- 식별자의 사용자·테넌트·작업 범위, 동일 키와 다른 입력의 충돌 처리, 보관 기간을 정한다.
- 로컬 상태 기록·외부 호출·결과 반영 각각의 경계를 정의한다.
- 외부 시스템이 지원하는 중복 억제·결과 조회·취소 계약을 확인한다.
- 응답을 잃은 경우 성공도 실패도 확정하지 않고 결과 조회·대사로 이어지게 한다.
- 중단된 시도를 재개하거나 정리할 담당 흐름과 관측 정보를 둔다.
멱등성 키의 저장과 업무 처리가 경쟁 조건에서 따로 움직이면 중복 억제가 깨질 수 있다. 키가 존재한다는 확인만으로 완료 처리하지 말고 진행 중·완료·실패·결과 불명 상태와 원자적 갱신 범위를 확인한다. [S10]
반환 타입도 결과의 차이를 드러낼 수 있다. 아래는 언어 선택과 무관하게 계약을 보여 주기 위한 TypeScript 예시다.
type PaymentAttemptResult =
| { kind: "approved"; approvalId: string }
| { kind: "declined"; reasonCode: string }
| { kind: "outcome-unknown"; attemptId: string };
이 타입 자체가 중복 결제를 방지하지는 않는다. 호출자가 “결과 불명”을 “결제 실패”로 오해하지 않게 돕는다. 실제 중복 억제와 복구는 저장소·외부 API 계약·경쟁 처리·검증이 맡는다.
Outbox를 도입한다면 로컬 데이터와 이벤트 기록의 원자성을 어떻게 확보하는지, 전달 중복과 소비자 중복 처리를 어떻게 다루는지 본다. Outbox가 외부 시스템의 모든 부작용을 정확히 한 번만 실행하게 해 준다고 확대 해석하지 않는다.
29.3 Frontend 예시: 비동기 응답과 사용자 범위
async function refreshOrders() {
const orders = await api.getOrders();
store.setOrders(orders);
}
이 코드도 짧지만 다음 조건이 보이지 않는다.
- 호출 중 사용자가 로그아웃하거나 다른 계정으로 로그인하면?
- 더 최신 필터의 요청이 먼저 끝나고 과거 요청이 나중에 끝나면?
- 화면을 떠난 뒤 응답이 도착하면?
- API 실패를 빈 배열로 바꿔 “주문 없음”으로 표시하면?
- SSR에서 여러 사용자의 요청이 같은 저장소 인스턴스를 공유하면?
개선안을 리뷰할 때 확인할 계약
| 경계 | 드러나야 할 정보 | 확인할 행동 |
|---|---|---|
| 요청 수명 | 시작·취소·완료와 소유 화면 | 화면 이동 후 불필요한 작업과 상태 반영 |
| 응답 순서 | 어떤 요청의 결과가 유효한가 | 응답 순서를 뒤집어 최신 상태 유지 |
| 인증 범위 | 현재 사용자·테넌트·인증 세대 | 로그아웃 전 요청이 후속 상태를 바꾸지 않음 |
| 캐시 | 키·유효 기간·공유 범위·초기화 | 다른 사용자나 필터의 결과 혼입 방지 |
| 실패 의미 | 오류·빈 결과·결과 불명 | 상태별 문구와 가능한 행동 |
| 실행 환경 | 브라우저 앱·SSR 요청별 소유권 | 서로 다른 서버 요청의 상태 격리 |
인증 세대는 로그인 상태가 바뀌기 전후를 구분하는 클라이언트 내부 표식 같은 방법을 뜻한다. 이것을 서버 인가의 근거로 사용해서는 안 된다.
AbortController 등으로 요청을 취소해도 서버의 처리가 없었다는 뜻은 아니다. 쓰기 요청의 중복 억제는 서버 계약으로 다룬다. 클라이언트에서도 취소만 믿지 말고, 이미 완료된 응답이나 다른 비동기 단계가 현재 화면 상태를 덮어쓰지 않는지 확인한다.
UI 상태를 타입으로 표현하는 것은 이런 구분을 보존하는 한 방법이다.
type LoadState<T> =
| { kind: "idle" }
| { kind: "loading" }
| { kind: "success"; data: T }
| { kind: "empty" }
| { kind: "error"; errorCode: string; retryAllowed: boolean };
화면이 기존 데이터를 유지하며 새로 고치는 UX라면 refreshing·이전 데이터 같은 상태가 더 필요할 수 있다. 이 예시 타입을 모든 화면에 그대로 강제하기보다 실제 사용자 흐름의 불가능한 조합을 줄이는지 판단한다.
29.4 위험 가시성의 완료 기준
중요한 동작 하나를 골라 다음 문장을 코드와 증거로 채울 수 있어야 한다.
이 호출은 어디에 어떤 부작용을 만들며, 언제까지 기다리고, 어떤 조건에서 다시 시도하며, 동시에 실행되거나 응답을 잃으면 어떤 상태가 남는다. 그 상태는 어디서 확인하고 어떻게 조정한다.
계약이 없으면 먼저 계약을 정한다. 계약은 있는데 호출부에서 찾기 어렵다면 이름·배치·타입을 고친다. 계약과 구현이 다르면 실제 동작을 고치고 실패 조건을 검증한다. 세 문제를 전부 “네이밍 개선”으로 처리하지 않는다.
30. 템플릿을 하나의 제품으로 보는 추가 기준
원문의 28개 관점은 일반 서비스에도 적용된다. 템플릿에는 재사용·복제·조합·업데이트·제거 때문에 생기는 추가 책임이 있다.
30.1 최소 구성과 안전한 기본값
사용자가 기본 명령으로 시작했을 때 어떤 구성인지 명확해야 한다. 테스트용 인증 우회, 메모리 저장소, 가짜 결제 어댑터가 있다면 용도와 제한을 드러낸다. 운영 프로필이 이를 실수로 채택하지 않게 한다.
DB·캐시·인증·메시지 시스템을 모두 띄워야 빈 화면 하나를 실행할 수 있다면 최소 구성을 다시 검토한다. 선택 기능을 위한 확장 위치와 운영상 필수 기능은 구분한다.
검증: 최소 구성, 대표 확장 구성, 지원하지 않는 잘못된 조합을 각각 실행한다. 마지막 조합은 조용히 잘못 동작하는 대신 이해할 수 있는 오류로 거부되어야 한다.
30.2 옵션 조합의 수와 검증 책임
옵션이 늘면 지원할 조합도 늘어난다. 저장소 3개와 인증 방식 4개를 제공한다는 이유로 모든 조합이 검증된 것은 아니다.
| 옵션 상태 | 필요한 설명 |
|---|---|
| 기본 지원 | 기본값, 동작, 자동 검증 범위 |
| 선택 지원 | 추가 전제, 조합 제약, 운영 책임 |
| 실험 | 확인한 범위와 미검증 조건 |
| 비지원 | 왜 비지원인지, 잘못 선택했을 때의 오류 |
위험이 높은 조합은 직접 검증하고, 나머지는 선정 원칙을 기록한다. 일부 조합 테스트로 모든 조합의 안전성을 주장하지 않는다.
30.3 생성·복사 후 수정 권한
생성 파일 중 사용자가 수정할 부분, 다시 생성될 부분, 공통으로 관리하는 부분을 구분한다. 코드 생성기가 있으면 재실행 시 사용자의 수정이 덮어써지는지 확인한다.
모든 파일에 “수정 금지”를 붙여 사용자 변경을 막는 방식도 비용이 크다. 사용자가 실제로 바꾸는 정책은 안정된 수정 지점으로 제공한다.
30.4 버전과 업데이트 전파
템플릿 원본의 버전과 사용 프로젝트가 출발한 버전을 식별할 수 있어야 한다. 복사된 프로젝트는 원본 패치를 자동으로 받지 않는 경우가 많다.
| 제공 방식 | 리뷰에서 확인할 업데이트 문제 |
|---|---|
| 저장소 복사 | 원본 변경을 어떻게 찾아 선택적으로 반영하는가? |
| 코드 생성 | 재생성 시 사용자 수정과 충돌을 어떻게 처리하는가? |
| 공통 라이브러리 | 공개 계약·지원 버전·업그레이드 순서를 어떻게 관리하는가? |
| 혼합 방식 | 어떤 코드가 어디서 관리되며 중복 패치를 어떻게 피하는가? |
검증: 사용자 수정이 들어간 대표 소비자에 템플릿의 작은 보안·계약 패치를 반영해 본다. 수정 보존, 충돌 설명, 테스트, 되돌림·재적용 경로를 확인한다.
30.5 샘플 코드의 대표성
샘플은 가장 많이 복제되는 설명서다. 성공 경로만 보여 주고 실패·권한·설정 누락을 숨기면 사용자가 그 빈칸을 프로젝트마다 다시 채운다.
복제할 샘플에는 해당 기능에 필요한 최소 실패 처리와 검증을 넣고, 설명을 위해 생략한 부분은 표시한다. 데모 편의를 위한 우회가 권장 운영 코드처럼 보이지 않게 한다.
30.6 도입·유지 비용
기본 실행의 메모리·외부 서비스·설정 수, 첫 기능 추가의 필수 개념, CI 시간, 업그레이드·패치 작업을 본다. 팀이 사용하지 않는 기능을 이해·운영해야 한다면 재사용 이익이 줄어든다.
“도메인을 더 추가해도 된다”는 선언만으로 비용을 평가하지 않는다. 기본 기능을 끄거나 삭제할 때의 비용도 함께 잰다.
30.7 템플릿에서 졸업할 수 있는가
사용 프로젝트가 커지면서 기본 구조를 바꿀 수 있어야 한다. 데이터·도메인 정책이 템플릿 고유 registry나 설정 언어에 갇혀 있는지, 일반 코드로 이동할 경로가 있는지 본다.
안전한 기본 흐름은 제공하되, 변경할 수 있는 경계와 변경 후 사용자가 맡는 책임을 명시한다. 모든 변경을 금지하는 것이 장기 유지보수성은 아니다.
30.8 배포 판단에 필요한 최소 증거
| 배포하려는 주장 | 그 주장에 필요한 증거 |
|---|---|
| 새 프로젝트를 시작할 수 있다. | 깨끗한 환경의 설치·실행·기본 테스트 |
| 기본 패턴을 복제해 기능을 만들 수 있다. | 작성자 외 사용자의 대표 기능 추가 |
| 선택 기능을 분리할 수 있다. | 최소·선택 구성의 동작과 제거 확인 |
| 패치를 사용 프로젝트에 전달할 수 있다. | 사용자 수정이 있는 소비자의 업데이트 검증 |
| 특정 운영 구성을 지원한다. | 그 구성의 장애·배포·복구 조건에 맞는 증거 |
지원하지 않는 기능을 명시적으로 제외하는 것도 성숙한 선택이다. 없는 기능을 안전하다고 주장하지 않고, 사용자가 잘못된 전제로 도입하지 않게 한다.
31. Backend Template에서 깊게 볼 시나리오
아래 표는 실제 코드 리뷰에서 선택할 시나리오다. 기능이 없는 경우 적용 제외 사유를 적는다. 모든 템플릿에 모든 기술을 추가하라는 뜻은 아니다.
| 시나리오 | 따라갈 경계 | 확인할 결과 |
|---|---|---|
| 정상 쓰기 요청 | 입력·인가·정책·트랜잭션·저장·응답 | 규칙과 커밋 의미가 일치하고 민감정보가 새지 않는다. |
| 중복·동시 요청 | 요청 식별·DB 제약·외부 부작용 | 같은 논리적 작업의 중복 효과를 계약대로 처리한다. |
| 외부 응답 지연·유실 | 시간 제한·재시도·결과 저장 | 대기와 자원이 제한되고 결과 불명을 조회·조정할 수 있다. |
| DB 오류·경쟁 | 트랜잭션·충돌·오류 변환 | 잘못된 일부 상태가 남지 않거나 남은 상태가 설명된다. |
| 메시지 중복·역순 | 발행·소비·중복 기록·버전 | 지원하는 전달 조건에서 규칙이 유지된다. |
| 신·구 버전 공존 | API·스키마·이벤트 | 선언한 지원 기간 동안 읽기·쓰기가 호환된다. |
| 여러 서버의 작업 실행 | 스케줄러·작업 소유권·저장소 | 중복 실행·중단·재개를 정의한 규칙으로 처리한다. |
| 세션·토큰 갱신 경쟁 | 세션·인증 클라이언트·토큰 저장·락 | 지원하는 인증 구조에서 사용자 상태가 섞이지 않고 경쟁을 처리한다. |
| 다른 사용자 리소스 접근 | 인증·리소스 조회·인가 | 객체 ID를 바꿔도 권한 없는 조회·수정이 거부된다. |
| 큰 입력·목록 조회 | 입력 상한·쿼리·페이지·직렬화 | 메모리·호출 수·응답 크기의 제한이 유지된다. |
| 종료·재시작 | 신규 요청 차단·진행 작업·메시지 확인 | 완료·재전달·재개 조건이 설명되고 실제로 확인된다. |
| 선택 어댑터 제거 | 조립·의존성·설정·테스트 | 최소 구성이 불필요한 연결·설정 없이 동작한다. |
리뷰어가 요청 하나를 따라가며 적을 것
입력의 신뢰 수준, 권한 판단 위치, 규칙을 소유한 객체, 트랜잭션 시작·종료, 외부 부작용, 성공의 의미, 오류 변환, 연결 가능한 진단 정보를 적는다. 이 흐름을 설명하지 못한 상태에서 패키지 이름만 보고 구조를 평가하지 않는다.
예를 들어 세션 저장소와 OAuth 인가 클라이언트 저장소가 모두 등장한다면 각각 무엇을 키로 어떤 상태를 저장하는지 확인한다. 같은 저장소 제품을 사용한다고 두 상태의 수명과 책임이 같은 것은 아니다. 실제 인증 구성과 사용 라이브러리의 계약을 읽고 판단한다.
비용이 작은 개선부터 비교
중복 생성을 막는 요구라면 DB 유일성 제약과 충돌 처리가 충분한지 먼저 본다. 원격 부작용과의 조정이 필요할 때 멱등성·결과 조회·이벤트 기록 같은 추가 수단을 검토한다. 모든 위험의 해결책을 분산 락·사가·새로운 인프라 도입으로 고정하지 않는다.
32. Frontend Template에서 깊게 볼 시나리오
프론트엔드는 폴더 구조와 컴포넌트 분리만으로 평가하기 쉽지만, 실제 결함은 상태 수명·사용자 경계·비동기 경쟁·배포 호환에서 드러나는 경우가 많다.
| 시나리오 | 따라갈 경계 | 확인할 결과 |
|---|---|---|
| 목록 최초 진입 | route·기능 조립·조회·렌더링 | loading·success·empty·error가 의미에 맞게 구분된다. |
| 상세 URL 직접 접속·새로고침 | URL·서버 제공·라우터·권한 | 지원 경로가 직접 진입에서도 동작하고 잘못된 경로를 처리한다. |
| 빠른 필터 변경 | URL/폼 상태·요청 식별·캐시 | 과거 응답이 최신 화면을 덮지 않는다. |
| 화면 이동·언마운트 | 요청·구독·타이머·캐시 수명 | 불필요한 작업·리스너·상태 반영이 누적되지 않는다. |
| 로그아웃 중 응답 도착 | 인증 상태·요청·캐시·전역 store | 이전 사용자 응답이 다음 세션 상태에 들어가지 않는다. |
| 사용자·테넌트 전환 | 캐시 키·초기화·서버 인가 | 데이터 범위가 분리되고 UI 제한과 서버 권한이 구분된다. |
| 저장 버튼 중복 클릭 | UI pending·작업 식별·서버 계약 | 화면의 중복 클릭 방지와 서버의 중복 처리 책임이 연결된다. |
| 낙관적 갱신 실패 | 임시 상태·오류·재조회·롤백 | 잘못된 성공 상태가 남지 않고 최신 변경을 덮어 되돌리지 않는다. |
| 세션 만료 | API 오류·갱신·재로그인·이동 | 무한 갱신·리다이렉트·재시도 없이 다음 행동을 제공한다. |
| 공통 HTTP 설정 변경 | API 바인딩·base URL·헤더·시간 제한 | 각 기능이 상충하는 전송 정책을 따로 구현하지 않는다. |
| 새 배포 후 기존 탭 사용 | HTML·청크·CDN·라우트 | 자산 부재·버전 불일치에서 복구 경로가 있다. |
| 다국어 전환 | 화면·행동·오류·빈 상태·접근성 이름 | 주요 사용자 문구가 빠지지 않고 날짜·숫자 표시가 맞는다. |
| 키보드·보조기술 사용 | 포커스·라벨·다이얼로그·상태 변경 | 핵심 흐름을 조작하고 현재 상태를 이해할 수 있다. |
| 여러 SSR 요청 | 요청별 인증·캐시·store·조립 | 요청 간 사용자 상태가 공유되지 않는다. |
| 기능 추가·삭제 | 공개 API·route·조립·번들 | 다른 기능 내부 변경 없이 예측한 범위에서 작업한다. |
32.1 상태의 소유권
서버 원본 데이터, URL 상태, 폼 초안, 일시적 UI 상태, 인증 상태가 어디에 속하는지 구분한다. 같은 값을 여러 저장소에 복제했다면 어느 값이 기준이며 언제 맞춰지는지 설명해야 한다.
전역 store는 그 자체로 문제도 해법도 아니다. 수명과 공유 범위가 맞는지가 중요하다. 화면 하나의 임시 상태를 앱 전체가 공유하거나, SSR 요청별 정보가 프로세스 전역에 남는 상황을 특히 본다.
32.2 UI에 필요한 계약과 내부 계약
컴포넌트가 HTTP 상태 코드·토큰·재시도 엔진을 모두 알아야 하면 경계가 약할 수 있다. 반대로 공통 어댑터가 모든 실패를 false로 바꾸면 화면이 사용자에게 필요한 행동을 선택할 수 없다.
사용자 취소, 입력 오류, 권한 부족, 재로그인 필요, 일시 장애, 처리 결과 불명을 필요한 범위에서 구분한다. “다시 시도” 버튼이 실제로 안전한지도 서버 계약과 함께 검토한다.
32.3 접근성과 국제화
접근성을 자동 스캔 통과로만 판정하지 않는다. 키보드 순서·포커스 복귀·오류와 입력의 연결·로딩 및 완료 상태 전달을 실제 화면에서 확인한다. WCAG는 이런 검토에 사용할 기준을 제공하지만, 일부 검사항목 통과만으로 전체 준수를 선언하지 않는다. [S7]
국제화는 메뉴 이름 교체에서 끝나지 않는다. 버튼·검증 오류·empty·loading·알림·접근성 이름·날짜·숫자의 범위와 누락 시 동작을 본다. 아직 한 언어만 지원한다면 실제 요구와 확장 계획을 기준으로 범위를 정한다.
32.4 대규모 기능 증가
기능 수가 늘어날 때 라우팅·초기화·번들·타입 검사·공통 파일 충돌이 어떻게 늘어나는지 본다. 각 도메인을 디렉터리로 나눴다는 사실만으로 독립성이 증명되지는 않는다.
특히 앱 부트스트랩이 기능의 공개 계약만 조합하는지, 기능 내부의 세부 오류·상태·API까지 알고 있는지 확인한다. 조립 지점이 존재한다는 이유만으로 결함은 아니며, 거기에 모인 지식의 성격과 변경 비용을 본다.
33. Platform / 배포 기반 템플릿에서 깊게 볼 시나리오
플랫폼 구성을 제공하는 템플릿에 적용한다. 일반 애플리케이션 템플릿에 Kubernetes·고가용성 구성을 반드시 추가하라는 뜻은 아니다.
| 시나리오 | 확인할 대상 | 확인할 결과 |
|---|---|---|
| 새 환경 생성 | 구성 원본·권한·버전·네트워크·비밀값 | 숨은 수동 상태 없이 지원 환경을 재구성한다. |
| 인스턴스·노드 중단 | 트래픽·복제·상태 저장·작업 재개 | 선언한 장애 범위에서 업무 규칙과 복구 목표를 지킨다. |
| 공통 의존성 장애 | DB·인증·DNS·외부 저장소 | 재시작·재시도 연쇄로 장애가 확대되지 않는다. |
| readiness·liveness 실패 | 검사 의미·임계값·라우팅·재시작 | 재시작으로 해결할 장애와 트래픽 제외가 필요한 상태를 구분한다. |
| 백업·복구 | 데이터·키·설정·권한·복구 순서 | 실제 복원과 정합성 확인이 가능하다. |
| 비밀값·인증서 교체 | 발급·주입·반영·폐기·재연결 | 교체 중간 상태와 실패 복귀를 설명한다. |
| 자원 압박 | CPU·메모리·저장 공간·연결·큐 | 과부하 감지·제한과 복구 동작이 검증된다. |
| 공급망·배포 권한 | 빌드 출처·산출물·계정·환경 | 검증한 산출물을 권한 있는 경로로 배포한다. |
| 구성 차이 누적 | 선언한 설정·실제 적용 상태 | 수동 변경을 식별하고 유지·원복 결정을 기록한다. |
| 기반 제거·이전 | 데이터·DNS·인증서·비밀·계정·비용 | 필요한 이력을 남기고 불필요한 자원과 권한을 회수한다. |
고가용성 주장에 필요한 추가 질문
두 인스턴스가 같은 호스트·디스크·전원·네트워크·DB를 공유한다면 어떤 장애가 여전히 공통 장애인지 적는다. 인스턴스 수만으로 독립된 장애 영역이 확보됐다고 판단하지 않는다.
데이터 복제와 백업도 구분한다. 잘못된 삭제나 손상이 복제될 수 있다면 복제만으로 복구할 수 있는 범위를 설명해야 한다.
Kubernetes를 사용할 경우 잘못된 liveness 설정은 부하가 높은 인스턴스를 반복 재시작해 남은 인스턴스의 부담을 키울 수 있다. 검사 경로·빈도·실패 임계값을 실제 장애 시나리오와 연결한다. [S5]
34. 실제 리뷰를 수행하는 순서
34.1 리뷰 대상과 증거 시점을 고정한다
저장소, 브랜치·커밋, 미커밋 변경의 유무, 확인 날짜, 실행 환경, 리뷰 목적을 기록한다. 기존 변경을 보존하고 무엇을 읽고 실행했는지 구분한다.
README·설계 문서는 주장과 의도를 찾는 자료다. 실제 동작의 증거는 코드·구성·현재 실행 결과에서 찾는다. 이전 버전의 테스트 결과를 현재 코드의 증거로 그대로 재사용하지 않는다.
34.2 핵심 주장과 적용 범위를 적는다
“다중 인스턴스 지원”, “기능별 경계 강제”, “선택 연동 제거 가능”, “안전한 재시도”처럼 검증 가능한 문장으로 바꾼다. 적용하지 않는 기능과 그 이유도 함께 기록한다.
예를 들어 “확장성 우수”라는 주장은 “기능을 추가할 때 다른 기능 내부를 수정하지 않으며, 정한 규모에서 빌드·초기화 비용이 예산을 넘지 않는다”처럼 나눠야 확인할 수 있다.
34.3 실행 경로와 신뢰 경계를 지도처럼 정리한다
입력·권한·정책·상태 저장·외부 I/O·오류·관측·복구의 연결을 대표 경로로 확인한다. 정확한 관계를 보여 주는 간단한 표나 다이어그램을 사용한다.
정상 조회 하나, 상태를 바꾸는 요청 하나, 인증·권한 경로 하나, 외부 호출 또는 비동기 경로 하나를 우선 선정할 수 있다. 이것은 시작 표본이며 저장소 전체 검토를 대체하지 않는다.
34.4 중요한 실패와 경계를 먼저 검증한다
데이터 손상·권한 우회·결과 불명·무제한 자원 사용·복구 불가처럼 피해가 큰 경로부터 본다. 위험이 없는 단순 스타일 항목에 먼저 시간을 쓰지 않는다.
대표 위반이나 실패를 재현할 때는 격리된 검증 환경을 사용한다. 운영 데이터 삭제·실제 결제·외부 전송을 발생시키는 검증은 별도 실행 범위와 승인이 필요한 작업이다.
34.5 변경·삭제·업데이트를 한 번 따라간다
기능 추가, 정책 변경, 선택 기능 제거, 소비자 패치 반영을 실제 diff나 구체적인 작업 경로로 확인한다. 미래 가능성을 추측하는 설명보다 비용을 더 잘 보여 준다.
34.6 반복되는 패턴을 확인하며 범위를 넓힌다
좋은 샘플 하나만 보고 모든 기능이 같다고 판단하지 않는다. 다른 작성 시기·규모·도메인·예외 경로의 표본도 확인한다.
검색 결과 개수는 위치를 찾는 데 쓴다. catch, any, common, @Transactional이 몇 번 나오는지만으로 결함 수를 세지 않는다. 해당 맥락과 도달 가능한 실행 경로를 확인한다.
34.7 발견 사항과 미검증을 분리한다
확인된 결함, 조건부 구조적 위험, 아직 확인하지 못한 항목을 나눠 적는다. 각각 근거·발생 조건·영향·최소 개선 방향·완료 검증을 연결한다.
같은 원인을 여러 관점에서 다시 발견했다면 하나의 항목에 관련 관점을 연결한다. 증거가 없는 결론은 질문이나 미검증 항목으로 남긴다.
34.8 필요한 검증까지만 수행한다
먼저 읽어서 확인할 수 있는 계약을 확인하고, 남은 위험을 해결할 실험만 실행한다. 작은 스타일 변경에 대규모 E2E나 부하 테스트를 붙이지 않는다. 반대로 동시성 문제를 단일 요청 테스트로 닫지 않는다.
충분한 증거가 모이면 다음 위험으로 이동한다. 검사를 많이 실행했다는 사실을 리뷰의 깊이로 대신하지 않는다.
34.9 결과를 사용 결정으로 연결한다
“좋다/나쁘다” 대신 어떤 용도에서 지금 사용할 수 있고, 무엇을 고쳐야 하며, 어떤 주장은 검증이 필요한지 적는다. 범위가 제한된 합격도 유효한 결과다.
비교에 유용한 측정 항목
| 측정 | 활용 | 오해하지 말 것 |
|---|---|---|
| 대표 과제의 탐색·변경 시간 | 인지 부하·DX 개선 전후 | 사람·과제 차이를 무시한 절대 등급 |
| 함께 바뀌는 정책·모듈·계약 | 변경 범위와 조율 비용 | 파일 수만으로 계산한 품질 |
| 필요한 CI의 시간·실패 설명·불안정성 | 피드백 비용 | 테스트 수가 많을수록 안전하다는 주장 |
| 부하별 지연·오류·포화 자원 | 용량과 제한 동작 | 다른 조건의 평균값 비교 |
| 복구 시간·손실·정합성 확인 범위 | 회복 가능성 | 백업 성공을 복구 성공으로 간주 |
| 소비자 패치 적용의 수정·충돌 | 템플릿 업데이트 비용 | 원본 패치 완료를 모든 소비자 완료로 간주 |
측정값에는 비교 기준과 조건을 붙인다. 이 가이드는 업계 공통의 합격 시간·최대 파일 수·최소 커버리지 비율을 제시하지 않는다.
35. 심각도·성숙도·증거·완료를 구분하는 판정 체계
원문의 단계 체계는 출발점으로 쓸 수 있지만, 통제 장치의 강도와 검증 환경이 한 줄에 섞여 있었다. 여기서는 다음 네 가지를 따로 기록한다.
- 문제의 심각도: 발생하면 얼마나 큰 피해가 생기는가?
- 통제 수준: 중요한 규칙을 어떤 수단으로 보호하는가?
- 검증 증거: 어떤 버전·조건·환경에서 무엇을 확인했는가?
- 조치 상태: 합의한 개선과 검증이 끝났는가?
35.1 발견 사항의 성격
| 분류 | 기준 | 표현 예시 |
|---|---|---|
| 확인된 결함 | 현재 코드·구성 또는 실행 결과로 계약 위반을 입증 | “권한 검사를 거치지 않는 이 경로에서 다른 사용자 리소스를 반환한다.” |
| 구조적 위험 | 지원 조건에서 문제가 될 인과 경로가 있으며 영향 확인이 남음 | “외부 지연 동안 자원을 점유하는 구조다. 목표 부하에서 고갈되는지는 미확인이다.” |
| 미검증 | 관련 자료·실행 결과가 부족해 판단할 수 없음 | “복구 스크립트는 있으나 실제 복구 결과를 확인하지 못했다.” |
| 개선 제안 | 확인된 계약 위반 없이 이해·비용을 개선할 여지 | “같은 역할의 이름을 통일하면 탐색 부담을 줄일 수 있다.” |
실행 재현이 없어도 충분한 정적 증거로 결함을 확정할 수 있다. 반대로 테스트를 한 번 실행했다는 사실만으로 원인과 영향이 입증되는 것도 아니다.
35.2 심각도
다음은 이 문서의 판정 예시다. 조직의 사고 등급과 연결할 때는 정의를 맞춘다.
| 등급 | 판단 기준 | 예시와 조건 |
|---|---|---|
| Critical | 심각한 보안·데이터·금전 피해 또는 광범위한 서비스 상실로 이어지는 도달 가능한 경로 | 인증 없이 민감정보 접근, 실제 데이터의 비가역적 대량 손상 등 |
| High | 지원하는 사용·배포·장애 조건에서 중요한 기능 실패나 큰 피해를 유발 | 다중 서버에서 업무 중복 실행, 결과 불명 작업의 무방비 재실행 등 |
| Medium | 피해 범위가 제한되거나 변경·운영 비용을 반복해서 높임 | 정책 중복으로 변경 누락이 반복됨, 주요 진단 정보 부족 등 |
| Low | 계약 위반과 직접적인 운영 피해가 작고 주로 가독성·편의에 영향 | 모호한 지역 변수명, 제한된 문서 불일치 등 |
같은 구조도 데이터·권한·발생 조건에 따라 등급이 달라진다. 아키텍처 경계가 없다는 사실, 인터페이스가 많다는 사실, common이 크다는 사실만으로 Critical을 부여하지 않는다.
다음 정보를 함께 적는다.
- 발생 조건과 도달 가능성
- 영향을 받는 사용자·데이터·서비스
- 탐지와 복구의 난이도
- 기본 설정·샘플을 통해 다른 프로젝트로 복제되는 범위
- 근거의 확실성과 아직 확인할 가정
불확실성은 별도로 표시한다. 증거가 부족한데 “높은 확률” 같은 표현을 임의로 붙이지 않는다.
35.3 조치 우선순위
| 우선순위 | 처리 기준 |
|---|---|
| P0 | 현재 심각한 피해가 발생하거나 노출된 경로의 즉시 차단·완화가 필요 |
| P1 | 해당 용도의 도입·출시·확대 전에 해결할 차단 항목 |
| P2 | 현재 사용 범위에서 조건을 관리하며 계획적으로 개선 |
| P3 | 효과와 비용을 비교해 선택할 개선 |
이 분류는 관점별 고정 순위가 아니다. 데이터 복구가 없는 서비스에서는 회복 가능성이 최우선이 될 수 있고, 배포할 수 없는 템플릿에서는 개발자 경험의 실행 경로가 도입 차단 항목이 될 수 있다.
예방 비용과 피해·복제 범위를 함께 고려하되, 낮은 비용의 스타일 개선으로 심각한 미해결 위험을 가리지 않는다.
35.4 통제 수준
원문의 Level 0~4 취지를 다음처럼 좁혀 사용한다. 프로젝트 전체가 아니라 선정한 규칙에 부여한다.
| 수준 | 의미 | 필요한 근거 |
|---|---|---|
| M0 — 통제 부재 확인 | 필요한 규칙을 지킬 수단이 없다. | 관련 경로를 확인한 결과 |
| M1 — 명시 | 규칙·책임·제약이 적혀 있다. | 현재 계약·설정 설명·문서 |
| M2 — 구현·일관 적용 | 필요한 코드 경로에 규칙이 구현되어 있다. | 대표·예외 경로의 실제 구현 |
| M3 — 위반 검출 | 의미 있는 자동 검증이 위반을 검출한다. | 검사 구성과 관련 실패·통과 증거 |
| M4 — 경계에서 강제 | 타입·공개 범위·DB 제약·권한 등으로 규칙 위반을 직접 제한한다. | 적용 경계와 우회 검증 |
미확인은 M0가 아니다. 필요한 경로를 읽지 못했다면 미평가 또는 미확인으로 남긴다. 문서만 존재하는 상태와 문서에 적힌 구현이 실제로 확인된 상태도 구분한다.
모든 규칙에 M4가 필요하거나 가능한 것은 아니다. 낮은 피해의 표기 규칙과 금전·인가 규칙에 같은 통제 비용을 쓰지 않는다. 강한 통제가 일부 경로에만 적용되면 그 범위만 기록한다.
35.5 검증 증거
| 표기 | 확인한 것 | 확대해서 주장할 수 없는 것 |
|---|---|---|
| E0 — 설명·주장 | 문서·설계 의도가 있다. | 실제 구현·동작 |
| E1 — 정적 확인 | 코드·설정에서 구현과 경로를 확인했다. | 실행 환경의 전체 동작 |
| E2 — 테스트 실행 | 명시한 테스트가 해당 버전에서 통과했다. | 테스트하지 않은 실패·규모 |
| E3 — 통합·실험 확인 | 실제 의존성, 선택한 부하·장애·배포·복구 조건에서 확인했다. | 다른 구성·데이터량·실제 운영 기간 |
| E4 — 실제 운영 관찰 | 정한 기간·사용량·환경에서 운영 결과와 대응 기록을 확보했다. | 모든 장애·미래 규모의 안전성 |
이 표는 모든 성질에 적용되는 단일 사다리가 아니다. 높은 번호의 증거 하나가 낮은 번호의 모든 검증을 대신하지 않는다. 실제 운영에서 정상 요청을 처리했다는 증거와 복구 실험의 증거는 별도로 필요할 수 있다.
예를 들어 “통제 M3, 단위 테스트 E2, 다중 인스턴스 경쟁 미검증”처럼 적는다. 코드에 강제 장치가 있어도 운영 복구를 검증했다는 뜻은 아니다.
실험은 실험으로 기록한다. 장애 주입·부하·복구를 수행한 환경이 실험실이라면 E3 범위다. 원문의 “Level 5 — 운영 검증”처럼 실험과 실제 운영을 하나의 표현으로 합치지 않는다.
35.6 항목 상태와 완료의 정의
| 상태 | 의미 |
|---|---|
| 충족 | 합의한 범위·목표와 필요한 검증을 만족한다. |
| 부분 충족 | 일부 경로·구성·검증이 남아 있다. |
| 미충족 | 필요한 계약·구현·통제가 없거나 확인된 결함이 남아 있다. |
| 미검증 | 현재 증거로 충족 여부를 판단할 수 없다. |
| 적용 제외 | 이 사용 범위에 해당하지 않으며 이유가 있다. |
“검토 중”, “조치 중”, “보류”, “위험 수용”은 별도의 작업 상태로 관리한다. 위험을 수용했다고 기술적으로 충족한 것은 아니다. 수용 이유·책임자·보완 수단·재검토 조건을 적는다.
개선 항목을 닫으려면 다음이 연결되어야 한다.
- 원래 위험과 발생 조건
- 변경한 코드·구성·계약
- 문제를 검출하거나 남은 위험을 확인하는 검증
- 검증한 버전·환경·실행 결과
- 남아 있는 제한과 후속 책임
문서의 체크 표시나 구현자의 “완료” 설명만으로 닫지 않는다. 수정 후 현재 상태를 확인한다.
35.7 전체 성숙도를 요약하는 방법
기본 보고는 관점별 목표 대비 상태, 도입·출시 차단 항목, 미검증 목록으로 한다. 28개 관점의 단순 평균으로 인증 우회나 복구 불가를 상쇄하지 않는다.
진행률이 필요하면 먼저 독립적으로 검증 가능한 세부 기준을 고정한다. 적용 항목 중 충족·부분 충족·미충족·미검증 수를 각각 보고하고, 적용 제외는 사유와 함께 분리한다. 미검증 항목을 분모에서 빼서 완료율을 높이지 않는다.
점수를 꼭 사용한다면 가중치·배점·합격 조건·미검증 처리·차단 규칙을 사전에 합의한다. 기준이 바뀌면 이전 점수와 직접 비교하지 않는다. 서로 목적이 다른 Backend와 Frontend 템플릿의 단일 점수 경쟁은 피한다.
35.8 사용 결정의 표현
| 결정 | 뜻 |
|---|---|
| 지정 범위에서 사용 가능 | 선언한 범위의 필수 기준과 검증을 충족 |
| 조건부 사용 가능 | 사용 조건·제외 기능·보완 책임을 구체적으로 제한 |
| 해당 용도의 사용 보류 | 필수 계약의 결함이나 중요한 검증 공백이 남음 |
| 판단 보류 | 범위·목표·증거가 부족해 결정할 수 없음 |
새 템플릿에 실제 운영 이력이 없다는 이유만으로 영구적으로 사용을 막는 것은 적절하지 않다. 도입 전에 필요한 실험·제한을 정하고, 사용 범위를 넓히면서 운영 증거를 축적한다.
36. 실제 리뷰 결과에 사용할 양식
아래 양식의 빈칸은 실제 리뷰에서 채울 항목이다. 현재 프로젝트의 평가 결과가 아니다.
36.1 리뷰 범위
| 항목 | 기록 |
|---|---|
| 대상 저장소·프로젝트 | 기재 |
| 커밋·작업 상태·확인 시점 | 기재 |
| 목적과 지원 실행 구성 | 기재 |
| 필수 요구와 규모·운영 목표 | 기재 |
| 읽은 코드·구성 범위 | 기재 |
| 수행한 테스트·실험 | 기재 |
| 확인하지 못한 범위·이유 | 기재 |
| 이전 리뷰와 비교 가능한 범위 | 기재 |
36.2 28개 관점 판정표
목표 통제와 확인 통제는 동일한 범위에서 비교한다. 구체적인 규칙이 여러 개면 관점 아래 세부 행을 추가한다.
| 번호 | 관점 | 적용 여부·사유 | 목표·확인 통제 | 증거 | 판정·잔여 위험 |
|---|---|---|---|---|---|
| 1 | 코드 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 2 | 구조적 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 3 | 변경 용이성 | 미평가 | 미평가 | 미확인 | 미검증 |
| 4 | 인지 부하 | 미평가 | 미평가 | 미확인 | 미검증 |
| 5 | 위험 가시성 | 미평가 | 미평가 | 미확인 | 미검증 |
| 6 | 실패 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 7 | 운영 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 8 | 디버깅 가능성 | 미평가 | 미평가 | 미확인 | 미검증 |
| 9 | 유지보수 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 10 | 테스트 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 11 | 데이터 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 12 | 동시성 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 13 | 확장성 | 미평가 | 미평가 | 미확인 | 미검증 |
| 14 | 성능 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 15 | 보안 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 16 | 의존성 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 17 | API / Contract 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 18 | 배포 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 19 | 설정 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 20 | 개발자 경험 | 미평가 | 미평가 | 미확인 | 미검증 |
| 21 | Guardrail 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 22 | 추상화 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 23 | 일관성 | 미평가 | 미평가 | 미확인 | 미검증 |
| 24 | 네이밍 / 의미 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 25 | 조직 확장성 | 미평가 | 미평가 | 미확인 | 미검증 |
| 26 | Ownership 성숙도 | 미평가 | 미평가 | 미확인 | 미검증 |
| 27 | 삭제 가능성 | 미평가 | 미평가 | 미확인 | 미검증 |
| 28 | 회복 가능성 | 미평가 | 미평가 | 미확인 | 미검증 |
36.3 발견 사항 양식
| 필드 | 작성할 내용 |
|---|---|
| ID·제목 | 다른 항목과 구분되는 ID와 구체적인 문제 |
| 성격 | 확인된 결함 / 구조적 위험 / 미검증 / 개선 제안 |
| 관련 관점 | 28개 관점 중 해당 번호 |
| 근거 | 현재 파일·심볼·설정, 필요한 코드 범위, 실행 결과 |
| 발생 조건 | 어떤 입력·순서·장애·배포·규모에서 문제가 되는가? |
| 영향 | 어떤 사용자·데이터·자원·소비자에 무엇이 발생하는가? |
| 심각도·우선순위 | 등급과 해당 판단의 이유 |
| 확실성과 남은 가정 | 직접 확인한 사실과 추론의 경계 |
| 최소 개선 방향 | 위험을 줄이는 가장 작은 변경과 비교할 대안 |
| 비용·부작용 | 추가 복잡성·운영 책임·호환성·이행 비용 |
| 완료 기준 | 구현자가 끝났는지 판단할 관찰 가능한 조건 |
| 검증 방법 | 그 위험을 직접 다루는 테스트·실험·정적 검사 |
| 담당·기한·상태 | 실제 조치 책임과 진행 상태 |
| 재검증 결과 | 변경 버전·실행 결과·잔여 위험 |
36.4 부정확한 리뷰와 실행 가능한 리뷰의 차이
다음은 작성 방식의 예시다. 실제 저장소에서 발견한 문제를 뜻하지 않는다.
| 부정확한 표현 | 실행 가능한 표현 |
|---|---|
| “추상화가 너무 많다.” | “목록 조회 경로에서 세 wrapper가 같은 입력을 그대로 전달한다. 각 wrapper가 보호하는 계약을 확인하고, 역할이 없는 단계를 제거한 뒤 오류·취소 동작이 유지되는지 검증한다.” |
| “분산 락을 도입하라.” | “지원하는 다중 인스턴스에서 같은 작업의 중복 실행을 막아야 한다. DB 조건부 갱신·제약·작업 소유권으로 해결 가능한지 비교하고 중단·재개까지 검증한다.” |
| “운영 준비가 안 됐다.” | “복구 절차 문서는 있으나 현재 버전과 데이터 규모로 실행한 증거가 없다. 복구 시간·손실·정합성 기준을 정하고 해당 환경에서 검증해야 한다.” |
| “캐시를 지우면 된다.” | “로그아웃 시 캐시 제거뿐 아니라 이전 세션의 진행 중 요청이 캐시를 다시 채우지 않는지 확인한다. 늦은 응답을 의도적으로 전달하는 시나리오로 검증한다.” |
| “아키텍처 90점이다.” | “공개 경계는 구현되어 있으나 상대 경로를 통한 우회 검출이 미확인이다. 대표 위반이 CI에서 차단되는지 확인해야 한다.” |
36.5 최종 리뷰 요약 양식
- 사용 결정: 어느 구성·용도에서 사용 가능·조건부 가능·보류인가?
- 확인된 강점: 어떤 위험을 실제로 막고 있으며 근거는 무엇인가?
- 차단 항목: 도입·배포·규모 확대 전에 무엇을 해결해야 하는가?
- 주요 구조적 위험: 어떤 조건에서 나타나며 어떻게 확인할 것인가?
- 미검증: 실행·자료·환경이 부족한 범위는 어디인가?
- 개선 순서: 먼저 고칠 이유, 최소 변경, 비용, 완료 기준은 무엇인가?
- 재검토 조건: 규모·버전·의존성·인증·배포 방식이 어떻게 바뀌면 다시 봐야 하는가?
37. 원문에서 보강·교정한 주요 내용
원문의 범위는 넓고 유용하다. 다음은 실제 리뷰에 적용할 때 오해를 줄이기 위해 바꾼 지점이다.
| 원문의 표현·구성 | 보강판의 처리 |
|---|---|
| 관점별 P0~P3 고정 분류 | 실제 피해·발생 조건·복제 범위·현재 목표를 기준으로 우선순위를 정한다. |
| 아키텍처 경계 부재를 Critical 예시에 포함 | 경계 위반이 어떤 피해로 이어지는지 확인한 뒤 심각도를 정한다. |
| “알림이 원인보다 증상만 알리는가?”라는 질문 | 증상 기반 알림을 정상적인 접근으로 인정하고 대응 가능성과 원인 조사 경로를 본다. [S2] |
| 문서화부터 운영 검증까지 하나의 성숙도 단계 | 통제 수준과 검증 환경을 분리한다. |
| 장애 주입·부하·복구 실험을 운영 검증에 묶음 | 실험에서 확인한 범위와 실제 운영 관찰을 별도로 기록한다. |
| 구현체 하나인 추상화를 과설계 신호로 제시 | 외부 경계·테스트·변경 격리의 가치와 학습 비용을 비교한다. [S1] |
| 파일 수·호출 깊이·5분 추적 등을 인지 부하 지표로 제시 | 보조 지표로 사용하고 실제 과제에서 숨은 규칙과 탐색 실패를 관찰한다. |
| 프레임워크 의존을 위험 신호로 제시 | 선언한 분리 목표와 실제 결합 비용을 기준으로 판단한다. |
| TypeScript 경로 관련 규칙을 guardrail 예시에 포함 | paths 설정과 실제 의존성 금지 검사를 구분한다. [S4] |
| 같은 검증의 다양한 이름을 일관성 문제로 제시 | null·blank·입력·도메인·인가의 의미를 먼저 구분한다. |
| 일반적인 오류 문구를 디버깅 위험 신호로 제시 | 외부의 안전한 안내와 내부 원인·연결 정보의 보존을 구분한다. |
| 테스트 계층 간 중복 검증을 피하도록 표현 | 같은 기능이어도 계층별 실패를 다루면 가치가 있음을 반영한다. |
| dual write를 포함한 마이그레이션 순서 예시 | 적용 조건·불일치·구버전 쓰기·백필 경쟁을 함께 평가한다. |
| feature 제거 시 migration 정리를 간단히 표현 | 이미 적용한 이력을 임의로 지우지 않고 안전한 제거 경로를 설계한다. |
| Backend·Frontend의 항목 목록 중심 | 실제 입력·경쟁·실패·배포 시나리오와 확인할 결과를 추가한다. |
| 템플릿 재사용의 장기 비용이 여러 관점에 분산 | 옵션 조합·기본값·샘플·소비자 업데이트·졸업 경로를 별도로 다룬다. |
| 점수·등급 중심으로 읽힐 가능성 | 적용 제외·미검증·목표 수준·증거 범위·차단 항목을 명시한다. |
38. 참고한 공식 자료와 사용 범위
확인일: 2026-09-25. 아래 자료는 각각의 원칙을 확인하는 근거다. 이 문서의 28개 분류, 평가표, 예시 시나리오 전체가 해당 기관의 공식 기준이라는 뜻은 아니다.
| 표기 | 자료 | 이 문서에서 참고한 내용 |
|---|---|---|
| S1 | Google Engineering Practices — What to look for in a code review | 설계·복잡성·불필요한 일반화·테스트의 유효성·명명·리뷰 범위 |
| S2 | Google SRE — Monitoring Distributed Systems | 증상과 원인 구분, 이해 가능하고 대응할 수 있는 알림 |
| S3 | AWS Well-Architected — Control and limit retry calls | 재시도 상한·간격·jitter, 중첩 재시도와 부작용 위험 |
| S4 | TypeScript — TSConfig paths | 경로 해석 설정의 역할과 출력 import 경로를 변경하지 않는다는 제한 |
| S5 | Kubernetes — Liveness, Readiness, and Startup Probes | 검사 목적의 구분과 잘못된 liveness가 만드는 연쇄 장애 |
| S6 | OWASP — Authorization Cheat Sheet | 최소 권한·기본 거부·요청별 권한 검증·클라이언트 검사 한계 |
| S7 | W3C — Web Content Accessibility Guidelines 2.2 | 키보드·포커스·오류 식별·상태 메시지 등 접근성 검토의 기준 |
| S8 | SLSA v1.2 — Provenance | 산출물의 출처와 생성 과정을 추적하는 검증 가능한 정보 |
| S9 | OWASP ASVS 5.0 — General Data Protection | 민감정보 전송·캐시·수집·보호 정책의 확인 |
| S10 | AWS Well-Architected — Make mutating operations idempotent | 작업 식별·중복 억제·상태 추적·원자성·보관 기간의 검토 |
리뷰에서 최종적으로 남겨야 할 것은 “고급 패턴을 많이 썼다”는 평가가 아니다. 어떤 규칙을 어디서 지키고, 무엇을 변경하면 어디까지 영향이 가며, 어떤 실패를 확인했고, 무엇이 아직 미검증인지를 다른 사람이 같은 근거로 판단할 수 있어야 한다.