프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 CLAUDE.md의 리뷰 기준만 읽고 시작했고, 개선 작업 기준은 main에 들어가지 않은 초안 (브랜치 docs/improvement-manual의 docs/improvement 11개)에만 있었다. 백엔드 docs/work/와 같은 모양으로 README(크기·공통 단계·커밋·보고), playbook 여섯(new-feature, improve, research-design, docs-writing, operate, delegate, 모두 같은 9절 뼈대), reference 일곱(gates, review-criteria, structure, testing, performance, defect-patterns, decisions)과 evidence.md를 둔다. 초안의 장을 나눠 옮긴 표는 evidence.md 1.1절이다. SPEC.md의 공통 완료 기준 9개는 improve.md 5절로 옮겨, 문서 체계 정리가 SPEC.md를 이력으로 옮길 수 있게 한다. 진입 문서에는 지난 리뷰 ID를 쓰지 않고 내용과 날짜로 쓴다. ID는 evidence.md와 결정·결함 패턴 색인에만 둔다. 결함 패턴 번호 P-NN은 결정 번호 꼴과 겹쳐 영역 글자+번호(G·T·C·S·W·B)로 다시 매기고 옛 번호 대응을 evidence.md 4절에 남겼다. 열린 결정 대기는 2026-11-06 리뷰 기준으로 갱신했다. 버린 대안: 초안처럼 docs/improvement/ 장 번호 체계를 유지하기. 백엔드와 진입 경로·검사기가 갈라진다. 위험·한계: 이 커밋만으로는 문서 검사 범위 밖이다. docs/README.md가 이 폴더를 링크하는 커밋부터 verify:documentation이 경로를 본다. cold-read 시험은 하지 않았다. 검증: python3 scripts/check-work-docs.py rc=0(뒤 커밋에서 더함). Refs: design-docs harness/01-harness-design.md 13절, PR #6
14 KiB
리뷰 기준
이 repo를 리뷰할 때(전체·모듈·PR·diff 리뷰 모두)의 기준이다. 일반 기준의 정본은 리뷰 가이드다: design-docs conventions/template-maturity-review-guide.md(이 문서의 「가이드 N절」). repo 안 docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md는 그 사본이고, 복사한 프로젝트가 docs/reviews/와 함께 지울 수 있다. 가이드를 지운 프로젝트도 이 문서만으로 판정할 수 있게 썼다. 절차는 ../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개 관점 번호로 분류한다. 결함 하나는 항목 하나로 적고 관련 관점 번호를 모두 붙인다. 같은 결함을 여러 번 세지 않는다.
- 성격, 심각도(Critical
Low), 우선순위(P0P3), 통제 수준(M0M4), 증거(E0E4)를 따로 적는다. 확인하지 못한 것은 M0가 아니라미확인이다. - 발견은 가이드 36.3절 양식, 최종 요약은 36.5절 양식, 관점별 판정은 36.2절 표를 쓴다.
- README와 설계 문서는 주장이다. 근거는 현재 커밋의 코드·설정·실행 결과에서 찾는다(가이드 34.1절). 이전 리뷰의 실행 결과를 현재 증거로 재사용하지 않는다.
- 리뷰에서는 코드를 고치지 않는다. 고치는 일은 리뷰 문서를 근거로 따로 한다.
- 심각도 체계는 가이드의 것(Critical
Low, 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 「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 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 |
| 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 「오케스트레이터 발견」 절에 둔다.
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. 판단을 적는 법
- 확인한 사실 / 기록된 의도 / 추론을 나눈다(가이드 41.3절). 다운스트림 파일을 열지 않고 이름으로 추정한 문장이 CHANGELOG에 틀린 이행 안내로 남은 일이 있다.
- 결정이 필요한 것은 선택지, 권하는 안, 결정할 사람을 적는다(decisions.md 3절 형식).
- 리뷰에 쓴 스킬과 그 스킬의 기준으로 무엇을 봤는지를 「범위」 절에 한 줄씩 적는다 [제안].
9. 총괄이 README에 쓰는 것
범위(가이드 36.1절), 28개 관점 판정표(36.2절), 최종 요약(36.5절), 발견 색인. High 이상 발견은 코드에서 직접 다시 확인한 뒤에 쓴다.
10. 커밋·CHANGELOG의 리뷰 ID
- 결함 수정 커밋은 꼬리말
Refs:에 라운드 접두어를 붙인 발견 ID를 적는다(Refs: <MMDD>/<NN>-<MM>꼴). 형식의 정본은 design-docsconventions/commit-and-pr.md3.4절과 가이드 36.3절이다. CHANGELOG.md의 리뷰 ID도MMDD/NN-MM꼴이어야 한다.tests/unit/changelog-review-ids.test.ts가 검사한다.- 호환을 깨는 변경은 type 뒤
!와BREAKING CHANGE:꼬리말을 단다. 본문은 문제 → 고른 방법과 버린 대안 → 위험·한계 → 검증 순서다.