Files
clean-architecture-backend-…/docs/work/operate.md
T
DongHyeonka 63c63413d1 docs(work): 지도와 작업 종류별 playbook으로 작업 매뉴얼을 만든다
문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와
리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이
"이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는
없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지),
커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음).

고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs
delegation-loop/02-design.md 4~6·10절):
- CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본
  AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는
  곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던
  내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은
  reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절.
- docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개
  (new-feature, improve, research-design, docs-writing, operate, delegate, 모두
  같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns,
  decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고
  review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에
  나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고,
  improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다.
- improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과
  수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난
  수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25,
  +13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다.
- 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를
  README 4절과 AGENTS.md에 같은 말로 적었다.
- 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인
  (reference/decisions.md, reference/defect-patterns.md)에만 둔다.
- 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md,
  docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운
  CLAUDE.md 「Layer workflow」를 가리키던 줄).

위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라
초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어
docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/
본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의
성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다.

검증
- python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80,
  playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
  AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0
- CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest
  .guidanceNamesTheArchitectureSourceSetTask가 기대하는
  "./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는
  이 커밋을 push한 뒤 desktop에서 돌린다
2026-11-06 19:58:44 +09:00

8.1 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된 브랜치만 받을 수 있다.
  • 자기 브랜치 push 허용 여부. desktop 검증이 필요한 일이면 brief가 허용해야 한다. 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에서 돌린다.
  • 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를 쓴다.
  • RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
  • Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다.

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 지도에서 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 6절에 더해 reference/gates.md 4절 표를 붙인다. desktop 정리 결과(지운 worktree, checkout 브랜치, stash@{0} 상태)를 한 줄로 적는다.

9. 자주 하는 실수

  • desktop 기존 checkout에서 브랜치를 바꿔 다른 세션의 작업을 방해한다. 자기 worktree를 만든다.
  • 짧게 끝난 실행을 통과로 적는다. 캐시 재사용인지, 태스크가 실제로 돌았는지 로그로 확인한다.
  • performance lane을 workflow와 다른 속성으로 돌린다. reference/gates.md 5절을 따른다.