2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는 문서가 지금 코드와 다른 말을 한다. - 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로 가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/, 패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06). - 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다. optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리 블록이 옮긴 곳을 가리킨다(1112/09-02). - 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로 가리킨다(1112/08-17). - 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007), drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는 꼬리 문장(1112/02-08). - 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다 (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은 verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07). - create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자 (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15). - secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장 (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫 (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조 (1106/14-02). 고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다. 버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다). 위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제 docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드 예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture 규칙과 부딪쳐 결정 대기로 남긴다. 검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과 FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다. Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04, 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15, 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02, 0929/14-03, 0929/13-10, 1106/14-02
14 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)을 하나씩 끝까지. 음성 fixture(expect: fail)는 정해진 종료 코드면 통과 |
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 게이트 셋이 실패하던 일이 있다.
- 대상:
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)은 이 제한을 이름으로 대며 실패한다. merge 판정에서는 이 실패를 호스트 원인으로 보고 뺀다(소유자 결정 2026-11-11에 따라 2026-11-12에 정함, decisions.md 2.2절). 뺄 수 있는 조건은 둘이고, 하나라도 어기면 merge 가능이 아니다.
- FE-GATE-013의 실패가 사전 점검의 user namespace 제한 하나뿐이다.
scripts/verify.sh parts FE-GATE-013으로 돌린 뒤 명령(config/ci/gates.json의 FE-GATE-013commandIds에서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-0NNID가 실제로 있는가. 설명·수치가 코드와 맞는지는 보지 않는다. - 예외: 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).