docs(work): 세 경우의 확인 리뷰를 독립 리뷰어 둘로 하고 총괄이 합친다
문제: 2026-11-06 같은 커밋을 두 세션이 따로 확인 리뷰했더니 합친 결함
8건 중 1건만 겹쳤다. 라운드의 Important 2건도 한 리뷰어의 첫 리뷰 밖에서
나왔다. 반복은 마지막 확인 리뷰의 0건으로 멈추는데, 리뷰어 하나의 0은
남은 결함이 0이라는 증거로 약하다.
고른 방법: 2026-11-07 소유자 결정("(c)로 받기")대로 세 경우에만
서로 결과를 보지 않는 리뷰어 둘이 같은 범위를 보고 총괄이 합친다.
- 멈추는 확인 리뷰: 리뷰어 하나가 0을 내면 두 번째가 본다. 둘 다 0이어야
멈춘다(improve.md 4.5 1)
- 수정 diff가 상한에 가까운 리뷰: 추가 1,000줄 이상
- Critical·Important를 고친 수정의 리뷰
정본 리뷰어만 리뷰 폴더에 커밋하고 ID를 매긴다. 다른 쪽은 보고에 같은
양식을 두고 임시 번호 B-NN-MM을 쓴다. 합칠 때 총괄이 같은 결함끼리
짝짓고, 다른 쪽에만 있는 결함은 정본 리뷰어가 탐침으로 다시 확인해 다음
번호로 넣는다. 겹침 비율을 색인 절과 지표 기록(M11)에 적는다.
버린 대안: 언제나 둘(비용 약 2배), 지금처럼 하나(멈춤 판정이 약함).
소유자가 2~3라운드 겹침 비율을 보고 다시 정한다.
위험·한계:
- "상한에 가까움"을 추가 1,000줄 이상으로 정한 것은 기본값이다
(decisions.md 2.1에 적음)
- 세션은 공유 노트 폴더의 다른 노트를 먼저 읽는다. 독립성은 brief의
금지 문장과 노트 이름 분리에 기대고, 막는 장치는 없다
- 같은 범위를 두 번 보므로 그 리뷰의 비용이 약 두 배다
검증: 이 커밋의 트리에서 python3 scripts/check-work-docs.py rc=0. desktop 검증은 다음 커밋의 트리로 했다(그 커밋 본문)
This commit is contained in:
@@ -34,6 +34,9 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
- 검증 칸에는 실행 위치와 증거 위치를 쓴다: desktop worktree, `flock /tmp/claude-gates/heavy.lock`, 로그 `~/<작업 이름>-logs/`([operate.md](operate.md) 4.1절). 7절에는 커밋 허용과 자기 브랜치 push 허용을 따로 쓴다.
|
||||
- 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸부터 보라고 적고, 지난 라운드에서 열린 채 넘어온 「Declined to judge」를 다시 판정시킬지도 적는다.
|
||||
- 리뷰 brief에는 쓸 심각도 체계([reference/review-criteria.md](reference/review-criteria.md) 3절)와 "발견마다 이번 수정이 만들었나 / 이전부터"를 요구한다.
|
||||
- 독립 리뷰어 둘([improve.md](improve.md) 4.1절의 세 경우)이면 범위·기준 커밋·심각도 체계가 같은 brief 둘을 쓰고, 두 세션을 함께 띄운다. 다른 칸은 셋이다: 정본 리뷰어인지(ID를 매기고 리뷰 폴더에 커밋한다), 출력 위치(다른 쪽은 보고에 두고 `B-NN-MM`), 5절에 "자기 리뷰를 끝내기 전에 상대 리뷰의 브랜치·문서·보고·노트를 읽지 않는다".
|
||||
- 두 리뷰가 끝나면 총괄이 합친다. 같은 결함(같은 원인·같은 위치)끼리 짝짓고, 다른 쪽에만 있는 결함은 정본 리뷰어에게 보내 탐침으로 다시 확인한 뒤 다음 번호로 넣게 한다. 그 라운드 색인 절은 총괄이 쓰고 대응표(`B-NN-MM` → 정본 ID)를 둔다.
|
||||
- 겹침 비율(두 리뷰가 모두 찾은 결함 수 / 합친 결함 수)을 그 라운드 색인 절과 design-docs `delegation-loop/metrics.md`의 M11 칸에 적는다. 2~3라운드 기록이 쌓이면 소유자가 이 방식을 다시 본다.
|
||||
- 대조할 때: 보고의 태스크 이름·테스트 수를 desktop 로그에서 grep으로 찾는다. High·Important 이상은 총괄이 코드에서 직접 다시 확인한다.
|
||||
- 리뷰 결과를 받으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`로 색인이 빠짐없는지 본다. 수정 묶음은 색인에서 배정한다.
|
||||
- 교훈을 보낼 곳: 그 playbook의 「자주 하는 실수」, 코드 결함 모양은 [reference/defect-patterns.md](reference/defect-patterns.md), 거짓 통과는 [reference/gates.md](reference/gates.md) 6절, 근거는 [evidence.md](evidence.md).
|
||||
@@ -82,6 +85,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
|
||||
- Agent 도구(세션 안의 하위 에이전트)는 이 repo의 `.claude/settings.json`이 막는다. 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 그 세션이 직접 하거나, 이 playbook대로 별도 세션에 맡긴다. 막혔다고 Agent로 우회하지 않는다.
|
||||
- 실행 위치(desktop, 공유 잠금, desktop worktree)는 [operate.md](operate.md) 4.1절이다.
|
||||
- 하위 세션은 공유 노트 폴더의 다른 노트를 먼저 읽는다. 독립 리뷰어 둘은 노트 파일 이름을 서로 다르게 정해 주고, brief에 상대 노트를 읽지 말라고 쓴다.
|
||||
|
||||
## 5. 완료 기준
|
||||
|
||||
|
||||
@@ -214,5 +214,5 @@
|
||||
| T5-2 | 기록 2 | 소유자 지시로 생긴 큰 변경도 따로 멈춰야 하나 | 고침 — design-docs `conventions/work-thinking-order.md` 2.3절, 스킬 `research-first` |
|
||||
| T5-V | 기록 「위반」 1 | 총괄 보고를 영어로 씀 | 고침 — `docs/work/README.md` 6절, design-docs `conventions/delegation-loop.md` 5·11절. 훅으로는 막지 않는다(보고 문장은 도구 호출이 아니라 훅이 볼 수 없다) |
|
||||
|
||||
- 기준선과 새 매뉴얼의 리뷰 발견은 8건 중 1건만 겹쳤다. 리뷰 방식을 바꿀지는 매뉴얼 규칙으로 넣지 않고 소유자에게 물을 제안으로 남겼다(매뉴얼 수정 세션 보고).
|
||||
- 기준선과 새 매뉴얼의 리뷰 발견은 8건 중 1건만 겹쳤다. 이를 근거로 확인 리뷰를 독립 리뷰어 둘로 할지 소유자에게 물었고, 2026-11-07 소유자가 세 경우에만 둘로 하는 안을 골랐다(소유자 원문 "(c)로 받기"). 넣은 곳: `improve.md` 4.1절 「독립 리뷰어 둘」·4.5절 1, `delegate.md` 4.1·4.3절, `reference/review-criteria.md` 10절 「ID」, `reference/decisions.md` 2.1, design-docs `conventions/delegation-loop.md` 3절 5·9절 M11, `delegation-loop/metrics.md`.
|
||||
- 「자주 하는 실수」에 넣은 줄: `improve.md`(strict lane 탐침), `operate.md`(`--rerun` 범위를 기존 줄에 더함, push 뒤 검증), `docs-writing.md`(`--history` 0을 믿음), `delegate.md`(두 리뷰의 ID).
|
||||
|
||||
@@ -46,6 +46,13 @@
|
||||
8. `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. 색인 절이 따로 있으면 `--index-heading "<절 제목>"`을 붙인다. rc=0이어야 한다. 지난 라운드 색인에서 빠진 ID 때문에 처음부터 rc=1이면, 빠진 ID를 이번 색인 절에 「색인 보완」 한 줄로 이름만 적는다. 지난 영역 문서는 고치지 않는다.
|
||||
9. 판단하지 않은 항목은 「Declined to judge」에 위치와 이유를 적는다. 맡긴 쪽이 다음 묶음에 배정하거나 결정으로 닫는다. 지난 라운드에서 열린 채 넘어온 Declined는 brief가 맡겼을 때만 다시 판정한다. 맡기지 않았으면 건수와 위치만 적는다.
|
||||
|
||||
**독립 리뷰어 둘.** 아래 셋 중 하나면 같은 범위를 서로 결과를 보지 않는 리뷰어 둘이 따로 리뷰하고 맡긴 쪽이 합친다([delegate.md](delegate.md) 4.1절).
|
||||
|
||||
- 멈추는 확인 리뷰: 리뷰어 하나가 0을 냈으면 멈추기 전에 두 번째 리뷰어가 같은 범위를 본다(4.5절 1).
|
||||
- 수정 diff가 추가 1,000줄 이상인 확인 리뷰(상한 1,500줄에 가까움. 세는 법은 4.4절).
|
||||
- Critical·Important(전체 리뷰는 High)를 고친 수정의 확인 리뷰.
|
||||
- 리뷰어는 자기 문서를 끝내기 전에 다른 리뷰어의 브랜치·문서·보고·노트를 읽지 않는다. 리뷰 폴더에 문서를 커밋하는 것은 brief가 정한 정본 리뷰어뿐이다. 다른 리뷰어는 같은 양식을 보고에 두고, ID 자리에 임시 번호 `B-NN-MM`을 쓴다.
|
||||
|
||||
### 4.2 결함 수정
|
||||
|
||||
1. 원인 경로를 확인한다. 증상이 아니라 원인을 적는다.
|
||||
@@ -77,7 +84,7 @@
|
||||
|
||||
리뷰 → 수정 → 확인 리뷰는 아래 넷이 모두 참일 때만 멈춘다.
|
||||
|
||||
1. 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다. Minor도 기록만 하지 않고 고친다.
|
||||
1. 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다. 서로 보지 않은 리뷰어 둘이 모두 0이어야 한다(4.1절 「독립 리뷰어 둘」). Minor도 기록만 하지 않고 고친다.
|
||||
2. 열린 「Declined to judge」가 0이다. 다른 브랜치가 처리했지만 아직 합치지 않은 항목은 합친 트리에서 확인할 때까지 열린 것으로 센다.
|
||||
3. 합친 트리에서 라운드 끝 게이트가 모두 통과했다.
|
||||
4. 리뷰 README의 남은 항목이 0이다. 결정으로 닫은 항목은 결정 위치를 적었다.
|
||||
|
||||
@@ -52,6 +52,7 @@
|
||||
| `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, `AGENTS.md` 테스트 작성 규칙 2 |
|
||||
| 학습 문서 | 삭제된 코드를 설명하는 학습 문서(`docs/study/*.ko.md`, `docs/*-superpowers-package/`)는 현재 코드에 맞게 갱신 | 소유자 | 2026-09-25 | 결정 6 |
|
||||
| client 오류 문구 | 한국어. `Category`별 문구 표 하나를 shared-contract에 | 소유자 | 2026-09-25 | 결정 11 |
|
||||
| 확인 리뷰 독립 리뷰어 둘 | 세 경우에 서로 결과를 보지 않는 리뷰어 둘이 같은 범위를 리뷰하고 총괄이 합친다: 반복을 멈추기 직전 확인 리뷰(리뷰어 하나가 0을 내면 두 번째가 본다), 수정 diff가 상한에 가까운 리뷰("가까움"은 추가 1,000줄 이상 — 기본값), Critical·Important를 고친 수정의 리뷰. 그 밖은 하나. 2~3라운드 두 리뷰의 겹침 비율을 기록하고 그 결과로 언제나 하나·언제나 둘로 옮길지 다시 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 원문 "(c)로 받기"), `docs/work/improve.md` 4.1·4.5절, `docs/work/delegate.md` 4.1절 |
|
||||
|
||||
### 2.2 구조·조립
|
||||
|
||||
|
||||
@@ -265,7 +265,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
|
||||
- 라운드 밖(다른 문서, 커밋, 주석)에서는 리뷰 폴더 날짜의 월일을 붙인다: `MMDD/<ID>`(가이드 36.3절).
|
||||
- 영역 번호 자리에 `NN` 같은 자리표시자를 남기지 않는다. 리뷰가 끝난 뒤 영역 접두어를 바꾸지 않는다.
|
||||
- 영역 번호는 그 라운드 영역 표의 순번이다. 지난 라운드 번호와 맞추지 않아도 된다. 지난 라운드 영역 하나를 둘로 나누면 뒤에 새 번호를 잇고(04를 나누면 04·05), 「범위」 절에 지난 영역과의 대응을 적는다.
|
||||
- 한 라운드의 ID는 리뷰 하나가 매긴다. 같은 범위를 두 리뷰가 따로 봤으면 brief가 정한 쪽이 정본이다. 다른 쪽 발견은 정본의 다음 번호로 새 ID를 받고, 두 ID의 대응표를 README의 그 라운드 색인 절에 둔다. 다른 쪽 문서를 그대로 합치지 않는다(같은 ID가 다른 결함을 가리킨다).
|
||||
- 한 라운드의 ID는 리뷰 하나가 매긴다. 같은 범위를 두 리뷰가 따로 봤으면(독립 리뷰어 둘, [improve.md](../improve.md) 4.1절) brief가 정한 쪽이 정본이다. 다른 쪽은 임시 번호 `B-NN-MM`을 쓰고, 그 발견은 합칠 때 정본의 다음 번호로 새 ID를 받는다. 두 ID의 대응표를 README의 그 라운드 색인 절에 둔다. 다른 쪽 문서를 그대로 합치지 않는다(같은 ID가 다른 결함을 가리킨다).
|
||||
- ID는 리뷰 문서·brief·커밋에서 쓴다. 매뉴얼(`docs/work/`) 본문에는 쓰지 않는다.
|
||||
|
||||
## 11. 판단을 적는 법
|
||||
|
||||
Reference in New Issue
Block a user