From 38d9bcfe701a0a132129081b7e8add985b49b00b 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절의 라운드 상한(세 라운드)은 전체 리뷰 횟수만 센다. 2026-11 전체 리뷰와 수정이 주간 사용량의 절반(50%)을 썼고, 전 범위 첫 파동이 리뷰어 비용의 80%, 이후 파동이 2%였다. 또 main·nightly 단계 실패(예: main push의 Firefox 첫 렌더 흔들림)를 재실행 초록이나 PR 단계 검증으로 닫고 같은 원인의 다른 모양이 되풀이됐다. 위임 루프 운영 12절(design-docs 사용량 회고 PR)을 이 playbook에 맞춘다. 기존 줄 끝에 문장을 붙여 150줄 한도를 지켰다(새 줄 0). - 2절: 열린 끝 일은 brief의 예산·멈출 기준을 받는다. 없으면 묻는다. - 4.1: 전체 리뷰는 라운드마다 한 번, 그 뒤 확인은 직전 수정 diff만. 새 눈 리뷰는 PR당 한 번 + 고친 뒤 확인 한 번. - 4.2 9단계와 9절: main·nightly 실패는 실패를 낸 게이트를 같은 조건으로 돌려 rc를 본다. 재실행 초록이나 PR 단계 검증으로 닫지 않는다. - 4.5: 예산은 세 라운드 상한과 별개의 확인 지점이다. 닿았는데 기준이 아직 아니면 멈추고 남은 발견·쓴 양을 보고해 계속할지 묻는다. 고른 방법: 4.5절의 기준과 소유자 결정(각자 유지)은 건드리지 않았다. 예산은 기준을 낮추지 않고 계속할지 묻는 지점만 더한다. 위험·한계: 위임 루프 운영 12절은 cold-read 시험 전이라 이 줄도 시험 전이다. verify:documentation은 짝 백엔드 checkout이 없는 worktree라 PASS_SCOPED(19개 참조 미확인)로 끝났다. 검증: scripts/verify.sh docs rc=0(improve.md 150/150, 진입 경로 272/350, 이력 ID 0, 상대 링크 121개), corepack pnpm verify:documentation rc=0 (PASS_SCOPED). 노트북 laptop-gate로 돌렸다. Refs: design-docs delegation-loop/retro/2026-11-13-usage-waste.md --- docs/work/improve.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/work/improve.md b/docs/work/improve.md index 4374ae5c..7d311533 100644 --- a/docs/work/improve.md +++ b/docs/work/improve.md @@ -19,7 +19,7 @@ - 리뷰: 범위(전체 / 영역 / PR / 커밋 범위 `..`), 기준 커밋. - 수정: 고칠 발견 목록(ID, 위치)과 리뷰 문서 경로. 발견 ID 없이 고치지 않는다. 그 고침이 무엇을 막는지 아무도 모르게 된다. -- 공통: 브랜치, 커밋 허용 여부, 돌릴 게이트. 그 발견에 필요한 소유자 결정이 [reference/decisions.md](reference/decisions.md)에도 brief에도 없으면 그 발견만 멈추고 묻는다. +- 공통: 브랜치, 커밋 허용 여부, 돌릴 게이트. 그 발견에 필요한 소유자 결정이 [reference/decisions.md](reference/decisions.md)에도 brief에도 없으면 그 발견만 멈추고 묻는다. 열린 끝 일(「발견 0까지」「모두 고친다」)이면 예산·멈출 기준(최대 라운드, 서브에이전트 수, 사용량 상한)도 받는다. 없으면 시작하지 않고 총괄에 묻는다(design-docs `conventions/delegation-loop.md` 12.3절). ## 3. 크기와 사고 순서 @@ -51,7 +51,7 @@ 8. 총괄이 High 이상과 새 P1을 코드에서 직접 다시 읽거나 실행해 확인하고, 재확인 칸에 그 사실을 적는다. 9. README에 범위, 28개 관점 판정표, 최종 요약, 발견 색인을 쓴다(양식 review-criteria.md 7절). 총괄 자신의 실수도 적는다. -- PR·diff 리뷰는 바뀐 파일의 영역만 읽는다. 게이트는 2단계대로 한 번 돌린다(멈춤 판정에 merge 단계 전부가 필요하다). 범위의 base는 직전 리뷰(diff 리뷰 포함)가 본 범위의 끝 커밋, head는 맡긴 쪽이 정한 커밋(없으면 fetch한 `origin/main`)이고 둘을 머리말에 적는다. 판정 체계·양식·ID 체계(`NN-MM`)는 같고, 수정 라운드의 diff 리뷰는 그 라운드 README 「조치」 절 아래 절로 적는다. +- PR·diff 리뷰는 바뀐 파일의 영역만 읽는다. 게이트는 2단계대로 한 번 돌린다(멈춤 판정에 merge 단계 전부가 필요하다). 범위의 base는 직전 리뷰(diff 리뷰 포함)가 본 범위의 끝 커밋, head는 맡긴 쪽이 정한 커밋(없으면 fetch한 `origin/main`)이고 둘을 머리말에 적는다. 판정 체계·양식·ID 체계(`NN-MM`)는 같고, 수정 라운드의 diff 리뷰는 그 라운드 README 「조치」 절 아래 절로 적는다. 전체 리뷰는 라운드마다 한 번(첫 파동)이다. 그 뒤 확인은 직전 수정 diff와 그 주변만 본다. 같은 범위를 새 눈으로 전 범위 다시 맡기지 않고, 새 눈 리뷰는 PR당 한 번 + 고친 뒤 확인 한 번이다. 2026-11 전체 리뷰에서 첫 전 범위 파동이 리뷰어 서브에이전트 비용의 80%, 이후 파동은 2%였다(design-docs `delegation-loop/retro/2026-11-13-usage-waste.md` 2절). - 리뷰 중에 코드를 고치지 않는다. 의심 결함은 별도 worktree의 임시 테스트로 확인하고 그 코드는 리뷰 문서나 공유 노트에만 남긴다. 리뷰 문서는 리뷰 시점 기록이다. 고친 뒤에도 영역 문서를 고치지 않고, 처리 결과는 같은 README의 「조치」 절에 적는다. ### 4.2 결함 수정 @@ -65,7 +65,7 @@ 6. 템플릿 원래 상태 밖에서도 돌린다: 기능을 더한 상태(`create:feature`), 제품 확장 지점을 채운 상태, 입력·객체가 셋 이상. 원래 상태로만 확인한 수정이 다음 라운드에 다시 결함이 됐다. 7. 수정이 새로 가정하는 것을 커밋 본문 「위험·한계」에 적는다(8절 「새로 가정하는 것」). 8. 그 동작을 설명하는 문서를 같은 변경에서 고친다. adapter 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다. 다운스트림에 보이는 변경은 `CHANGELOG.md` 미출시 절에 적는다. -9. 커밋 전 게이트를 돌린다([reference/gates.md](reference/gates.md) 2절). +9. 커밋 전 게이트를 돌린다([reference/gates.md](reference/gates.md) 2절). 실패가 CI의 main·nightly 단계에서 났으면 그 실패를 낸 게이트를 desktop에서 같은 조건(부하·브라우저·프로필)으로 돌려 그 rc를 본다. PR 단계 검증이나 재실행 초록만으로 닫지 않고, 같은 원인은 증상 낱말이 아니라 그 원인이 들어갈 수 있는 게이트 전체에서 찾는다(design-docs `conventions/delegation-loop.md` 12.1절 6·7단계). ### 4.3 리팩터링, 성능, 구조, 테스트 구조 @@ -90,7 +90,7 @@ - 채워도 바로 끝내지 않는다. 그 라운드의 Medium·Low를 고치고 멈춘다. 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 남긴다(형식 [reference/decisions.md](reference/decisions.md) 3절). 이유 없는 이월("나중에", "범위 밖")은 남기지 않는다. - 마지막 Medium·Low 수정은 다음 리뷰를 받지 않는다. 그래서 그 수정도 4.2절 6단계와 merge 판정을 그대로 거친다. 짝 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 두 기준을 맞추지 않는다(소유자 결정 2026-11-05 「각자 유지」). -- 2026-11-03 리뷰의 수정 라운드 뒤로 세 라운드를 더 돌아도 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게 보고한다. 라운드는 전체 리뷰 한 번이다(diff 리뷰는 세지 않는다). 2026-11-05·06 리뷰가 그 첫째·둘째다. +- 2026-11-03 리뷰의 수정 라운드 뒤로 세 라운드를 더 돌아도 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게 보고한다. 라운드는 전체 리뷰 한 번이다(diff 리뷰는 세지 않는다). 2026-11-05·06 리뷰가 그 첫째·둘째다. 예산은 이 상한과 별개의 확인 지점이다. brief 5절의 예산(최대 라운드·서브에이전트 수·사용량 상한)에 닿았는데 위 셋과 「남은 문제 0」이 아직 아니면 멈추고, 남은 발견 수·심각도·쓴 양을 총괄에게 보고해 계속할지 묻는다. 기준을 낮추는 것이 아니다(design-docs 12.3절). - 수정 결과의 "고침"은 확정이 아니다. 다음 리뷰가 ID별로 다시 판정한다. 보고에도 "다음 리뷰에서 재판정"이라고 적는다. ## 5. 완료 기준 @@ -144,7 +144,7 @@ ## 9. 자주 하는 실수 - 게이트 목록을 지난 라운드에서 가져온다. `scripts/verify.sh merge`로 stage 전부를 돌린다. -- 다시 돌려 통과한 결과를 "통과"로 쓴다. 실패한 회차를 적고 원인을 찾는다. +- 다시 돌려 통과한 결과를 "통과"로 쓴다. 실패한 회차를 적고 원인을 찾는다. main·nightly 단계 실패의 고침을 PR 단계 검증으로 닫는 것도 같다. 실패를 낸 게이트를 돌려 그 rc를 본다(4.2절 9단계). - 지운 코드의 실행 동작만 옮기고, 그 코드를 읽던 검사·테스트가 지키던 것을 놓친다. 지우기 전에 `git grep`으로 읽는 곳을 찾는다. - 짝 백엔드 사실을 문서만 보고 옮긴다. 생성기와 폼까지 코드를 따라간다. - "부하 탓"으로 닫는다. 부하를 낮춘 재현과 결정적 재현으로 확인하기 전에는 원인이 아니다.