이 대화를 모르는 서브에이전트에게 AGENTS.md부터 읽혀 두 일(새 기능 만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가 나왔다. 고친 것: - new-feature: 생성·기준선 다시 쓰기를 desktop에서 하고 --apply-back으로 받는다. FE-GATE-020은 제품 기능을 지우지 않으므로 그 기능의 제거 드릴을 따로 돌린다(사실과 달랐다). 생성 명령이 만드는 첫 context는 중간이다. 새 기능은 FE-GATE-026도 돌린다. 매뉴얼 예시 이름이 오면 묻는다. 초기 JS 기록의 파일을 적는다. - gates·improve·AGENTS: FE-GATE-013 결정 대기 동안의 merge 판정 문구, PR·diff 리뷰도 merge 단계 전부를 돌린다, diff 리뷰의 base·head 규칙과 ID 체계와 둘 곳, 라운드 세는 법, "빠른 게이트 8개"를 "검사 8개 (package script)"로. - review-criteria: 발견 한 개의 칸(가이드 36.3절 줄임)과 통제 M0~M4· 증거 E0~E4의 뜻을 옮긴다. 가이드 없이 판정할 수 있다는 문장을 맞춘다. - README·CLAUDE·decisions·rules/docs·skills: 최근 리뷰 README의 실제 절 이름, 사고 순서 흔적의 여섯 칸과 design-docs 위치, 보고 칸과 말투의 정본, `docs/work/README.md`를 가리키게, 리뷰 README 조치 절 예외, 스킬의 새 명령 모양. 고치지 않은 것: 세션에 주입된 옛 CLAUDE.md(시험 세션이 이 브랜치 전에 시작했다). 검증: scripts/verify.sh docs rc=0, scripts/verify.sh hooks 통과.
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절). -
desktop의 FE-GATE-013. ssh 셸에서 비특권 user namespace가 막혀
test:system의 provider 테스트가 호스트 원인으로 실패한다. 시스템 설정은 바꾸지 않는다.scripts/verify.sh parts FE-GATE-013으로 그 게이트의 명령을 하나씩 끝까지 돌려, 실패가 호스트 전제 하나뿐인지와 뒤 명령의 결과를 함께 적는다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다(reference/decisions.md). -
노트북에서 꼭 돌려야 하면 노트북 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「Updating a copied project」와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로 통과했고(FE-GATE-013은 4.1절대로 적었다), 트리 해시가 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에서 숫자를 옮긴다.