Files
clean-architecture-backend-…/docs/work
DongHyeonka 447a77a35d docs(work): 운영 playbook 시험에서 나온 게이트 실행 빈틈 여섯을 닫는다
문제: 2026-11-07 합친 브랜치 전체 게이트를 매뉴얼만 보고 돌리게 했더니
(1회차 수정 전 매뉴얼) 여섯 곳에서 답이 없었다.
- gates.md 3절 묶음에 main job(configuration-cache, compose smoke,
  http3, notification pr)과 경로 필터 PR lane이 없어 "workflow와 같은
  명령"이 아니었다
- 합친 트리가 어떤 경로 필터 lane을 켜는지 정하는 절차가 없었다
- 집계 태스크 전체가 실제로 돌았음을 보이는 법이 없었다(--rerun은
  앞 태스크 하나만)
- lychee 대체 명령(--links docs)이 lychee 범위보다 좁았고, buf와
  dependency review는 대체 안내가 없었다
- compose bind mount가 tmp/heap-dumps를 root로 만들어 git worktree
  remove가 실패했다
- 결과 기록 형식이 게이트 하나 = Gradle 명령 하나를 가정했다

고른 방법:
- gates.md 3절을 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것,
  (다) 로컬 도구가 없는 것으로 나눈다. (가)에 workflow의 run 줄을
  더하고, (나)는 git diff --name-only를 on.pull_request.paths(glob)와
  pr-adapters.yml emit 줄(정규식)에 맞추는 절차로, (다)는 job마다
  로컬 대체와 대체가 못 보는 것을 적은 표로 둔다
- 실제 실행 증명: 새 worktree와 --no-build-cache, 로그의 FROM-CACHE 0
- 링크 검사 대체는 lychee와 같은 glob을 git ls-files로 넘긴다
- operate.md 4.1에 compose down과 root 폴더 지우기 한 줄
- gates.md 4절은 한 줄 = 명령 하나, 여러 명령 job은 순번, 「실제
  실행」 칸
- 처리 표(evidence.md 9절)에 T6 여섯 행
버린 대안: workflow의 모든 job 명령을 gates.md에 옮겨 적기. workflow가
정본이라 옮긴 사본이 낡는다. 경로 필터 lane은 절차만 둔다.

위험·한계:
- (가)의 명령은 workflow의 사본이다. workflow를 바꾸면 이 블록도 고쳐야
  한다
- 경로 필터 맞추기는 손으로 한다. glob을 기계로 맞추는 도구는 없다
- 같은 범위 링크 검사는 지금 rc=1이다. src/README.md와 fileserver·
  objectstorage README의 상대 링크 3건이 기준 커밋부터 깨져 있다(이번
  범위 밖)

검증:
- python3 scripts/check-work-docs.py rc=0. improve.md 141/150,
  delegate.md 121/150, operate.md 131/150, 진입 경로 최대 290/350,
  본문 이력 0줄
- 바꾼 문서를 읽는 테스트: grep 결과 0(delivery-evidence.md 이름만
  걸림)
- desktop: 바꾼 것을 패치로 73d39212 위에 얹어 이 커밋과 같은 트리
  7e28874c를 만들고, flock 아래 :app-bootstrap:documentContractTest
  --rerun --no-build-cache rc=0, 66건 실패 0 건너뜀 0, FROM-CACHE 0,
  직전 1분 부하 5.64. 같은 트리에서 check-work-docs.py rc=0,
  --history docs/manual 16줄 rc=1(기대대로)
  (desktop ~/manual-gap-fix-2-logs/final-*.log)
- 링크 검사(lychee와 같은 범위) rc=1, 깨진 3건은 위 위험·한계의 것
  (desktop ~/manual-gap-fix-2-logs/links-lychee-scope.log)
2026-11-07 00:35:12 +09:00
..

작업 매뉴얼

이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다. 읽는 순서는 하나다: 루트 CLAUDE.md(지도) → 이 README → 맡은 일의 playbook 하나. 규칙의 정본은 AGENTS.md와 registry(src/config/architecture/modules.json)다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다.

1. 어떤 playbook인가

맡은 일 playbook
새 업무 기능이나 새 capability 모듈을 만든다 new-feature.md
있는 코드를 리뷰·수정·리팩터링·최적화한다. 구조·테스트 구조를 바꾼다 improve.md
바꾸기 전에 대안을 비교하고 소유자 결정을 받는다 research-design.md
매뉴얼·안내 문서를 쓰거나 고친다 docs-writing.md
게이트를 돌린다, 릴리스한다, 파생 서비스에 템플릿 변경을 넘긴다 operate.md
큰 일을 나눠 다른 세션에 맡긴다 delegate.md

둘에 걸리면 이렇게 고른다. 결정이 먼저 필요하면 research-design이다. 동작이 바뀌는 코드가 있으면 new-feature나 improve다. 문서만 바뀌면 docs-writing이다.

2. 크기 정하기

  • 크기는 작음·중간·큼 셋이다. 정의와 크기별로 할 단계는 design-docs conventions/work-thinking-order.md 2절이 정본이다.
  • 요약: 작음은 파일 몇 개·새 결정 없음·되돌리기 쉬움, 중간은 leaf(또는 문서 폴더) 하나 안의 여러 파일이나 소유자 없이 정할 작은 결정 하나, 큼은 새 체계·아키텍처·공개 계약·소유자 결정이 필요한 일이다.
  • brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다.
  • brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다.
  • 이 repo에서 "경계"는 registry의 leaf 하나다. 파일 수가 아니라 바뀌는 경계와 영향으로 정한다.
  • 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 docs/web/http-contract.md, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 보안 정책.
  • 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다(research-design.md).

3. 모든 작업의 공통 단계

  1. 기준 커밋을 고정한다. git rev-parse HEAD를 산출물과 보고에 적는다.
  2. 이미 정한 것을 읽는다: reference/decisions.md, docs/reviews/에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다.
  3. 소유 leaf를 찾는다. registry의 source_path로 정하고, 가장 가까운 src/**/CLAUDE.md를 읽는다.
  4. 스킬을 고른다. 정본은 AGENTS.md 「Superpowers Workflow」다. playbook에 작업별 스킬이 있다.
  5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
  6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 operate.md 「실행 위치」대로 한다.
  7. 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절).
  8. 완료를 말하기 전에 검증한다(superpowers:verification-before-completion). 돌리지 못한 검증은 못 돌렸다고, 이유와 함께 쓴다(HARD-STOP 6).

4. 커밋

  • 기본 정책은 human-only다(AGENTS.md). 에이전트는 stage·commit·amend·push하지 않는다.
  • 예외는 하나다. brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다(desktop 검증은 operate.md 4.1절 「push 전에 검증하기」).
  • 그때도 main 병합, main·다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자가 한다.
  • 메시지 형식은 design-docs conventions/commit-and-pr.md를 따른다. AI 꼬리말과 자리표시자(TBD, TODO, 채우지 않은 칸)를 넣지 않는다.

5. 막혔을 때

  • 소유자만 정할 수 있는 것(공개 계약, 파생 서비스 동작, 보안 정책, 새 leaf, 되돌리기 비싼 선택)은 근거와 권하는 안을 붙여 한 번 묻고, 그 항목만 멈춘다.
  • brief를 준 쪽이 있으면 그쪽에 묻는다. 없으면 소유자에게 묻는다.
  • 묻는 형식: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람.

6. 보고

  • 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다.
  • 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(위치와 내용, 고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다.
  • 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다.
  • 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다.
  • 사고 순서 흔적 칸을 둔다(conventions/work-thinking-order.md 3절). 다른 세션이 맡긴 일이면 design-docs conventions/delegation-loop.md 5절 양식을 쓴다.

7. 필요할 때만 읽는 문서

문서 내용
reference/gates.md 게이트 목록, 바꾼 것에 맞는 게이트, 결과 기록 형식, 거짓 통과 막기
reference/review-criteria.md 결함 정의, 심각도, 증거·통제 수준, 점검 항목, 리뷰 문서 양식
reference/defect-patterns.md 반복해서 나온 결함의 모양과 막는 기준
reference/decisions.md 이미 정한 결정의 색인, 결정을 다시 여는 조건과 기록하는 법
evidence.md 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID

8. 이 폴더를 고칠 때

  • 분량 상한: 지도 120줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + README + playbook 하나) 350줄. reference/는 상한이 없다.
  • 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 evidence.md로 옮긴다.
  • 고친 뒤 python3 scripts/check-work-docs.py가 통과해야 한다. 절차는 docs-writing.md다.