프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 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
12 KiB
게이트
무엇을 돌릴지는 언제인지로 정한다. 작업 중에는 바뀐 테스트 파일만, 커밋 전에는 빠른 게이트 8개, 통합 때는 5개를 더, merge 가능을 말할 때는 merge 단계 전부를 CI와 같은 env로 돌린다. 어디서 어떻게 돌리는지는 ../operate.md 4.1절이다.
작업 중 바뀐 테스트 파일 하나 (2절)
커밋 전 빠른 게이트 8개 (2절)
묶음 끝·통합 + 5개 (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)을 하나씩 끝까지. 음성 fixture(expect: fail)는 정해진 종료 코드면 통과 |
desktop |
script <이름>… |
package script를 하나씩(예: verify:documentation, test:unit) |
desktop |
| stage id | config/ci/gates.json stages의 그 단계 gateIds 전부 |
desktop |
- stage id는 계약 파일에서 읽는다. 단계가 바뀌면 스크립트를 고치지 않아도 따라간다.
--dry-run은 돌릴 명령만 보인다. - 게이트·stage는 실패가 있어도 끝까지 돌고 게이트마다
<이름> rc=<n> <초>s한 줄을 남긴다. 하나라도 실패하면 rc=1이다. 종료 코드 2는 사용법, 4는 원격 준비 실패다. - 잘못된 단계·게이트 ID는 desktop에 보내기 전에 노트북에서 거절한다.
- 환경 변수로 바꿀 수 있는 것(호스트, 원격 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 |
release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회귀가 147커밋 동안 아무 게이트에도 걸리지 않은 일이 있다. 바꾼 것이 release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.
3. merge 가능 판정
"merge 가능"은 다음 방법으로만 말한다(소유자 지시 2026-11-03). 고른 스크립트 목록이 다 통과했다는 것은 근거가 아니다. 스크립트를 골라 "23개 통과"라고 보고했지만 merge 게이트 셋이 실패하던 일이 있다.
- 대상:
config/ci/gates.json의stages중merge의gateIds전부. - 명령: 게이트마다
corepack pnpm ci:gate <ID>. workflow도 같은 명령을 쓴다.scripts/verify.sh merge가 그것을 돈다. - env: workflow 전역 env와 같은 꼴(
CI=true,VITE_COMMIT_SHA40자리,VITE_BUILD_ID,RELEASE_ID,CI_RUNNER_IMAGEdigest).CI=true를 빼지 않는다. 빼고 "통과"라고 했다가, 넣자 FE-GATE-005·008·020이 실패한 일이 있다.SOURCE_DATE_EPOCH는ci:gate가 HEAD에서 만든다. - 작업 폴더: 깨끗한 checkout.
scripts/verify.sh의 desktop worktree가 그것이다. 노트북 checkout은.claude/worktrees/를 품고 있어test:system의 repo 복사와 vite 파일 감시가 깨진다. - 한 게이트 안의 명령:
ci:gate는 그 게이트의 명령 중 첫 실패에서 멈춘다. 뒤 명령의 결과가 필요하면scripts/verify.sh parts <ID>로 돌린다. - 기록: 게이트마다 결과·시간·핵심 숫자(테스트 수, 초기 JS 바이트, 파일 수)와 실행 시점의 부하를 표로 남긴다. 게이트 로그는
artifacts/quality/gates/의FE-GATE-0NN.txt에 쌓이고,scripts/verify.sh가 desktop 로그 폴더의gate-artifacts/로 복사한다. 실패를 고칠 때마다 다시 돌리고 회차를 남긴다.
가끔 떨어지는 게이트. 다시 돌려 통과시킨 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다(testing.md 5절). "세 번째 실행에서 통과"로 적혔던 FE-GATE-008의 두 실패는 둘 다 테스트 결함이었다. 원인을 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0을 적는다.
desktop에서 FE-GATE-013. ssh 셸에서 비특권 user namespace가 막혀 bwrap --unshare-net이 실패하고, test:system의 provider 테스트가 호스트 원인으로 떨어진다. 사전 점검(scripts/check-system-test-prerequisites.ts)은 이제 이 제한을 이름으로 대며 실패한다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다(decisions.md). 결정 전까지 merge 판정 보고에는 FE-GATE-013을 "호스트 제약 실패"로 적고, scripts/verify.sh parts 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와 docs/README.md 1절 끝 문단이다.
- 범위:
docs/README.md와 그 1절이 링크한 문서. 폴더 링크는 그 폴더 바로 아래.md만 본다. 루트AGENTS.md, 이 폴더와docs/work/는 1절에서 링크되어 범위 안이다. - 보는 것: 백틱 안의 repo 경로(
:줄꼬리는 떼고 본다), 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크,corepack pnpm <script>와 백틱 안<prefix>:<name>꼴의 package script,FE-GATE-0NNID가 실제로 있는가. 설명·수치가 코드와 맞는지는 보지 않는다. - 예외: git이 무시하는 생성 산출물, 복사한 프로젝트가 지운 작업 이력(루트
README.md의 지워도 되는 파일 표)은 없어도 된다. - 짝 백엔드 경로:
config/contracts/backend-contract-pin.json이 고정한 커밋의 트리에서 찾는다. 옆 checkout이 없거나 그 커밋이 없으면 실패가 아니라 "확인 못 함"으로 남긴다. - 도는 곳: FE-GATE-017은 merge 체인 밖이다. 그러나 같은 검사가 merge 게이트 안에서도 돈다.
tests/unit/documentation-readiness.test.ts가 문서를 복사해 검사를 돌리고(FE-GATE-005), 기능을 지우거나 더한 사본을 만드는 FE-GATE-020의 드릴도 문서를 복사해 돌린다(복사 목록은scripts/lib/removal-fixture.ts). 그래서 1절 문서의 경로 하나가 틀리면 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가 실패한다. 예외는 이유와 함께config/ci/ungated-scripts.json·config/ci/ungated-tests.json에 둔다. 이 목록을 늘리는 것은 게이트 기준을 낮추는 일이다(꼭 지킬 것 4).