Files
clean-architecture-frontend…/docs/improvement/07-verification-gates.md
T
DongHyeonka e9d9c3694f docs: 리뷰 절차가 merge 단계 게이트 전부를 ci:gate로 돌린다
문제: CLAUDE.md 전체 리뷰 절차 2단계가 돌릴 명령 11개를 손으로
적는다. 이 목록은 merge 단계 명령 87개 중 10개만 돌리고, merge
게이트 14개 중 7개(001, 008, 009, 011, 012, 013, 020)는 전혀 돌지
않는다. 명령을 직접 부르면 ci:gate가 하는 로그·증거 검사, 음성
fixture의 기대 실패, workflow env도 빠진다. 2026-11-03 리뷰가 실제
CI에서 항상 실패하던 merge 게이트 둘(1103/11-06, 12-09)을 놓친 경로다.

고른 방법: 2단계를 "config/ci/gates.json의 merge 단계 gateIds 전부를
workflow env로 ci:gate 하나씩, verify:documentation은 따로"로 바꾸고
목록을 손으로 적지 않는다. 자세한 방법은 개선 매뉴얼 07장 3절을
가리킨다. 매뉴얼 01·07장과 부록 P-01에서 옛 목록을 전제로 쓴 문장을
같이 고친다. 줄 수는 그대로라 매뉴얼의 CLAUDE.md 줄 참조는 맞다.
버린 대안: 목록에 빠진 명령을 더 적기(다음에 게이트가 바뀌면 다시
갈라진다). merge 단계를 읽는 명령(ci:gate:stage merge)은 이 작업
범위 밖이라 더하지 않았다.

위험·한계: 리뷰 시작 비용이 커진다(FE-GATE-020만 약 20분). 실행
위치와 잠금은 매뉴얼 07장 7절을 따른다. 추적하지 않는 AGENTS.md는
이 변경을 받지 않는다.

검증: 로컬 정적 대조(매뉴얼의 경로·script·FE-GATE ID 문제 0건).
desktop의 verify:documentation과 문서 unit 테스트는 이 커밋을 보내
돌린다.

Refs: 1105/12-03
2026-11-05 22:33:03 +09:00

13 KiB

07. 검증과 게이트

핵심

무엇을 돌릴지는 언제인지로 정한다. 작업 중에는 바뀐 테스트 파일만, 커밋 전에는 빠른 게이트 8개, 통합 때는 5개를 더, merge 가능을 말할 때는 merge 단계 14개를 CI와 같은 env로 돌린다.

작업 중       바뀐 테스트 파일 하나                     (1절)
커밋 전       빠른 게이트 8개                           (2절, SPEC.md 31줄)
레인 끝·통합  + 5개                                     (2절, SPEC.md 32줄)
merge 판정    ci:gate로 merge 단계 14개, workflow env   (3절)
리뷰 시작     merge 단계 14개 + verify:documentation    (3절, CLAUDE.md 리뷰 절차 2단계)

게이트 ID·단계·명령의 정본은 config/ci/gates.json이다. 이 장은 그 목록을 다시 적지 않는다.

1. 명령 규칙

  • 패키지 스크립트는 corepack pnpm <script>로 돌린다. npm run으로 돌리면 제거 드릴이 npm_execpath를 pnpm으로 가정해 모든 검사가 Unknown command로 실패한다(1103 README 10.4절).
  • 테스트 파일 하나는 node scripts/run-vitest.ts run <file>로 돌린다. 이 runner가 src/.generated/를 먼저 만든다. pnpm exec vitest run <file>은 그 단계를 건너뛰어 import 오류로 실패하고, pnpm test:unit -- <file>은 범위를 좁히지 않는다(docs/testing/taxonomy.md 42~53줄).
  • 실패를 경고로 낮추지 않는다. continue-on-error나 경고만 내는 스크립트를 쓰지 않는다(docs/testing/taxonomy.md 3~4줄).

2. 언제 무엇을

때 돌릴 것 근거
작업 중 바뀐 테스트 파일. 브라우저 테스트는 그 spec 하나 1절
커밋 전(작업마다) check:architecture, check:types, lint, test:unit, test:component, test:integration, test:contract, test:runtime-schema SPEC.md 31줄
레인 끝·통합 위에 더해 check:ci, check:adapter-inventory, verify:documentation, test:sample-removal, build SPEC.md 32줄
브랜치를 합칠 때마다 커밋 전 8개. 합친 뒤에만 생긴 실패는 기록한다 1103 README 14.1·14.3절
merge 가능이라고 말하기 전 merge 단계 14개(3절) 사용자 지시
리뷰 시작 merge 단계 14개(3절)와 verify:documentation(FE-GATE-017) CLAUDE.md 27줄. 손으로 적은 명령 목록만 돌리다 merge 게이트 둘을 놓친 일(1103 README 10.5절)로 목록을 merge 단계로 바꿨다(1105/12-03)
라우트 로딩·청크·초기 화면을 바꿀 때 merge 단계에 더해 check:bundle(FE-GATE-012)과 lab 게이트 test:performance(FE-GATE-026) 06장 2절
공급망·release 경로를 바꿀 때 release 단계 게이트(config/ci/gates.json의 stages 중 release) 4절

release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회귀가 147커밋 동안 아무 게이트에도 걸리지 않았다 (1103/15-01, 1103 README 5절 원인 2). 바꾼 것이 release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.

3. merge 가능 판정

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

  1. 대상: config/ci/gates.json의 stages 중 merge의 gateIds 14개(FE-GATE-001~013, FE-GATE-020).

  2. 명령: 게이트마다 corepack pnpm ci:gate -- FE-GATE-0NN. workflow도 같은 명령을 쓴다 (.gitea/workflows/quality-gates.yml 74줄).

  3. env: workflow의 전역 env(.gitea/workflows/quality-gates.yml 25~31줄)를 그대로 준다.

    변수 값
    CI true. 빼지 않는다. 이 값이 있어야 빌드 식별값을 엄격하게 검사한다
    VITE_COMMIT_SHA 40자리 커밋 SHA
    VITE_BUILD_ID gitea-<run>-<attempt> 꼴
    RELEASE_ID <ref>-<run>-<attempt> 꼴
    CI_RUNNER_IMAGE <image>@sha256:<64자리> 꼴 digest

    CI=true 없이 "14개 통과"라고 했다가, 넣자 FE-GATE-005·008·020이 실패한 적이 있다(1103 README 14.5절 끝 문단, 1103/11-08).

  4. 작업 폴더: 깨끗한 checkout. 노트북 main checkout은 .claude/worktrees/를 품고 있어 test:system의 repo 복사와 vite 파일 감시가 깨진다. desktop checkout에는 이 폴더가 없다(7절).

  5. 한 게이트 안의 명령: ci:gate는 그 게이트의 명령 중 첫 실패에서 멈춘다. 뒤 명령의 결과가 필요하면 따로 돌린다. 4라운드는 FE-GATE-013의 test:system 뒤 명령 7개를 따로 돌렸다(1105 README 11.1절).

  6. 기록: 게이트마다 결과·시간·핵심 숫자(테스트 수, 초기 JS 바이트, 파일 수)와 실행 시점의 부하를 표로 남긴다. 게이트 로그는 artifacts/quality/gates/FE-GATE-0NN.txt에 쌓인다. 실패를 고칠 때마다 다시 돌리고 회차를 남긴다 (1103 README 14.5절 표).

3.1 가끔 떨어지는 게이트

  • 다시 돌려 통과시킨 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다(05장 5절). 1103 조치에서 FE-GATE-008이 "세 번째 실행에서 통과"로 적혔던 두 실패는 둘 다 테스트 결함이었다(1103/11-09, 1103/11-10).
  • 원인을 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0을 적는다. FE-GATE-008은 연속 3회였다(1103 README 14.5절 12~14회차).

3.2 desktop에서 FE-GATE-013

desktop에서는 FE-GATE-013의 test:system 중 provider 테스트 18건이 호스트 원인으로 실패한다. ssh 셸에서 비특권 user namespace가 막혀 bwrap --unshare-net이 실패한다. 사전 점검은 이 조건을 보지 않고 PASS를 낸다(1105/12-01).

  • 러너 전제를 어떻게 할지는 결정 대기다(1105 README 7절 D4). 결정 전까지 merge 판정 보고에는 FE-GATE-013을 "환경 실패"로 적고, 실패 18건이 모두 그 원인인지와 뒤 명령 7개의 결과를 함께 적는다(1105 README 11.1절 표).
  • 시스템 설정은 바꾸지 않는다.

4. CI env에서만 나는 실패

로컬 env로 통과해도 workflow env에서 실패하는 결함이 반복됐다(부록 P-05).

발견 모양
1103/11-06 e2e가 build id를 "local-build"로 고정했다. workflow는 VITE_BUILD_ID를 넣으므로 FE-GATE-008이 실제 CI에서 항상 실패
1103/11-07 workflow 전역 env의 빌드 식별값이 vitest와 dev server로 새어, merge 게이트 다섯 개가 실제 CI에서 항상 실패
1103/11-08 CI=true가 테스트 안의 로컬 빌드까지 release 빌드로 검사되게 해, merge 게이트 셋이 workflow env에서 실패

기준:

  • merge 판정은 3절 env로만 한다.
  • 테스트는 바깥 env에서 무엇을 물려받는지 고정한다. 테스트가 직접 띄우는 빌드·서버의 env는 테스트가 정한다 (04장 6절).

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

사전 점검·준비 단계가 "통과"를 내고, 그 뒤 실제 단계가 원인 없는 원문 오류로 실패하는 결함이다(부록 P-07).

  • 1105/12-01: scripts/check-system-test-prerequisites.ts가 실행 파일·cgroup·systemd bus만 보고 bwrap을 실제로 돌리지 않는다. 그래서 PASS 뒤 provider 테스트가 bwrap 원문 오류로 떨어진다.
  • 1103/11-04: test:system이 git worktree에서 .git 때문에 실패하는데 사전 점검은 PASS를 낸다.

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

6. 문서 검사

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

  • 범위: docs/README.md와, 그 §1이 링크한 문서. 폴더 링크는 그 폴더 바로 아래 .md만 본다. 이 매뉴얼은 §1에서 링크되어 범위 안이다(README 결정 M-3).
  • 보는 것: 백틱 안의 repo 경로(:줄 꼬리는 떼고 본다), 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크, corepack pnpm <script>와 백틱 안 <prefix>:<name> 꼴의 package script, FE-GATE-0NN ID가 실제로 있는가.
  • 보지 않는 것: 설명·수치가 코드와 맞는가.
  • 예외: git이 무시하는 생성 산출물, 복사한 프로젝트가 지운 작업 이력(루트 README.md 「Files you can delete after copying」의 경로)은 없어도 된다.
  • 짝 백엔드 경로: clean-architecture-backend-template/<경로> 꼴의 경로와 그 repo로 나가는 링크는 옆 checkout이 있을 때만 확인한다. 없으면 실패가 아니라 "확인 못 함"으로 남긴다. 옆 checkout이 다른 커밋이면 실패한다. desktop의 옆 백엔드 checkout은 pin과 다른 커밋이라, desktop에서는 백엔드 참조 몇 곳 때문에 실패할 수 있다(1105 README 11.1절, 1105/12-02). 그때는 실패가 그 참조뿐인지 확인해 적는다.
  • 도는 곳: FE-GATE-017은 documentation 단계라 merge 체인 밖이다. 그러나 같은 검사가 merge 게이트 안에서도 돈다. tests/unit/documentation-readiness.test.ts가 문서를 복사해 검사를 돌리고(FE-GATE-005), 기능을 지우거나 더한 사본을 만드는 FE-GATE-020의 두 드릴(test:sample-removal, test:feature-scaffold)도 문서를 복사해 돌린다 (scripts/lib/removal-fixture.ts 50~60줄). 그래서 §1 문서의 경로 하나가 틀리면 merge가 막힌다.
  • 샘플과 함께 지워지는 경로는 새 문서에서 이름으로 쓰지 않는다. 참조 기능 폴더, 그 기능의 테스트, 기능 모양 기준선 파일과 측정 스크립트 같은 것이다(목록: scripts/test-sample-removal.ts의 머리말과 SAMPLE_EXTRAS). 백틱으로 쓰면 샘플 제거 사본에서 "없는 경로"가 되어 FE-GATE-020이 실패한다. 백틱을 빼면 그 경로가 검사 밖으로 나간다. 1103 조치가 참조 기능 경로 26줄을 백틱 밖으로 옮긴 것이 검사 약화로 기록됐다(1105/14-03, Low·P3, 미조치). 그래서 그 경로를 소유한 문서의 절을 가리킨다(예: 06장 1절).
  • 돌리는 법: corepack pnpm verify:documentation. 옆 checkout 없는 임시 worktree에서 pnpm으로 돌리면 pnpm이 node_modules 재설치를 시도하다 멈춘다. 그런 곳에서는 node scripts/verify-documentation-readiness.ts로 직접 돌린다(1105 README 11.5절).
  • 문서 관련 unit 테스트: tests/unit/documentation-readiness.test.ts, tests/unit/deletable-history-documents.test.ts, tests/unit/changelog-review-ids.test.ts.

7. 소유자 환경

이 절은 이 repo 소유자의 기계에 묶인 규칙이다. 복사한 프로젝트는 이 절을 자기 환경으로 바꾼다(README 결정 M-4). 출처: 2026-11-05 사용자 지시와 그날의 실행 기록(1105 README 11절).

  • 테스트·게이트는 노트북에서 돌리지 않는다. 노트북은 다른 작업과 함께 돌아 전체 테스트에 죽는다. ssh desktop의 /home/donghyeon/workspace/clean-architecture-frontend-template 에서 돌린다.

  • 변경은 git으로 보낸다. push하지 않은 브랜치는 노트북에서 직접 보낸다. remote는 더하지 않는다.

    git push desktop:/home/donghyeon/workspace/clean-architecture-frontend-template <branch>:refs/heads/<branch>
    

    보내기 전에 desktop에서 git status가 비었는지 본다. 바뀐 파일이 있으면 덮어쓰지 말고 먼저 확인한다.

  • PATH. 비대화형 ssh에는 node가 없다. export PATH=$HOME/.nvm/versions/node/v24.14.0/bin:$PATH를 먼저 한다.

  • 잠금. 무거운 실행은 flock /tmp/claude-gates/heavy.lock으로 감싸 하나씩 돌린다. 백엔드 세션도 같은 desktop에서 같은 잠금을 쓴다.

  • merge 단계 runner. desktop의 /tmp/claude-gates/run-merge-stage.sh 가 3절의 env를 넣고 게이트마다 잠금 아래 ci:gate를 돌려 summary.txt와 게이트별 로그를 남긴다. GATES="005 008"처럼 일부만 돌릴 수 있다. 오래 걸리므로 nohup setsid로 띄우고 끝나기를 기다린다.

  • 끝나면 되돌린다. 다른 세션도 같은 checkout을 쓴다. 실행이 끝나면 checkout을 처음 브랜치로 되돌리고 git status가 비었는지 본다.

  • 노트북에서 꼭 돌려야 하면 main checkout이 아니라 깨끗한 복제본(git clone --no-hardlinks, 그 뒤 corepack pnpm install --frozen-lockfile --offline)에서 돌린다. 노트북은 inotify 감시가 부족해 vite가 들어가는 게이트에 CHOKIDAR_USEPOLLING=1을 준다. 시스템 한도는 바꾸지 않는다.

지금 이해하면 되는 것

  • 커밋 전 8개, 통합 때 5개 더, merge 판정은 ci:gate로 14개를 workflow env(CI=true 포함)로.
  • 다시 돌려 통과한 것은 통과가 아니다. 원인을 찾고, 고친 뒤 연속 실행으로 확인한다.
  • 실행은 desktop에서, 잠금 아래에서, 끝나면 checkout을 되돌린다.