Files
clean-architecture-frontend…/docs/improvement/06-performance.md
T
DongHyeonka 40e3b2f814 docs(improvement): 테스트 구조와 성능 측정의 개선 기준을 적는다
문제: 테스트 결함(변이 생존, 템플릿 원래 상태만 봄, 브라우저 추정·
그리는 중인 화면에 기댐, 고정 경로·포트)이 라운드마다 반복됐다.
가끔 떨어지는 테스트를 "부하 탓"으로 닫았다가 테스트 결함으로
정정한 일이 두 번 있다. 성능 숫자는 측정 조건 없이 남아 비교할 수
없고, lab 게이트는 release 단계에만 있다.

고른 방법: 05장에 테스트 위치 기준(taxonomy 가리킴), 검출력 확인
(RED·변이·원래 상태 밖 입력·단언 범위), 환경 의존 표, flaky 금지와
조사 절차(반복 실행→실패 기록→결정적 재현→수정→변이), 실행 비용을
적는다. 06장에 세 측정 맥락, 언제 재나, 측정 조건 표, 예산 사이 균형,
숫자를 고칠 때를 적는다. 참조 기능과 함께 지워지는 기록 파일과 측정
스크립트는 이름을 쓰지 않고 그것을 소유한 문서 절을 가리킨다.

위험·한계: 실행 격리(빈 포트·실행별 출력)와 기능 라우트 첫 진입
측정은 [제안]이다. 실행 격리는 결정 대기(1105/12-04)다.

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
2026-11-05 22:15:44 +09:00

7.6 KiB
Raw Blame History

06. 성능·최적화 기준

핵심

이 템플릿의 성능 목표는 예산이다. 요청량·데이터량 목표는 없다(1105 README 0절). 예산은 세 측정 맥락으로 나뉘고, 맥락마다 재는 곳과 막는 게이트가 다르다.

번들(빌드 산출물) ── check:bundle      FE-GATE-012  merge 단계   초기 JS bytes·파일 수, lazy 청크 bytes
lab(실험실 브라우저) ── test:performance FE-GATE-026  release 단계 LCP·CLS·이름 붙은 상호작용(중앙값)
field(운영 표본)    ── field Web Vitals FE-GATE-018  field 단계   p75 LCP·CLS·INP, 28일

숫자의 정본은 config/performance/budgets.json이고, 세 맥락의 계약은 docs/operations/performance-evidence.md 1~13줄이다. 이 장은 숫자를 다시 적지 않는다. 언제 재는지, 어떤 조건으로 재는지, 숫자를 고칠 때 무엇을 같이 하는지만 정한다.

1. 정본

무엇 정본
예산 값 config/performance/budgets.json
세 맥락의 계약과 측정 항목 docs/operations/performance-evidence.md
번들 예산 검사 scripts/check-bundle.ts(check:bundle)
lab 측정 scripts/test-performance.ts(test:performance), 기본값 scripts/lib/lab-performance.ts(5회, 포트 4173)
템플릿 그대로의 초기 JS 기준선, 기능·context 하나당 증가량, 그 기록을 재는 테스트와 갱신 명령 docs/operations/performance-evidence.md 「번들 예산의 기준선과 여유」 절. 기록 파일과 측정 스크립트는 참조 기능과 함께 지워지므로 이 매뉴얼은 이름을 쓰지 않고 그 절을 가리킨다(07장 6절)
규모 설계와 예산의 근거 docs/architecture/scale-architecture.md
측정 결과에 붙일 정보의 일반론 가이드 14절 「측정 결과에 반드시 붙일 정보」

2. 언제 재나

바꾼 것 잴 것
라우트 로딩, dynamic import, 초기 화면, 청크 나누기(vite.config.ts) check:bundle과 test:performance 둘 다
의존성 추가·갱신 check:bundle. 갱신 하나가 초기 JS를 약 7 KB 늘려 예산을 넘긴 예가 있다(1103/13-03, zod 4.6.x)
기능 추가(create:feature) 생성 명령의 Next: 안내대로 초기 JS 기록을 다시 쓰고 FE-GATE-005·012를 돌린다(1103 README 14.6절 #2)
성능 최적화 작업 바꾸기 전·후를 같은 조건으로(3절)

lab 게이트는 release 단계에만 있다. merge 게이트만 돌리면 lab 회귀를 모른다. 예제 화면 진입 회귀가 147커밋 동안 아무 게이트에도 걸리지 않았다(1103/15-01). 라우트 로딩을 건드린 커밋은 merge 게이트에 더해 test:performance를 돌린다 (07장 2절).

3. 측정 조건

측정값에는 아래를 함께 적는다. 하나라도 빠지면 다른 측정과 비교하지 않는다(가이드 14절).

항목 이 repo에서
위치 desktop(07장 7절). 노트북 측정은 비교에 쓰지 않는다
하드웨어·런타임 CPU 모델·논리 코어 수·Node 버전. lab 결과 JSON이 자동으로 담는다
부하 측정 앞뒤의 load average. lab 결과 JSON이 담는다. 다른 무거운 실행과 겹치지 않게 잠금 아래에서 잰다
브라우저와 조건 lab: Chromium, 1280×720, contract-fast-4g, CPU 4배 감속, 빈 캐시·새 browser context(scripts/test-performance.ts 211~221줄)
반복과 통계 기본 5회의 중앙값으로 판정한다. 표본 전부와 퍼짐을 함께 적는다(같은 파일 226~231줄). 예: "중앙값 227 ms(표본 223·224·227·438·526)"(1103/15-01)
빌드 커밋과 build id. 비교하는 두 빌드는 같은 env로 만든다. 커밋 ID가 빌드에 박혀 초기 JS가 몇 바이트 달라진다(1103 README 14.5절 10회차)
대조군 바꾸기 전 커밋을 같은 세션·같은 조건에서 함께 잰다. 지난 측정값을 대조군으로 쓰지 않는다
규모 기능 수에 따른 비용은 참조 기능을 복제한 실제 모양 기능 25개·100개로 재고 호스트 부하를 함께 적는다(SPEC.md D-18)

4. 예산 사이의 균형

  • 초기 JS bytes와 초기 파일 수는 함께 본다. bytes를 줄이려고 청크를 나누면 파일 수가 는다. HTTP/1.1에서는 요청이 줄을 서서 첫 화면이 늦어진다. 파일 수 상한은 HTTP/2 호스팅을 전제로 정했다(docs/operations/performance-evidence.md 「초기 청크 수와 HTTP/1.1」, 1103 README 14.6절 #4).
  • 청크 이름으로 크기를 판단하지 않는다. 공용 청크는 안에 든 모듈 하나의 이름을 받는다. 출처별 크기는 sourcemap으로 나눠 잰다(같은 문서 「번들 예산의 기준선과 여유」).
  • 재방문 비용도 본다. release마다 이름이 바뀌는 청크에 큰 라이브러리가 들어가면 코드가 같아도 다시 받는다(같은 문서 「build id와 재방문 캐시」).
  • 여유를 적는다. 예산에서 기준선을 뺀 여유와, 기능 하나가 쓰는 양을 함께 보고한다. 1103 조치 끝에 초기 JS 여유가 쓰기 기능 하나 남짓이었다(1103 README 14.5절 끝 문단, 14.7절).

5. 숫자를 고칠 때

  • 기준선 기록은 손으로 고치지 않는다. 측정 스크립트를 --initial-baseline --write로 돌리고 같은 변경에 넣는다 (docs/operations/performance-evidence.md 35~36줄). 손으로 적은 숫자는 두 번 낡았다(같은 문서 22줄).
  • 대조 허용치는 남은 여유보다 작아야 한다. 기록 대조 허용 1%(약 2 KB)가 남은 여유(1,873 B)보다 커서 여유를 다 쓰는 변경이 통과할 수 있다(1105/15-02). 허용치를 정할 때 여유·측정 오차와 비교한다. 부록 P-46.
  • 예산 값(config/performance/budgets.json)을 올리는 것은 결정이다. 이유·대안·재검토 조건을 08장 형식으로 남긴다. 예: 초기 파일 수 상한을 26에서 32로 올린 것(1103 README 14.6절 #4).
  • 문서에 측정값을 적을 때는 커밋과 측정일을 붙인다. 그 숫자가 지금 빌드와 다를 수 있다고 적는다.

6. 성능 쪽 반복 결함

패턴 막는 기준
release 단계에만 있는 게이트의 회귀를 아무도 모른다(1101/15-01, 1103/15-01) 2절: 라우트 로딩을 건드리면 test:performance도 돌린다
실패 메시지가 무엇을 얼마나 넘었는지 말하지 않는다(1103/15-03) 예산 검사는 넘은 항목·잰 값·초과량을 모두 출력한다(docs/operations/performance-evidence.md 5~7줄)
측정 조건 없이 숫자만 남아 비교할 수 없다 3절 표
lab이 화면 하나·조건 하나만 잰다. 기능 라우트 첫 진입(약 400 ms), / 밖 화면의 layout shift, 스크롤바가 보이는 환경을 어느 게이트도 재지 않는다(1105/15-04, 15-01, 15-05, 모두 미조치) 기능 라우트 로딩을 바꾸면 그 라우트 첫 진입을 lab과 같은 조건으로 따로 재고 결과에 적는다 [제안]
부하가 높은 시간대의 실패를 "부하 탓"으로 닫는다. 두 번 다 원인은 테스트에 있었다(1103/11-09, 11-10) 05장 5절: 부하를 낮춘 재현과 결정적 재현으로 확인한 뒤에만 부하를 원인으로 쓴다

전체 목록은 부록의 「성능」 행이다.

지금 이해하면 되는 것

  • 예산 숫자는 config/performance/budgets.json, 맥락별 계약은 performance-evidence.md가 정본이다.
  • 라우트 로딩을 건드리면 merge 게이트에 더해 lab 게이트도 돌린다.
  • 측정값에는 위치·부하·반복 수·빌드·대조군을 붙인다. 붙이지 않은 숫자는 비교하지 않는다.