Files
clean-architecture-backend-…/docs/work/operate.md
T
DongHyeonka d46bab9659
pr / gradle (pull_request) Successful in 16m42s
pr / vulnerabilities (pull_request) Successful in 37s
pr / done (pull_request) Canceled after 0s
ci!: workflow를 pr·main·release 셋으로 접고 단계 job 모양만 검사한다
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로
나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations·
TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸
모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는
한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절).

소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다.

- .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와
  `./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities`
  (trivy), 필수 검사 하나 `done`.
- main.yml: push마다 mainCheck·integrationCheck·build-logic 시험·
  configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서
  PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos,
  jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck.
- release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea
  레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명
  앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은
  `needs: jpa-release-gate`가 대신한다.
- 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 +
  저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다.
- verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의
  계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로
  바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에
  선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른
  run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는
  needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른
  working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job
  하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다
  (build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를
  TestKit 시험으로 둔다.
- scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업
  트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의
  손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트
  포워더·configuration cache 스크립트다.
- workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease
  RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을
  .gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다.
- 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic
  AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조,
  docs/upgrade B-57~B-61.

버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수
없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기
(결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다.

위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지
않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를
다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다.
`.github/workflows/messaging-certification.yml`은 메시징 분리 작업이
지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이
없어 실제 태그로는 돌려 보지 않았다.

BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법,
릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity-
review.md B-57~B-61을 따른다.
2026-11-08 21:55:43 +09:00

15 KiB

운영 — 게이트 실행, desktop 검증, 릴리스, 파생 서비스

검증을 실제로 돌리고, 릴리스하고, 템플릿 변경을 파생 서비스에 넘기는 절차다. 무엇을 돌릴지는 reference/gates.md가 정하고, 이 playbook은 어디서 어떻게 돌리는지 정한다.

1. 언제 쓰나

  • 다른 playbook의 검증 단계에서 Gradle·Docker·테스트·게이트를 돌릴 때(4.1·4.2절).
  • 여러 묶음을 합친 트리를 라운드 끝 게이트로 검증할 때.
  • 릴리스 태그 전 확인을 할 때(4.3절).
  • 템플릿 변경을 파생 서비스가 받을 수 있게 준비할 때(4.4절).
  • 게이트 자체(build-logic, workflow)를 고치는 일은 improve.md다.

2. 받아야 할 것

  • 대상 브랜치와 커밋 sha. desktop은 push된 브랜치나, 노트북이 보낸 패치(4.1절 「push 전에 검증하기」)를 받는다.
  • 자기 브랜치 push 허용 여부. brief 7절이 push를 허용하지 않았으면 패치로 검증한다. main push는 허용되지 않는다.
  • 돌릴 게이트 목록(없으면 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의 Gradle은 --no-daemon(다시 부르는 Gradle에는 GRADLE_OPTS=-Dorg.gradle.daemon=false)으로 돌린다. 오래 사는 daemon 하나가 여러 worktree의 빌드를 받으면 서로 호환되지 않는 compiler worker가 쌓여 메모리를 채운다(2026-11-08: worker 41개, 14.2GB, 스왑 4GB). scripts/verify.sh는 둘 다 한다. 노트북 개발자용 repo 기본값(src/gradle.properties)은 daemon을 그대로 쓴다.
  • 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이 함께 도는지 본다.
  • runner의 job 컨테이너 안의 localhost는 dind 데몬이 띄운 서비스가 아니다. Testcontainers는 이것을 스스로 처리한다. compose로 띄운 서비스에 localhost로 붙는 job은 scripts/ci/redis-topology.sh처럼 포트를 넘겨야 한다.

scripts/verify.sh가 아래 절차를 한다. scripts/verify.sh <단계>는 지금 작업 트리(커밋하지 않은 변경 포함)를 패치로 만들어 desktop에 보내고, 기준 커밋에서 새 worktree를 만들어 얹고, 트리 해시가 같은지 본 뒤 잠금 아래에서 단계를 돌리고, 로그를 ~/<브랜치 이름>-logs/<단계>.log에 남기고, worktree를 지운다. push하지 않는다. 단계와 돌리는 명령은 reference/gates.md 1절이다. 아래는 스크립트가 하는 일이고, 스크립트를 쓸 수 없을 때(다른 기준 커밋, 단계 밖의 명령 하나) 손으로 한다.

절차:

# 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 <게이트> --no-daemon --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 4절).
  • RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
  • workflow job이 도구를 내려받아 설치하는 단계(curl … | sh, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니다. 받아도 되고, 받은 DB의 갱신 시각을 기록에 적는다.
  • compose를 띄웠으면 지우기 전에 docker compose … down을 한다.
  • Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다.

push 전에 검증하기. push한 커밋은 고쳐 쓰지 않는다. 그래서 커밋 본문에 desktop 결과를 쓰거나 push가 허용되지 않았으면, 커밋 전에 바꾼 것을 패치로 보내 같은 트리에서 돌린다.

# 노트북: 커밋할 파일만 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에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다.
ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --no-daemon --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 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절의 scripts/verify.sh round, (나) workflow에만 있는 job 중 바뀐 영역의 것, (다) 로컬 도구가 없는 것 전체다.
  2. 잠금을 얻은 뒤 1분 부하를 적고 돌린다. 한 번에 하나씩이다.
  3. 첫 실행이 실패하면 원인을 찾아 고치고 다시 돌린다. 첫 실행과 다시 돌린 결과를 둘 다 적는다.
  4. 결과를 reference/gates.md 4절 형식으로 적는다: 게이트, rc, 시간, 직전 부하, 로그 경로, 대상 커밋.
  5. 보고한 태스크 이름과 테스트 수가 로그에 있는지 grep으로 확인한다.

4.3 릴리스

  • 릴리스는 v* 태그 push로 시작한다(.gitea/workflows/release.yml). 태그와 push는 소유자가 한다.
  • 태그 전에 그 커밋에서 scripts/verify.sh release를 돌리고, release.yml을 손으로 실행(workflow_dispatch)해 리허설한다. 손으로 실행하면 모든 release lane, 이미지 빌드, SBOM, 이미지 검사까지 돌고 push·서명은 하지 않는다.
  • 태그는 PR 단계와 main 단계를 이미 통과한 main 커밋에서 자른다. 그래서 releaseCheck는 ci를 다시 돌리지 않는다.
  • 이미지는 이 Gitea의 컨테이너 레지스트리(<서버>/<소유자>/caskeleton)에 올리고, digest를 cosign 키 쌍으로 서명한다(소유자 결정 2026-11-07: Gitea는 keyless 서명에 필요한 OIDC 토큰을 주지 않는다). repo secret PACKAGE_TOKEN·COSIGN_PRIVATE_KEY·COSIGN_PASSWORD는 소유자가 만든다. 서명 job은 확인에 쓴 공개 키를 로그에 남긴다. 배포 쪽 admission 정책은 그 공개 키로 확인한다.

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 6절에 더해 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 3절).
  • 커밋하고 push한 뒤 desktop에서 돌려, 결과를 커밋 본문에 못 넣는다. push 전에 패치로 검증한다(4.1절).