frontend-quality-gates / merge / static checks (pull_request) Successful in 1m20s
frontend-quality-gates / merge / tests (pull_request) Failing after 10m12s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 5m38s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / main / self-tests and removal drills (pull_request) Skipped
PR run은 무엇을 바꿨든 merge 게이트 14개를 전부 돈다. 문서만 고친 PR도 scaffold 드릴(FE-GATE-020, run 241 tests job 15:58 중 약 8.5분)과 브라우저 게이트를 돈다. 소유자가 「PR은 바뀐 범위만, 문서만이면 문서 검사, 공용 파일이면 전체, 건너뛴 검사는 로그에, 경로표는 계약 시험으로」를 정했다(2026-11-13, design-docs ci/manual.md 4절, 계획 FE-2). config/ci/pr-gate-selection.json이 경로표다. global 파일(config/, scripts/, .gitea/, 도구 설정, lockfile 등)이나 어느 줄에도 안 걸리는 파일이 하나라도 바뀌면 전부 돈다. 아니면 파일마다 rules를 위에서부터 보고, 처음 맞는 줄의 게이트를 always(001·002·003·010)에 더한다. - 문서(docs/**, **/*.md, .claude/**)는 FE-GATE-005까지 돈다. - 접근성 기록은 009·020까지, recipes는 007·012까지 돈다. - scaffold 드릴 입력(src/features 등)은 앱 게이트와 020을 돈다. - 그 밖의 src·tests는 020을 뺀 앱 게이트를 돈다. scripts/lib/pr-gate-selection.ts가 판정한다. run-ci-gate.ts는 CI_PR_BASE_REF(pull_request run에서만 base 브랜치, 나머지는 빈 값)가 있을 때만 판정을 부른다. 안 도는 게이트는 `건너뜀: <ID> — <이유>`를 찍고 게이트 로그도 그 한 줄로 남긴 뒤 성공으로 끝난다. diff는 base와의 merge base에서 잰다. checkout이 얕아 처음 한 번 history를 받는다. 받지 못하거나 diff를 못 읽으면 이유를 찍고 전부 돈다. merge job 셋의 env 바인딩은 계약(expectedEnvironmentBindings)과 gates.json에 두고 workflow를 다시 만들었다. 버린 대안: - workflow on.paths·job if:로 건너뛰기: 필수 검사가 보고 없이 남는다 (매뉴얼 4.4절). - 고르는 job을 따로 두기: needs job이 줄 끝으로 간다. - vitest --changed: coverage 문턱이 전체 실행을 전제한다. - 맞는 줄을 모두 합치기: src 아래 AGENTS.md 같은 문서가 앱 게이트 전부를 불렀다. 위험·한계: - 경로표가 놓친 실패는 main push가 잡는다. main은 늘 전부 돈다. - scaffold 줄은 드릴 스크립트가 이름으로 부르는 src·tests 경로를 손으로 옮긴 것이다. 계약 시험이 그 이름들이 scaffold 줄에 걸리는지 본다. - 공개 repo라 checkout의 origin에서 인증 없이 fetch한다. 비공개로 바뀌면 fetch가 실패하고 전부 돈다(로그에 이유). 검증(desktop): pr-gate-selection 시험(표가 merge 게이트 전부를 덮음, 추적 파일 1631개 전부가 줄에 걸림, scaffold 드릴 이름 범위, 문서만·접근성· 앱·scaffold·전역·모르는 파일·빈 diff 선택, 건너뜀 문구 형식, 실제 git 얕은 clone에서 merge base diff, fetch 실패면 전부)을 3회 통과했다. test-timeout-declarations 통과. 자식 프로세스 시험 둘의 timeout은 잰 값 48 ms·291 ms다. check:ci-workflow, check:types:node·test, eslint 통과. scripts/verify.sh merge(CI=true, main950ea11a위, 트리e031a8a5): 14개 전부 rc=0(008 282초, 020 404초). gate FE-GATE-029 rc=0.
작업 매뉴얼
이 폴더는 이 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다.