Files
clean-architecture-backend-…/docs/work/operate.md
T
DongHyeonka c67c713177 feat(agents)!: Agent 금지를 풀고 결과만 돌려주는 서브에이전트 셋을 둔다
Agent 도구를 프로젝트 설정으로 막아 두어서, 넓은 검색·구조 리뷰·앱을
띄워 보는 확인처럼 결과만 받으면 되는 일도 메인 세션 컨텍스트에 쌓이거나
하위 세션을 따로 띄워야 했다. 소유자가 2026-11-07에 금지를 풀고, 결과만
받는 일은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야
하는 위임은 하위 세션으로 나누기로 정했다(design-docs
harness/01-harness-design.md 8절, 13절 Q5).

- .claude/settings.json에서 "Agent" deny를 지웠다(.env deny는 남긴다).
- .claude/agents/: arch-reviewer(HARD-STOP 1~5·registry를 읽기만 하고
  판정), verify-api(desktop에서 공유 잠금 아래 bootstrap-local.sh로 앱을
  띄워 health와 지정 endpoint를 호출), code-simplifier(동작을 바꾸지
  않는 단순화 제안). 셋 다 Edit·Write 도구가 없다.
- 나누는 기준을 AGENTS.md 「일하는 방식」과 docs/work/delegate.md
  4.3절에 썼다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는
  직접 하거나 하위 세션에 맡긴다.
- scripts/tests/test_claude_setup.py: deny가 없고, 정의마다 이름·발동
  조건·도구 목록이 있고, 쓰기 도구가 없고, verify-api가 desktop 절차를
  따르는지 본다.

버린 대안: 금지 유지(설계 권함, 소유자가 자료 쪽으로 정함), Explore만
허용하는 훅(맨 deny를 빼면 allow로 예외를 못 판다).

위험: 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지
못한다(arch-reviewer, verify-api). 정의 본문이 읽기 명령만 쓰라고 하고,
노트북 Gradle·Docker는 소유자 전역 훅이 서브에이전트 안에서도 막는다.
데스크톱 앱에서 서브에이전트 기록이 소유자에게 어떻게 보이는지는 확인하지
못했다.

검증: python3 -m unittest discover -s scripts/tests rc=0. arch-reviewer에
Edit를 더한 사본, Agent deny를 되살린 사본에서 각각 시험 1건이 실패했다.
check-work-docs·check-docs rc=0.

BREAKING CHANGE: 파생 서비스에서도 Agent 도구가 열린다. 막으려면 서비스
설정에 deny를 남긴다. docs/upgrade/2026-11-harness.md 2절 5행.
2026-11-07 22:08:42 +09:00

12 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의 기존 checkout ~/workspace/clean-architecture-backend-template은 여러 세션이 함께 쓴다. 그 stash@{0}는 소유자의 보관분이다. 건드리지 않는다. git stash pop·drop·clear와 이름 없는 git stash를 쓰지 않는다.
  • design-docs repo는 노트북 ~/workspace/desktop-server-git/design-docs에 있다.

절차:

# 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 4절).
  • RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
  • workflow job이 도구를 내려받아 설치하는 단계(curl … | sh, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다.
  • 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가 허용되지 않았으면, 커밋 전에 바꾼 것을 패치로 보내 같은 트리에서 돌린다.

# 노트북: 커밋할 파일만 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 --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절의 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것, (다) 로컬 도구가 없는 것 전체다.
  2. 잠금을 얻은 뒤 1분 부하를 적고 돌린다. 한 번에 하나씩이다.
  3. 첫 실행이 실패하면 원인을 찾아 고치고 다시 돌린다. 첫 실행과 다시 돌린 결과를 둘 다 적는다.
  4. 결과를 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/, 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절).