Files
clean-architecture-backend-…/docs/work/operate.md
T
DongHyeonka c8db79a78f docs(work): 쌓인 매뉴얼 빈틈과 조사 문서의 매뉴얼 규칙을 한 묶음으로 넣는다
cold-read 3회차(수정 세션 넷의 빈틈 9건), 통합·배치·문서 체계·번역 세션이
「매뉴얼에서 답을 못 찾았다」고 적은 곳, 프론트 총괄 교훈 둘, design-docs
repo-structure 01·02·03의 「매뉴얼에 넣을 규칙」 중 백엔드 몫이 아직 매뉴얼에
없다. 세션마다 같은 판단을 스스로 다시 했다.

넣은 자리(항목별 표는 PR 본문):
- delegate.md: upgrade 안내 「커밋:」 줄은 총괄이 합칠 때 적는다, 두 라운드
  연속 결함이면 조사로, 병합 커밋에는 충돌 해결만, 자주 하는 실수 둘(충돌
  없음은 merge-tree로, PR 만들기 전 head 브랜치의 PR을 API로).
- improve.md: 절차 문서 결함과 대기 결함의 RED 모양, 테스트 Javadoc도 고친다,
  그 코드를 지키는 lane 찾기, 두 라운드 연속 결함이면 조사로.
- docs-writing.md: 문체·용어·언어 범위(코드 주석 제외), check-docs도 돌린다,
  이동 커밋에 참조 수정을 같이, 번역 기준(영어 절 제목, 레지스트리 yaml,
  머리말 없는 runbook, MANIFEST는 납품 당시 해시).
- operate.md 4.1: zsh 파이프 rc와 자기 실행 멈추기, runner 사실(capacity 1,
  12코어·31GB, 잠금 밖), 취약점 DB는 설치가 아니다, 형식은 나누기 전에.
- reference/gates.md: 커밋하는 수정의 lockfile, 처음 켜진 lane의 이전 실패,
  lychee·buf·trivy 공식 이미지, smoke 이미지가 이 트리에서 만들어졌음,
  원래 있던 실패 가리기(세 번), 순서 의존 재현, 공유 잠금 기다리기, 증거
  실행의 --no-build-cache, 거짓 통과 두 줄(OOM 재시작, 조건 안 set -e),
  새 7절 「workflow·검사 스크립트를 더할 때」.
- reference/review-criteria.md: 관점 2·4·9·18·20·21·23·26·27의 볼 곳과 결함,
  Important 예시, leaf 변경 체크리스트(README 다섯 칸, 문서 검사).
- reference/decisions.md: brief와 결정 원문이 다르면 원문, 취약점 DB 기본값.
- reference/terms.md(새): 영어 그대로 쓰는 말과 「개발 환경」의 뜻.
- README.md 2절(최상위 폴더는 큼), new-feature.md(테스트 환경·release/는
  leaf 안), docs/ci-cd/template-vs-consumer.md(docs-check·link-check·
  check-repo-layout은 파생 서비스도 유지), settings-and-runtime 규칙.

버린 대안: 항목마다 따로 커밋(소유자 결정: 매뉴얼 보강은 한 묶음).

위험: 정한 기본값 둘은 소유자 확인 대상이다: 취약점 DB 받기 허용,
병합 커밋에 충돌 해결만. operate.md는 143/150줄, improve.md 144/150줄로
상한에 가깝다.

검증: check-work-docs(진입 경로 최대 269/350), check-docs, unittest 모두 rc=0.
2026-11-07 22:21:04 +09:00

144 lines
13 KiB
Markdown

# 운영 — 게이트 실행, desktop 검증, 릴리스, 파생 서비스
검증을 실제로 돌리고, 릴리스하고, 템플릿 변경을 파생 서비스에 넘기는 절차다. 무엇을 돌릴지는 [reference/gates.md](reference/gates.md)가 정하고, 이 playbook은 어디서 어떻게 돌리는지 정한다.
## 1. 언제 쓰나
- 다른 playbook의 검증 단계에서 Gradle·Docker·테스트·게이트를 돌릴 때(4.1·4.2절).
- 여러 묶음을 합친 트리를 라운드 끝 게이트로 검증할 때.
- 릴리스 태그 전 확인을 할 때(4.3절).
- 템플릿 변경을 파생 서비스가 받을 수 있게 준비할 때(4.4절).
- 게이트 자체(build-logic, workflow)를 고치는 일은 [improve.md](improve.md)다.
## 2. 받아야 할 것
- 대상 브랜치와 커밋 sha. desktop은 push된 브랜치나, 노트북이 보낸 패치(4.1절 「push 전에 검증하기」)를 받는다.
- 자기 브랜치 push 허용 여부. brief 7절이 push를 허용하지 않았으면 패치로 검증한다. main push는 허용되지 않는다.
- 돌릴 게이트 목록(없으면 [reference/gates.md](reference/gates.md) 2절로 정한다)과 로그를 둘 이름.
## 3. 크기와 사고 순서
- 게이트를 돌리고 기록하는 일은 보통 작음이다: 목적 한 줄, 대상 확인, 실행과 기록.
- 라운드 끝 전체 묶음, 첫 실행이 실패해 원인을 찾는 일은 중간이다. 실패 원인 찾기는 `superpowers:systematic-debugging`.
- 릴리스와 파생 서비스 쪽 병합은 소유자가 정한다.
## 4. 절차
### 4.1 실행 위치 — 소유자 환경
> 이 절은 이 repo 소유자의 기계에 묶인 규칙이다. 공용 정본은 design-docs `conventions/delegation-loop.md` 11절이다. 다른 환경(파생 서비스 등)은 이 절만 자기 환경으로 바꾼다.
- 노트북에서는 git, grep, 파일 읽기, 문서 편집, `python3 scripts/*.py` 검사만 한다. **Gradle, Docker, Testcontainers, 테스트, 게이트, 성능 측정은 desktop에서 돌린다.** 예외는 편집 훅의 한 파일 포매터 하나다(Gradle 없이 JVM 한 번, 캐시에 있는 jar만. 소유자 결정 2026-11-07, `scripts/hooks/README.md`).
- desktop의 Gradle·Docker 실행은 모두 공유 잠금 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 짝 프론트 repo도 같은 desktop에서 같은 잠금을 쓴다.
- desktop의 기존 checkout `~/workspace/clean-architecture-backend-template`은 여러 세션이 함께 쓴다. 그 `stash@{0}`는 소유자의 보관분이다. 건드리지 않는다. `git stash pop`·`drop`·`clear`와 이름 없는 `git stash`를 쓰지 않는다.
- design-docs repo는 노트북 `~/workspace/desktop-server-git/design-docs`에 있다.
- desktop 기본 셸은 zsh다. 파이프의 rc는 `bash -o pipefail -c '<명령> | tee <로그>'; echo "rc=$?"`로 받는다(zsh에는 `PIPESTATUS`가 없다). 자기 실행을 멈출 때는 시작할 때 남긴 PID로 `kill <PID>`를 쓴다. `pkill -f <경로>`는 그 경로가 든 ssh 명령줄 자신과도 맞아 세션을 끊는다.
- CI runner(2026-11-07): Gitea Actions가 켜졌고, desktop에 `desktop-runner` 하나(`gitea/runner` dind, `capacity: 1`, label `ubuntu-latest`)가 돈다. desktop은 12코어·31GB다. CI job은 공유 잠금을 쓰지 않으므로, 손으로 돌린 게이트가 느리면 `docker ps`로 runner job이 함께 도는지 본다.
절차:
```bash
# 1) 노트북: 검증할 변경을 자기 브랜치에 커밋하고 push한다(brief가 허용한 경우)
git push origin <자기 브랜치>
# 2) desktop: 기존 checkout을 건드리지 않게 따로 worktree를 만든다
ssh desktop
cd ~/workspace/clean-architecture-backend-template
git fetch origin
git worktree add ~/workspace/<작업 이름> origin/<자기 브랜치>
mkdir -p ~/<작업 이름>-logs
uptime # 다른 빌드가 돌고 있는지 부하를 본다
# 3) 공유 잠금 아래에서 한 번에 하나씩 돌리고 rc와 로그를 남긴다
cd ~/workspace/<작업 이름>/src
flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?"
# 4) 끝나면 worktree를 지운다
cd ~/workspace/clean-architecture-backend-template
git worktree remove ~/workspace/<작업 이름>
```
- 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. 같은 worktree의 다음 실행이 결과 XML을 덮어쓰니, 명령이 끝날 때마다 그 태스크의 `build/test-results/<태스크>/`를 로그 폴더로 복사한다(세는 법은 [reference/gates.md](reference/gates.md) 4절).
- RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니다. 받아도 되고, 받은 DB의 갱신 시각을 기록에 적는다.
- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(dev lane overlay `src/app-bootstrap/compose-lanes/dev.yaml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`compose.yaml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`.
- Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다.
**push 전에 검증하기.** push한 커밋은 고쳐 쓰지 않는다. 그래서 커밋 본문에 desktop 결과를 쓰거나 push가 허용되지 않았으면, 커밋 전에 바꾼 것을 패치로 보내 같은 트리에서 돌린다.
```bash
# 노트북: 커밋할 파일만 stage하고(git status로 확인) 트리 해시를 적어 둔다
git add <바꾼 파일>... && git status --short && git write-tree
# desktop: 기준 커밋(push된 커밋)에서 worktree를 만든다
ssh desktop 'cd ~/workspace/clean-architecture-backend-template && git fetch origin && git worktree add --detach ~/workspace/<작업 이름> <기준 커밋>'
# 노트북: 패치를 보내 얹는다. 마지막 줄이 위 트리 해시와 같아야 한다
git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업 이름> && git apply --index && git write-tree'
```
- 그다음 위 3) 4)대로 돌리고 지운다. 결과를 본문에 적어 커밋한 뒤 `git rev-parse HEAD^{tree}`가 같은 해시인지 본다. 같으면 desktop이 돌린 트리가 그 커밋이다.
- RED는 같은 방법으로 테스트 파일만 stage해 보낸다. 한 파일의 일부만 stage하는 법은 design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」이다.
- 형식은 편집 훅이 파일마다 맞추므로 보통 바뀌는 것이 없다. 그래도 커밋을 나누기 전에 확인한다(나눈 뒤에 고치면 앞 커밋을 다시 만들어야 한다). 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다.
```bash
ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --console=plain'
ssh desktop 'cd ~/workspace/<작업 이름> && git diff --binary' | git apply --index && git write-tree # 노트북
ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' # 같은 해시여야 한다
```
- 검증한 트리를 커밋 여럿으로 나누면 중간 커밋마다 그 커밋의 트리를 같은 방법으로 보내 그 커밋이 바꾼 leaf의 `check`(문서·스크립트만 바꿨으면 그 검사)를 돌린다. PR 단계 묶음 같은 무거운 게이트는 마지막 트리에서 한 번 돌린다.
### 4.2 게이트 실행과 기록
1. [reference/gates.md](reference/gates.md) 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절의 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것, (다) 로컬 도구가 없는 것 전체다.
2. 잠금을 얻은 뒤 1분 부하를 적고 돌린다. 한 번에 하나씩이다.
3. 첫 실행이 실패하면 원인을 찾아 고치고 다시 돌린다. 첫 실행과 다시 돌린 결과를 둘 다 적는다.
4. 결과를 [reference/gates.md](reference/gates.md) 4절 형식으로 적는다: 게이트, rc, 시간, 직전 부하, 로그 경로, 대상 커밋.
5. 보고한 태스크 이름과 테스트 수가 로그에 있는지 grep으로 확인한다.
### 4.3 릴리스
- 릴리스는 `v*` 태그 push로 시작한다(`.github/workflows/release.yml`). 태그와 push는 소유자가 한다.
- 태그 전에 그 커밋에서 `./gradlew :releaseCheck -PgitRevision=<sha> --console=plain`을 desktop에서 돌린다. sha 없이 돌리면 설계대로 실패한다.
- 태그는 PR 게이트와 main 단계를 이미 통과한 main 커밋에서 자른다. 그래서 `releaseCheck`는 `ci`를 다시 돌리지 않는다.
- 이미지 서명·SBOM은 workflow가 한다(cosign keyless).
### 4.4 파생 서비스에 템플릿 변경 넘기기
- 파생 서비스는 이 템플릿을 받아 도메인을 채운 repo다. 템플릿 변경을 두 방식으로 받는다: 기준 커밋을 적은 tracked snapshot에 3-way로 반영하거나(`template.lock.json`), `git merge upstream/main`을 한다.
- 템플릿 쪽에서 할 일: 파생 서비스가 따라 고쳐야 하는 변경은 `docs/upgrade/`의 안내에 행을 더하고 커밋 제목에 `!`를 단다. 안내 문서 형식은 `docs/upgrade/2026-11-maturity-review.md`다.
- 파생 서비스가 유지할 게이트와 지워도 되는 템플릿 전용 게이트는 `docs/ci-cd/template-vs-consumer.md`다.
- 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두고, 지도(`AGENTS.md`)에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다.
- `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`, `skills/`, `agents/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 `.env` 읽기 차단 같은 권한을 바꾸려면 그 파일을 자기 repo에서 고친다.
- 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다.
## 5. 완료 기준
- brief가 요구한 게이트마다 rc, 시간, 직전 부하, desktop 로그 경로, 대상 커밋이 있다.
- 못 돌린 게이트는 이유가 있다. 캐시로 통과한 것과 집계가 뺀 lane을 적었다.
- desktop에 만든 worktree를 지웠다(`git worktree list`에 없다). 기존 checkout의 브랜치와 `stash@{0}`가 그대로다.
- 노트북에서 Gradle·Docker를 돌리지 않았다.
## 6. 하지 말 것
- 노트북에서 Gradle·Docker·테스트를 돌리지 않는다.
- 잠금 없이 desktop에서 무거운 명령을 돌리지 않는다.
- desktop 기존 checkout에서 브랜치를 바꾸거나 stash를 꺼내지 않는다. 자기 worktree를 쓴다.
- 다른 브랜치나 main에 push하지 않는다. 태그를 만들지 않는다.
- 첫 실행 실패를 지우고 두 번째 성공만 보고하지 않는다.
## 7. 막혔을 때
- desktop에 접속할 수 없거나 잠금이 오래 풀리지 않으면 기다린 시간과 상태(`uptime`, 잠금을 쥔 프로세스)를 적어 묻는다. 노트북에서 대신 돌리지 않는다.
- 게이트가 이 일과 무관해 보이는 이유로 실패하면 같은 게이트를 기준 커밋에서 돌려 원래 있던 실패인지 가린다. 원래 있던 실패면 보고하고 그 게이트만 멈춘다.
## 8. 보고 형식
[README](README.md) 6절에 더해 [reference/gates.md](reference/gates.md) 4절 표를 붙인다. desktop 정리 결과(지운 worktree, checkout 브랜치, `stash@{0}` 상태)를 한 줄로 적는다.
## 9. 자주 하는 실수
- desktop 기존 checkout에서 브랜치를 바꿔 다른 세션의 작업을 방해한다. 자기 worktree를 만든다.
- 짧게 끝난 실행을 통과로 적는다. 캐시 재사용인지, 태스크가 실제로 돌았는지 로그로 확인한다.
- 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸린다. 태스크마다 붙인다(`:domain-core:test --rerun :application-core:test --rerun`). `ci` 같은 집계 태스크는 새 worktree에서 `--no-build-cache`로 돌린다([reference/gates.md](reference/gates.md) 3절).
- 커밋하고 push한 뒤 desktop에서 돌려, 결과를 커밋 본문에 못 넣는다. push 전에 패치로 검증한다(4.1절).