Files
clean-architecture-frontend…/docs/work/reference/review-criteria.md
T
DongHyeonka 18ea5e939b docs(work): cold-read 시험에서 막힌 곳과 사실과 다른 곳을 고친다
이 대화를 모르는 서브에이전트에게 AGENTS.md부터 읽혀 두 일(새 기능
만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가
나왔다. 고친 것:

- new-feature: 생성·기준선 다시 쓰기를 desktop에서 하고 --apply-back으로
  받는다. FE-GATE-020은 제품 기능을 지우지 않으므로 그 기능의 제거
  드릴을 따로 돌린다(사실과 달랐다). 생성 명령이 만드는 첫 context는
  중간이다. 새 기능은 FE-GATE-026도 돌린다. 매뉴얼 예시 이름이 오면
  묻는다. 초기 JS 기록의 파일을 적는다.
- gates·improve·AGENTS: FE-GATE-013 결정 대기 동안의 merge 판정 문구,
  PR·diff 리뷰도 merge 단계 전부를 돌린다, diff 리뷰의 base·head 규칙과
  ID 체계와 둘 곳, 라운드 세는 법, "빠른 게이트 8개"를 "검사 8개
  (package script)"로.
- review-criteria: 발견 한 개의 칸(가이드 36.3절 줄임)과 통제 M0~M4·
  증거 E0~E4의 뜻을 옮긴다. 가이드 없이 판정할 수 있다는 문장을 맞춘다.
- README·CLAUDE·decisions·rules/docs·skills: 최근 리뷰 README의 실제 절
  이름, 사고 순서 흔적의 여섯 칸과 design-docs 위치, 보고 칸과 말투의
  정본, `docs/work/README.md`를 가리키게, 리뷰 README 조치 절 예외,
  스킬의 새 명령 모양.

고치지 않은 것: 세션에 주입된 옛 CLAUDE.md(시험 세션이 이 브랜치 전에
시작했다).

검증: scripts/verify.sh docs rc=0, scripts/verify.sh hooks 통과.
2026-11-08 17:53:36 +09:00

180 lines
16 KiB
Markdown

# 리뷰 기준
이 repo를 리뷰할 때(전체·모듈·PR·diff 리뷰 모두)의 기준이다. 일반 기준의 정본은 리뷰 가이드다: design-docs `conventions/template-maturity-review-guide.md`(이 문서의 「가이드 N절」). repo 안 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`는 정본 위치만 적은 포인터다(절 번호는 정본과 같다). 가이드를 읽을 수 없는 프로젝트를 위해 발견 양식과 등급 정의를 7·8절에 줄여 옮겼다. 절차는 [../improve.md](../improve.md) 4.1절이다.
```text
발견 하나 = 항목 하나 (관련 관점 번호를 모두 붙인다, 가이드 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개 관점 번호로 분류한다. 결함 하나는 항목 하나로 적고 관련 관점 번호를 모두 붙인다. 같은 결함을 여러 번 세지 않는다.
- 성격, 심각도(Critical~Low), 우선순위(P0~P3), 통제 수준(M0~M4), 증거(E0~E4)를 따로 적는다. 확인하지 못한 것은 M0가 아니라 `미확인`이다.
- 발견은 가이드 36.3절 양식, 최종 요약은 36.5절 양식, 관점별 판정은 36.2절 표를 쓴다.
- README와 설계 문서는 주장이다. 근거는 현재 커밋의 코드·설정·실행 결과에서 찾는다(가이드 34.1절). 이전 리뷰의 실행 결과를 현재 증거로 재사용하지 않는다.
- 리뷰에서는 코드를 고치지 않는다. 고치는 일은 리뷰 문서를 근거로 따로 한다.
- 심각도 체계는 가이드의 것(Critical~Low, P0~P3) 하나만 쓴다. 소유자 지시의 "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` 「Support scope」 |
| 현재 계약 | `docs/README.md` 1절이 링크한 문서 |
| 게이트가 지키는 것 | `config/ci/gates.json`과 각 검사 스크립트 |
| 생성 명령으로 기능을 더하면 템플릿 파일을 고치지 않고 merge를 통과한다 | `docs/manual/README.md`, `docs/manual/reference/create-feature.md` |
| 지울 수 있다고 한 것은 지워도 게이트가 통과한다 | 루트 `README.md`의 지워도 되는 파일 표, FE-GATE-020 |
| 짝 백엔드와 맞춘 계약 | `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](../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](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](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](structure.md) 12절) | FE-GATE-020 |
| 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절), M0~M4 또는 `미확인`, E0~E4(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](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:` 꼬리말을 단다. 본문은 문제 → 고른 방법과 버린 대안 → 위험·한계 → 검증 순서다.