frontend-quality-gates / merge / static checks (pull_request) Successful in 1m23s
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-028 / manual-accessibility-review (pull_request) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (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-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 / FE-GATE-017 / diagram-review (pull_request) Canceled after 0s
frontend-quality-gates / main / self-tests and removal drills (pull_request) Canceled after 0s
frontend-quality-gates / merge / tests (pull_request) Canceled after 11m31s
FE-GATE-008의 Firefox 시험이 가끔 첫 화면 5초 대기에서 실패한다
(old-tab-chunk-recovery.spec.ts, preload-use.spec.ts,
platform-overview.spec.ts). runner run 127과 desktop merge 검증에서
실패했고, 다시 돌리면 통과해 묻혔다.
Playwright는 Firefox 프로필을 os.tmpdir()에 만든다. desktop과 CI job
모두 /tmp가 같은 SATA SSD 위에 있다. Firefox는 시험 context의
localStorage·IndexedDB를 그 프로필(디스크)에 둔다. 그래서 디스크가
붐비면 context마다 첫 localStorage 접근이 디스크 일을 기다린다.
Chromium·WebKit은 시험 context 저장소를 메모리에 둔다. 앱은 첫 렌더
전에 색 구성 설정을 localStorage에서 읽어, 그 대기가 첫 화면 대기에
들어간다. desktop e2e 전체 8회(2026-11-13)에서 Firefox 앱 부팅 463회
중 19회가 0.7~3.8초 멈췄고, Chromium·WebKit은 16 ms를 넘지 않았다.
tests/support/browser/browser-test.ts가 Firefox worker의 프로필을 RAM
파일시스템에 둔다. os.tmpdir()가 이미 tmpfs면 그대로 쓴다. 아니면
/dev/shm에 worker 수 x 64 MB 자리가 있을 때 그 안에 폴더를 만든다.
Playwright의 browser fixture가 launch하는 동안만 TMPDIR를 그 폴더로
돌리고 바로 되돌린다. 그래서 fixture build 같은 다른 임시 파일은
디스크에 그대로 남는다. 프로필이 그 폴더에 생기지 않으면 시험을
실패시킨다. 자리가 없으면 이유를 한 줄 알리고 디스크에 둔다. strict
fixture와 strict를 쓰지 않는 spec 둘(preload-use, chunk-load-error)이
이 test를 바탕으로 쓴다. docs/work/reference/testing.md 5절 표에 원인을
적었다.
버린 대안:
- worker마다 localStorage를 미리 한 번 건드리는 예열: 브라우저 프로세스당
한 번 드는 준비 비용으로 봤다. 예열 뒤에도 19/463이 멈췄다. 예열
context를 바로 닫는 판은 21/464로 더 나빴다.
- toolkit.storage.synchronous=0(SQLite fsync 끔): 15/224로 그대로였다.
- 첫 화면 대기 timeout 늘리기, worker 줄이기: 원인을 덮는다.
- 시험 실행 전체에 TMPDIR 걸기: fixture build까지 RAM에 들어간다.
위험·한계:
- CI job 컨테이너는 /dev/shm이 64 MB다(2026-11-13 runner 확인). /tmp는
같은 SSD 위에 있다. 그래서 CI에서는 프로필이 디스크에 남고 로그에
이유가 한 줄 찍힌다. CI까지 고치려면 runner가 job 컨테이너에 RAM
자리를 줘야 한다(--shm-size 또는 --tmpfs /tmp). runner 설정이라 이
커밋에 넣지 않았다.
- 64 MB/worker는 Firefox worker 6개 프로필 합이 가장 컸을 때 211 MB(1개
35 MB)인 것을 보고 잡은 여유다.
- Playwright의 두 동작에 기댄다. fixture 의존성을 적힌 순서로 준비하는
것과, launch할 때 os.tmpdir()를 읽는 것이다. 어느 쪽이 바뀌어도
폴더가 비므로 시험이 실패해 알린다.
검증(desktop):
- 재현: Firefox 6개를 동시에 띄우고 context 8개씩 localStorage 첫 접근을
쟀다. 프로필 /tmp에서 최대 8,157 ms(384회), /dev/shm에서 최대 17 ms
(384회).
- 수정본 e2e 전체 10회: 매번 189 passed. Firefox 부팅 576회 중 0.5초를
넘는 멈춤 0회(최대 36 ms), 부하 15.9~31.2. 프로필은 매번 /dev/shm에
5~6개, 디스크 0개, 끝난 뒤 남은 폴더 0개.
- 변이: launch 전에 TMPDIR를 돌리지 않게 하면 theme.spec.ts(firefox)가
2 failed, 안전장치 메시지로 실패한다.
- check:types:test, eslint(바뀐 파일), check:test-evidence:source 통과.
- scripts/verify.sh gate FE-GATE-008(CI=true, main ee95573f 위): rc=0 205초,
e2e 189 passed, browser-capabilities 69, storybook 11, visual 7.
- scripts/verify.sh docs, desktop verify:documentation 통과.
작업 매뉴얼
이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다.
읽는 순서는 하나다: 루트 AGENTS.md(지도) → 이 README → 맡은 일의 playbook 하나. Claude Code 세션에서는 루트 CLAUDE.md가 AGENTS.md를 가져온다.
규칙의 정본은 AGENTS.md, .dependency-cruiser.json, config/ci/gates.json이다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다.
1. 어떤 playbook인가
| 맡은 일 | playbook |
|---|---|
새 기능을 만든다(create:feature) |
new-feature.md |
| 있는 코드를 리뷰·수정·리팩터링·최적화한다. 구조·테스트 구조를 바꾼다 | improve.md |
| 바꾸기 전에 대안을 비교하고 소유자 결정을 받는다 | research-design.md |
| 매뉴얼·안내 문서를 쓰거나 고친다 | docs-writing.md |
| 게이트를 돌린다, 릴리스한다, 파생 프로젝트에 템플릿 변경을 넘긴다 | operate.md |
| 큰 일을 나눠 다른 세션에 맡긴다 | delegate.md |
둘에 걸리면 이렇게 고른다. 결정이 먼저 필요하면 research-design이다. 동작이 바뀌는 코드가 있으면 new-feature나 improve다. 문서만 바뀌면 docs-writing이다.
2. 크기 정하기
- 크기는 작음·중간·큼 셋이다. 정의와 크기별로 할 단계는 design-docs(이 repo 옆 checkout
desktop-server-git/design-docs)conventions/work-thinking-order.md2절이 정본이다. - 요약: 작음은 파일 몇 개·새 결정 없음·되돌리기 쉬움, 중간은 경계 하나(adapter 그룹, 기능 폴더, 문서 폴더) 안의 여러 파일이나 소유자 없이 정할 작은 결정 하나, 큼은 새 체계·아키텍처·공개 계약·소유자 결정이 필요한 일이다.
- brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다. brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다.
- 아래는 파일이 하나여도 큼이다: import 규칙(
.dependency-cruiser.json), 최상위src/폴더, adapter 배럴의 공개 표면, 게이트 단계·기준(config/ci/gates.json,config/performance/budgets.json), 짝 백엔드와 맞춘 계약(config/contracts/), 런타임 설정 키, 파생 프로젝트가 따라 고쳐야 하는 변경, 보안 정책. - 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다(research-design.md). 소유자가 그 변경을 이미 정했으면(결정 색인 행, 소유자 원문) 그 결정이 소유자 검토다. 출처와 시각을 보고에 적고 만든다. 결정이 다루지 않은 범위만 멈추고 묻는다.
3. 모든 작업의 공통 단계
- 기준 커밋을 고정한다.
git rev-parse HEAD를 산출물과 보고에 적는다. - 이미 정한 것을 읽는다: reference/decisions.md,
docs/reviews/에서 가장 최근 리뷰 README의 「결정이 필요한 것」「조치」「미검증」 절. 정한 것은 다시 묻지 않는다. - 바뀌는 경계를 찾고 가장 가까운
src/<계층>/AGENTS.md를 읽는다. 위험은 파일 수가 아니라 경계로 정한다: 사용자 데이터(결과 불명 쓰기, 브라우저 저장소), 공개 포트·배럴, merge 게이트, 짝 백엔드 계약을 건드리면 높다. - 스킬을 고른다. playbook 3절에 작업별 스킬이 있고, 이 repo의 스킬은
.claude/skills/다(new-feature,desktop-gates, 분야 지식fe-*). 여러 분야에 걸치면 experts.md의 명단·렌즈표로 고른다. 파일을 바꾸는 일은 직접 하거나 하위 세션에 맡기고, 결과만 받는 일은 서브에이전트에 맡겨도 된다(delegate.md 4.3절). - 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
- 무거운 실행(pnpm, 게이트, 브라우저, 빌드)은 operate.md 「실행 위치」대로
scripts/verify.sh로 한다. - 일이 다른 경계나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절).
- 완료를 말하기 전에 검증한다(
superpowers:verification-before-completion). 돌리지 못한 검증은 못 돌렸다고, 이유와 함께 쓴다(꼭 지킬 것 5).
4. 커밋
- 커밋·push는 brief가 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다(desktop 검증은
scripts/verify.sh가 패치로 옮긴다). - main 병합, main·다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자(또는 소유자가 정한 총괄)가 한다.
- 메시지 형식은 design-docs
conventions/commit-and-pr.md를 따른다. AI 꼬리말과 자리표시자(TBD,TODO, 채우지 않은 칸)를 넣지 않는다. 결함 수정은 꼬리말Refs:에 발견 ID를 적는다(형식은 reference/review-criteria.md 11절). - 커밋 하나에 논리 변경 하나다. 동작 변경을 위한 리팩터링은 앞 커밋으로 나눈다. 그 작업이 바꾼 파일만 stage한다.
5. 막혔을 때
- 소유자만 정할 수 있는 것(공개 계약, 파생 프로젝트 동작, 보안 정책, 게이트 기준, 되돌리기 비싼 선택)은 근거와 권하는 안을 붙여 한 번 묻고, 그 항목만 멈춘다.
- brief를 준 쪽이 있으면 그쪽에 묻는다. 없으면 소유자에게 묻는다. 형식: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람.
6. 보고
- 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다. 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다.
- 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다. 숫자(테스트 수, 실패 수, 시간)는 로그에서 옮긴다.
- 착수할 때 예측(p30·p50·p80과 근거)을, 끝 보고 직전에 실측을
docs/ledger/estimates.jsonl에 한 줄씩 더한다(형식docs/ledger/README.md). - 사고 순서 흔적 칸(목적·선행 사례·방법·필요한 정보·격차·만들고 시험 여섯 줄, 생략한 단계는 이유)을 둔다(design-docs
conventions/work-thinking-order.md5절). 다른 세션이 맡긴 일이면 design-docsconventions/delegation-loop.md5절 양식을 쓴다.
7. 필요할 때만 읽는 문서
| 문서 | 내용 |
|---|---|
| reference/gates.md | scripts/verify.sh, 언제 무엇을 돌리나, merge 가능 판정, CI env, 문서 검사 범위 |
| reference/review-criteria.md | 결함 정의, 등급, 증거, 28개 관점마다 볼 곳, 리뷰 문서 양식 |
| reference/structure.md | 폴더·모듈·코드 구조 기준, 바꿀 때 같이 고칠 것 |
| reference/testing.md | 테스트 위치, 검출력 확인, 가끔 떨어지는 테스트 |
| reference/performance.md | 예산 세 맥락, 측정 조건, 숫자를 고칠 때 |
| reference/defect-patterns.md | 반복해서 나온 결함의 모양과 막는 기준 |
| reference/decisions.md | 이미 정한 결정의 색인, 결정 대기 쓰는 법 |
| evidence.md | 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID |
8. 이 폴더를 고칠 때
- 분량 상한이 있다: 지도(루트
AGENTS.md), 루트CLAUDE.md, 폴더 지역 규칙(src/**/AGENTS.md, 옆에@AGENTS.md한 줄CLAUDE.md), 이 README, playbook, 진입 경로(지도 + 루트CLAUDE.md+ README + playbook 하나). 줄 수의 정본은scripts/check-work-docs.py의 상수이고, 넘으면 그 검사가 상한과 함께 알린다.reference/는 상한이 없다. - 본문에 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 evidence.md로 옮긴다. 루트
AGENTS.md·CLAUDE.md,src/**/AGENTS.md,.claude/아래 문서도 같다.reference/decisions.md·reference/defect-patterns.md와 리뷰 문서는 ID를 둔다. - 고친 뒤
scripts/verify.sh docs(노트북)와 desktopscripts/verify.sh script verify:documentation이 통과해야 한다. 절차는 docs-writing.md다.