문제: 테스트 결함(변이 생존, 템플릿 원래 상태만 봄, 브라우저 추정· 그리는 중인 화면에 기댐, 고정 경로·포트)이 라운드마다 반복됐다. 가끔 떨어지는 테스트를 "부하 탓"으로 닫았다가 테스트 결함으로 정정한 일이 두 번 있다. 성능 숫자는 측정 조건 없이 남아 비교할 수 없고, lab 게이트는 release 단계에만 있다. 고른 방법: 05장에 테스트 위치 기준(taxonomy 가리킴), 검출력 확인 (RED·변이·원래 상태 밖 입력·단언 범위), 환경 의존 표, flaky 금지와 조사 절차(반복 실행→실패 기록→결정적 재현→수정→변이), 실행 비용을 적는다. 06장에 세 측정 맥락, 언제 재나, 측정 조건 표, 예산 사이 균형, 숫자를 고칠 때를 적는다. 참조 기능과 함께 지워지는 기록 파일과 측정 스크립트는 이름을 쓰지 않고 그것을 소유한 문서 절을 가리킨다. 위험·한계: 실행 격리(빈 포트·실행별 출력)와 기능 라우트 첫 진입 측정은 [제안]이다. 실행 격리는 결정 대기(1105/12-04)다. 검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
7.6 KiB
7.6 KiB
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.md35~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 게이트도 돌린다.
- 측정값에는 위치·부하·반복 수·빌드·대조군을 붙인다. 붙이지 않은 숫자는 비교하지 않는다.