Files
clean-architecture-frontend…/docs/work/reference/review-criteria.md
T
DongHyeonka 8de1403b92 ci(gates): 선택 runtime 제거 드릴 셋을 main 단계의 FE-GATE-030으로 옮긴다
문제: runner PR 1회(merge job 셋, capacity 1이라 차례로)가 28.5분이다
(run 151). tests job의 FE-GATE-020이 13분 13초로 가장 크고, 그 안의
선택 runtime 제거 드릴 셋(optional recipe, browser file/storage,
realtime)이 약 7분이다. worker를 늘리지 않는 대책을 다 넣어도 25분
목표에 닿지 않는다.

고른 방법(소유자 결정 p, 2026-11-12): 그 드릴 셋을 새 게이트
FE-GATE-030 `optional-removability`로 떼어 main 단계(`main_gate`,
FE-GATE-029 다음)에서 돌린다. 샘플 제거와 scaffold 드릴은 merge의
FE-GATE-020에 남는다. 짝 백엔드가 무거운 lane을 nightly로 옮긴 것과
같은 모양이다.
- 계약: 정규 게이트 ID를 001..030으로, MAIN_READY를 029·030으로,
  main_gate job의 게이트를 029·030으로 바꾼다. 계약 보고서의 gateCount는
  29(016은 은퇴).
- scaffold 드릴의 제외 목록에서 셋을 뺀다. 이제 merge 명령이 아니라서,
  계약 검사가 「merge 밖 명령을 제외하면 숨긴다」고 거절했다.
- main job 이름을 `main / self-tests and removal drills`로 바꾼다.
- 시험: 020은 merge·merge_test에서 sample·scaffold만, 030은
  main·main_gate에서 셋을 돈다고 단언한다. 승격 공식 시험에 030을 더한다.
- 문서: 결정 색인(decisions.md 2.2), 구조·시험·리뷰 기준·CI 문서,
  fe-structure 스킬의 드릴 명령.

위험·한계: 선택 runtime을 바꾼 PR의 제거 회귀는 병합 뒤 main run에서
본다. main이 빨강이면 다음 PR이 고친다. 그런 PR은
`scripts/verify.sh gate FE-GATE-030`을 직접 돌려야 한다(structure.md
12절에 적음). 파생 프로젝트가 main job 이름을 필수 검사로 걸었으면
이름이 바뀐다.

검증(desktop): generate:ci-workflow, 생성 시험 스냅샷 갱신,
ci-workflow-generation·promotion-readiness·feature-scaffold-drill·
removal-drill-test-paths·example-feature-rules 등 483개 통과,
check:ci(29 gates) rc=0, check:ci:gating rc=0, verify:documentation
PASS_SCOPED, check:types·eslint rc=0. 로그 /tmp/claude-gates/w2fe2-o1b~g/.
2026-11-13 02:03:01 +09:00

16 KiB

리뷰 기준

이 repo를 리뷰할 때(전체·모듈·PR·diff 리뷰 모두)의 기준이다. 일반 기준의 정본은 리뷰 가이드다: design-docs conventions/template-maturity-review-guide.md(이 문서의 「가이드 N절」). repo 안 docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md는 정본 위치만 적은 포인터다(절 번호는 정본과 같다). 가이드를 읽을 수 없는 프로젝트를 위해 발견 양식과 등급 정의를 7·8절에 줄여 옮겼다. 절차는 ../improve.md 4.1절이다.

발견 하나 = 항목 하나 (관련 관점 번호를 모두 붙인다, 가이드 0.3절)
  ├─ 성격      확인된 결함 / 구조적 위험 / 미검증 / 개선 제안   (가이드 35.1절)
  ├─ 심각도    Critical / High / Medium / Low                 (35.2절)
  ├─ 우선순위  P0~P3                                          (35.3절)
  ├─ 통제      M0~M4, 확인 못 했으면 「미확인」(M0 아님)       (35.4절)
  └─ 증거      E0~E4                                          (35.5절)

1. 리뷰의 규칙

  • 발견은 가이드의 28개 관점 번호로 분류한다. 결함 하나는 항목 하나로 적고 관련 관점 번호를 모두 붙인다. 같은 결함을 여러 번 세지 않는다.
  • 성격, 심각도(CriticalLow), 우선순위(P0P3), 통제 수준(M0M4), 증거(E0E4)를 따로 적는다. 확인하지 못한 것은 M0가 아니라 미확인이다.
  • 발견은 가이드 36.3절 양식, 최종 요약은 36.5절 양식, 관점별 판정은 36.2절 표를 쓴다.
  • README와 설계 문서는 주장이다. 근거는 현재 커밋의 코드·설정·실행 결과에서 찾는다(가이드 34.1절). 이전 리뷰의 실행 결과를 현재 증거로 재사용하지 않는다.
  • 리뷰에서는 코드를 고치지 않는다. 고치는 일은 리뷰 문서를 근거로 따로 한다.
  • 심각도 체계는 가이드의 것(CriticalLow, P0P3) 하나만 쓴다. 소유자 지시의 "Minor"는 Low로 읽는다.

이 repo의 리뷰 전제(루트 AGENTS.md 첫 문단·꼭 지킬 것 1·2와 같다).

  • 이 repo는 템플릿(reference implementation)이다. 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이지 죽은 코드가 아니다. 갈라진 중복 복사본은 문제로 본다.
  • adapter 배럴(src/adapters/*/index.ts)이 공개 경계다.
  • adapter끼리 import할 수 있는 예외는 .dependency-cruiser.json의 kernel 예외(src/adapters/platform/ 폴더 전체, browser-file-storage/result.ts, cross-context-invalidation/index.ts)뿐이다. 새 파일 단위 예외를 제안하지 않는다.
  • 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. SSR은 없다.

2. 결함으로 보는 것

결함은 이 repo가 스스로 한 약속을 어기는 것이다.

약속 어디에
지원 범위와 상태 값 루트 README.md 「기능 켜고 끄기」의 「지원 범위」
현재 계약 docs/README.md 1절 지도의 「현재 계약」·「운영」 폴더
게이트가 지키는 것 config/ci/gates.json과 각 검사 스크립트
생성 명령으로 기능을 더하면 템플릿 파일을 고치지 않고 merge를 통과한다 docs/manual/README.md, docs/manual/reference/create-feature.md
지울 수 있다고 한 것은 지워도 게이트가 통과한다 루트 README.md의 지워도 되는 파일 표, FE-GATE-020, FE-GATE-030
짝 백엔드와 맞춘 계약 docs/architecture/backend-api-and-server-state-contract.md 4.1·6·6.1절, config/contracts/backend-contract-pin.json

결함으로 보지 않는 것: 소비자 없는 코드와 빈 레지스트리, 지원 범위 밖이라고 적힌 기능이 없는 것(예: SSR, bulk results), 서버 메모리 상태·다중 인스턴스 경쟁(탭 사이 경쟁은 본다), 인터페이스가 많다·kernel이 크다는 사실만으로(가이드 35.2절 끝 문단).

헷갈리는 경우:

경우 판정
게이트가 코드와 무관하게 항상 실패하거나, 실패 이유를 숨긴다 결함. 사용자 피해가 없으면 Medium, merge·release를 막으면 P1
게이트가 PASS인데 그 뒤 단계가 실패한다 결함(검사가 거짓 PASS를 낸다)
문서 문장이 코드와 다르다 결함. 코드가 맞다. 문장이 사용자를 틀린 행동으로 이끌면 등급을 올린다
같은 사실을 여러 곳에 손으로 적었고 아직 같다 구조적 위험
같은 사실의 손 사본이 이미 서로 다르다 확인된 결함
수정이 템플릿 원래 상태에서만 맞다 결함. 지원 구성(기능 추가·확장 지점 채움)에서 재현하면 확인된 결함

3. 심각도와 우선순위 — 이 repo의 판정 예

같은 모양이면 같은 등급을 준다. 등급을 영역 제안과 다르게 매기면 README 「심각도 조정」 표에 이유를 남긴다.

등급 이 repo의 예
High·P1 결과 불명 쓰기를 키 없이 다시 보내 같은 항목이 둘 생긴다(가이드 35.2절 High 예시와 같은 모양). 짝 백엔드의 업무 거절이 모든 쓰기에서 결과 불명이 되어 폼이 막힌다. 두 템플릿을 짝으로 쓰면 업로드가 연결되지 않는다
Medium·P1 사용자 피해 없이 merge·release 게이트가 틀린 답을 내거나 이유를 숨긴다. "생성 명령으로 빠른 출시"라는 핵심 약속을 깨는 것도 여기다
Medium·P2 위험한 경로가 남았지만 템플릿이 그리는 경로는 막고, 제품이 직접 hook을 부를 때만 닿는다
Low·P3 낡은 문장, 이름, 작은 진단 누락
  • P1의 기준: 도입·출시·확대 전에 해결해야 하는 것(가이드 35.3절). 이 repo에서는 merge 단계 게이트를 막는 것과, 지원 구성에서 짝 백엔드와 쓰는 기본 경로를 막는 것이다.
  • 복제 범위를 함께 적는다. 다운스트림이 그대로 복제하는 기본값이면 그 사실을 적는다.

4. 증거 규칙

  • 현재 커밋에서 찾는다. 다른 세션이 같은 커밋에서 낸 결과도 가져다 쓰지 않고 다시 돌린다.
  • 실행 증거에는 조건을 붙인다. 커밋, 위치(desktop), env(CI env인지), 부하, 반복 수. 부하가 높을 때의 실패는 따로 표시한다.
  • desktop에 CI env를 준 실행은 실제 러너가 아니다. 실제 Gitea 러너는 꺼져 있다. 이 실행의 증거 수준은 E2~E3이고, 「실제 CI 미검증」을 함께 적는다.
  • "오케스트레이터 확인"의 뜻을 지킨다. 재확인 칸에 이 말을 쓰면 총괄이 그 줄을 직접 읽었거나 직접 실행했다는 뜻이다.
  • 확인하지 못한 것은 「미확인」이다. M0(통제 부재 확인)와 다르다.
  • 서브에이전트의 리뷰 결과는 코드를 실행하지 않았으면 E1이다. High 이상은 총괄이 다시 확인한다.

5. 28개 관점 — 이 repo에서 볼 곳

관점의 일반 설명은 가이드 1~28절이다. 「검사」 칸이 비어 있으면 그 관점을 기계로 지키는 게이트가 없다는 뜻이다. 관점마다 지난 대표 발견은 ../evidence.md 3절이다.

# 관점 이 repo에서 볼 곳 검사
1 코드 성숙도 판정 규칙이 모인 곳: src/adapters/http/backend-envelope.ts, 효과 분류, 폼 상태 FE-GATE-002·003
2 구조적 성숙도 docs/architecture/layers.md, .dependency-cruiser.json check:architecture(FE-GATE-010)
3 변경 용이성 기능 하나를 더하거나 지울 때 템플릿 파일을 고쳐야 하는가 FE-GATE-020
4 인지 부하 기능 작성자가 알아야 할 등록 규약 수, docs/manual/ 막힘
5 위험 가시성 결과 불명·재전송·삭제 같은 위험이 코드와 화면에 드러나는가(가이드 29절)
6 실패 성숙도 짝 백엔드 오류 응답의 분류, 결과 불명 처리 FE-GATE-007
7 운영 성숙도 docs/runbooks/, docs/operations/, release job 로그 FE-GATE-021~025
8 디버깅 가능성 실패 메시지가 원인과 고칠 파일을 말하는가, traceId
9 유지보수 성숙도 낡은 문장, CHANGELOG 미출시 절 verify:documentation
10 테스트 성숙도 변이 검출, 템플릿 원래 상태 밖 입력(testing.md) FE-GATE-005~009
11 데이터 성숙도 로그아웃·계정 삭제 뒤 남는 데이터(IndexedDB, OPFS, Cache Storage)
12 동시성 성숙도 탭 사이 경쟁, Web Locks, 같은 입력 재제출, 한 checkout 두 실행
13 확장성 기능 수 증가 축: 초기 JS 여유, 기능 모양 상한 FE-GATE-005, FE-GATE-012
14 성능 성숙도 performance.md FE-GATE-012·026
15 보안 성숙도 docs/security/browser-boundary.md, 저장 키, 401 전달, CSP FE-GATE-013
16 의존성 성숙도 advisory, lockfile, 의존성 변경 증거 FE-GATE-001·013
17 API / Contract 성숙도 짝 백엔드 계약 pin, 답 표, 생성기가 옮긴 사실 FE-GATE-007, 짝 계약 대조 테스트
18 배포 성숙도 docs/architecture/static-delivery.md, 호스팅 헤더, 배포 슬롯 FE-GATE-019
19 설정 성숙도 런타임 설정과 빌드 식별값, CI env verify:documentation(runtime variables)
20 개발자 경험 create:feature, 로컬 실행, 한 파일 테스트 실행
21 Guardrail 성숙도 게이트가 맞는 답을 내는가, 사전 점검이 실제로 확인하는가 check:ci
22 추상화 성숙도 descriptor·포트가 실제 요청을 통제하는가
23 일관성 같은 판정을 하는 두 표가 같은가
24 네이밍 / 의미 성숙도 오류 code·상태 이름의 뜻
25 조직 확장성 기능 브랜치끼리 같은 줄 충돌, 다운스트림 동기화 비용
26 Ownership 성숙도 규칙 comment의 담당·재검토 조건, 두 repo 사이 몫
27 삭제 가능성 기능·recipe·선택 runtime 제거(structure.md 12절) FE-GATE-020, FE-GATE-030
28 회복 가능성 회복 필요 응답 뒤 행동, SW 비상 경로, release rollback FE-GATE-025

6. 다시 판정할 때

다음 라운드 리뷰는 지난 발견 전부의 지금 상태를 표 하나로 적는다.

  • 상태: 고침 / 일부 / 남음 / 결정 대기. 지난 「고침」도 코드로 다시 본다. 코드는 들어왔지만 완료 기준 실행이 없으면 「일부」다(가이드 35.6절, 결함 패턴 G14).
  • 「일부」면 남은 부분에 새 등급을 매긴다. 남은 부분이 원래보다 좁으면 등급을 내린다.
  • 지난 수정이 만든 새 결함은 새 발견으로 세고, 원인 수정 커밋을 적는다.

7. 리뷰 문서 형식

폴더와 ID. 폴더는 docs/reviews/<YYYY-MM-DD>-maturity-review/, README 하나와 영역 문서 NN-<영역>.md. 발견 ID는 라운드 안에서 NN-MM(영역 번호-순번), 라운드 밖에서는 MMDD/NN-MM(가이드 36.3절). 총괄이 직접 찾은 발견은 관련 영역 번호를 쓰고 README 「오케스트레이터 발견」 절에 둔다. diff 리뷰도 같은 체계를 쓴다(바뀐 파일의 영역 번호).

발견 하나의 칸(가이드 36.3절을 줄인 것). 설계 선택이 없는 단순 결함은 「결정의 근거」「대안 비교」「단순화의 보존 조건」「재검토 조건」을 적용 제외 — 이유 한 문장으로 둔다.

칸 적을 것
ID·제목 NN-MM과 구체적인 문제
성격, 관련 관점 2절의 넷 중 하나, 28개 관점 번호 전부
근거, 발생 조건, 영향 파일·심볼·설정·실행 결과(file:line), 어떤 입력·순서·장애·규모에서, 누구에게 무엇이
심각도·우선순위, 통제, 증거 등급과 이유(3절), M0M4 또는 미확인, E0E4(8절)
확실성과 남은 가정, 결정의 근거 확인한 사실과 추론의 경계, 설계 선택이면 지금 제약과 선택 이유
최소 개선 방향, 대안 비교, 비용·부작용 위험을 줄이는 가장 작은 변경, 여러 선택지면 비교
완료 기준, 검증 방법 끝났는지 볼 관찰 가능한 조건, 그 위험을 직접 다루는 테스트·실험
상태, 재검증 결과 열림·고침·일부·결정 대기, 변경 버전과 결과

README 절 순서. 가이드 36.5절 요약 일곱 항목과 36.1·36.2절을 담는다.

절 내용
머리말 기준 가이드, 대상 커밋, 영역 수, 실행 위치, 리뷰 중 코드를 고치지 않았다는 사실
0 평가 전제 가이드 0.1절 표
1 사용 결정 용도별 사용 가능·조건부·보류와 막는 항목(36.5-1)
2 차단 항목 새 High, 새 P1(재확인 칸 포함), 이월 항목 중 남은 큰 것, 심각도 조정과 합침
3 물은 것에 대한 답 리뷰를 맡긴 쪽이 따로 물은 것
4 새 발견 건수 지난 라운드와 심각도·우선순위·성격별 비교
5~10 확인된 강점, 반복되는 원인, 결정이 필요한 것, 미검증, 개선 순서, 재검토 조건(36.5-2~7)
11 리뷰 범위 36.1절 표, 게이트 실행 결과, 영역 분할, 합친 중복, 실행 방식과 안전 사항, 총괄 자신의 실수
12 28개 관점 판정 36.2절 표. 종합은 평균하지 않는다. 한 영역이라도 미충족이면 미충족(35.7절)
13 지난 발견 상태 6절
14 오케스트레이터 발견 36.3절 양식
15 새 발견 색인 영역 문서에서 기계적으로 모은다. 손으로 옮기지 않는다

수정 라운드가 끝나면 같은 README에 「조치」 절(방법, 결정, 통합에서 생긴 것, 발견별 상태, 확인, 남은 문제)을 더한다.

영역 문서 절 순서. 0 결론(몇 줄) · 1 범위(36.1절, 읽은 경로, 돌린 것, 확인하지 못한 것) · 2 지난 발견 재판정(6절) · 3 이번 발견(36.3절 양식. 설계 선택이 없는 단순 결함은 선택 비교 칸을 「적용 제외」와 한 문장 이유로) · 4 28개 관점 판정(36.2절) · 5 설계 선택 설명(가이드 41절, 여러 타당한 선택지가 있는 발견만) · 6 실험·실행 기록.

8. 통제와 증거의 뜻

  • 통제(가이드 35.4절, 선정한 규칙 하나에 매긴다): M0 지킬 수단이 없음을 확인함 · M1 규칙이 적혀 있음 · M2 필요한 코드 경로에 구현됨 · M3 자동 검사가 위반을 잡음 · M4 타입·공개 범위·권한 같은 경계가 위반을 막음. 읽지 못했으면 M0가 아니라 미확인이다.
  • 증거(가이드 35.5절): E0 문서·주장 · E1 코드·설정을 읽어 확인 · E2 명시한 테스트가 그 버전에서 통과 · E3 실제 의존성·부하·장애 조건의 통합·실험 · E4 실제 운영 관찰. 높은 번호 하나가 낮은 번호의 다른 검증을 대신하지 않는다.

9. 판단을 적는 법

  • 확인한 사실 / 기록된 의도 / 추론을 나눈다(가이드 41.3절). 다운스트림 파일을 열지 않고 이름으로 추정한 문장이 CHANGELOG에 틀린 이행 안내로 남은 일이 있다.
  • 결정이 필요한 것은 선택지, 권하는 안, 결정할 사람을 적는다(decisions.md 3절 형식).
  • 리뷰에 쓴 스킬과 그 스킬의 기준으로 무엇을 봤는지를 「범위」 절에 한 줄씩 적는다 [제안].

10. 총괄이 README에 쓰는 것

범위(가이드 36.1절), 28개 관점 판정표(36.2절), 최종 요약(36.5절), 발견 색인. High 이상 발견은 코드에서 직접 다시 확인한 뒤에 쓴다.

11. 커밋·CHANGELOG의 리뷰 ID

  • 결함 수정 커밋은 꼬리말 Refs:에 라운드 접두어를 붙인 발견 ID를 적는다(Refs: <MMDD>/<NN>-<MM> 꼴). 형식의 정본은 design-docs conventions/commit-and-pr.md 3.4절과 가이드 36.3절이다.
  • CHANGELOG.md의 리뷰 ID도 MMDD/NN-MM 꼴이어야 한다. tests/unit/changelog-review-ids.test.ts가 검사한다.
  • 호환을 깨는 변경은 type 뒤 !와 BREAKING CHANGE: 꼬리말을 단다. 본문은 문제 → 고른 방법과 버린 대안 → 위험·한계 → 검증 순서다.