Files
clean-architecture-frontend…/docs/work/reference/gates.md
T
DongHyeonka fe9990b4cc docs(ledger): 흔들린 시험 기록을 두고 시간·순서 단언 규칙을 가리킨다
흔들린 시험을 적는 곳이 없다. 2026-11-12~13 이틀에 프론트 흔들림이
여섯 건이었다. 재실행으로 통과시킨 것은 세션 노트에만 남았다. 같은
모양(첫 렌더 5초 창, 잠금 순서 가정)이 다시 들어와도 리뷰 기준에 막을
줄이 없다.

docs/ledger/flaky-tests.jsonl을 두고 여섯 건을 첫 줄들로 넣는다. 칸은
design-docs ci/manual.md 8.5절이다(date·test·category·first_run·verdict·
quarantined_until·fixed_by). 여기에 대응하는 표를 docs/ledger/README.md
「흔들림 기록」에 둔다. 이 파일도 estimates.jsonl처럼 더하기만 하고
.gitattributes merge=union으로 합친다. README 지워도 되는 파일 표와
docs/README.md 지도에 넣었다. testing.md 5절 조사 절차에 6번(기록)을
더했다. 리뷰 기준 2절 「헷갈리는 경우」에 벽시계 상한·시작 순서 단언을
구조적 위험으로 적고, gates.md 3절에서 둘을 가리킨다(ci/manual.md 8.4절).

버린 대안: scripts/verify.sh docs가 이 파일의 칸과 범주까지 검사하게
하는 안. 이번 범위(계획 FLAKY-1) 밖이라 뒤로 미뤘다. 지금은 손으로
맞춘다.

위험·한계: platform-overview.spec.ts:48(WebKit)은 원인 조사 전이다.
범주는 5초 창에서 실패한 꼴만 보고 fixed-time으로 적었다.

검증: scripts/verify.sh docs(노트북) OK, desktop verify:documentation.
2026-11-13 19:38:52 +09:00

16 KiB

게이트

무엇을 돌릴지는 언제인지로 정한다. 작업 중에는 바뀐 테스트 파일만, 커밋 전에는 검사 몇 개(package script, 2절 표), 통합 때는 몇 개를 더, merge 가능을 말할 때는 merge 단계 전부를 CI와 같은 env로 돌린다. 어디서 어떻게 돌리는지는 ../operate.md 4.1절이다.

작업 중       바뀐 테스트 파일 하나                          (2절)
커밋 전       검사(package script)                            (2절)
묶음 끝·통합  + 검사 더                                       (2절)
merge 판정    scripts/verify.sh merge (stage 전부, CI env)   (3절)
리뷰 시작     merge 단계 + documentation 단계                (3절)

게이트 ID·단계·명령의 정본은 config/ci/gates.json이고 설명은 docs/operations/ci-quality-gates.md다. 이 문서는 그 목록을 다시 적지 않는다.

1. 진입점 scripts/verify.sh

scripts/verify.sh <단계> [대상…] [--on here|<호스트>] [--log <이름>] [--dry-run]
단계 하는 일 기본 위치
docs 작업 매뉴얼 검사(scripts/check-work-docs.py)와 장부 형식 여기(노트북)
hooks repo 훅·검사기·장부 시험(python3 -m unittest discover -s scripts/tests) 여기
gate <ID>… 게이트마다 corepack pnpm ci:gate <ID>, CI env로 desktop
parts <ID> 그 게이트의 명령(commandIds)을 args와 함께 하나씩 끝까지. 음성 fixture(expect: fail)는 ci:gate처럼 정해진 종료 코드와 정해진 진단 문구(expectedDiagnosticId)가 둘 다 있어야 통과 desktop
script <이름>… [-- 인자…] package script를 하나씩(예: verify:documentation). -- 뒤 인자는 script가 하나일 때만 넘긴다(예: scripts/verify.sh script test:sample-removal -- --feature=<id>) desktop
exec -- <명령…> 명령 하나. 한 테스트 파일(node scripts/run-vitest.ts run <파일>)이나 package script가 아닌 node 스크립트 desktop
stage id config/ci/gates.json stages의 그 단계 gateIds 전부 desktop
  • stage id는 계약 파일에서 읽는다. 단계가 바뀌면 스크립트를 고치지 않아도 따라간다. --dry-run은 돌릴 명령만 보인다.
  • 게이트·stage는 실패가 있어도 끝까지 돌고 게이트마다 <이름> rc=<n> <초>s 한 줄을 남긴다. 하나라도 실패하면 rc=1이다. 종료 코드 2는 사용법, 4는 원격 준비 실패다.
  • 잘못된 단계·게이트 ID는 desktop에 보내기 전에 노트북에서 거절한다.
  • desktop에서 바뀐 파일(생성 명령, 기준선 다시 쓰기의 결과)은 로그 폴더의 changes.patch에 남는다. --apply-back을 주면 그 패치를 노트북 작업 트리에 얹는다. 예: scripts/verify.sh script create:feature --apply-back -- <id> --with-create.
  • VERIFY_SNAPSHOT=1을 주면 artifacts·dist·test-results를 로그 폴더의 snapshot/에 복사한다. 리뷰어가 함께 읽는 사본이다.
  • 환경 변수로 바꿀 수 있는 것(호스트, 원격 checkout, 기준 ref, 잠금, 로그 폴더, node 경로)은 스크립트 머리 주석에 있다. 복사한 프로젝트는 ../operate.md 4.1절과 이 값만 자기 환경으로 바꾼다.

2. 언제 무엇을

  • 패키지 스크립트는 corepack pnpm <script>로 돌린다. npm run으로 돌리면 제거 드릴이 pnpm을 가정해 모든 검사가 Unknown command로 실패한다.
  • 테스트 파일 하나는 node scripts/run-vitest.ts run <file>로 돌린다. 이 runner가 src/.generated/를 먼저 만든다. pnpm exec vitest run <file>은 그 단계를 건너뛰어 import 오류로 실패하고, pnpm test:unit -- <file>은 범위를 좁히지 않는다(docs/testing/taxonomy.md).
  • 실패를 경고로 낮추지 않는다. continue-on-error나 경고만 내는 스크립트를 쓰지 않는다.
때 돌릴 것
작업 중 바뀐 테스트 파일. 브라우저 테스트는 그 spec 하나
커밋 전(작업마다) check:architecture, check:types, lint, test:unit, test:component, test:integration, test:contract, test:runtime-schema
묶음 끝·통합 위에 더해 check:ci, check:adapter-inventory, verify:documentation, test:sample-removal, build
브랜치를 합칠 때마다 커밋 전 8개. 합친 뒤에만 생긴 실패는 기록한다
merge 가능이라고 말하기 전 scripts/verify.sh merge(3절)
리뷰 시작 scripts/verify.sh merge와 scripts/verify.sh documentation(FE-GATE-017)
라우트 로딩·청크·초기 화면을 바꿀 때 merge 단계(check:bundle의 FE-GATE-012 포함)에 더해 lab 게이트 test:performance(FE-GATE-026)
공급망·release 경로를 바꿀 때 scripts/verify.sh release
작업 매뉴얼·훅을 바꿀 때 노트북 scripts/verify.sh docs, scripts/verify.sh hooks. 문서(작업 매뉴얼, .claude/ 아래 문서, AGENTS.md·CLAUDE.md 포함)를 바꿨으면 desktop scripts/verify.sh script verify:documentation도
검사 script·그 fixture를 바꿀 때 merge에 더해 scripts/verify.sh gate FE-GATE-029(검사기 자기 시험은 main 단계에 있다)

release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회귀가 147커밋 동안 아무 게이트에도 걸리지 않은 일이 있다. 바꾼 것이 release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.

3. merge 가능 판정

"merge 가능"은 다음 방법으로만 말한다(소유자 지시 2026-11-03). 고른 스크립트 목록이 다 통과했다는 것은 근거가 아니다. 스크립트를 골라 "23개 통과"라고 보고했지만 merge 게이트 셋이 실패하던 일이 있다.

  1. 대상: config/ci/gates.json의 stages 중 merge의 gateIds 전부.
  2. 명령: 게이트마다 corepack pnpm ci:gate <ID>. workflow도 같은 명령을 쓴다. scripts/verify.sh merge가 그것을 돈다.
  3. env: workflow 전역 env와 같은 꼴(CI=true, VITE_COMMIT_SHA 40자리, VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE digest). CI=true를 빼지 않는다. 빼고 "통과"라고 했다가, 넣자 FE-GATE-005·008·020이 실패한 일이 있다. SOURCE_DATE_EPOCH는 ci:gate가 HEAD에서 만든다.
  4. 작업 폴더: 깨끗한 checkout. scripts/verify.sh의 desktop worktree가 그것이다. 노트북 checkout은 .claude/worktrees/를 품고 있어 test:system의 repo 복사와 vite 파일 감시가 깨진다.
  5. 한 게이트 안의 명령: ci:gate는 그 게이트의 명령 중 첫 실패에서 멈춘다. 뒤 명령의 결과가 필요하면 scripts/verify.sh parts <ID>로 돌린다.
  6. 기록: 게이트마다 결과·시간·핵심 숫자(테스트 수, 초기 JS 바이트, 파일 수)와 실행 시점의 부하를 표로 남긴다. 게이트 로그는 artifacts/quality/gates/의 FE-GATE-0NN.txt에 쌓이고, scripts/verify.sh가 desktop 로그 폴더의 gate-artifacts/로 복사한다. 실패를 고칠 때마다 다시 돌리고 회차를 남긴다.

가끔 떨어지는 게이트. 다시 돌려 통과시킨 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다(testing.md 5절). "세 번째 실행에서 통과"로 적혔던 FE-GATE-008의 두 실패는 둘 다 테스트 결함이었다. 원인을 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0을 적는다.

흔들림 기록과 시간 단언. 흔들린 시험은 처음 본 날 docs/ledger/flaky-tests.jsonl에 한 줄 남긴다(testing.md 5절 6번). 새 시험이 벽시계 상한이나 시작 순서를 단언하면 리뷰가 막는다(리뷰 기준 2절, design-docs ci/manual.md 8.4절).

FE-GATE-013은 시스템 컨테이너 안에서 돈다. provider sandbox는 systemd user manager와 bubblewrap을 쓴다. CI의 job 컨테이너에는 둘 다 없고, desktop ssh 셸은 비특권 user namespace가 막혀 있다. 그래서 계약(config/ci/gates.json의 hostEnvironment)이 이 게이트를 scripts/run-in-system-container.sh 안에서 돌게 하고, workflow와 scripts/verify.sh가 같은 길을 쓴다. 래퍼는 일회용 privileged systemd 컨테이너(config/ci/system-container.Dockerfile)를 띄워 작업 트리를 복사하고 root로 돌린 뒤 artifacts/를 되가져온다. Docker가 필요하다(CI는 runner의 dind, desktop은 호스트 Docker). 컨테이너 안에서 통과하면 다른 게이트처럼 통과로 센다(소유자 결정 2026-11-11: 조건이 되는 실행 환경을 찾아 초록으로). 컨테이너 안은 root라 「비특권 runner에서 bwrap user namespace」 조건 자체는 증명하지 않는다. 실패하면 scripts/verify.sh parts FE-GATE-013으로 명령마다 보고, SYSTEM_CONTAINER_KEEP=1이면 컨테이너를 남긴다. 호스트 시스템 설정은 바꾸지 않는다.

컨테이너를 띄울 수 없는 호스트의 FE-GATE-013. Docker가 없거나 privileged 컨테이너를 막는 호스트에서는 래퍼가 종료 코드 3으로 끝난다. 그런 호스트는 VERIFY_HOST_ENVIRONMENT=off를 주어 게이트를 호스트에서 돌리고 아래로 판정한다. desktop ssh 셸에서는 비특권 user namespace가 막혀 bwrap --unshare-net이 실패하고, test:system의 provider 테스트가 호스트 원인으로 떨어진다. 사전 점검(scripts/check-system-test-prerequisites.ts)은 이 제한을 이름으로 대며 실패한다. merge 판정에서는 이 실패를 호스트 원인으로 보고 뺀다(소유자 결정 2026-11-11에 따라 2026-11-12에 정함, decisions.md 2.2절). 뺄 수 있는 조건은 둘이고, 하나라도 어기면 merge 가능이 아니다.

  1. FE-GATE-013의 실패가 사전 점검의 user namespace 제한 하나뿐이다.
  2. VERIFY_HOST_ENVIRONMENT=off scripts/verify.sh parts FE-GATE-013으로 돌린 뒤 명령(config/ci/gates.json의 FE-GATE-013 commandIds에서 test-system 다음 것)이 모두 rc=0이다.

보고 문구는 「merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약(user namespace)이라 판정에서 뺌(뒤 명령 결과 첨부, 모두 rc=0)」이다. 이것은 merge 판정이지 게이트 충족이 아니다. FE-GATE-013의 「충족」은 그 조건을 갖춘 runner에서 FE-GATE-013이 통과한 것으로만 적는다. 시스템 설정은 바꾸지 않는다.

4. CI env에서만 나는 실패

로컬 env로 통과해도 workflow env에서 실패하는 결함이 반복됐다(결함 패턴 G3).

모양 기준
e2e가 build id를 "local-build"로 고정해 workflow의 VITE_BUILD_ID와 어긋났다 merge 판정은 3절 env로만 한다
workflow 전역 env의 빌드 식별값이 vitest와 dev server로 새어 merge 게이트 다섯 개가 실제 CI에서만 실패했다 테스트가 직접 띄우는 빌드·서버의 env는 테스트가 정한다. 테스트용 로컬 빌드 식별값은 scripts/lib/build-environment.ts가 한 곳에서 준다
CI=true가 테스트 안의 로컬 빌드까지 release 빌드로 검사되게 했다 같음

5. 검사가 PASS인데 그 뒤가 실패

사전 점검·준비 단계가 "통과"를 내고, 그 뒤 실제 단계가 원인 없는 원문 오류로 실패하는 결함이다(결함 패턴 G5). 예: 사전 점검이 실행 파일·cgroup·systemd bus만 보고 bwrap을 실제로 돌리지 않아 PASS 뒤 provider 테스트가 bwrap 원문 오류로 떨어졌다. git worktree에서 .git 때문에 실패하는 단계를 사전 점검이 PASS로 냈다.

기준: 사전 점검은 본 단계가 쓰는 것과 같은 방법으로 한 번 실행해 본다. 실패하면 원인 이름을 붙여 멈춘다. 존재 여부만 보는 점검은 PASS가 아니라 "확인 안 함"(UNVERIFIED)으로 적는다.

6. 게이트를 믿을 조건 — 거짓 통과 막기

  • 검사가 실제 대상과 비교하는지 본다. 자기 산출물, 이전 release, 상수 true, 오류 화면, fixture 전용 규칙을 보고 통과하면 거짓 통과다(결함 패턴 G7).
  • 검사기 자신을 지키는 음성 fixture가 있어야 한다. 통제는 통과 fixture와 거절 fixture가 둘 다 있어야 검증된다(docs/testing/taxonomy.md). 아키텍처 검사기가 0개 모듈을 훑고 통과한 일 뒤로 check:architecture는 자체 그래프와 고정 fixture를 쓴다.
  • 확인하지 못한 판정은 PASS가 아니라 UNVERIFIED다. 코드에 상수 true 판정을 두지 않는다.
  • 게이트를 고친 뒤 그 게이트가 막던 결함을 다시 넣어(변이) 실패하는지 본다.
  • 게이트 실행 뒤 git status가 비어야 한다. 비지 않으면 고정 출력 경로·추적 파일 쓰기 결함이다(결함 패턴 G4).

7. 문서 검사

verify:documentation(FE-GATE-017, documentation 단계)이 문서를 검사하는 범위와 방법의 정본은 scripts/verify-documentation-readiness.ts, scripts/lib/docs-system.ts와 docs/README.md 5절이다.

  • 범위: 살아 있는 문서 전부(루트 AGENTS.md·README.md, docs/ 아래 기록 밖 문서, src/의 AGENTS.md·모듈 README, .claude/ 아래 문서). 기록(docs/design/, docs/history/)은 머리 블록만 보고, 결정 기록(docs/adr/)은 본문의 언어·문체도 본다.
  • 보는 것: 언어(한국어인가), 문체(「~한다」), 숫자 복사, 기록의 머리 블록, 문서 지도와 루트 README 필수 절. 그리고 백틱 안의 repo 경로(:줄 꼬리는 떼고 본다), 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크, corepack pnpm <script>와 백틱 안 <prefix>:<name> 꼴의 package script, FE-GATE-0NN ID가 실제로 있는가. 설명·수치가 코드와 맞는지는 보지 않는다.
  • 예외: git이 무시하는 생성 산출물, 복사한 프로젝트가 지운 작업 이력(루트 README.md의 지워도 되는 파일 표)은 없어도 된다.
  • 짝 백엔드 경로: config/contracts/backend-contract-pin.json이 고정한 커밋의 트리에서 찾는다. 옆 checkout이 없거나 그 커밋이 없으면 실패가 아니라 "확인 못 함"으로 남긴다.
  • 도는 곳: FE-GATE-017은 merge 체인 밖이다. 그러나 같은 검사가 merge 게이트 안에서도 돈다. tests/unit/documentation-readiness.test.ts가 이 repo 그대로 한 번, 문서를 복사해 여러 번 검사를 돌리고(FE-GATE-005), 기능을 지우거나 더한 사본을 만드는 FE-GATE-020의 드릴도 문서를 복사해 돌린다(복사 목록은 scripts/lib/removal-fixture.ts). 그래서 살아 있는 문서의 경로 하나, 영어 문단 하나가 merge를 막는다.
  • 돌리는 법: desktop에서 scripts/verify.sh script verify:documentation. 설치가 끝난 worktree라 pnpm이 재설치 대기로 멈추지 않는다.
  • 작업 매뉴얼의 분량·이력 ID·뼈대는 verify:documentation이 보지 않는다. scripts/verify.sh docs가 본다.

8. 게이트·검사 스크립트를 더할 때

  • 새 게이트·명령은 config/ci/gates.json에 더하고 workflow는 생성기로 다시 만든다(check:ci가 대조한다). 손으로 workflow만 고치지 않는다.
  • 새 검사에는 통과 fixture와 거절 fixture를 함께 둔다. 실패 메시지는 넘은 항목·잰 값·고칠 파일을 말한다.
  • 새 package script가 어느 게이트에서도 돌지 않으면 check:ci:gating(main 단계 FE-GATE-029)이 실패한다. PR에서는 돌지 않고 main에 push한 뒤 돈다. 예외는 이유와 함께 config/ci/ungated-scripts.json·config/ci/ungated-tests.json에 둔다. 이 목록을 늘리는 것은 게이트 기준을 낮추는 일이다(꼭 지킬 것 4).