main(5250ff95)의 PR #17·#18·#20·#21·#22를 받는다. 충돌 정리: - tests/setup.ts: main의 자식 프로세스 timeout 감시를 그대로 두고, Testing Library는 DOM이 있는 파일에만 불러오는 이 브랜치의 방식을 남긴다. - tests/system/ci-runner/ci-artifact-contract.test.ts: main이 같은 결함 (.claude 추적 파일 ENOENT)을 저장소 배치 등록부의 provider-fixture-skip 집합으로 이미 고쳤다. main 쪽을 받고 이 브랜치의f90ffb6c고침은 버린다. CHANGELOG의 그 행도 지운다. - 작업 매뉴얼·스킬(gates.md 3절, operate·improve·new-feature, evidence, desktop-gates·fe-testing 스킬): 기본은 시스템 컨테이너 경로, main의 D8 판정(사전 점검의 userns 제한 하나뿐이고 뒤 명령 모두 rc=0이면 merge 판정에서 뺀다)은 컨테이너를 띄울 수 없는 호스트에 쓴다. - 그 호스트에서 D8 절차를 그대로 돌릴 수 있게 scripts/verify.sh에 VERIFY_HOST_ENVIRONMENT=off(hostEnvironment 게이트를 이 호스트에서 바로 돈다)를 더하고 원격 실행에도 넘긴다. 시험 하나를 더한다. - decisions.md는 main 그대로(D8이 2.2절에 있어 이 브랜치의 O-21 행은 겹친다). 검증(노트북): python3 -m unittest discover -s scripts/tests 73개 통과, scripts/verify.sh docs rc=0. desktop merge 단계는 이 커밋에서 다시 돈다.
11 KiB
운영 — 게이트 실행, desktop 검증, 릴리스, 파생 프로젝트
게이트를 어디서 어떻게 돌리고 결과를 어떻게 남기는지, 릴리스와 파생 프로젝트 동기화를 어떻게 하는지의 절차다. 무엇을 돌릴지는 reference/gates.md다.
1. 언제 쓰나
- 게이트·테스트·빌드·브라우저 실행을 돌리거나 그 결과를 기록할 때. 다른 playbook의 검증 단계도 실행은 이 절차를 쓴다.
- merge 가능을 말하기 전, 릴리스 단계(
release·production)를 돌릴 때. - 파생 프로젝트(이 템플릿을 복사해 쓰는 repo)에 템플릿 변경을 넘길 때.
2. 받아야 할 것
- 돌릴 트리: 브랜치와 커밋, 또는 지금 작업 트리(커밋 안 된 변경 포함).
scripts/verify.sh는 지금 트리를 패치로 옮기므로 push가 필요 없다. - 돌릴 단계나 게이트 ID(
config/ci/gates.json). - 로그 이름(기본은
<브랜치>-<단계>). 보고에 쓸 이름을 정해--log로 준다.
3. 크기와 사고 순서
- 게이트를 돌리고 기록하는 일은 보통 작음이다. 1단계(무엇을 증명하려고 돌리나 한 줄)와 6단계(rc와 로그)만 남긴다.
- 게이트·workflow·
config/ci/자체를 바꾸는 일은 큼이다(README 2절). 그것은 improve.md 구조 변경으로 하고, 거짓 통과 막기(reference/gates.md 6절)를 같이 본다. - 스킬:
desktop-gates(이 절차의 실행 순서표), 완료 주장 전superpowers:verification-before-completion.
4. 절차
4.1 실행 위치 — 소유자 환경
-
pnpm·게이트·브라우저·빌드는 노트북에서 돌리지 않는다. 노트북은 다른 작업과 함께 돌아 전체 테스트에 죽는다(소유자 결정 2026-11-05). desktop(
ssh desktop, 12코어 31 GB)에서 돌린다. 노트북에서는 git·읽기·python3표준 라이브러리 검사(scripts/verify.sh docs,scripts/verify.sh hooks)만 한다. -
진입점은
scripts/verify.sh다. desktop 단계는 스크립트가 알아서 옮긴다.scripts/verify.sh merge --log fe-feature-x하는 일: 노트북의 지금 트리(커밋 안 된 변경 포함)를 기준 커밋(
origin/main과 갈라진 곳)에 대한 패치로 만들어 desktop에 보낸다 → desktop 공유 checkout(~/workspace/clean-architecture-frontend-template)에서 새 worktree를 기준 커밋으로 만든다 → 패치를 얹고 트리 해시가 노트북과 같은지 본다 → 그 트리를 커밋 하나로 만들어(깨끗한 HEAD, 훅을 거치지 않는commit-tree) →CI=true corepack pnpm install --frozen-lockfile --offline→flock /tmp/claude-gates/heavy.lock아래 같은 단계를 돈다 →/tmp/claude-gates/<로그 이름>/에summary.txt, 단계별 로그,gate-artifacts/(게이트 로그 사본),status-after.txt(게이트가 추적 파일을 바꿨는지)를 남긴다 → worktree를 지운다. -
공유 checkout을 건드리지 않는다. desktop의 그 checkout은 다른 세션도 쓴다. 브랜치를 바꾸지 않고,
stash를 건드리지 않는다. 어쩔 수 없이 그 checkout에서 돌려야 하면 잠금 안에서 바꾸고 끝나면 처음 브랜치로 되돌린 뒤git status가 비었는지 본다. -
잠금. 무거운 실행은 하나씩 돈다. 백엔드 세션도 같은 desktop에서 같은 잠금을 쓴다. 다른 세션이 잠금을 쥐고 있으면 기다리고, 기다리는 동안 다른 일을 한다. 오래 걸리는 단계는 background로 띄우고 끝나기를 한 번 기다린다(짧은 간격으로 확인하지 않는다).
-
CI env.
scripts/verify.sh는 게이트를 workflow와 같은 꼴의 env로 돌린다:CI=true,VITE_COMMIT_SHA(그 worktree의 HEAD),VITE_BUILD_ID,RELEASE_ID,CI_RUNNER_IMAGE(@sha256:digest 꼴).CI=true를 빼면 CI에서만 나는 실패를 놓친다(reference/gates.md 4절). -
FE-GATE-013.
scripts/verify.sh가 이 게이트를 시스템 컨테이너(scripts/run-in-system-container.sh) 안에서 돌린다. 호스트 Docker가 privileged 컨테이너를 띄운다. 시스템 설정은 바꾸지 않는다. 컨테이너를 띄울 수 없는 호스트에서만VERIFY_HOST_ENVIRONMENT=off scripts/verify.sh parts FE-GATE-013으로 호스트에서 명령을 하나씩 끝까지 돌려, 실패가 호스트 전제(user namespace) 하나뿐이고 뒤 명령이 모두 rc=0이면 merge 판정에서 뺀다. 게이트 충족은 조건을 갖춘 실행 환경에서 통과한 것으로만 센다(reference/gates.md 3절). -
노트북에서 꼭 돌려야 하면 노트북 checkout이 아니라 깨끗한 복제본(
git clone --no-hardlinks, 그 뒤corepack pnpm install --frozen-lockfile --offline)에서 돌리고 vite가 들어가는 게이트에CHOKIDAR_USEPOLLING=1을 준다. 노트북 checkout의.claude/worktrees/가test:system의 repo 복사와 vite 파일 감시를 깨뜨린다. -
desktop에서 파일을 만드는 명령(생성 명령, 기준선 다시 쓰기)은
--apply-back으로 결과를 노트북 작업 트리에 받는다:scripts/verify.sh script create:feature --apply-back -- <id>,scripts/verify.sh exec --apply-back -- <명령…>. 바뀐 파일은 언제나 로그 폴더의changes.patch에도 남는다. -
한 테스트 파일도 desktop에서:
scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>. -
desktop의 비대화형 ssh에는 node가 PATH에 없다. 스크립트가
~/.nvm/versions/node/v<.nvmrc>/bin을 앞에 붙인다. 손으로 돌릴 때도 같다.
4.2 게이트 실행과 기록
- 단계를 고른다(reference/gates.md 2절). merge 가능을 말하려면
scripts/verify.sh merge다. 게이트 하나는scripts/verify.sh gate FE-GATE-005, package script 몇 개는scripts/verify.sh script verify:documentation. - 돌리기 전에
ssh desktop uptime으로 부하를 본다. 높으면 기록에 적는다. - 돌린다. stage는 실패가 있어도 끝까지 돌고 게이트마다 rc와 초를 적는다(
ci:gate는 한 게이트 안에서는 첫 실패에서 멈춘다. 뒤 명령이 필요하면parts). - 기록한다: 단계·게이트, rc, 시간, 핵심 숫자(테스트 수, 초기 JS 바이트, 파일 수), 실행 직전 부하, 대상 트리 해시(
summary.txt첫 줄), 로그 경로. 숫자는 로그에서 옮긴다. - 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다. 다시 돌려 통과한 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다. 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0과 횟수를 적는다.
status-after.txt가 비어 있지 않으면 게이트가 추적 파일을 바꾼 것이다. 결함으로 적는다.
4.3 릴리스
- 릴리스 단계는
scripts/verify.sh release, 운영 승격 조건은scripts/verify.sh production이다. 단계와 게이트는config/ci/gates.json의stages가 정한다. release는 merge가 통과한 트리에서만 의미가 있다(needs). - 라우트 로딩·청크·초기 화면, 공급망·release 경로를 바꿨으면 merge만으로 부족하다. release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.
- 운영 복구 절차는
docs/runbooks/와docs/operations/가 정본이다. 런북 게이트(FE-GATE-021~025)는 production 단계다. - 태그 push·Gitea Actions 켜기·branch protection은 소유자가 한다.
4.4 파생 프로젝트에 템플릿 변경 넘기기
- 소유자 환경의 파생 프로젝트는 둘이고 받는 법이 다르다. 하나는 이력을 공유하지 않아 기준점을 지정한 3-way 병합을 일반 커밋 하나로 남기고, 다른 하나는 이력을 공유해 merge로 받는다. 각 repo의 기준점 파일과 지난 동기화 기록을 먼저 읽는다.
- 템플릿 쪽 안내는 루트
README.md「원본 업데이트 반영」과CHANGELOG.md의 미출시·버전 절이다. 다운스트림에 보이는 변경과 BREAKING 단계는 CHANGELOG에 적는다. - 루트
AGENTS.md·CLAUDE.md,.claude/,docs/work/는 템플릿 계약이라 파생 프로젝트도 받는다(소유자 결정 2026-11-07). 예전처럼CLAUDE.md를 걸러 내지 않는다. 파생 프로젝트가 바꿀 것은 이 문서 4.1절과 delegate.md 4.3절(소유자 환경)뿐이다.docs/ledger/estimates.jsonl은 줄을 비우고 자기 줄을 쌓는다. - 파생 프로젝트 repo에는 쓰지 않는다(그 일은 그 repo의 세션이 한다). 템플릿 쪽에서는 이행 안내와 확인 방법만 준다.
5. 완료 기준
- 돌린 단계마다 rc, 시간, 부하, 트리 해시, 로그 경로가 기록에 있다. 숫자는 로그에서 옮겼다.
- merge 가능을 말했으면 merge 단계 전부가
CI=trueenv로 통과했고, 트리 해시가 PR head 트리와 같다. - desktop 공유 checkout의 브랜치와
git status가 실행 전과 같고, 만든 worktree가 지워졌다.
6. 하지 말 것
- 노트북 checkout에서 pnpm·게이트·브라우저를 돌리지 않는다.
- desktop 공유 checkout의 브랜치를 바꾼 채 두거나
stash를 건드리지 않는다. - 게이트를 골라 돌린 결과로 merge 가능을 말하지 않는다.
CI=true를 빼고 돌린 결과로도 말하지 않는다. - 다시 돌려 통과한 결과를 "통과"로 쓰지 않는다. 시스템 설정(inotify 한도, user namespace)을 바꾸지 않는다.
- desktop에 env를 준 실행을 실제 CI 러너 결과로 쓰지 않는다. 증거에 「실제 CI 미검증」을 함께 적는다.
7. 막혔을 때
scripts/verify.sh가 rc=4(원격 준비 실패)를 내면 메시지를 본다: 기준 커밋이 desktop에 없으면 그 커밋을 push하거나 brief를 준 쪽에 묻는다. 트리 해시가 다르면 패치가 줄바꿈·권한을 잃은 것이다. 손으로 고치지 말고 원인을 적어 묻는다.- 잠금이 오래 풀리지 않으면 누가 쥐고 있는지(
ssh desktop 'ps -ef | grep flock') 적고 기다린다. 남의 실행을 죽이지 않는다. - 호스트 전제(브라우저, 글꼴, bwrap)로 실패하면 게이트 결함인지 호스트 문제인지 가린 뒤, 호스트 문제면 그 사실과 증거를 적고 소유자에게 묻는다.
8. 보고 형식
README 6절의 「확인」 줄을 이 표로 쓴다.
| 단계·게이트 | rc | 시간 | 핵심 숫자 | 부하 | 트리 | 로그 |
|---|---|---|---|---|---|---|
| merge / FE-GATE-005 | 0 | 134s | unit 3,090 통과 | 1.0 | summary.txt 첫 줄 |
/tmp/claude-gates/<이름>/FE-GATE-005.log |
9. 자주 하는 실수
- 노트북 checkout에서 한 파일 테스트쯤은 괜찮다고 돌린다. 한 파일도 desktop에서
scripts/verify.sh script나ssh desktop으로 돌린다. - 한 테스트 파일을
pnpm exec vitest run <file>로 돌려 생성물이 없어 실패한다.node scripts/run-vitest.ts run <file>을 쓴다. - 캐시된 산출물(
dist/,artifacts/)이 남은 checkout에서 돌려 다른 실행의 결과를 읽는다.scripts/verify.sh의 새 worktree를 쓴다. - 게이트 로그 대신
ci:gate의 마지막 줄만 옮긴다.gate-artifacts/FE-GATE-0NN.txt에서 숫자를 옮긴다.