# 운영 — 게이트 실행, desktop 검증, 릴리스, 파생 프로젝트 게이트를 어디서 어떻게 돌리고 결과를 어떻게 남기는지, 릴리스와 파생 프로젝트 동기화를 어떻게 하는지의 절차다. 무엇을 돌릴지는 [reference/gates.md](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](README.md) 2절). 그것은 [improve.md](improve.md) 구조 변경으로 하고, 거짓 통과 막기([reference/gates.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 단계는 스크립트가 알아서 옮긴다. ```bash 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](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](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 -- `, `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 게이트 실행과 기록 1. 단계를 고른다([reference/gates.md](reference/gates.md) 2절). merge 가능을 말하려면 `scripts/verify.sh merge`다. 게이트 하나는 `scripts/verify.sh gate FE-GATE-005`, package script 몇 개는 `scripts/verify.sh script verify:documentation`. 2. 돌리기 전에 `ssh desktop uptime`으로 부하를 본다. 높으면 기록에 적는다. 3. 돌린다. stage는 실패가 있어도 끝까지 돌고 게이트마다 rc와 초를 적는다(`ci:gate`는 한 게이트 안에서는 첫 실패에서 멈춘다. 뒤 명령이 필요하면 `parts`). 4. 기록한다: 단계·게이트, rc, 시간, 핵심 숫자(테스트 수, 초기 JS 바이트, 파일 수), 실행 직전 부하, 대상 트리 해시(`summary.txt` 첫 줄), 로그 경로. 숫자는 로그에서 옮긴다. 5. 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다. 다시 돌려 통과한 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다. 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0과 횟수를 적는다. 6. `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](delegate.md) 4.3절(소유자 환경)뿐이다. `docs/ledger/estimates.jsonl`은 줄을 비우고 자기 줄을 쌓는다. - 파생 프로젝트 repo에는 쓰지 않는다(그 일은 그 repo의 세션이 한다). 템플릿 쪽에서는 이행 안내와 확인 방법만 준다. ## 5. 완료 기준 - 돌린 단계마다 rc, 시간, 부하, 트리 해시, 로그 경로가 기록에 있다. 숫자는 로그에서 옮겼다. - merge 가능을 말했으면 merge 단계 전부가 `CI=true` env로 통과했고, 트리 해시가 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](README.md) 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 exec -- node scripts/run-vitest.ts run <파일>`로 돌린다(4.1절). - 한 테스트 파일을 `pnpm exec vitest run `로 돌려 생성물이 없어 실패한다. `node scripts/run-vitest.ts run `을 쓴다. - 캐시된 산출물(`dist/`, `artifacts/`)이 남은 checkout에서 돌려 다른 실행의 결과를 읽는다. `scripts/verify.sh`의 새 worktree를 쓴다. - 게이트 로그 대신 `ci:gate`의 마지막 줄만 옮긴다. `gate-artifacts/FE-GATE-0NN.txt`에서 숫자를 옮긴다.