문제: 하네스 PR #13이 더한 작업 매뉴얼·규칙은 이 브랜치가 바꾼 문서 체계의 옛 모습을 적는다. - 옛 경로: `docs/architecture/decisions/`, `docs/superpowers/`, 루트 `SPEC.md`, 목표 설계였던 `docs/testing/frontend-platform-testing-strategy.md` - 옛 검사 범위: 「docs/README.md 1절이 링크한 문서, 폴더 링크는 바로 아래 .md만」. 지금 verify:documentation은 살아 있는 문서 전부를 보고 언어· 문체·숫자·머리 블록도 본다 - 옛 docs/README.md 절(1절 묶음 / 2절 목표 설계 / 3절 작업 이력)과 README 절 이름(「Support scope」, 「Updating a copied project」) - #13의 template-contract-documents 시험은 README 지워도 되는 표를 `docs/superpowers/` 행으로 찾는데, 그 행은 이제 없다 고른 방법: 그 줄만 새 위치·새 절 이름·새 범위로 고친다(.claude/rules/docs.md, docs/work의 docs-writing·operate·research-design·reference 다섯, docs/problem-statement.md). 시험은 `docs/history/` 행으로 표를 찾는다. docs/work/evidence.md는 백엔드처럼 매뉴얼 규칙의 근거 기록이라 고치지 않고 `HISTORY_HOLDERS`에 넣어 참조·숫자 검사에서 뺀다. 위험: 하네스 문서의 다른 문장은 건드리지 않았다. 하네스 세션이 쓴 뜻을 바꾸지 않으려는 것이다. 검증: 문서 검사 여섯이 0건, `git grep -n -E 'docs/superpowers|architecture/decisions'`가 기록·CHANGELOG·출처 표시 밖에서 0건.
101 lines
11 KiB
Markdown
101 lines
11 KiB
Markdown
# 운영 — 게이트 실행, 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절).
|
|
- **desktop의 FE-GATE-013.** ssh 셸에서 비특권 user namespace가 막혀 `test:system`의 provider 테스트가 호스트 원인으로 실패한다. 시스템 설정은 바꾸지 않는다. `scripts/verify.sh parts FE-GATE-013`으로 그 게이트의 명령을 하나씩 끝까지 돌려, 실패가 호스트 전제 하나뿐인지와 뒤 명령의 결과를 함께 적는다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다([reference/decisions.md](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 게이트 실행과 기록
|
|
|
|
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로 통과했고(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](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 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`에서 숫자를 옮긴다.
|