From e2cd451fb58d7c1c1f89886c97160561758ec8e2 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 22:38:04 +0900 Subject: [PATCH] =?UTF-8?q?docs(work):=20=ED=99=95=EC=9D=B8=20=EB=A6=AC?= =?UTF-8?q?=EB=B7=B0=EC=97=90=20=EC=98=88=EC=82=B0=20=ED=99=95=EC=9D=B8=20?= =?UTF-8?q?=EC=A7=80=EC=A0=90=EA=B3=BC=20=EC=8B=A4=ED=8C=A8=ED=95=9C=20?= =?UTF-8?q?=EB=8B=A8=EA=B3=84=20=EA=B2=80=EC=A6=9D=EC=9D=84=20=EB=8D=94?= =?UTF-8?q?=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 개선 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 --- docs/work/improve.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/work/improve.md b/docs/work/improve.md index c1710cc7..cc0788d0 100644 --- a/docs/work/improve.md +++ b/docs/work/improve.md @@ -20,7 +20,7 @@ - 리뷰: 범위(전체 / 영역 / 커밋 범위 `..`와 pathspec), 쓸 심각도 체계(전체 리뷰용인지 확인 리뷰용인지). - 수정: 고칠 발견 목록(ID, 위치)과 리뷰 문서 경로. -- 공통: 기준 커밋, 브랜치, 커밋 허용 여부, 검증할 게이트. +- 공통: 기준 커밋, 브랜치, 커밋 허용 여부, 검증할 게이트. 열린 끝 일(「발견 0까지」「모두 고친다」)이면 예산·멈출 기준(최대 라운드, 서브에이전트 수, 사용량 상한)도 받는다. 없으면 시작하지 않고 총괄에 묻는다(design-docs `conventions/delegation-loop.md` 12.3절). - 그 발견에 필요한 소유자 결정이 났는지. [reference/decisions.md](reference/decisions.md)에 없고 brief에도 없으면 그 발견만 멈추고 묻는다. ## 3. 크기와 사고 순서 @@ -52,6 +52,7 @@ - 수정 diff가 추가 1,000줄 이상인 확인 리뷰(상한 1,500줄에 가까움. 세는 법은 4.4절). - Critical·Important(전체 리뷰는 High)를 고친 수정의 확인 리뷰. - 리뷰어는 자기 문서를 끝내기 전에 다른 리뷰어의 브랜치·문서·보고·노트를 읽지 않는다. 리뷰 폴더에 문서를 커밋하는 것은 brief가 정한 정본 리뷰어뿐이다. 다른 리뷰어는 같은 양식을 보고에 두고, ID 자리에 임시 번호 `B-NN-MM`을 쓴다. +- 전 범위 리뷰는 라운드마다 한 번(첫 파동)이다. 그 뒤 확인 리뷰는 직전 수정 diff(4.4절)와 그 주변만 본다. 같은 범위를 새 눈으로 전 범위 다시 맡기지 않고, 새 눈 리뷰는 PR당 한 번 + 고친 뒤 확인 한 번이다. 2026-11 전체 리뷰에서 첫 전 범위 파동이 리뷰어 서브에이전트 비용의 80%, 이후 파동은 2%였다(design-docs `delegation-loop/retro/2026-11-13-usage-waste.md` 2절). ### 4.2 결함 수정 @@ -65,6 +66,7 @@ 7. 파생 서비스가 따라 고쳐야 하면 `docs/upgrade/`의 안내에 행을 적고, 커밋 제목에 `!`와 `BREAKING CHANGE:` 꼬리말을 단다. 문서에 이미 적힌 규칙을 검사가 더 엄하게 지키게 되어 그 규칙을 어기던 코드가 새로 실패하는 것도 여기에 든다(규칙은 이미 정해져 있어 크기는 올리지 않는다). - 안내의 범위(머리 「범위」)가 아직 main에 합쳐지지 않았으면 파생 서비스는 그 행을 받기 전이다. 같은 표면의 행이 있으면 그 행을 고쳐 최종 동작을 적고, 머리 「커밋:」 목록에 이번 커밋을 더한다. main에 합쳐진 안내는 고치지 않고 새 행을 더한다. 8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)). registry는 lane을 모른다. 그 lane은 바꾼 클래스·기능 이름으로 leaf `build.gradle`의 `strictTestLanes` 블록과 lane source set(`src//`)의 테스트를 grep해 찾는다. brief의 lane 목록에 없는 lane이 걸리면 그것도 돌리고 보고에 적는다. +9. 실패가 CI의 main·nightly 단계에서 났으면, 그 단계에서만 도는 태스크를 desktop에서 직접 돌려 그 rc를 본다. PR 단계 검증(`verify.sh pr`)만으로 닫지 않는다. 같은 원인은 증상 낱말이 아니라 그 원인이 들어갈 수 있는 단계 전체에서 찾는다(5단계, design-docs `conventions/delegation-loop.md` 12.1절 6·7단계). ### 4.3 리팩터링, 성능, 구조, 테스트 구조 @@ -92,6 +94,7 @@ 4. 리뷰 README의 남은 항목이 0이다. 결정으로 닫은 항목은 결정 위치를 적었다. - 다른 멈춤 기준은 이 repo에서 쓰지 않는다. "새 Important가 0이면 멈춤"과 "Minor는 기록만"은 소유자가 거뒀다. 짝 프론트 repo는 자기 기준을 쓴다(소유자 결정 "각자 유지"). +- **예산은 멈춤 기준이 아니라 확인 지점이다.** brief 5절의 예산(최대 라운드·서브에이전트 수·사용량 상한)에 닿았는데 위 넷이 아직 참이 아니면 멈추고, 남은 발견 수·심각도·쓴 양을 총괄에게 보고해 계속할지 묻는다. 기준을 낮추는 것이 아니다(design-docs `conventions/delegation-loop.md` 12.3절). - 코드로 닫을 수 없는 것은 소유자 결정이 필요한 항목뿐이다. 근거와 권하는 안을 붙여 질문으로 보고하고, 답을 받으면 다시 고친다. ## 5. 완료 기준 @@ -142,3 +145,4 @@ - 보고에 없는 태스크 이름을 적는다. 로그에서 태스크 이름을 grep해 확인한다. - 묶음별 검증으로 합친 트리 검증을 대신한다. 라운드 끝 게이트를 따로 돌린다. - strict lane에 돌릴 탐침을 새 클래스로 만들어 lane이 고르지 않는다. lane은 `build.gradle`의 `requires`(클래스 이름)나 `tag`로 테스트를 고른다. 탐침은 그 lane이 고르는 기존 클래스에 메서드로 넣는다. 탐침도 `-Werror`와 Error Prone으로 컴파일되니 경고를 남기지 않는다(예: 반환값을 버린 `catchThrowable`은 `CheckReturnValue` 오류다). +- main·nightly 단계 실패의 고침을 PR 단계 검증이나 재실행 초록으로 닫는다. 실패를 낸 단계의 태스크를 돌려 그 rc를 본다(4.2절 9단계). -- 2.54.0