문제: 성능 lane 단언을 빌드가 강제하게 된 뒤에도 docs/work/는 옛 동작을 안내했다. gates.md 5절은 "desktop에서 -Pperformance.assertions.enabled=true를 준다. 안 주면 httpclient의 시간 단언 없이 통과한다"고 했고, 3절 라운드 끝 명령과 improve.md·operate.md의 「자주 하는 실수」도 그 속성을 맞추라고 했다. 지금은 convention이 단언을 켜고 true 아닌 값이나 skip이 있으면 테스트 전에 실패하므로, 그 문장은 틀렸고 그 속성은 필요 없다. 또 2026-11-06 B3 desktop ci rc=0은 캐시 결과(태스크 701개 중 403개)였는데, 그 사이 httpclient CircuitBreakerStatusAccountingTest 2건은 기준 커밋에서도 10번 중 10번 실패하고 있었다. 캐시 결과를 현재 통과의 증거로 쓰면 이런 기존 결함을 놓친다. 고른 방법: - gates.md 5절을 새 동작으로 다시 쓰고(정본 AGENTS.md 「Gradle 정책 권위」, docs/testing/TESTING_STRATEGY.md), 1절 표와 6절 거짓 통과 표를 맞췄다. 3절 명령에서는 그 속성을 뺐다. workflow도 이제 주지 않는다. - improve.md의 같은 실수 줄은 지웠다. 빌드가 막으므로 더는 실수가 아니다. - operate.md 「자주 하는 실수」의 그 줄 자리에 캐시 교훈을 넣었다: 기준 상태와 시간·환경에 민감한 테스트는 그 태스크를 --rerun으로 다시 돌린다. gates.md 6절에도 한 줄, 근거는 evidence.md 2절, 결정은 decisions.md 2.7, 장치는 defect-patterns.md A7에 더했다. 위험·한계: --rerun은 지정한 태스크 하나만 다시 돈다. 집계 태스크 전체를 캐시 없이 돌리려면 --rerun-tasks가 필요하고 시간이 훨씬 길다. 이 매뉴얼은 그 둘을 가르는 기준까지는 정하지 않았다. 검증 - python3 scripts/check-work-docs.py: rc=0, 본문 이력 ID 0줄, improve.md 131/150, operate.md 115/150 - python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md AGENTS.md: 깨진 링크 0
116 lines
8.2 KiB
Markdown
116 lines
8.2 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된 브랜치만 받을 수 있다.
|
|
- 자기 브랜치 push 허용 여부. desktop 검증이 필요한 일이면 brief가 허용해야 한다. 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에서 돌린다.**
|
|
- 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`에 있다.
|
|
|
|
절차:
|
|
|
|
```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를 쓴다.
|
|
- RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
|
|
- Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다.
|
|
|
|
### 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` 지도에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다.
|
|
- `.claude/settings.json`(Agent 도구 금지)은 추적 파일이라 함께 넘어간다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 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`으로 다시 돌린다.
|