Files
DongHyeonka 50d623c40e
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Canceled after 0s
frontend-quality-gates / merge / static checks (pull_request) Canceled after 0s
frontend-quality-gates / merge / tests (pull_request) Canceled after 0s
frontend-quality-gates / merge / browser tests (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Canceled after 0s
frontend-quality-gates / external-vulnerability-provider (pull_request) Canceled after 0s
frontend-quality-gates / external-provenance-provider (pull_request) Canceled after 0s
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Canceled after 0s
frontend-quality-gates / deploy-promoted-release (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / self-tests and removal drills (pull_request) Canceled after 0s
Merge remote-tracking branch 'origin/main' into fix/r9-living-docs-sync
# Conflicts:
#	AGENTS.md
#	docs/work/reference/decisions.md
2026-11-13 04:30:07 +09:00

17 KiB

개선 — 리뷰, 결함 수정, 리팩터링, 성능, 구조, 테스트 구조

이미 있는 코드를 평가하거나 고치는 일의 절차다. 핵심은 하나다: 리뷰 → 수정 → 다음 라운드 리뷰를 새 High 0·새 P1 0·merge 게이트 전부 통과까지 돌고, 그 라운드의 Medium·Low를 고친 뒤 멈춘다(4.5절).

1. 언제 쓰나

지금 상태 작업
무엇이 틀렸는지 아직 모른다 리뷰
계약(지원 범위, 현재 계약 문서, 게이트, 생성 명령, 짝 계약)과 다른 동작이 확인됐다 결함 수정
동작은 맞는데 구조 비용이 크다 리팩터링
같은 조건에서 두 번 이상 잰 숫자가 예산을 넘거나 회귀했다 성능 최적화
최상위 src/ 폴더, adapter 그룹, 기능·context 경계, import 규칙이 바뀐다 구조 변경
테스트가 주장을 증명하지 못하거나 가끔 떨어진다 테스트 구조 개선

2. 받아야 할 것

  • 리뷰: 범위(전체 / 영역 / PR / 커밋 범위 <base>..<head>), 기준 커밋.
  • 수정: 고칠 발견 목록(ID, 위치)과 리뷰 문서 경로. 발견 ID 없이 고치지 않는다. 그 고침이 무엇을 막는지 아무도 모르게 된다.
  • 공통: 브랜치, 커밋 허용 여부, 돌릴 게이트. 그 발견에 필요한 소유자 결정이 reference/decisions.md에도 brief에도 없으면 그 발견만 멈추고 묻는다.

3. 크기와 사고 순서

  • 보통 중간이다: 영역 리뷰 하나, 수정 묶음 하나. 큼: 전체 리뷰, 구조 변경, 공개 포트·계약을 바꾸는 수정. 큰 일은 설계와 대안을 먼저 적는다(리뷰 가이드 41절의 일곱 질문).
  • 선행 사례는 둘이다: 같은 원인이 남은 다른 자리, 그리고 reference/defect-patterns.md의 같은 모양. 리뷰 전에 그 표를 훑는다.
  • 스킬은 소유자 규칙이다(리뷰·수정에 스킬을 쓴다). 불렀다는 사실보다 그 스킬의 기준으로 무엇을 봤는지가 증거다.
작업 절차 스킬 영역 스킬(바뀌는 경계에 맞춰)
리뷰 superpowers:requesting-code-review clean-architecture, codebase-design, security-and-hardening, performance-optimization, playwright-best-practices, frontend-ui-engineering, doubt-driven-development
리뷰 결과를 받아 고칠 때 superpowers:receiving-code-review —
결함 수정 superpowers:systematic-debugging → superpowers:test-driven-development 바뀌는 경계의 영역 스킬
리팩터링 refactor, codebase-design vercel-composition-patterns
성능 performance-optimization vercel-react-best-practices, 에이전트 web-performance-auditor
구조 변경 superpowers:brainstorming → superpowers:writing-plans clean-architecture
테스트 구조 superpowers:test-driven-development playwright-best-practices

4. 절차

4.1 리뷰

  1. 범위를 고정한다: 기준 커밋, 브랜치, 확인 시점, 노트북 worktree와 desktop이 깨끗한지. 전체 리뷰면 리뷰 가이드 0.1절 전제 표를 채운다. 이 repo의 고정 전제는 루트 AGENTS.md 첫 문단과 꼭 지킬 것 1·2다. 요청량·데이터량 목표가 없으니 그 칸은 "기능 수 증가 축과 번들·lab 예산으로 판정"으로 적는다.
  2. 게이트를 한 번 돌린다: VERIFY_SNAPSHOT=1 scripts/verify.sh merge와 scripts/verify.sh documentation. 손으로 적은 명령 목록을 돌리지 않는다(merge 게이트 일부가 빠진 사건이 있다).
  3. 결과를 함께 읽는다. desktop 로그 폴더(/tmp/claude-gates/<로그 이름>/)의 게이트 로그와 snapshot/(artifacts·dist·test-results 사본)을 모든 리뷰어가 읽는다. 리뷰어마다 다시 돌리지 않는다(delegate.md 4.2절).
  4. 영역을 나눈다. 가장 최근 docs/reviews/*-maturity-review/README.md의 영역 표를 다시 쓴다. 영역마다 서브에이전트 하나(결과만 받음) 또는 하위 세션 하나(문서를 커밋함).
  5. 영역 문서는 「지난 발견 재판정」부터 쓴다. 지난 라운드가 "고침"이라 한 것도 코드로 다시 본다. 코드는 들어왔지만 완료 기준 실행이 없으면 "일부"다.
  6. 더 필요한 실험은 목록으로 낸다(ID, 명령, env, 시간 상한, 변이 패치). 총괄이 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로 돌린다.
  7. 발견을 reference/review-criteria.md 양식으로 적는다. 같은 결함을 두 영역이 적으면 색인에서 하나로 합치고 「합친 중복」 표에 남긴다.
  8. 총괄이 High 이상과 새 P1을 코드에서 직접 다시 읽거나 실행해 확인하고, 재확인 칸에 그 사실을 적는다.
  9. README에 범위, 28개 관점 판정표, 최종 요약, 발견 색인을 쓴다(양식 review-criteria.md 7절). 총괄 자신의 실수도 적는다.
  • PR·diff 리뷰는 바뀐 파일의 영역만 읽는다. 게이트는 2단계대로 한 번 돌린다(멈춤 판정에 merge 단계 전부가 필요하다). 범위의 base는 직전 리뷰(diff 리뷰 포함)가 본 범위의 끝 커밋, head는 맡긴 쪽이 정한 커밋(없으면 fetch한 origin/main)이고 둘을 머리말에 적는다. 판정 체계·양식·ID 체계(NN-MM)는 같고, 수정 라운드의 diff 리뷰는 그 라운드 README 「조치」 절 아래 절로 적는다.
  • 리뷰 중에 코드를 고치지 않는다. 의심 결함은 별도 worktree의 임시 테스트로 확인하고 그 코드는 리뷰 문서나 공유 노트에만 남긴다. 리뷰 문서는 리뷰 시점 기록이다. 고친 뒤에도 영역 문서를 고치지 않고, 처리 결과는 같은 README의 「조치」 절에 적는다.

4.2 결함 수정

  1. 원인 경로를 확인한다. 증상이 아니라 원인을 적는다. 발견의 「완료 기준」 칸을 읽는다. 완료 기준의 기준은 그 칸이다.
  2. RED: 재현 테스트를 먼저 쓰고 수정 전 코드에서 실패하는 것을 실행으로 본다. 브라우저 없이 재현할 수 없으면 fake·fixture로 조건을 만든다. 리뷰가 Playwright 검증을 요구하면 spec 하나를 더한다.
    • RED가 없는 수정: 문서를 동작에 맞추면 문서의 주장을 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 테스트로 옮길 수 없으면 "RED 없음 — 이유"와 대신한 증거를 적는다.
  3. 검출력이 문제였던 발견(변이 생존)은 리뷰에 적힌 변이를 다시 넣어 새 테스트가 실패하는지 본다(reference/testing.md 3절).
  4. GREEN: 가장 작은 수정으로 통과를 본다. 공개 포트는 추가만 한다. 공용 로직은 src/adapters/platform/이나 src/contracts/에 둔다.
  5. 같은 원인의 다른 자리를 찾는다. 결과 불명 쓰기의 재전송 입구처럼 하나를 막으면 다른 입구에서 다시 나온다(reference/structure.md 6절).
  6. 템플릿 원래 상태 밖에서도 돌린다: 기능을 더한 상태(create:feature), 제품 확장 지점을 채운 상태, 입력·객체가 셋 이상. 원래 상태로만 확인한 수정이 다음 라운드에 다시 결함이 됐다.
  7. 수정이 새로 가정하는 것을 커밋 본문 「위험·한계」에 적는다(8절 「새로 가정하는 것」).
  8. 그 동작을 설명하는 문서를 같은 변경에서 고친다. adapter 파일을 더하거나 옮기면 docs/reviews/adapters/INVENTORY.md를 같은 커밋에서 고친다. 다운스트림에 보이는 변경은 CHANGELOG.md 미출시 절에 적는다.
  9. 커밋 전 게이트를 돌린다(reference/gates.md 2절).

4.3 리팩터링, 성능, 구조, 테스트 구조

  • 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 먼저 적는다(리뷰 가이드 36.3·39.9절). 기존 테스트가 그 조건을 지키는지 보고, 못 지키면 테스트부터 더한다. 바꾼 뒤 같은 테스트가 그대로 통과해야 한다. 테스트를 고쳐야 통과하면 동작이 바뀐 것이다. 소비자 없는 확장 지점은 지우지 않고, 갈라진 복사본은 하나로 합친다.
  • 성능: reference/performance.md의 조건으로 기준선을 다시 잰다 → 원인을 좁힌다(waterfall·청크 목록·trace) → 변경 하나 → 대조군(바꾸기 전 커밋)과 같은 세션에서 다시 잰다. 지난 측정값을 기준선으로 쓰지 않는다.
  • 구조 변경: 설계와 대안을 먼저 적고, reference/structure.md 3절 「바꿀 때 같이 고칠 것」을 같은 커밋에서 고친 뒤 제거 드릴(FE-GATE-020)을 돌린다.
  • 테스트 구조: reference/testing.md. 가끔 떨어지는 테스트는 재시도·timeout으로 덮지 않고 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로 원인을 찾는다.

4.4 수정 라운드와 묶음

  • 통합 브랜치 fix/maturity-review-<YYYY-MM-DD>(리뷰 날짜)를 만들고, 영역별 수정은 각자 worktree의 브랜치에서 한다. 다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다. CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다.
  • 총괄이 브랜치를 --no-ff로 하나씩 합치고, 합칠 때마다 커밋 전 게이트를 돌린다. 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 적는다. 합친 트리에서 merge 단계를 돌리고 회차별 결과를 표로 남긴다. 통합에서 커밋을 다시 지었으면(fixup 접기, rebase) 커밋 본문과 CHANGELOG가 적은 해시를 git merge-base --is-ancestor <해시> <브랜치 끝>으로 하나씩 대조하고, 결과를 PR 본문 「검증」에 적는다. 리뷰 라운드가 아닌 정리·기능 통합도 같다.
  • 큰 라운드는 작은 PR로 나눈다. 자기완결적인 변경 하나에 PR 하나(대략 100줄, 1,000줄이면 너무 크다). 리팩터링과 동작 변경은 PR을 나눈다. 병합은 소유자가 한다. 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다(발견 수가 줄어드는지 볼 수 없다).

4.5 멈춤 기준 — 이 repo는 하나다

아래 셋을 모두 채운 라운드에서 멈춘다(소유자 결정 2026-11-04).

  1. 그 라운드의 새 High 0.
  2. 그 라운드의 새 P1 0.
  3. merge 단계 게이트 전부 통과(reference/gates.md 3절 방법). FE-GATE-013은 시스템 컨테이너 안에서 돌아 같이 센다. 컨테이너를 띄울 수 없는 호스트에서만 같은 절의 두 조건으로 빼고 그 문구로 보고한다.
  • 채워도 바로 끝내지 않는다. 그 라운드의 Medium·Low를 고치고 멈춘다. 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 남긴다(형식 reference/decisions.md 3절). 이유 없는 이월("나중에", "범위 밖")은 남기지 않는다.
  • 마지막 Medium·Low 수정은 다음 리뷰를 받지 않는다. 그래서 그 수정도 4.2절 6단계와 merge 판정을 그대로 거친다. 짝 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 두 기준을 맞추지 않는다(소유자 결정 2026-11-05 「각자 유지」).
  • 2026-11-03 리뷰의 수정 라운드 뒤로 세 라운드를 더 돌아도 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게 보고한다. 라운드는 전체 리뷰 한 번이다(diff 리뷰는 세지 않는다). 2026-11-05·06 리뷰가 그 첫째·둘째다.
  • 수정 결과의 "고침"은 확정이 아니다. 다음 리뷰가 ID별로 다시 판정한다. 보고에도 "다음 리뷰에서 재판정"이라고 적는다.

5. 완료 기준

  • 리뷰: 모든 발견이 양식이고 성격·심각도·우선순위·통제·증거가 따로 있다. 지난 발견 전부의 지금 상태가 표 하나에 있다. 미검증 목록과 확인 방법, 결정이 필요한 항목마다 선택지와 결정할 사람이 있다.
  • 결함 수정(모든 발견에 공통):
    1. 동작을 바꾸면 RED → GREEN이 실행으로 있다. 없으면 "RED 없음 — 이유"와 대신한 증거가 있다.
    2. 검출력이 문제였던 발견은 변이를 다시 넣어 새 테스트가 실패한다.
    3. 커밋 전 검사(package script)가 통과한다: check:architecture, check:types, lint, test:unit, test:component, test:integration, test:contract, test:runtime-schema.
    4. 묶음 끝과 통합 때는 더해서 check:ci, check:adapter-inventory, verify:documentation, test:sample-removal, build가 통과한다.
    5. adapter 파일을 더하거나 옮겼으면 INVENTORY를 같은 커밋에서 고쳤다.
    6. 공용 로직은 kernel이나 src/contracts/에 있고 새 파일 단위 예외가 없다.
    7. 공개 포트는 추가만 했다. 깼으면 결정 표와 BREAKING 커밋이 있다.
    8. 논리 변경 하나에 커밋 하나, 메시지에 발견 ID, 바꾼 파일만 stage했다.
    9. 문서 요구는 문서의 각 주장이 코드 위치를 가리키는 것으로 확인했다.
    • 발견별 상태가 「고침 / 일부 / 결정 대기」 중 하나이고, 리뷰 가이드 35.6절의 다섯 연결(원래 위험, 바꾼 코드, 그 위험을 잡는 검증, 검증한 버전·환경·결과, 남은 제한)이 있다.
  • 리팩터링: 테스트 변경 없이 커밋 전 검사가 통과한다. 줄어든 이해 비용을 한 문장으로 말할 수 있다.
  • 성능: check:bundle(FE-GATE-012)과 test:performance(FE-GATE-026)가 통과하고, 전후 차이가 측정 잡음보다 크다(잡음 크기를 함께 적는다).
  • 구조 변경: check:architecture, check:adapter-inventory, verify:documentation, FE-GATE-020이 통과한다. merge 가능을 말하려면 merge 단계 전부가 통과했다.
  • 테스트 구조: 변이나 결정적 재현이 고친 뒤 기대대로 실패·통과하고, 반복 실행 실패 0과 횟수가 있다.

6. 하지 말 것

  • 리뷰 중에 코드를 고치지 않는다.
  • 지난 라운드의 실행 결과나 다른 세션이 낸 "통과"를 현재 증거로 쓰지 않는다. 바뀐 커밋에서 다시 돌린다.
  • 정한 결정을 결함으로 다시 올리지 않는다. 전제가 틀렸다는 새 증거가 있을 때만 근거와 함께 다시 연다.
  • 범위 밖 결함을 고치지 않는다. 버리지도 않는다. 보고의 「범위 밖에서 본 것」에 위치와 함께 적는다. 같은 결함을 여러 번 세지 않는다.
  • 게이트 기준(문턱, 예산, 기준선, skip·only)을 낮춰 통과시키지 않는다. 문서 검사를 피하려고 경로를 백틱 밖으로 옮기지 않는다.
  • 짝 백엔드 repo에 쓰지 않는다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다.

7. 막혔을 때

  • 고치는 법이 공개 동작(배럴 표면, 런타임 설정 키, 짝 계약, 파생 프로젝트 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 README 5절이다.
  • RED를 만들 수 없으면(실제 브라우저·호스트 권한이 필요하다, 기계에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다.
  • 같은 파일·장치에서 결함이 두 라운드 연속 나오면, 다음은 수정이 아니라 research-design.md로 "이 장치가 필요한가"를 먼저 본다.

8. 보고 형식

README 6절에 더해, 고친 발견마다 아래 칸을 쓴다. 리뷰 README의 「조치」 표에 그대로 옮길 수 있게 쓴다.

칸 적을 것
발견 ID와 한 줄 내용
상태 고침 / 일부(남은 것) / 결정 대기(이유·선택지·결정할 사람)
RED·GREEN 수정 전 실패한 테스트와 수정 뒤 통과, 로그 경로. 없으면 "RED 없음 — 이유"
검증 명령, 테스트 수, rc, 실행 위치(desktop), env(CI env인지), 로그 경로
새로 가정하는 것 빈 제품 파일, CI env 없음, 객체 하나, 기능 0개처럼 이 변경이 새로 기대는 상태와, 그 가정이 깨지는 구성에서 돌렸는지
약해진 검사 이 변경이 다른 검사를 약하게 했는가(없으면 없음)
범위 밖에서 본 것 위치와 내용. 고치지 않았다

9. 자주 하는 실수

  • 게이트 목록을 지난 라운드에서 가져온다. scripts/verify.sh merge로 stage 전부를 돌린다.
  • 다시 돌려 통과한 결과를 "통과"로 쓴다. 실패한 회차를 적고 원인을 찾는다.
  • 지운 코드의 실행 동작만 옮기고, 그 코드를 읽던 검사·테스트가 지키던 것을 놓친다. 지우기 전에 git grep으로 읽는 곳을 찾는다.
  • 짝 백엔드 사실을 문서만 보고 옮긴다. 생성기와 폼까지 코드를 따라간다.
  • "부하 탓"으로 닫는다. 부하를 낮춘 재현과 결정적 재현으로 확인하기 전에는 원인이 아니다.