Files
clean-architecture-backend-…/docs/work
DongHyeonka a490c20f3e fix(strict-lane)!: 태그 push·release로만 도는 workflow는 releaseCheck에만 센다
문제: verifyStrictLaneStages의 workflow 판독기는 `push: tags:`만 있거나
`release` trigger만 있는 workflow의 명령을 모든 단계의 실행으로 센다.
태그 push는 매 변경에 돌지 않는데, 그런 workflow에만 `:integrationCheck`
같은 단계를 두어도 검사가 통과한다(round7 05 「Declined to judge」 ①).

고른 방법: 소유자 결정(2026-11-07, "권하는 안대로", 리뷰 README 18.4절
(a))대로, 요청이나 경로 필터 없이 시작하는 trigger가 release 흐름뿐인
workflow — `release`, 또는 `branches`·`branches-ignore` 없이
`tags`·`tags-ignore`가 있는 `push` — 의 명령은 `:releaseCheck`에만
센다. 경로 필터 결정(2026-11-06)과 같은 원칙이다. 판독기는 trigger를
변경·release·경로 필터·요청 넷으로 나누고, workflow의 시작을 "매 변경 /
release 흐름만 / 돌지 않을 수 있음" 셋으로 낸다. release 흐름만인
workflow를 부르는 재사용 workflow도 같다. Invocation에 releaseFlowReason을
두고, whyNotExecuting(taskPath, buildDirectory)가 `:releaseCheck` 밖의
단계에 그 이유를 준다. 실패 메시지, AGENTS.md, src/README.md,
build-logic/README.md, 업그레이드 안내 B-36, 결정 색인 2.7절을 고쳤다.
버린 대안: 지금처럼 모든 단계에 세고 문서에 적는다 — 소유자가 위 안을
골랐다. release 단계 이름을 빌드 설정(`strictLaneStages`)으로 받는다 —
결정이 `releaseCheck`를 이름으로 정했고, 파생 서비스 설정 표면이 늘어
판독기 상수로 두었다.

위험·한계: 파생 서비스가 `releaseCheck`가 아닌 단계를 태그·release
workflow에서만 돌리면 이제 verifyStrictLaneStages --dry-run이 실패한다.
이 repo의 release.yml은 `-p optional-platforms integrationCheck`도
돌리지만 integration-main.yml(main push·nightly)이 같은 단계를 돌려
판정이 그대로다(두 빌드 확인). release의 `types`는 보지 않는다.
`branches`와 `tags`를 함께 둔 push는 지금처럼 모든 단계에 센다.

검증(desktop, 로그 ~/r8-f5b-logs/):
- RED: 기준 ac3c6a81에 테스트만 얹음. 68건 중 2건 실패 —
  WorkflowGradleInvocationsTest(세 workflow의 :integrationCheck가
  실행으로 셈), StrictLaneStagesFunctionalTest(UnexpectedBuildSuccess,
  "every strict lane is in an executed stage")
  (red-release-flow.log, TEST-*.xml)
- GREEN: 같은 두 클래스 46건·22건 실패 0 (green-release-flow.log)
- -p build-logic check javadoc rc=0(build-logic 테스트 173건 실패 0),
  :verifyStrictLaneStages --dry-run, -p optional-platforms
  :verifyStrictLaneStages --dry-run rc=0(둘 다 "every strict lane is in
  an executed stage"), check-work-docs.py와 상대 링크 검사 rc=0
  (summary.txt)

Refs: docs/reviews/2026-11-03-rereview/README.md 18.4절(cb340001)
BREAKING CHANGE: `releaseCheck`가 아닌 단계(:ci, :mainCheck, :integrationCheck, :performanceCheck 등)를 태그 push(`branches` 없는 `tags`)나 `release` trigger로만 시작하는 workflow에서만 돌리면 verifyStrictLaneStages --dry-run이 실패한다. 그 단계를 매 push·pull_request·schedule에 도는 workflow에서도 돌린다(docs/upgrade/2026-11-maturity-review.md B-36).
2026-11-07 01:37:14 +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다.