Files
DongHyeonka 3524d6b00b docs(work): 작업 매뉴얼 docs/work/를 두고 개선 매뉴얼 초안을 흡수한다
프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 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
2026-11-08 17:27:39 +09:00

6.9 KiB
Raw Permalink Blame History

성능 기준

이 템플릿의 성능 목표는 예산이다. 요청량·데이터량 목표는 없다. 예산은 세 측정 맥락으로 나뉘고, 맥락마다 재는 곳과 막는 게이트가 다르다. 괄호 안 결함 패턴 X0은 defect-patterns.md의 행이다.

번들(빌드 산출물)  ── 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. 정본

무엇 정본
예산 값 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
템플릿 그대로의 초기 JS 기준선, 기능·context 하나당 증가량, 갱신 명령 docs/operations/performance-evidence.md 「번들 예산의 기준선과 여유」 절, 기록 config/scale/feature-shape-ceilings.json
규모 설계와 예산의 근거 docs/architecture/scale-architecture.md
측정 결과에 붙일 정보의 일반론 리뷰 가이드 14절 「측정 결과에 반드시 붙일 정보」

2. 언제 재나

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

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

3. 측정 조건

측정값에는 아래를 함께 적는다. 하나라도 빠지면 다른 측정과 비교하지 않는다.

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

4. 예산 사이의 균형

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

5. 숫자를 고칠 때

  • 기준선 기록은 손으로 고치지 않는다. 측정 스크립트를 --initial-baseline --write로 돌리고 같은 변경에 넣는다. 손으로 적은 숫자는 두 번 낡았다. 묶음마다 맞아도 합친 트리에서 낡을 수 있으니 합친 끝에서 다시 잰다.
  • 대조 허용치는 남은 여유보다 작아야 한다. 기록 대조 허용 1%(약 2 KB)가 남은 여유(1,873 B)보다 커서 여유를 다 쓰는 변경이 통과할 수 있었다. 허용치를 정할 때 여유·측정 오차와 비교한다(결함 패턴 B1).
  • 예산 값(config/performance/budgets.json)을 올리는 것은 결정이다(꼭 지킬 것 4). 이유·대안·재검토 조건을 decisions.md 3절 형식으로 남기고 소유자 결정을 받는다. 예: 초기 파일 수 상한을 26에서 32로, 초기 JS 예산을 204,800 B에서 206,848 B로 올린 결정. 근거와 되돌림 규칙은 docs/operations/performance-evidence.md에 있다.
  • 문서에 측정값을 적을 때는 커밋과 측정일을 붙인다. 그 숫자가 지금 빌드와 다를 수 있다고 적는다.

6. 성능 쪽 반복 결함

패턴 막는 기준
release 단계에만 있는 게이트의 회귀를 아무도 모른다 2절: 라우트 로딩을 건드리면 test:performance도 돌린다
실패 메시지가 무엇을 얼마나 넘었는지 말하지 않는다 예산 검사는 넘은 항목·잰 값·초과량을 모두 출력한다
측정 조건 없이 숫자만 남아 비교할 수 없다 3절 표
lab이 화면 하나·조건 하나만 잰다. / 밖 화면의 layout shift, 스크롤바가 보이는 환경을 어느 게이트도 재지 않는다(결함 패턴 B2) 기능 라우트 로딩을 바꾸면 그 라우트 첫 진입을 lab과 같은 조건으로 따로 재고 결과에 적는다 [제안]
부하가 높은 시간대의 실패를 "부하 탓"으로 닫는다 testing.md 5절: 부하를 낮춘 재현과 결정적 재현으로 확인한 뒤에만 부하를 원인으로 쓴다
첫 화면에 필요 없는 코드가 배럴·side effect 판정 때문에 초기 청크에 들어간다(결함 패턴 B3) design-system은 side effect 없음을 선언하고, 기능 선언과 실행부를 나눈다