docs(work): 확인 리뷰에 예산 확인 지점과 실패한 단계 검증을 더한다 #44

Open
donghyeon.kang wants to merge 1 commits from docs/improve-review-budget into main
Owner

무엇을, 왜

개선 playbook(docs/work/improve.md)에 확인 리뷰의 예산 확인 지점과 「실패가 난 단계에서 GREEN」을 더한다. design-docs 위임 루프 운영 12절(사용량 회고, design-docs #9)을 이 playbook에 맞춘 것이다.

  • 문제: 4.5절 멈춤 기준이 「발견 0」 하나라 brief가 예산 없이 「발견 0까지」를 시키면 소유자가 멈출 때까지 사용량을 쓴다. 2026-11 전체 리뷰·수정이 주간 사용량의 50%를 썼고, 전 범위 첫 파동이 리뷰어 비용의 80%, 이후 파동이 2%였다. main 단계 실패의 고침을 verify.sh pr만 보고 닫아 main 전용 SpotBugs가 새로 빨개진 일도 있었다.
  • 변경(한 파일, 5줄 추가·1줄에 문장을 이어 붙임, 148/150줄): 2절 열린 끝 일은 brief 예산·멈출 기준을 받는다 / 4.1 전 범위 리뷰는 라운드마다 한 번, 그 뒤는 직전 수정 diff만, 새 눈 리뷰는 PR당 한 번 + 고친 뒤 확인 한 번 / 4.2 9단계와 9절 main·nightly 실패는 그 단계의 태스크를 돌려 rc를 본다 / 4.5 예산은 멈춤 기준이 아니라 확인 지점이다.

고른 방법과 버린 대안

  • 고른 것: 4.5절의 「발견 0」 기준과 소유자가 거둔 다른 멈춤 기준(새 Important 0, Minor 기록만)을 건드리지 않고, 예산에 닿았을 때 멈추고 계속할지 묻는 지점만 더했다.
  • 버린 것: 라운드 상한을 멈춤 기준으로 두는 안(소유자 규칙 「남은 문제 0」을 낮춘다). 새 절을 만드는 안(playbook 150줄 한도라 기존 절에 한 줄씩 걸었다).

위험과 영향

  • 4.5절의 완료 기준은 그대로다. 예산에 닿으면 사람 결정이 한 번 더 들어간다.
  • 위임 루프 운영 12절이 cold-read 시험 전이라 이 줄도 시험 전이다.
  • 검증하지 못한 것: 새 세션이 이 줄을 보고 따르는지. docs 외 코드·설정 변경은 없다.

검증

  • ~/.claude/bin/laptop-gate --log improve-budget-be-docs -- scripts/verify.sh docs rc=0 (improve.md 148/150, 진입 경로 한도 안, 이력 ID 0, 상대 링크 168개, 문서 시험 166건 OK). 노트북 감싸개로 돌렸다.
  • runner pr run은 이 PR이 올린 뒤 돈다. 기다리는 중이면 아직 안 본 것이다.

리뷰어가 볼 곳

  • docs/work/improve.md 4.5절 새 bullet(예산은 확인 지점이다)이 소유자 규칙 「남은 문제 0」과 어긋나지 않는지.

관련

  • design-docs conventions/delegation-loop.md 12절, delegation-loop/retro/2026-11-13-usage-waste.md
## 무엇을, 왜 개선 playbook(`docs/work/improve.md`)에 확인 리뷰의 예산 확인 지점과 「실패가 난 단계에서 GREEN」을 더한다. design-docs 위임 루프 운영 12절(사용량 회고, design-docs #9)을 이 playbook에 맞춘 것이다. - 문제: 4.5절 멈춤 기준이 「발견 0」 하나라 brief가 예산 없이 「발견 0까지」를 시키면 소유자가 멈출 때까지 사용량을 쓴다. 2026-11 전체 리뷰·수정이 주간 사용량의 50%를 썼고, 전 범위 첫 파동이 리뷰어 비용의 80%, 이후 파동이 2%였다. main 단계 실패의 고침을 `verify.sh pr`만 보고 닫아 main 전용 SpotBugs가 새로 빨개진 일도 있었다. - 변경(한 파일, 5줄 추가·1줄에 문장을 이어 붙임, 148/150줄): 2절 열린 끝 일은 brief 예산·멈출 기준을 받는다 / 4.1 전 범위 리뷰는 라운드마다 한 번, 그 뒤는 직전 수정 diff만, 새 눈 리뷰는 PR당 한 번 + 고친 뒤 확인 한 번 / 4.2 9단계와 9절 main·nightly 실패는 그 단계의 태스크를 돌려 rc를 본다 / 4.5 예산은 멈춤 기준이 아니라 확인 지점이다. ## 고른 방법과 버린 대안 - 고른 것: 4.5절의 「발견 0」 기준과 소유자가 거둔 다른 멈춤 기준(새 Important 0, Minor 기록만)을 건드리지 않고, 예산에 닿았을 때 **멈추고 계속할지 묻는** 지점만 더했다. - 버린 것: 라운드 상한을 멈춤 기준으로 두는 안(소유자 규칙 「남은 문제 0」을 낮춘다). 새 절을 만드는 안(playbook 150줄 한도라 기존 절에 한 줄씩 걸었다). ## 위험과 영향 - 4.5절의 완료 기준은 그대로다. 예산에 닿으면 사람 결정이 한 번 더 들어간다. - 위임 루프 운영 12절이 cold-read 시험 전이라 이 줄도 시험 전이다. - 검증하지 못한 것: 새 세션이 이 줄을 보고 따르는지. docs 외 코드·설정 변경은 없다. ## 검증 - `~/.claude/bin/laptop-gate --log improve-budget-be-docs -- scripts/verify.sh docs` rc=0 (improve.md 148/150, 진입 경로 한도 안, 이력 ID 0, 상대 링크 168개, 문서 시험 166건 OK). 노트북 감싸개로 돌렸다. - runner `pr` run은 이 PR이 올린 뒤 돈다. 기다리는 중이면 아직 안 본 것이다. ## 리뷰어가 볼 곳 - `docs/work/improve.md` 4.5절 새 bullet(예산은 확인 지점이다)이 소유자 규칙 「남은 문제 0」과 어긋나지 않는지. ## 관련 - design-docs `conventions/delegation-loop.md` 12절, `delegation-loop/retro/2026-11-13-usage-waste.md`
donghyeon.kang added 1 commit 2026-11-13 13:38:34 +00:00
개선 playbook에는 확인 리뷰를 몇 번까지 돌리는지, 한 번에 얼마나 쓰는지
정한 곳이 없다. 멈춤 기준(4.5절)은 발견 0 하나라 brief가 예산 없이
"발견 0까지"를 시키면 소유자가 멈출 때까지 사용량을 쓴다. 2026-11
전체 리뷰와 수정이 주간 사용량의 절반(50%)을 썼고, 전 범위 첫 파동이
리뷰어 비용의 80%, 이후 파동이 2%였다. 또 main 단계 실패의 고침을
PR 단계 검증(verify.sh pr)만 보고 닫아 main 전용 SpotBugs가 새로
빨개졌다.

위임 루프 운영 12절(design-docs 사용량 회고 PR)을 이 playbook에 맞춘다.
- 2절: 열린 끝 일은 brief의 예산·멈출 기준을 받는다. 없으면 묻는다.
- 4.1: 전 범위 리뷰는 라운드마다 한 번, 그 뒤는 직전 수정 diff만.
  새 눈 리뷰는 PR당 한 번 + 고친 뒤 확인 한 번.
- 4.2 9단계와 9절: main·nightly 실패는 그 단계의 태스크를 돌려 rc를
  본다. PR 단계 검증으로 닫지 않는다.
- 4.5: 예산은 멈춤 기준이 아니라 확인 지점이다. 닿았는데 넷이 아직
  아니면 멈추고 남은 발견·쓴 양을 보고해 계속할지 묻는다.

고른 방법: 소유자가 거둔 "새 Important 0이면 멈춤" 같은 다른 멈춤
기준을 되살리지 않았다. 예산은 기준을 낮추지 않고 계속할지 묻는
지점만 더한다. 라운드 상한을 멈춤 기준으로 두는 안은 버렸다.

위험·한계: 4.5절의 "발견 0" 기준 자체는 그대로다. 예산에 닿으면 사람
결정이 한 번 더 들어간다. 위임 루프 운영 12절은 cold-read 시험 전이라
이 줄도 시험 전이다.

검증: scripts/verify.sh docs rc=0(improve.md 148/150, 진입 경로 한도 안,
이력 ID 0, 상대 링크 168개). 노트북 laptop-gate로 돌렸다.

Refs: design-docs delegation-loop/retro/2026-11-13-usage-waste.md
All checks were successful
pr / done (pull_request) Successful in 13m51s
Required
Details
This pull request is blocked because it's outdated.
You are not authorized to merge this pull request.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin docs/improve-review-budget:docs/improve-review-budget
git checkout docs/improve-review-budget
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#44