docs(improvement): 이 repo의 결함 정의와 28개 관점 점검 위치를 적는다

문제: 가이드는 공용 일반론이라 이 repo에서 무엇을 결함으로 보고 어떤
등급을 줄지, 28개 관점마다 어디를 볼지 정해져 있지 않다. 라운드마다
같은 모양의 등급 조정을 다시 했다.

고른 방법: 이 repo가 스스로 한 약속(지원 범위, 현재 계약, 게이트,
생성 명령, 제거 가능성, 짝 계약)으로 결함을 정의하고, 지난 라운드의
등급 판정 예(게이트가 틀린 답을 내면 Medium·P1 등), 증거 규칙, 28개
관점별 볼 곳·검사·대표 발견, 지난 발견 재판정 방법, README·영역
문서 절 순서를 적는다. 심각도 체계는 가이드 35.2·35.3 하나만 쓴다.

위험·한계: 관점별 "볼 곳"은 지난 리뷰의 판정표에서 뽑은 것이라
빠진 곳이 있을 수 있다.

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
This commit is contained in:
DongHyeonka
2026-11-05 22:15:22 +09:00
parent 44961d7561
commit 01b4495214
+172
View File
@@ -0,0 +1,172 @@
# 02. 리뷰 기준
## 핵심
리뷰의 규칙은 `CLAUDE.md` 「리뷰 기준」(7~30줄)과 가이드가 정한다. 이 장은 그 규칙을 **이 repo의 경로·게이트·지난
결함으로 바꿔** 적는다. 무엇을 결함으로 보는지, 등급을 어떻게 매기는지, 28개 관점마다 어디를 보는지, 리뷰 문서를 어떤
모양으로 쓰는지.
```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. 결함으로 보는 것
결함은 **이 repo가 스스로 한 약속**을 어기는 것이다. 약속은 다음에 있다.
| 약속 | 어디에 |
| --- | --- |
| 지원 범위와 상태 값 | 루트 `README.md` 「Support scope」 |
| 현재 계약 | `docs/README.md` §1이 링크한 문서 |
| 게이트가 지키는 것 | `config/ci/gates.json`과 각 검사 스크립트 |
| 생성 명령으로 기능을 더하면 템플릿 파일을 고치지 않고 merge를 통과한다 | `docs/manual/README.md` 6줄, `docs/manual/reference/create-feature.md` |
| 지울 수 있다고 한 것은 지워도 게이트가 통과한다 | 루트 `README.md` 「Files you can delete after copying」, FE-GATE-020 |
| 짝 백엔드와 맞춘 계약 | `docs/architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1절, `config/contracts/backend-contract-pin.json` |
결함으로 보지 않는 것(`CLAUDE.md` 「이 repo의 리뷰 전제」, 가이드 0.1절 「지원·비지원」):
- 소비자 없는 코드와 빈 레지스트리(다운스트림용 확장 지점).
- 지원 범위 밖이라고 적힌 기능이 없는 것(예: SSR, bulk `results`). 없는 기능을 결함으로 세지 않는다.
- 서버 메모리 상태·다중 인스턴스 경쟁. 실행 형태가 브라우저 SPA라 적용하지 않는다. 탭 사이 경쟁은 본다.
- 인터페이스가 많다, kernel이 크다는 사실만으로(가이드 35.2절 끝 문단).
헷갈리는 경우:
| 경우 | 판정 | 예 |
| --- | --- | --- |
| 게이트가 코드와 무관하게 항상 실패하거나, 실패 이유를 숨긴다 | 결함. 사용자 피해가 없으면 Medium, merge·release를 막으면 P1 | 1103/02-06, 1105/12-01, 1105/13-01 |
| 게이트가 PASS인데 그 뒤 단계가 실패한다 | 결함(검사가 거짓 PASS를 낸다) | 1105/12-01, 1103/11-04 |
| 문서 문장이 코드와 다르다 | 결함. 코드가 맞다. 문장이 사용자를 틀린 행동으로 이끌면 등급을 올린다 | 1103/14-02(틀린 이행 안내) |
| 같은 사실을 여러 곳에 손으로 적었고 아직 같다 | 구조적 위험 | 1103 README 5절 원인 4 |
| 같은 사실의 손 사본이 이미 서로 다르다 | 확인된 결함 | 1105/01-02 |
| 수정이 템플릿 원래 상태에서만 맞다 | 결함. 지원 구성(기능 추가·예제 제거)에서 재현하면 확인된 결함 | 1105/09-01 |
## 2. 심각도와 우선순위 — 이 repo의 판정 예
가이드 35.2·35.3절을 지난 라운드가 이렇게 적용했다. 같은 모양이면 같은 등급을 준다. 등급을 영역 제안과 다르게
매기면 README 「심각도 조정」 표에 이유를 남긴다(1103 README 2.3절, 1105 README 2.4절).
| 등급 | 이 repo의 예 |
| --- | --- |
| High·P1 | 결과 불명 쓰기를 키 없이 다시 보내 같은 항목이 둘 생긴다(0929/03-03 상향, 가이드 35.2절 High 예시와 같은 모양). 짝 백엔드의 업무 거절이 모든 쓰기에서 결과 불명이 되어 폼이 막힌다(1103/03-01). 두 템플릿을 짝으로 쓰면 업로드가 연결되지 않는다(1103/01-01) |
| Medium·P1 | 사용자 피해 없이 merge·release 게이트가 틀린 답을 내거나 이유를 숨긴다(1103/02-06, 1103/12-01, 1103/15-01, 1105/09-01, 1105/12-01, 1105/13-01). "생성 명령으로 빠른 출시"라는 핵심 약속을 깨는 것도 여기다 |
| Medium·P2 | 위험한 경로가 남았지만 템플릿이 그리는 경로는 막고, 제품이 직접 hook을 부를 때만 닿는다(0929/03-03 남은 부분) |
| Low·P3 | 낡은 문장, 이름, 작은 진단 누락 |
- **P1의 기준:** 도입·출시·확대 전에 해결해야 하는 것(가이드 35.3절). 이 repo에서는 merge 게이트 14개를 막는 것과,
지원 구성에서 짝 백엔드와 쓰는 기본 경로를 막는 것이다.
- **복제 범위를 함께 적는다.** 다운스트림 둘(tech-log, memento)이 그대로 복제하는 기본값이면 그 사실을 적는다(가이드
35.2절 「다음 정보를 함께 적는다」).
## 3. 증거 규칙
- **현재 커밋에서 찾는다.** README와 설계 문서는 주장이다. 근거는 코드·설정·실행 결과다(`CLAUDE.md` 14줄, 가이드
34.1절). 지난 리뷰의 실행 결과를 현재 증거로 쓰지 않는다. 다른 세션이 같은 커밋에서 낸 결과도 가져다 쓰지 않고
다시 돌린다(1105 README 11.1절 끝 문단).
- **실행 증거에는 조건을 붙인다.** 커밋, 위치(desktop), env(workflow env인지), 부하, 반복 수. 부하가 높을 때의 실패는
따로 표시한다(1103 README 10.4절).
- **desktop에 workflow env를 준 실행은 실제 러너가 아니다.** 실제 Gitea 러너는 꺼져 있다. 그 사실을 미검증에 적는다
(1105 README 8절 첫 행). 이 실행의 증거 수준은 E2~E3이고, 「실제 CI 미검증」을 함께 적는다.
- **"오케스트레이터 확인"의 뜻을 지킨다.** 재확인 칸에 이 말을 쓰면 총괄이 그 줄을 직접 읽었거나 직접 실행했다는
뜻이다(1103 README 2절 머리말).
- **확인하지 못한 것은 「미확인」이다.** M0(통제 부재 확인)와 다르다(`CLAUDE.md` 12줄).
## 4. 28개 관점 — 이 repo에서 볼 곳
관점의 일반 설명은 가이드 1~28절이다. 아래는 이 repo에서 먼저 볼 곳과 그 관점을 지키는 검사, 지난 대표 발견이다.
「검사」 칸이 비어 있으면 그 관점을 기계로 지키는 게이트가 없다는 뜻이다.
| # | 관점 | 이 repo에서 볼 곳 | 검사 | 지난 대표 발견 |
| --- | --- | --- | --- | --- |
| 1 | 코드 성숙도 | 판정 규칙이 모인 곳: `src/adapters/http/backend-envelope.ts`, 효과 분류, 폼 상태 | FE-GATE-002·003 | 1103/03-01 |
| 2 | 구조적 성숙도 | `docs/architecture/layers.md`, `.dependency-cruiser.json`(03장) | `check:architecture`(FE-GATE-010) | 0929/12-03 |
| 3 | 변경 용이성 | 기능 하나를 더하거나 지울 때 템플릿 파일을 고쳐야 하는가 | FE-GATE-020 | 1103/12-01, 1105/09-01 |
| 4 | 인지 부하 | 기능 작성자가 알아야 할 등록 규약 수, `docs/manual/` 막힘 | | 1103 README 14.6절(매뉴얼만으로 기능 추가 재실험) |
| 5 | 위험 가시성 | 결과 불명·재전송·삭제 같은 위험이 코드와 화면에 드러나는가(가이드 29절) | | 1105/13-01, 1105/12-01 |
| 6 | 실패 성숙도 | 짝 백엔드 오류 응답의 분류, 결과 불명 처리 | FE-GATE-007 | 1105/01-01 |
| 7 | 운영 성숙도 | `docs/runbooks/`, `docs/operations/`, release job 로그 | FE-GATE-021~025 | 1105/13-01 |
| 8 | 디버깅 가능성 | 실패 메시지가 원인과 고칠 파일을 말하는가, `traceId` | | 1105/12-01 |
| 9 | 유지보수 성숙도 | 낡은 문장, CHANGELOG 미출시 절 | `verify:documentation` | 1103/14-01, 1105/14-01 |
| 10 | 테스트 성숙도 | 변이 검출, 템플릿 원래 상태 밖 입력(05장) | FE-GATE-005~009 | 1103/10-02, 1103/05-01 |
| 11 | 데이터 성숙도 | 로그아웃·계정 삭제 뒤 남는 데이터(IndexedDB, OPFS, Cache Storage) | | 1103/05-01 |
| 12 | 동시성 성숙도 | 탭 사이 경쟁, Web Locks, 같은 입력 재제출, 한 checkout 두 실행 | | 1103/05-01, 1105/12-04 |
| 13 | 확장성 | 기능 수 증가 축: 초기 JS 여유, 기능 모양 상한 | `check:scale:pr`(FE-GATE-005), FE-GATE-012 | 1105/15-02 |
| 14 | 성능 성숙도 | 06장 | FE-GATE-012·026 | 1103/15-01 |
| 15 | 보안 성숙도 | `docs/security/browser-boundary.md`, 저장 키, 401 전달, CSP | FE-GATE-013 | 1103/13-03 |
| 16 | 의존성 성숙도 | advisory, lockfile, 의존성 변경 증거 | FE-GATE-001·013 | 1103/13-03 |
| 17 | API / Contract 성숙도 | 짝 백엔드 계약 pin, 답 표, 생성기가 옮긴 사실 | FE-GATE-007, 짝 계약 대조 테스트(1103 결정 D6) | 1105/07-01, 1105/16-02 |
| 18 | 배포 성숙도 | `docs/architecture/static-delivery.md`, 호스팅 헤더, 배포 슬롯 | FE-GATE-019 | 1105/13-02 |
| 19 | 설정 성숙도 | 런타임 설정과 빌드 식별값, CI env | `verify:documentation`(runtime variables) | 1103/11-07, 1103/11-08 |
| 20 | 개발자 경험 | `create:feature`, 로컬 실행, 한 파일 테스트 실행 | | 1105/16-04 |
| 21 | Guardrail 성숙도 | 게이트가 맞는 답을 내는가, 사전 점검이 실제로 확인하는가 | `check:ci` | 1105/12-01, 1105/09-01 |
| 22 | 추상화 성숙도 | descriptor·포트가 실제 요청을 통제하는가 | | 1103/04-01 |
| 23 | 일관성 | 같은 판정을 하는 두 표가 같은가 | | 1105/01-02 |
| 24 | 네이밍 / 의미 성숙도 | 오류 code·상태 이름의 뜻 | | 1105/04-02 |
| 25 | 조직 확장성 | 기능 브랜치끼리 같은 줄 충돌, 다운스트림 동기화 비용 | | 1105/16-01 |
| 26 | Ownership 성숙도 | 규칙 `comment`의 담당·재검토 조건, 두 repo 사이 몫 | | 1105/13-02 |
| 27 | 삭제 가능성 | 참조 기능·recipe·선택 runtime 제거(03장 6절) | FE-GATE-020 | 1105/14-01 |
| 28 | 회복 가능성 | 회복 필요 응답 뒤 행동, SW 비상 경로, release rollback | FE-GATE-025 | 1105/02-02 |
## 5. 다시 판정할 때
다음 라운드 리뷰는 지난 발견 전부의 지금 상태를 표 하나로 적는다(1105 README 13절).
- 상태: 고침 / 일부 / 남음 / 결정 대기. 지난 「고침」도 코드로 다시 본다. 4라운드는 1103 조치의 「고침」 13건을
「일부」로 정정했다. 코드는 들어왔지만 완료 기준 실행이 없으면 「일부」다(가이드 35.6절, 1105 README 3.1절, 부록
P-27).
- 「일부」면 남은 부분에 새 등급을 매긴다. 남은 부분이 원래보다 좁으면 등급을 내린다(1105 README 2.3절 표).
- 지난 수정이 만든 새 결함은 새 발견으로 세고, 원인 수정 커밋을 적는다(1105 README 4절 끝 목록).
## 6. 리뷰 문서 형식
### 6.1 폴더와 ID
- 폴더: `docs/reviews/<YYYY-MM-DD>-maturity-review/`. README 하나와 영역 문서 `NN-<영역>.md`(`CLAUDE.md` 29줄).
- 발견 ID는 라운드 안에서 `NN-MM`(영역 번호-순번). 라운드 밖에서는 `MMDD/NN-MM`(가이드 36.3절).
- 총괄이 직접 찾은 발견은 관련 영역 번호를 쓰고 README 「오케스트레이터 발견」 절에 둔다(1105 README 14절).
### 6.2 README 절 순서
4라운드 README(1105)의 순서다. 가이드 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 지난 발견 상태 | 5절 |
| 14 오케스트레이터 발견 | 36.3절 양식 |
| 15 새 발견 색인 | 영역 문서에서 기계적으로 모은다. 손으로 옮기지 않는다 |
수정 라운드가 끝나면 같은 README에 「조치」 절을 더한다(01장 2절 산출물).
### 6.3 영역 문서 절 순서
1103·1105 영역 문서의 순서다(예: 1103 `11-tests-browser-release-scale.md`).
| 절 | 내용 |
| --- | --- |
| 0 결론 | 몇 줄 |
| 1 범위 | 36.1절. 읽은 경로, 돌린 것, 확인하지 못한 것 |
| 2 지난 발견 재판정 | 5절 |
| 3 이번 발견 | 36.3절 양식. 설계 선택이 없는 단순 결함은 선택 비교 칸을 「적용 제외」와 한 문장 이유로 |
| 4 28개 관점 판정 | 36.2절 |
| 5 설계 선택 설명 | 가이드 41절. 여러 타당한 선택지가 있는 발견만 |
| 6 실험·실행 기록 | 어디서 무엇을 돌렸나, 명령·결과 표, 미검증 목록 |
## 지금 이해하면 되는 것
- 결함은 이 repo가 스스로 한 약속(지원 범위, 현재 계약, 게이트, 생성 명령, 제거 가능성, 짝 계약)을 어기는 것이다.
- 게이트가 틀린 답을 내거나 이유를 숨기면 사용자 피해가 없어도 Medium·P1이다.
- 증거는 현재 커밋의 실행에서, 조건을 붙여서. 지난 「고침」도 다시 본다.