docs(work): cold-read 시험 2회차 빈틈 52건을 매뉴얼에 반영한다
문제: 2026-11-07 round7 수정 다섯, 통합, round8 확인 리뷰 둘, 문서 과제
하나를 이력 없는 세션 9개로 돌렸다. 매뉴얼에서 답을 못 찾은 곳이 52건
나왔고(1회차 35건), 코드 수정 과제에서 같은 질문이 되풀이됐다: desktop
포매터 결과 가져오기(4세션), 커밋 단위 모순(4), 테스트 수 세는 곳(3), RED 없는
수정의 증거(3), 넘어온 「범위 밖」 항목(3), PR 단계 명령 묶음(2).
고른 방법: 되풀이된 질문은 절차 한 곳에서 끝냈다.
- operate.md 4.1절: spotlessApply 결과를 노트북에 가져와 트리 해시를 맞추는
명령, 결과 XML 보관, 중간 커밋 검증, 도구 설치 단계는 따라 하지 않음
- gates.md: 단계별 묶음 표(PR·main·라운드 끝), 테스트 수 세는 명령, 앞 실행을
증거로 쓰는 조건, 중첩 빌드 FROM-CACHE, 탐침(rc 읽기, --tests 필터, 의존성)
- improve.md: RED 없는 수정의 증거, 같은 원인과 범위 밖의 경계, 업그레이드
안내 행, 약속한 응답으로 맞추기, 「정한 기본값」 확인, 넘어온 항목
- README 4절 커밋 단위(commit-and-pr 정본에 맞춤), 2절 소유자가 정한 큰 변경
- review-criteria 10절 확인 리뷰 README 절 순서, delegate 4.1절 기본값 옮기기
결정 색인에 기본값 일곱을 남겼다(소유자가 뒤집을 수 있다). 처리 표는
evidence.md 11절이다(34행, 고치지 않음 0, 소유자 결정 필요 0). 수정 과제의
답(round8 발견을 어떻게 고칠지)은 쓰지 않았다. 다음 시험이 그 과제다.
위험·한계: 분량 상한에 가까워졌다(improve 143/150, operate 141/150, README
77/80). cold-read 시험은 이 커밋 뒤 3회차가 한다. 기본값 일곱(커밋 단위,
넘어온 항목, 약속한 응답, 검사를 더 엄하게, 업그레이드 안내 행, 태그 단계,
도구 설치)은 소유자 확인 대상이다.
검증(트리 f43dbc29, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/C-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
lychee 범위 --links rc=0, check-review-index.py 2026-11-03-rereview rc=0
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- MongoNamespaceContractTest --rerun rc=0(3건)
- 테스트 수 세는 명령은 desktop의 지난 결과 XML로 시험했다
This commit is contained in:
+3
-2
@@ -25,7 +25,7 @@
|
||||
- brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다.
|
||||
- 이 repo에서 "경계"는 registry의 leaf 하나다. 파일 수가 아니라 바뀌는 경계와 영향으로 정한다.
|
||||
- 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 `docs/web/http-contract.md`, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 보안 정책.
|
||||
- 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다([research-design.md](research-design.md)).
|
||||
- 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다([research-design.md](research-design.md)). 소유자가 그 변경을 이미 정했으면(결정 색인 행, 소유자 원문) 그 결정이 소유자 검토다. 출처와 시각을 보고에 적고 만든다. 결정이 다루지 않은 범위만 멈추고 묻는다.
|
||||
|
||||
## 3. 모든 작업의 공통 단계
|
||||
|
||||
@@ -44,6 +44,7 @@
|
||||
- 예외는 하나다. brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다(desktop 검증은 [operate.md](operate.md) 4.1절 「push 전에 검증하기」).
|
||||
- 그때도 main 병합, main·다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자가 한다.
|
||||
- 메시지 형식은 design-docs `conventions/commit-and-pr.md`를 따른다. AI 꼬리말과 자리표시자(`TBD`, `TODO`, 채우지 않은 칸)를 넣지 않는다.
|
||||
- 커밋 하나에 논리 변경 하나다(같은 문서 3.1절). 수정 묶음도 결함(또는 같은 원인 하나)마다 커밋을 나누고, 동작 변경을 위한 리팩터링(규칙을 상수로 빼기 등)은 앞 커밋으로 나눈다. 나눈 커밋마다 그 커밋이 바꾼 것의 검사가 통과해야 한다([operate.md](operate.md) 4.1절 「push 전에 검증하기」).
|
||||
|
||||
## 5. 막혔을 때
|
||||
|
||||
@@ -56,7 +57,7 @@
|
||||
- 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다.
|
||||
- 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(위치와 내용, 고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다.
|
||||
- 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다.
|
||||
- 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다.
|
||||
- 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다. 테스트 수는 성공한 Gradle 로그에 없으니 결과 XML 사본에서 센다([reference/gates.md](reference/gates.md) 4절).
|
||||
- 사고 순서 흔적 칸을 둔다(`conventions/work-thinking-order.md` 3절). 다른 세션이 맡긴 일이면 design-docs `conventions/delegation-loop.md` 5절 양식을 쓴다.
|
||||
|
||||
## 7. 필요할 때만 읽는 문서
|
||||
|
||||
@@ -32,7 +32,8 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
|
||||
- brief의 「작업 종류」는 이 repo의 `docs/work/<종류>.md`다. 「이미 아는 것」에는 [reference/decisions.md](reference/decisions.md)의 결정을 **내용으로** 옮긴다. 검증 명령은 [reference/gates.md](reference/gates.md)와 빌드 파일에서 실제 태스크 이름을 확인해 쓴다.
|
||||
- 검증 칸에는 실행 위치와 증거 위치를 쓴다: desktop worktree, `flock /tmp/claude-gates/heavy.lock`, 로그 `~/<작업 이름>-logs/`([operate.md](operate.md) 4.1절). 7절에는 커밋 허용과 자기 브랜치 push 허용을 따로 쓴다.
|
||||
- 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸부터 보라고 적고, 지난 라운드에서 열린 채 넘어온 「Declined to judge」를 다시 판정시킬지도 적는다.
|
||||
- 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸과 「정한 기본값」부터 보라고 적고, 지난 라운드에서 열린 채 넘어온 「Declined to judge」와 README 남은 항목을 다시 판정시킬지도 적는다.
|
||||
- 수정 보고를 받으면 「정한 기본값」을 리뷰 README 처리 표와 [reference/decisions.md](reference/decisions.md) 기본값 행으로, 「범위 밖에서 본 것」을 README 남은 항목으로 옮긴다([reference/review-criteria.md](reference/review-criteria.md) 10절 「확인 리뷰 라운드의 README 절」). 옮기지 않은 기본값은 확인 리뷰가 볼 곳이 없다.
|
||||
- 리뷰 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)를 둔다.
|
||||
|
||||
@@ -32,13 +32,15 @@
|
||||
3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다.
|
||||
4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다.
|
||||
5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다.
|
||||
6. 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 [evidence.md](evidence.md)에 원래 문서·문장과 함께 모은다. 번호의 원래 문서가 이 repo에 없으면 그 번호가 가리키는 규칙 이름과 코드 위치를 근거로 적고, 원래 문서가 repo에 없다고 쓴다.
|
||||
6. 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 [evidence.md](evidence.md)에 원래 문서·문장과 함께 모은다. 걷어낸 문서 묶음(예: `docs/manual/`, 진입 문서)마다 절 하나를 두고, 같은 묶음을 다시 걷어내면 그 절에 표를 더한다. ID가 무엇을 가리키는지는 evidence.md 머리말 「표기」로 찾는다. 번호의 원래 문서가 이 repo에 없으면 그 번호가 가리키는 규칙 이름과 코드 위치를 근거로 적고, 원래 문서가 repo에 없다고 쓴다.
|
||||
7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다.
|
||||
8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다.
|
||||
9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다.
|
||||
9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(지도 3절: brief가 먼저다).
|
||||
10. `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다.
|
||||
11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다.
|
||||
12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`.
|
||||
- 이력 검사 패턴을 더하면 오탐을 시험한다. 잡아야 할 이력 문장과 잡지 말아야 할 보통 문장을 시험 파일로 만들어 `--history`로 돌린다. `docs/reviews/**` 밖 전체(`git ls-files '*.md' ':!docs/reviews'`)에도 돌려 새로 걸린 줄을 모두 읽는다. 검사 대상 파일의 오탐은 패턴을 좁혀 없애고, 대상 밖의 오탐은 보고에 적는다.
|
||||
- 기본 검사를 넓히는 커밋은 그 검사가 새로 잡는 문서를 고친 커밋 뒤에 둔다(또는 같은 커밋). 그래야 어느 커밋에서도 기본 모드가 rc=0이다.
|
||||
13. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다.
|
||||
|
||||
**playbook을 새로 만들 때의 뼈대** (모든 playbook이 같은 제목을 쓴다. 검사 스크립트가 본다):
|
||||
|
||||
@@ -317,3 +317,53 @@
|
||||
- 고친 오탐: 날짜로 쓴 결정(`owner decision 2026-11-06`, `소유자 결정 2026-11-07`)은 잡지 않는다.
|
||||
- 줄바꿈 검사: 한 줄에서 안 걸려도 다음 줄과 이었을 때 줄 경계를 넘는 ID(`(review` ↵ `2026-11-01 07-10)`)를 잡는다. 이번에 2줄(web·persistence-mongo)이 이 꼴이었다. persistence-fileserver·cache-redis의 갈린 괄호는 둘째 줄의 `RR-` 접두어가 따로 잡혔다.
|
||||
- 오탐 시험(`docs-writing.md` 4절 12단계): 잡아야 할 문장 10개는 모두 잡혔다. 잡지 말아야 할 문장 8개 중 하나가 걸렸다: 일부러 만든 "line 10-12 (b)"(콜론 없는 줄 범위 뒤 대안 표시)다. repo에는 그 꼴이 없어 그대로 뒀다. `docs/reviews/**` 밖 전체에 돌리면 새로 125줄이 걸린다. 모두 검사 대상 밖(모듈 README, ADR, `docs/httpclient/` 등)의 실제 ID이고, 검사 대상 안의 오탐은 0이다.
|
||||
|
||||
## 11. cold-read 시험 2회차 빈틈 처리 (2026-11-07)
|
||||
|
||||
2026-11-07 round7 수정과 통합, round8 확인 리뷰를 시험으로 돌렸다. 이력 없는 세션 9개가 1회차 수정을 넣은 매뉴얼(기준 `73d39212`, 통합과 리뷰는 `83a12f66`)로 일했다. 9개 모두 일은 끝냈고, 매뉴얼에서 답을 못 찾은 곳이 52건 나왔다(1회차 35건). 코드 수정 과제에서 같은 질문이 되풀이됐다. 아래는 공유 노트(`~/.config/Claude/side-session-notes/local_fcd89c34-c754-4c5b-a38f-fa322834286f/`)의 「매뉴얼에서 답을 못 찾은 곳」과 시험 기록(design-docs `delegation-loop/trials/2026-11-07-*.md`)의 「질문」 표를 한 줄씩 처리한 결과다. 기준 커밋 `83948d58`.
|
||||
|
||||
- 세션과 출처 번호: F1 `r8-f1-transport-errors`, F2 `r8-f2-arch-rules`, F3 `r8-f3-persistence`, F4 `r8-f4-idempotency`, F5 `r8-f5-small-fixes`(결함 수정 다섯), M `c-t4-2-manual-ids`(문서), I `r8-integration`(통합과 전체 게이트), A `r8-review-a`(정본 확인 리뷰어), B `r8-review-b`(다른 확인 리뷰어). `F1-3`은 F1 시험 기록 「질문」 표의 3번이다(노트의 순서와 같다). A는 노트 1~5와 2차의 추가 1건(A-6), B는 노트 11절의 1~5다. B의 시험 기록 「질문」 표는 "노트에 절이 없음"이라고 적었지만 노트 11절에 다섯 건이 있다.
|
||||
- 두 세션 이상이 같은 질문을 했으면 한 행으로 묶고 「세션」 칸에 수를 적었다. 묶은 행이 먼저다.
|
||||
- 처리 칸: 고침(고친 곳) / 고치지 않음(이유) / 소유자 결정 필요. 「고침(기본값)」은 이 수정이 정하고 결정 색인에 기본값으로 남긴 것이다(소유자가 뒤집을 수 있다).
|
||||
- 수정 과제의 답(round8 발견을 어떻게 고칠지)은 매뉴얼에 쓰지 않았다. 다음 시험이 그 과제다.
|
||||
|
||||
| # | 출처 | 세션 | 빈틈 | 처리 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| R2-1 | F1-3, F2-3, F3-2, F4-5 | 4 | desktop에서 `spotlessApply`로 고친 형식을 노트북 트리로 가져오는 절차가 없다. 첫 GREEN이 형식 위반으로 실패한 세션도 있다 | 고침 — `operate.md` 4.1절 「push 전에 검증하기」(형식 맞추기 명령 세 줄, 두 트리 해시 대조, 그 트리에서 게이트) |
|
||||
| R2-2 | F1-6, F3-6, F5-2, M-4 | 4 | 커밋 단위가 두 문서에서 다르다(`commit-and-pr.md` "논리 변경 하나", `improve.md` "묶음마다 커밋 하나") — **모순**. 리팩터링 추출을 따로 커밋하나, 나눈 중간 커밋도 검증하나, 검사를 넓히는 커밋은 언제 두나 | 고침(기본값) — `docs/work/README.md` 4절(논리 변경마다, 리팩터링은 앞 커밋, 커밋마다 그 검사), `improve.md` 4.4절(묶음은 브랜치 하나), `operate.md` 4.1절(중간 커밋은 바뀐 leaf `check`, 무거운 묶음은 마지막 트리), `docs-writing.md` 4절 12단계(검사를 넓히는 커밋은 문서 커밋 뒤), `reference/decisions.md` 2.1 「커밋 단위」(기본값) |
|
||||
| R2-3 | F4-6, F3-4, I-2 | 3 | 테스트 수를 어디서 세나(성공한 Gradle 로그에 없다). 같은 worktree의 다음 실행이 결과 XML을 덮어써 다시 셀 수 없다 | 고침 — `reference/gates.md` 4절 「테스트 수 세기」(복사와 세는 명령, desktop에서 시험), `operate.md` 4.1절, `docs/work/README.md` 6절 |
|
||||
| R2-4 | F2-1, F3-1, F4-3 | 3 | RED가 없는 수정(문서를 동작에 맞춤, 계약만 넓힘)은 무엇을 증거로 남기나 | 고침 — `improve.md` 4.2절 3단계 아래 줄, 5절, 8절 RED 칸, design-docs `conventions/work-thinking-order.md` 1절, 스킬 `research-first` 4절 |
|
||||
| R2-5 | A-2, B-1, I-4 | 3 | 수정 세션의 「범위 밖에서 본 것」이 README 남은 항목인지, 다음 확인 리뷰의 입력인지, 누가 판정하나(Declined와 같은 취급인가) | 고침(기본값) — `improve.md` 4.1절 9단계, `reference/review-criteria.md` 10절(확인 리뷰 문서 「넘어온 항목 판정」, 「확인 리뷰 라운드의 README 절」 끝 문단), `delegate.md` 4.1절, `reference/decisions.md` 2.1 「넘어온 「범위 밖」 항목」, design-docs `conventions/delegation-loop.md` 6절 |
|
||||
| R2-6 | F1-4, F4-7 | 2 | 앞 실행(같은 worktree의 UP-TO-DATE, 같은 트리 해시의 이전 실행)을 통과 증거로 써도 되나 | 고침 — `reference/gates.md` 4절 「앞 실행을 증거로 쓰기」. 3절 「실제로 돌았음을 보이기」가 4절을 가리킨다 |
|
||||
| R2-7 | F1-2, F2-2 | 2 | brief의 "pull request 단계 게이트"가 어느 명령들인지 한 곳에 없다 | 고침 — `reference/gates.md` 3절 「단계별 묶음」 표(PR·main·라운드 끝). F2가 찾지 못한 buf job은 3절 (다)에 이미 있다(F2가 읽은 `73d39212` 뒤에 더해졌다) |
|
||||
| R2-8 | F1-5, F4-2 | 2 | "같은 원인의 다른 자리를 찾는다"와 "범위 밖 결함을 고치지 않는다"의 경계 | 고침 — `improve.md` 4.2절 5단계(brief 영역 안이고 공개 동작이 그대로면 함께 고친다. 아니면 「범위 밖」에 권하는 안과 적는다) |
|
||||
| R2-9 | F4-4, F5-3 | 2 | 소유자가 이미 정한 큰 변경도 따로 멈추나. 규칙이 스킬과 design-docs에만 있고 repo 매뉴얼에 없다 | 고침 — `docs/work/README.md` 2절(정본 `conventions/work-thinking-order.md` 2.3절과 같은 뜻) |
|
||||
| R2-10 | F2-4, F5-1 | 2 | 아직 릴리스하지 않은 업그레이드 안내 행이 같은 표면을 다룰 때 고치나 더하나, 머리 「커밋:」 목록, `!` | 고침(기본값) — `improve.md` 4.2절 7단계 아래 줄, `reference/decisions.md` 2.7 「아직 합치지 않은 업그레이드 안내」 |
|
||||
| R2-11 | A-4, B-4 | 2 | 탐침이 그 source set에 없는 의존성을 써야 할 때 `build.gradle`·lockfile을 바꿔도 되나(A는 바꾸지 않고 E1, B는 버릴 worktree에서 바꿈) | 고침 — `reference/gates.md` 2절 「탐침」 셋째 줄(버릴 worktree에서만, 바꾼 줄을 적는다, 안 하면 E1), `improve.md` 4.1절 5단계 |
|
||||
| R2-12 | F1-1 | 1 | `improve.md` 7절 "응답 코드를 바꾸면 묻는다"가 레지스트리가 이미 약속한 응답으로 코드를 맞추는 경우(500→409)에도 해당하나 | 고침(기본값) — `improve.md` 7절 첫 줄, `reference/decisions.md` 2.3 「약속한 응답으로 맞추기」 |
|
||||
| R2-13 | F1-7 | 1 | 결정 색인 2.3절 표에 날짜 칸이 없다 | 고침 — `reference/decisions.md` 2절 머리(날짜는 「누가」나 「출처」 칸에). 기존 행은 이미 출처 칸에 날짜가 있어 표 모양은 두었다 |
|
||||
| R2-14 | F2-5 | 1 | 리뷰 권장안과 다른 안을 고르면 누가 확인하나 | 고침 — `improve.md` 3절 대안 줄, 8절 「정한 기본값」 칸(보고에 적어 확인 리뷰와 맡긴 쪽이 본다. 공개 동작이 다르면 묻는다) |
|
||||
| R2-15 | F3-3 | 1 | 임시 RED 메서드에도 Error Prone 규칙(`CheckReturnValue`)이 오류로 걸린다 | 고침 — `improve.md` 9절 strict lane 탐침 줄 |
|
||||
| R2-16 | F3-5 | 1 | 이미 문서화된 규칙을 검사가 더 엄하게 지키게 바꾸면 「파생 서비스가 따라 고쳐야 하는 변경」(큼·`!`)인가 | 고침(기본값) — `improve.md` 4.2절 7단계(`!`와 안내 행은 단다, 크기는 올리지 않는다), `reference/decisions.md` 2.7 「검사를 더 엄하게 하는 수정」 |
|
||||
| R2-17 | F3-7 | 1 | ArchUnit fixture도 `testQualityCheck`(SpotBugs)가 분석하고, Lombok 클래스를 상속한 fixture는 실패한다 | 고침 — `reference/gates.md` 2절 표(「테스트 코드(ArchUnit fixture 포함)」)와 그 아래 줄 |
|
||||
| R2-18 | F3-8 | 1 | optional 빌드 leaf의 RED·탐침에 main 리소스 임시 파일(임시 마이그레이션)을 두는 법 | 고침 — `improve.md` 4.2절 3단계(임시 파일은 main 리소스든 그 worktree에만) |
|
||||
| R2-19 | F4-1 | 1 | brief의 "같은 핸들"이 넘겨받기 전 핸들인지 적용한 핸들인지 정해지지 않았다 | 고침 — brief를 쓰는 규칙: design-docs `conventions/delegation-loop.md` 4.2절(결정을 옮길 때 대상이 둘 이상으로 읽히면 경우마다 적는다). repo 매뉴얼이 아니라 brief 문구의 빈틈이다 |
|
||||
| R2-20 | M-1 | 1 | brief 완료 기준(대조 테스트 통과)과 playbook(읽는 테스트가 없으면 lane을 돌리지 않음)이 다르다 | 고침 — `docs-writing.md` 4절 9단계, `reference/gates.md` 2절(brief가 lane을 정했으면 돌린다) |
|
||||
| R2-21 | M-2 | 1 | 이력 표기 정의가 없다(「1라운드」, `P30`·`W3-P30`) | 고침 — 이 문서 머리말 「더 오래된 표기」 |
|
||||
| R2-22 | M-3 | 1 | 걷어낸 ID의 근거를 이 문서 어느 절에 더하나. 9절 T4-1 행을 고치나 | 고침 — `docs-writing.md` 4절 6단계(문서 묶음마다 절 하나, 다시 걷어내면 그 절에 표). T4-1 행은 기록이라 두었다(8절 둘째 표가 그 결과다) |
|
||||
| R2-23 | M-5 | 1 | 새 이력 패턴의 오탐을 어떻게 시험하고 어디까지 받아들이나 | 고침 — `docs-writing.md` 4절 12단계 아래 줄. 이번 패턴 추가에 그대로 적용했다(10절 끝) |
|
||||
| R2-24 | I-1 | 1 | `mainCheck` 안 `verifyFeatureScaffold`의 중첩 빌드에는 `--no-build-cache`가 넘어가지 않아 FROM-CACHE 0을 만들 수 없다 | 고침 — `reference/gates.md` 3절 「실제로 돌았음을 보이기」 아래 줄(바깥 0, 중첩 빌드 N을 따로 적는다) |
|
||||
| R2-25 | I-3 | 1 | 라운드 끝 묶음의 태그 단계 범위(`release.yml`의 다른 gate job) | 고침(기본값) — `reference/gates.md` 3절 「단계별 묶음」 아래 줄, `reference/decisions.md` 2.7 「라운드 끝 태그 단계 범위」 |
|
||||
| R2-26 | I-5 | 1 | 확인 리뷰 README 안의 하위 절 순서, 처리 표 칸(`improve.md` 8절과 brief가 다름) | 고침 — `reference/review-criteria.md` 10절 「확인 리뷰 라운드의 README 절」(여덟 절의 순서, 처리 표 칸, brief가 먼저) |
|
||||
| R2-27 | I-6 | 1 | `trivy-fs` job은 trivy를 내려받아 설치한다. 설치까지 하나 | 고침(기본값) — `operate.md` 4.1절(설치 단계는 따라 하지 않는다), `reference/gates.md` 3절 (다) 표, `reference/decisions.md` 2.1 「desktop 도구 설치」, design-docs `conventions/delegation-loop.md` 11절 |
|
||||
| R2-28 | A-1 | 1 | 독립 리뷰어 둘일 때 정본 리뷰어의 색인 검사: 매뉴얼은 rc=0을 요구하고 README 색인 절은 총괄이 쓰게 한다 — **모순**(발견 `1103/RR8-06-01`) | 고침 — `scripts/check-review-index.py --extra-index`, `improve.md` 4.1절 7·8단계와 5절, `delegate.md` 4.1절, `reference/decisions.md` 2.1 「리뷰 README 분담」. 시험: 정본 리뷰어 커밋 `27260ad0`의 리뷰 폴더에 옵션 없이 rc=1(180 중 172), 리뷰어 A의 색인 표(`r8-review-a-probes/index-table.md`)를 넘기면 rc=0(180/180). 리뷰가 권한 "임시 사본" 절차 대신 옵션을 골랐다: 복사·붙이기 단계 없이 명령 하나로 같은 대조를 한다 |
|
||||
| R2-29 | A-3 | 1 | 확인 리뷰 범위에 결함 수정이 아닌 커밋(매뉴얼 수정)이 섞이면 그것도 보나("그 수정만 본다") | 고침 — `improve.md` 4.1절 3단계(brief 범위의 커밋을 본다, 결함 수정이 아닌 커밋은 영역 하나로) |
|
||||
| R2-30 | A-5 | 1 | strict lane에 `--tests` 필터로 탐침만 돌려도 되나 | 고침 — `reference/gates.md` 2절 「탐침」 둘째 줄(`requires` lane은 필터 없이. `StrictTestLanePlugin`의 required 검사가 고른 클래스가 다 돌지 않으면 실패시킨다) |
|
||||
| R2-31 | A-6 | 1 | 두 리뷰의 「이번 수정 / 이전부터」 분류가 다를 때 어느 쪽을 쓰나 | 고침 — `reference/review-criteria.md` 10절 「ID」 끝 줄(정본 리뷰어가 근거를 붙여 정하고 차이를 대응표에) |
|
||||
| R2-32 | B-2 | 1 | 확인 리뷰가 수정 세션의 「정한 기본값」을 어떻게 다루나, README·결정 색인으로 옮겨졌는지 누가 보나(round8 Important 회귀 하나가 옮겨지지 않은 기본값에서 나왔다) | 고침 — `improve.md` 4.1절 2단계(옮겨지지 않은 공개 동작 기본값은 발견), `delegate.md` 4.1절(총괄이 옮긴다), `reference/review-criteria.md` 10절, design-docs `conventions/delegation-loop.md` 6절 |
|
||||
| R2-33 | B-3 | 1 | 상한을 넘는 범위를 brief가 노트 하나로 받았을 때 문서 모양 | 고침 — `improve.md` 4.4절(출력 파일 하나면 그 안에 단위마다 절) |
|
||||
| R2-34 | B-5 | 1 | 탐침 rc를 읽는 법(결함 동작을 단언한 탐침과 약속을 단언한 탐침이 섞임) | 고침 — `reference/gates.md` 2절 「탐침」 첫 줄, `reference/review-criteria.md` 10절 「실행한 명령과 결과」 칸 |
|
||||
|
||||
- 합계: 52건, 34행. 고침 34행(그중 기본값 7행), 고치지 않음 0, 소유자 결정 필요 0.
|
||||
- 소유자 결정(2026-11-07)으로 한 일: 이력 ID 0 규칙을 진입 문서로 넓혔다(10절, 결정 색인 2.1 「이력 ID 0 규칙의 범위」).
|
||||
- 「자주 하는 실수」에 넣은 줄: `improve.md`(탐침의 Error Prone을 기존 줄에 더함).
|
||||
|
||||
+17
-15
@@ -28,7 +28,7 @@
|
||||
- 보통 중간이다: 확인 리뷰 하나, 수정 묶음 하나.
|
||||
- 큼: 전체 리뷰, 구조 변경, 공개 계약을 바꾸는 수정. 큰 일은 1~5단계 결과와 대안을 소유자가 먼저 본다.
|
||||
- 이 작업에서 선행 사례는 둘이다: 같은 원인이 남은 다른 자리, 그리고 [reference/defect-patterns.md](reference/defect-patterns.md)의 같은 모양.
|
||||
- 대안은 고치는 법 2~3개를 비교한다. 고른 것과 버린 것을 커밋 본문에 쓴다.
|
||||
- 대안은 고치는 법 2~3개를 비교한다. 고른 것과 버린 것을 커밋 본문에 쓴다. 리뷰의 권장안을 버리면 버린 이유를 커밋 본문에, 고른 안을 보고 「정한 기본값」에 적는다(확인 리뷰와 맡긴 쪽이 본다). 고른 안의 공개 동작이 권장안과 다르면 7절대로 묻는다.
|
||||
- 스킬: 리뷰는 `superpowers:requesting-code-review`의 리뷰어 지침과 바뀐 경계의 영역 스킬, 결함 수정은 `superpowers:systematic-debugging` → `superpowers:test-driven-development`, 리팩터링은 `refactor`·`codebase-design`, 성능은 `performance-optimization`, 구조 변경은 `superpowers:brainstorming` → `superpowers:writing-plans`. 리뷰 결과를 받아 고칠 때는 `superpowers:receiving-code-review`.
|
||||
- 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 이 세션이 직접 한다. 나눠야 하면 [delegate.md](delegate.md)대로 별도 세션에 맡긴다.
|
||||
|
||||
@@ -37,14 +37,14 @@
|
||||
### 4.1 리뷰
|
||||
|
||||
1. 범위를 고정한다. 확인 리뷰는 pathspec과 `git diff --stat <base>..<head> -- <pathspec>` 결과를 문서에 적는다.
|
||||
2. 확인 리뷰는 수정 보고의 「새로 가정하는 것」 칸부터 본다. 가정마다 다른 코드·설정·운영에서 참인지 확인한다. 그 칸이 없으면(보고가 repo에 없거나 옛 양식) 수정 커밋 본문의 「위험·한계」와 리뷰 README 처리 표의 「결정」 칸에서 가정을 뽑고, 뽑은 곳을 문서 「범위」 절에 적는다.
|
||||
3. 그다음 수정 diff와, diff가 바꾼 동작의 주변 코드를 읽는다. 확인 리뷰는 저장소 전체가 아니라 그 수정만 본다. 읽은 주변 코드에서 본 결함은 이전부터 있었어도 발견으로 적고 「이전부터」로 표시한다. 그 밖을 찾아 나서지 않는다.
|
||||
2. 확인 리뷰는 수정 보고의 「새로 가정하는 것」 칸부터 본다. 가정마다 다른 코드·설정·운영에서 참인지 확인한다. 그 칸이 없으면(보고가 repo에 없거나 옛 양식) 수정 커밋 본문의 「위험·한계」와 리뷰 README 처리 표의 「결정」 칸에서 가정을 뽑고, 뽑은 곳을 문서 「범위」 절에 적는다. 보고의 「정한 기본값」도 읽는다. 공개 동작을 바꾸는 기본값이 결정 색인과 README 처리 표 어디에도 없으면 발견으로 적는다.
|
||||
3. 그다음 수정 diff와, diff가 바꾼 동작의 주변 코드를 읽는다. 확인 리뷰는 저장소 전체가 아니라 brief 범위의 커밋만 본다. 결함 수정이 아닌 커밋(매뉴얼 수정 등)도 범위에 있으면 영역 하나로 따로 본다. 읽은 주변 코드에서 본 결함은 이전부터 있었어도 발견으로 적고 「이전부터」로 표시한다. 그 밖을 찾아 나서지 않는다.
|
||||
4. 전체 리뷰는 게이트를 먼저 한 번 돌려 결과를 적고([reference/gates.md](reference/gates.md)), 영역을 나눈다([delegate.md](delegate.md) 「나누는 법」).
|
||||
5. 의심 결함은 별도 worktree의 임시 테스트(탐침)로 확인한다. 탐침 코드는 고칠 때 옮겨 쓸 수 있게 남기고(소유자 환경에서는 공유 노트 폴더, design-docs `conventions/delegation-loop.md` 11절), worktree는 지운다.
|
||||
5. 의심 결함은 별도 worktree의 임시 테스트(탐침)로 확인한다. 탐침 코드는 고칠 때 옮겨 쓸 수 있게 남기고(소유자 환경에서는 공유 노트 폴더, design-docs `conventions/delegation-loop.md` 11절), worktree는 지운다. 탐침의 단언과 rc 읽기, 의존성 더하기, strict lane 필터는 [reference/gates.md](reference/gates.md) 2절 「탐침」이다.
|
||||
6. 발견을 [reference/review-criteria.md](reference/review-criteria.md) 양식으로 적는다. 발견마다 증거 수준과 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다.
|
||||
7. 리뷰 폴더 README에 이번 라운드의 색인 절 하나를 더한다: 발견 ID, 심각도, 한 줄 내용, 결정이 필요한 질문. 발견 ID를 모두 이름으로 적는다. 범위(`A~B`)와 이어 쓰기(`A·07`)는 된다. 건수만 쓰지 않는다. README의 다른 절(처리 표, 결정의 답, 라운드 끝 게이트)은 맡긴 쪽이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면(독립 리뷰어 둘 포함) 색인 절도 맡긴 쪽이 쓰고, 리뷰어는 README를 고치지 않고 보고에 같은 표를 둔다.
|
||||
8. `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌려 rc=0을 본다. 색인 절이 따로 있으면 `--index-heading "<절 제목>"`을 붙인다. 색인 절을 맡긴 쪽이 쓰면 보고의 색인 표만 담은 파일을 `--extra-index <파일>`로 넘겨 rc=0을 본다. 그때 옵션 없이 돌린 rc=1은 맡긴 쪽이 색인 절을 쓰면 닫히니, 보고에 두 결과를 함께 적는다. 지난 라운드 색인에서 빠진 ID 때문에 처음부터 rc=1이면, 빠진 ID를 이번 색인 절에 「색인 보완」 한 줄로 이름만 적는다. 지난 영역 문서는 고치지 않는다.
|
||||
9. 판단하지 않은 항목은 「Declined to judge」에 위치와 이유를 적는다. 맡긴 쪽이 다음 묶음에 배정하거나 결정으로 닫는다. 지난 라운드에서 열린 채 넘어온 Declined는 brief가 맡겼을 때만 다시 판정한다. 맡기지 않았으면 건수와 위치만 적는다.
|
||||
9. 판단하지 않은 항목은 「Declined to judge」에 위치와 이유를 적는다. 맡긴 쪽이 다음 묶음에 배정하거나 결정으로 닫는다. 지난 라운드에서 넘어온 항목(열린 Declined, 수정 세션의 「범위 밖에서 본 것」을 README가 남은 항목으로 옮긴 것)은 brief가 맡겼을 때만 다시 판정하고, 문서에 「넘어온 항목 판정」 절을 둔다. 맡기지 않았으면 건수와 위치만 적는다.
|
||||
|
||||
**독립 리뷰어 둘.** 아래 셋 중 하나면 같은 범위를 서로 결과를 보지 않는 리뷰어 둘이 따로 리뷰하고 맡긴 쪽이 합친다([delegate.md](delegate.md) 4.1절).
|
||||
|
||||
@@ -57,11 +57,13 @@
|
||||
|
||||
1. 원인 경로를 확인한다. 증상이 아니라 원인을 적는다.
|
||||
2. RED: 결함을 재현하는 테스트를 먼저 쓰고, 수정 전 코드에서 실패하는 것을 실행으로 본다. 실패 메시지가 그 결함을 말해야 한다. 컴파일 오류나 준비 실패는 RED가 아니다.
|
||||
3. 수정과 테스트를 이미 같이 썼으면, 기준 커밋에 테스트만 얹은 임시 worktree에서 RED를 본다. 실 DB·Redis가 필요한 결함은 실 vendor lane에서 본다.
|
||||
3. 수정과 테스트를 이미 같이 썼으면, 기준 커밋에 테스트만 얹은 임시 worktree에서 RED를 본다. 실 DB·Redis가 필요한 결함은 실 vendor lane에서 본다. RED용 임시 파일은 테스트든 main 리소스(임시 마이그레이션 등)든 그 worktree에만 둔다.
|
||||
- RED가 없는 수정도 있다. 문서를 동작에 맞추면, 문서의 주장을 그대로 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 이름·설명 문제처럼 테스트로 옮길 수 없으면 틀린 문장과 실제 동작의 출처를 적는다. 동작은 두고 계약만 넓히면 새 케이스가 기준 커밋에서도 통과함을 보이고 「지키는 테스트」로 적는다. 보고 RED 칸에는 "RED 없음 — 이유"를 쓴다.
|
||||
4. 가장 작은 수정으로 GREEN을 본다.
|
||||
5. 같은 원인의 다른 자리를 찾는다. 경계마다 다시 구현된 규칙은 한 곳만 고치면 다른 곳에서 다시 갈라진다.
|
||||
5. 같은 원인의 다른 자리를 찾는다. 경계마다 다시 구현된 규칙은 한 곳만 고치면 다른 곳에서 다시 갈라진다. 찾은 자리가 brief 영역 안이고 공개 동작이 바뀌지 않으면 함께 고치고 보고에 적는다. 공개 동작이 바뀌거나 brief 영역 밖이면 고치지 않고 「범위 밖에서 본 것」에 권하는 안과 함께 적는다. 묶음 상한(4.4절)도 지킨다.
|
||||
6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`CLAUDE.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다.
|
||||
7. 파생 서비스가 따라 고쳐야 하면 `docs/upgrade/`의 안내에 행을 더하고, 커밋 제목에 `!`와 `BREAKING CHANGE:` 꼬리말을 단다.
|
||||
7. 파생 서비스가 따라 고쳐야 하면 `docs/upgrade/`의 안내에 행을 적고, 커밋 제목에 `!`와 `BREAKING CHANGE:` 꼬리말을 단다. 문서에 이미 적힌 규칙을 검사가 더 엄하게 지키게 되어 그 규칙을 어기던 코드가 새로 실패하는 것도 여기에 든다(규칙은 이미 정해져 있어 크기는 올리지 않는다).
|
||||
- 안내의 범위(머리 「범위」)가 아직 main에 합쳐지지 않았으면 파생 서비스는 그 행을 받기 전이다. 같은 표면의 행이 있으면 그 행을 고쳐 최종 동작을 적고, 머리 「커밋:」 목록에 이번 커밋을 더한다. main에 합쳐진 안내는 고치지 않고 새 행을 더한다.
|
||||
8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)).
|
||||
|
||||
### 4.3 리팩터링, 성능, 구조, 테스트 구조
|
||||
@@ -74,9 +76,9 @@
|
||||
|
||||
### 4.4 수정 묶음의 크기
|
||||
|
||||
- 묶음 하나는 리뷰 영역 하나 안이고 발견 8건 이하다. 묶음마다 커밋 하나다.
|
||||
- 묶음 하나는 리뷰 영역 하나 안이고 발견 8건 이하다. 묶음마다 브랜치 하나이고, 커밋은 논리 변경마다 나눈다([README](README.md) 4절).
|
||||
- 확인 리뷰 하나가 보는 수정 diff는 추가 1,500줄 이하다(`git diff --shortstat <base>..<head>`, 테스트 포함, lockfile·스냅숏 같은 생성 파일과 리뷰 기록 `docs/reviews/**` 제외). 넘으면 확인 리뷰를 나눈다. 묶음 커밋이 따로 있으면 커밋별로, 한 커밋에 여러 영역이 섞였으면 영역 pathspec별로(`git diff --shortstat <base>..<head> -- <pathspec>`) 나눠 각각 상한 안이 되게 한다. 테스트 파일은 그 테스트가 지키는 코드의 영역에 넣는다.
|
||||
- 나누는 것은 맡긴 쪽이 brief로 한다. 상한을 넘는 범위를 brief 하나로 받았으면, 한 세션이 나눈 단위를 차례로 보고 단위마다 문서 하나를 쓴다. 그렇게 했다고 보고에 적는다.
|
||||
- 나누는 것은 맡긴 쪽이 brief로 한다. 상한을 넘는 범위를 brief 하나로 받았으면, 한 세션이 나눈 단위를 차례로 보고 단위마다 문서 하나를 쓴다. brief가 출력 파일 하나를 정했으면(정본이 아닌 리뷰어의 노트 등) 그 파일 안에 단위마다 절 하나를 둔다. 그렇게 했다고 보고에 적는다.
|
||||
- 왜: 지난 수정 라운드에서 추가 줄이 2,000줄 아래면 다음 확인 리뷰 발견이 9건 이하였고, 5,000줄을 넘으면 19건 이상이었다([evidence.md](evidence.md) 「수정 묶음 크기」). 상한 값은 판단이다. 라운드당 새 결함 수로 다시 맞춘다.
|
||||
- 묶음을 합친 트리는 따로 검증한다([reference/gates.md](reference/gates.md) 「라운드 끝」). 두 묶음의 수정은 한 트리에서 처음 만날 때 새 결함을 만든다.
|
||||
|
||||
@@ -95,7 +97,7 @@
|
||||
## 5. 완료 기준
|
||||
|
||||
- 리뷰: 모든 발견이 양식대로이고 증거 수준이 있다. 색인 검사가 rc=0이다(색인 절을 맡긴 쪽이 쓰면 `--extra-index`로 본 rc). 결정이 필요한 항목마다 선택지와 권하는 안이 있다.
|
||||
- 결함 수정: 수정 전 실패(RED)와 수정 뒤 통과(GREEN) 로그가 있다. 같은 원인의 다른 자리를 확인했다. 해당 게이트가 rc=0이다(desktop 로그 경로). 보고에 「새로 가정하는 것」이 있다.
|
||||
- 결함 수정: 수정 전 실패(RED)와 수정 뒤 통과(GREEN) 로그가 있다. RED가 없는 수정은 "RED 없음 — 이유"와 대신한 증거가 있다(4.2절 3단계). 같은 원인의 다른 자리를 확인했다. 해당 게이트가 rc=0이다(desktop 로그 경로). 보고에 「새로 가정하는 것」이 있다.
|
||||
- 리팩터링: 보존 조건 테스트가 전후 모두 통과하고 `architectureCheck`가 통과한다. 지운 코드를 가리키는 문서·주석이 grep으로 0이다.
|
||||
- 성능: 전후 숫자가 같은 조건에서 나왔다. 회귀 테스트가 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run` 통과).
|
||||
- 구조 변경: `architectureCheck`, `verifyDependencyLocks`, `ci`, `mainCheck`가 통과한다. 문서에 leaf 개수를 적지 않았다.
|
||||
@@ -114,7 +116,7 @@
|
||||
|
||||
## 7. 막혔을 때
|
||||
|
||||
- 고치는 법이 공개 동작(응답 코드, 기동 실패 조건, env 키, 파생 서비스 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다.
|
||||
- 고치는 법이 공개 동작(응답 코드, 기동 실패 조건, env 키, 파생 서비스 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다. 레지스트리·`docs/web/http-contract.md`·Javadoc이 이미 약속한 응답으로 코드를 맞추는 것은 결함 수정이라 묻지 않는다(4.2절 7단계의 안내 행은 적는다). 약속한 곳끼리 다르면 셋째 줄대로 한다.
|
||||
- RED를 만들 수 없으면(실 vendor가 없다, 머신에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다.
|
||||
- 계약을 적은 곳끼리(설계서, 포트 Javadoc, 모듈 README, 테스트) 다르게 말하고 [reference/decisions.md](reference/decisions.md)에 결정이 없으면, 어느 쪽도 고르지 않는다. 양쪽 근거를 표로 붙이고 권하는 안과 함께 묻는다. 그 발견만 멈춘다.
|
||||
|
||||
@@ -126,11 +128,11 @@
|
||||
| --- | --- |
|
||||
| 발견 | 고친 발견의 ID와 한 줄 내용(brief와 리뷰 문서에서는 ID를 쓴다) |
|
||||
| 상태 | 완료 / 부분(무엇이 남았나) / 못 함(이유) |
|
||||
| RED | 수정 전 실패한 테스트 이름과 수, 로그 경로 |
|
||||
| RED | 수정 전 실패한 테스트 이름과 수, 로그 경로. 없으면 "RED 없음 — 이유"와 대신한 증거 |
|
||||
| 검증 | 명령, 테스트 수, rc, 로그 경로 |
|
||||
| 처리 내용 | 바꾼 것, 고치다 새로 찾아 고친 것 |
|
||||
| 새로 가정하는 것 | 이 변경이 다른 코드·설정·운영에 새로 기대는 것. 확인 리뷰가 여기서 시작한다 |
|
||||
| 정한 기본값 | 소유자가 확인할 것 |
|
||||
| 정한 기본값 | 소유자가 확인할 것. 리뷰 권장안과 다른 안을 골랐으면 그것도 |
|
||||
| 범위 밖에서 본 것 | 위치와 내용. 고치지 않았다 |
|
||||
|
||||
## 9. 자주 하는 실수
|
||||
@@ -138,4 +140,4 @@
|
||||
- 색인을 손으로 옮기다 발견이 빠진다. 색인 검사 스크립트를 돌린다.
|
||||
- 보고에 없는 태스크 이름을 적는다. 로그에서 태스크 이름을 grep해 확인한다.
|
||||
- 묶음별 검증으로 합친 트리 검증을 대신한다. 라운드 끝 게이트를 따로 돌린다.
|
||||
- strict lane에 돌릴 탐침을 새 클래스로 만들어 lane이 고르지 않는다. lane은 `build.gradle`의 `requires`(클래스 이름)나 `tag`로 테스트를 고른다. 탐침은 그 lane이 고르는 기존 클래스에 메서드로 넣는다. 탐침도 `-Werror`로 컴파일되니 경고를 남기지 않는다.
|
||||
- strict lane에 돌릴 탐침을 새 클래스로 만들어 lane이 고르지 않는다. lane은 `build.gradle`의 `requires`(클래스 이름)나 `tag`로 테스트를 고른다. 탐침은 그 lane이 고르는 기존 클래스에 메서드로 넣는다. 탐침도 `-Werror`와 Error Prone으로 컴파일되니 경고를 남기지 않는다(예: 반환값을 버린 `catchThrowable`은 `CheckReturnValue` 오류다).
|
||||
|
||||
+11
-1
@@ -56,8 +56,9 @@ cd ~/workspace/clean-architecture-backend-template
|
||||
git worktree remove ~/workspace/<작업 이름>
|
||||
```
|
||||
|
||||
- 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다.
|
||||
- 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. 같은 worktree의 다음 실행이 결과 XML을 덮어쓰니, 명령이 끝날 때마다 그 태스크의 `build/test-results/<태스크>/`를 로그 폴더로 복사한다(세는 법은 [reference/gates.md](reference/gates.md) 4절).
|
||||
- RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
|
||||
- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다.
|
||||
- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(`docker-compose.dev.yml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`docker-compose.infra.yml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`.
|
||||
- Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다.
|
||||
|
||||
@@ -74,6 +75,15 @@ git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업
|
||||
|
||||
- 그다음 위 3) 4)대로 돌리고 지운다. 결과를 본문에 적어 커밋한 뒤 `git rev-parse HEAD^{tree}`가 같은 해시인지 본다. 같으면 desktop이 돌린 트리가 그 커밋이다.
|
||||
- RED는 같은 방법으로 테스트 파일만 stage해 보낸다. 한 파일의 일부만 stage하는 법은 design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」이다.
|
||||
- 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다.
|
||||
|
||||
```bash
|
||||
ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --console=plain'
|
||||
ssh desktop 'cd ~/workspace/<작업 이름> && git diff --binary' | git apply --index && git write-tree # 노트북
|
||||
ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' # 같은 해시여야 한다
|
||||
```
|
||||
|
||||
- 검증한 트리를 커밋 여럿으로 나누면 중간 커밋마다 그 커밋의 트리를 같은 방법으로 보내 그 커밋이 바꾼 leaf의 `check`(문서·스크립트만 바꿨으면 그 검사)를 돌린다. PR 단계 묶음 같은 무거운 게이트는 마지막 트리에서 한 번 돌린다.
|
||||
|
||||
### 4.2 게이트 실행과 기록
|
||||
|
||||
|
||||
@@ -26,6 +26,8 @@
|
||||
|
||||
「결정 N」은 `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」의 N번, `1101`은 `docs/reviews/2026-11-01-maturity-review/README.md`, `1103`은 `docs/reviews/2026-11-03-rereview/README.md`다.
|
||||
|
||||
날짜 칸은 2.1 표에만 있다. 2.2~2.7 표에 행을 더할 때는 날짜를 「누가」 칸(예: "기본값(2026-11-07)")이나 「출처」 칸 끝에 쓴다.
|
||||
|
||||
### 2.1 작업 방식
|
||||
|
||||
| 주제 | 결정 | 누가 | 날짜 | 출처 |
|
||||
@@ -34,6 +36,9 @@
|
||||
| 커밋 예외 | brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다. main 병합·main 또는 다른 브랜치 push·force push는 하지 않는다 | 소유자(2026-11-06), 커밋과 push를 나눠 읽는 것은 기본값(2026-11-06) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」, `docs/work/README.md` 4절, `docs/work/evidence.md` 9절 |
|
||||
| 리뷰 README 분담 | 리뷰어는 리뷰 폴더 README에 자기 라운드의 색인 절 하나만 쓴다. 처리 표·결정의 답·라운드 끝 게이트·남은 것은 총괄이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면(독립 리뷰어 둘 포함) 색인 절도 총괄이 쓰고, 리뷰어는 보고의 색인 표를 `check-review-index.py --extra-index`로 대조해 rc=0을 보인다 | 기본값 | 2026-11-06, 2026-11-07 | `docs/work/evidence.md` 9·11절 |
|
||||
| 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`. 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 |
|
||||
| 커밋 단위 | 커밋 하나에 논리 변경 하나(`conventions/commit-and-pr.md` 3.1절). 수정 묶음은 브랜치 하나이고 결함(또는 같은 원인)마다 커밋을 나눈다. 나눈 커밋마다 그 커밋이 바꾼 leaf `check`를 돌리고, 무거운 묶음은 마지막 트리에서 | 기본값(옛 "묶음마다 커밋 하나"를 정본에 맞춤) | 2026-11-07 | `docs/work/evidence.md` 11절 |
|
||||
| 넘어온 「범위 밖」 항목 | 수정 세션의 「범위 밖에서 본 것」은 총괄이 README 남은 항목으로 옮기고(멈춤 기준 4가 센다), 다음 확인 리뷰가 brief를 받아 판정한다. 「정한 기본값」은 처리 표와 이 색인 기본값 행으로 옮긴다 | 기본값 | 2026-11-07 | `docs/work/evidence.md` 11절 |
|
||||
| desktop 도구 설치 | workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림 | 기본값(소유자 기계를 바꾸는 일) | 2026-11-07 | `docs/work/operate.md` 4.1절 |
|
||||
| 하위 세션 보고 | 총괄에게도 쉬운 한국어로 쓴다. Slack 브리핑은 전역 `~/.claude/CLAUDE.md` 규칙이 하위 세션에도 그대로 적용된다. brief 7절에 "Slack 말고"가 있으면 보내지 않는다 | 기본값(전역 규칙의 적용 범위를 적음) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「보고」 |
|
||||
| 커밋 예외(지난 것) | `refactor/review-followup`에 Wave마다 커밋(2026-09-25), 리뷰 수정을 `refactor/maturity-review-2026-11`에 커밋·push(2026-11-03) | 소유자 | 2026-09-25, 2026-11-03 | 결정 1, `1101` 17절 |
|
||||
| 리뷰 발견 처리 | Minor도 기록만 하지 않고 고친다. 보고할 때 남은 문제가 0이어야 한다. 수정이 새 결함을 만들면 리뷰·수정을 0까지 반복한다 | 소유자 | 2026-11-05 | `1103` 16절 |
|
||||
@@ -89,6 +94,7 @@
|
||||
| 감싼 carrier를 전송이 읽는 법 | web·GraphQL·STOMP·gRPC 네 전송 모두 원인 사슬의 첫 carrier를 본다. 감싼 carrier의 응답이 500 `INTERNAL_ERROR` 대신 그 carrier의 코드가 된다 | 소유자 | `1103` 18.4절(RR7-01-05), 2026-11-06 |
|
||||
| `Retry-After` 값 | web `RetryAfterAdvisor` 표는 레지스트리 `retry_after_seconds` 칸과 코드마다 같다. 빠져 있던 7개(`DB_UNAVAILABLE` 5, `DB_SERIALIZATION_FAILURE` 1, `DB_DEADLOCK` 1, `DB_IDLE_IN_TX_TIMEOUT` 2, `OUTBOX_PUBLISH_FAILED` 30, `JOB_EXECUTOR_REJECTED` 5, `JOB_TIMEOUT` 10)를 채웠고, `OperationalErrorRegistryContractTest`가 둘을 대조한다 | 소유자 | 2026-11-07 총괄 세션 전달(소유자 원문 "권하는 안대로"), r8-f1 보고 「범위 밖」 1 |
|
||||
| GraphQL 인자 변환 실패 | Spring GraphQL 인자 binder의 `BindException`(`@Argument` 값이 파라미터 타입으로 바뀌지 않음)은 `BAD_PARAMETER`(`REQUEST`)로 답하고, WARN 한 줄(예외 타입만, 입력값 없음)을 남긴다. web이 바뀌지 않는 경로 변수에 답하는 것과 같다 | 소유자 | 2026-11-07 같은 전달, r8-f1 보고 「범위 밖」 2 |
|
||||
| 약속한 응답으로 맞추기 | 레지스트리·`docs/web/http-contract.md`·Javadoc이 이미 약속한 응답으로 코드를 맞추는 것은 결함 수정이다. 고치기 전에 묻지 않고, 응답이 바뀌니 업그레이드 안내 행은 적는다. 약속한 곳끼리 다르면 묻는다 | 기본값(2026-11-07) | `docs/work/improve.md` 7절, `docs/work/evidence.md` 11절 |
|
||||
| STOMP 필수 header 누락 | 필수 header·destination 변수가 없을 때 Spring이 던지는 `MessageHandlingException`은 ERROR 그대로 둔다. 메시지에 입력값이 없고, Spring이 같은 타입으로 서버 실패(handler의 `Error` 등)도 감싸서 타입만으로는 클라이언트 탓을 가를 수 없다 | 기본값(2026-11-07) | 2026-11-07 총괄 지시, r8-f1 보고 「범위 밖」 3 |
|
||||
|
||||
### 2.4 멱등성
|
||||
@@ -182,6 +188,9 @@
|
||||
| 에이전트가 원칙에서 바로 정한 것 | Kafka 주소 키 하나, composition이 persistence-jpa를 함께 가져옴 등 7건 | 기본값 | `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」 끝 목록 |
|
||||
| 묶음별 기본값 | 각 라운드 처리 표의 「결정」 칸(예: SES replay 창 1h, Retry-After 30) | 기본값 | `1101` 13·14·16절, `1103` 6·10·12·15·16·17절 표 |
|
||||
| 경로 필터 workflow와 단계 검사 | `paths:`·`paths-ignore:` trigger만 있는 workflow는 strict lane 단계 실행으로 세지 않는다 | 소유자 | `1103` 18.4절(RR7-05-01), 2026-11-06 |
|
||||
| 검사를 더 엄하게 하는 수정 | 이미 문서에 적힌 규칙을 검사(ArchUnit·검사기)가 더 엄하게 지키게 되는 수정은 결함 수정이라 크기를 올리지 않는다. 규칙을 어기던 파생 서비스 코드가 새로 실패하므로 업그레이드 안내 행과 `!`·`BREAKING CHANGE:`를 단다. 새 규칙을 만드는 검사는 큼이다 | 기본값(2026-11-07) | `docs/work/improve.md` 4.2절 7단계, `docs/work/evidence.md` 11절 |
|
||||
| 아직 합치지 않은 업그레이드 안내 | 안내 범위가 main에 합쳐지기 전이면 같은 표면의 행을 고쳐 최종 동작을 적고 머리 「커밋:」 목록을 늘린다. 합쳐진 안내는 고치지 않고 새 행 | 기본값(2026-11-07) | 같은 곳 |
|
||||
| 라운드 끝 태그 단계 범위 | 라운드 끝은 PR·main 단계 전부와 `releaseCheck` 두 명령. `release.yml`의 다른 job은 릴리스 전에만 | 기본값(2026-11-07) | `docs/work/reference/gates.md` 3절 |
|
||||
| 태그·릴리스 workflow와 단계 검사 | `push`에 `tags:`만 있거나(`branches`·`paths` 없이) `release` trigger만 있는 workflow는 `releaseCheck` 단계에서만 실행으로 센다. 다른 단계(pull request·main·nightly)로는 세지 않는다 | 소유자 | `1103` 18.4절(round7 05 Declined ①), 2026-11-07 |
|
||||
|
||||
## 3. 새 결정을 기록하는 법
|
||||
|
||||
@@ -53,10 +53,18 @@
|
||||
| build-logic·workflow | `-p build-logic check javadoc`, 두 빌드의 `verifyStrictLaneStages --dry-run` |
|
||||
| 패키지 규칙, 생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) |
|
||||
| 마이그레이션 | persistence-jpa `check`, 잠금 대기 lane(`postgresqlMigrationLockWaitIntegrationTest`), 마이그레이션 lane |
|
||||
| 테스트 코드 | 그 leaf `testQualityCheck` |
|
||||
| 테스트 코드(ArchUnit fixture 포함) | 그 leaf `testQualityCheck` |
|
||||
| compose·Dockerfile | compose 검사 스크립트, 실제 `docker build`와 기동 |
|
||||
|
||||
어떤 테스트가 그 문서를 읽는지는 `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`로 찾는다. 걸리는 테스트가 없으면(주석만 걸려도 없음이다) document-contract lane은 돌리지 않고 grep 명령과 결과를 보고에 적는다. 리뷰 기록(`docs/reviews/**`)도 같다.
|
||||
- ArchUnit 위반·허용 fixture도 `testQualityCheck`(SpotBugs)가 분석한다. 외부 라이브러리의 Lombok 클래스를 상속한 fixture는 SpotBugs가 `lombok.Generated`를 찾지 못해 실패한다(missing analysis class). 그런 상속 fixture는 두지 않는다.
|
||||
|
||||
어떤 테스트가 그 문서를 읽는지는 `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`로 찾는다. 걸리는 테스트가 없으면(주석만 걸려도 없음이다) document-contract lane은 돌리지 않고 grep 명령과 결과를 보고에 적는다. 리뷰 기록(`docs/reviews/**`)도 같다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(brief가 먼저다).
|
||||
|
||||
**탐침**: 의심 결함이나 RED를 보려고 별도 worktree에서 잠깐 돌리는 테스트다. 버릴 worktree에서만 돌리고 커밋하지 않는다.
|
||||
|
||||
- 탐침마다 무엇을 단언했는지 적는다. 결함 동작을 단언했으면 rc=0이 확인이고, 약속(Javadoc·결정)을 단언했으면 실패가 확인이다. 둘이 섞이면 rc만으로 결과를 읽을 수 없다.
|
||||
- strict lane에 `--tests`를 붙여 탐침만 돌려도 된다. 단 `requires`(클래스 이름)로 고르는 lane은 고른 클래스가 모두 돌지 않으면 실패한다(`StrictTestLanePlugin`의 required 검사). 그 lane은 필터 없이 돌린다. 필터 실행은 탐침의 증거일 뿐 lane 통과의 증거가 아니다.
|
||||
- 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 `build.gradle` 한 줄을 더하고 `--write-locks`로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다.
|
||||
|
||||
**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 루트 `CLAUDE.md`는 그 범위 밖이라 `scripts/check-work-docs.py`가 본다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다):
|
||||
|
||||
@@ -70,7 +78,19 @@ python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(
|
||||
|
||||
여러 묶음을 합친 트리는 workflow가 PR과 main push에서 돌리는 것을 모두 돌린다. 정본은 `.github/workflows/`다. (가)는 늘 도는 것, (나)는 바뀐 파일로 켜지는 것, (다)는 로컬에 도구가 없는 것이다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다.
|
||||
|
||||
**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다. `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다.
|
||||
**단계별 묶음.** brief가 단계 이름으로 게이트를 시키면 아래 줄을 돈다.
|
||||
|
||||
| brief의 말 | 돌릴 것 |
|
||||
| --- | --- |
|
||||
| pull request 단계 게이트 | (가)의 `# PR` 줄과 `verify-compose-profile-contracts.sh`, (나)에서 `pull_request`로 켜지는 것, (다) |
|
||||
| main 단계 | (가)의 `# main push` 줄과 `run-compose-runtime-smoke.sh`, (나)에서 main `push`로 켜지는 것 |
|
||||
| 라운드 끝 | 위 둘 전부와 (가)의 `# 태그` 두 줄 |
|
||||
|
||||
- 태그 두 줄(`releaseCheck`)은 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·gRPC·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다.
|
||||
|
||||
**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다.
|
||||
|
||||
- `mainCheck` 안의 `verifyFeatureScaffold`는 생성한 복사본에서 Gradle을 따로 띄워(`scripts/verify-feature-scaffold.sh`) 바깥의 `--no-build-cache`를 받지 않는다. 바깥 빌드는 FROM-CACHE를 만들 수 없으니 그 로그에 나온 FROM-CACHE는 중첩 빌드의 것이다. 「실제 실행」 칸에 "바깥 FROM-CACHE 0, 중첩 빌드 FROM-CACHE N(태스크 이름)"으로 적는다.
|
||||
|
||||
(가) 늘 도는 것:
|
||||
|
||||
@@ -117,7 +137,7 @@ bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-pr
|
||||
| `link-check.yml`(lychee) | 2절 끝의 같은 범위 상대 링크 검사 | 외부 URL |
|
||||
| `ci-quality-gates.yml` `grpc-proto-buf`(`buf lint`·`buf breaking`) | buf가 있으면 job의 `run` 줄 그대로. 없으면 못 돌림으로 적는다. diff에 `.proto`·`buf*.yaml`이 없으면 "해당 없음 — proto 변경 없음" | 전부 |
|
||||
| `dependency-vulnerability.yml` `dependency-review`·`dependency-submission` | GitHub에서만 돈다. diff에 lockfile·`src/gradle/libs.versions.toml` 변경이 없으면 "해당 없음", 있으면 PR 결과를 보고 남은 문제로 적는다 | 전부 |
|
||||
| `dependency-vulnerability.yml` `trivy-fs` | trivy가 있으면 job의 `run` 줄 그대로, 없으면 못 돌림 | — |
|
||||
| `dependency-vulnerability.yml` `trivy-fs` | 이미 설치된 trivy가 있으면 job의 검사 줄 그대로. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) |
|
||||
|
||||
## 4. 결과 기록
|
||||
|
||||
@@ -128,6 +148,20 @@ bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-pr
|
||||
- 한 줄은 명령 하나다. 여러 명령으로 된 job(`configuration-cache`, notification `pr`)은 명령마다 한 줄을 쓰고 「게이트」 칸에 `<job> 1/7`처럼 순번을 붙인다. Gradle의 태스크 집계 줄은 명령마다 하나씩 나오므로 로그도 명령마다 나눈다.
|
||||
- 「실제 실행」 칸은 로그의 `> Task` 줄에서 센다: executed(꼬리 없음), UP-TO-DATE, FROM-CACHE. 테스트 수는 그 명령이 새로 쓴 JUnit XML에서 센다.
|
||||
|
||||
**테스트 수 세기.** 성공한 Gradle 로그(`--console=plain`)에는 테스트 수가 찍히지 않는다. 같은 worktree의 다음 실행(특히 `--tests` 필터 실행)은 같은 leaf의 XML을 덮어쓴다. 그래서 명령이 끝날 때마다 XML을 로그 폴더로 복사하고 사본에서 센다.
|
||||
|
||||
```bash
|
||||
cp -r <leaf 경로>/build/test-results/<태스크> ~/<작업 이름>-logs/<명령 이름>-xml
|
||||
x=~/<작업 이름>-logs/<명령 이름>-xml
|
||||
for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | grep -o '<testsuite [^>]*' | grep -o " $k=\"[0-9]*\"" | tr -dc '0-9\n' | awk -v k=$k '{s+=$1} END {print k"="s+0}'; done
|
||||
```
|
||||
|
||||
**앞 실행을 증거로 쓰기.** 다시 돌리지 않고 앞 실행을 증거로 쓸 수 있는 것은 둘이다.
|
||||
|
||||
- 같은 worktree에서 앞 명령이 만든 출력이라 이번 명령의 태스크가 UP-TO-DATE로 끝났다. 앞 명령의 로그와 XML 사본을 함께 적는다.
|
||||
- 같은 트리 해시에서 돈 자기 실행 로그가 있다(맡은 발견이 이미 커밋된 수정에 들어 있을 때 등). 로그에 적힌 트리 해시와 지금 트리 해시를 함께 적는다.
|
||||
- 트리가 다르거나 다른 세션 보고의 「통과」는 증거가 아니다(E0). 다시 돌린다.
|
||||
|
||||
함께 적는다:
|
||||
|
||||
- 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다.
|
||||
|
||||
@@ -245,15 +245,29 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
|
||||
|
||||
| 절 | 적을 것 |
|
||||
| --- | --- |
|
||||
| 범위 | pathspec, `git diff --stat` 결과, 함께 읽은 주변 코드, 수정 보고의 「새로 가정하는 것」 |
|
||||
| 범위 | pathspec, `git diff --stat` 결과, 함께 읽은 주변 코드, 수정 보고의 「새로 가정하는 것」·「정한 기본값」 |
|
||||
| 불러온 스킬과 적용한 기준 | 스킬, 그 스킬의 기준, 그 기준으로 본 것 |
|
||||
| 실행한 명령과 결과 | 명령, rc, 직전 1분 부하 |
|
||||
| 실행한 명령과 결과 | 명령, rc, 직전 1분 부하. 탐침이면 무엇을 단언했나(결함 동작 / 약속, [gates.md](gates.md) 2절 「탐침」) |
|
||||
| 못 본 것 | 무엇과 이유 |
|
||||
| 항목 재확인 | 고쳤다고 한 항목마다 닫힘 / 부분 / 안 닫힘 |
|
||||
| 넘어온 항목 판정 | brief가 맡겼을 때만: 지난 라운드 Declined와 README 남은 항목마다 판정(결함 / 결함 아님 / 결정 필요)과 근거 |
|
||||
| 결함 | `### <ID> · <심각도> · <한 줄 제목>` 아래 발견 필드 |
|
||||
| Declined to judge | 판단하지 않은 것, 위치, 이유 |
|
||||
| 결론 | Critical·Important·회귀 수, 결함 수와 "이번 수정 / 이전부터" 구분 |
|
||||
|
||||
**확인 리뷰 라운드의 README 절**: 리뷰 폴더 README에 라운드마다 절 하나를 두고, 하위 절을 이 순서로 둔다. 앞의 다섯은 리뷰가 끝나면, 뒤의 셋은 수정과 합치기가 끝나면 쓴다. 누가 쓰는지는 [improve.md](../improve.md) 4.1절 7단계다.
|
||||
|
||||
1. 결과 — 색인 표(ID, 심각도, 한 줄 내용, 이번 수정 / 이전부터, 증거, 결정이 필요한 질문)
|
||||
2. 리뷰어 B와의 대응 — 독립 리뷰어 둘일 때만. `B-NN-MM` → 정본 ID, 겹침 비율
|
||||
3. 실행 — 리뷰어별 명령·결과·로그 위치
|
||||
4. 결정이 필요한 것 — 항목 · 선택지 · 권하는 안과 이유 · 정할 사람
|
||||
5. 넘어온 항목 판정 — 지난 라운드 남은 항목마다 판정과 위치
|
||||
6. 멈춤 기준 상태 — [improve.md](../improve.md) 4.5절 넷
|
||||
7. 처리 — 처리 표: 발견 · 상태 · 고친 커밋 · RED · 검증 · 정한 기본값. [improve.md](../improve.md) 8절 보고에서 옮긴다. brief가 다른 칸을 정하면 brief를 따른다
|
||||
8. 합친 트리와 게이트 — 병합 순서, 충돌과 처리, 라운드 끝 게이트 표([gates.md](gates.md) 4절), 못 돌린 것
|
||||
|
||||
수정 세션 보고의 「정한 기본값」은 7의 처리 표와 [decisions.md](decisions.md)(기본값 행)로, 「범위 밖에서 본 것」은 README 남은 항목(6의 넷째)으로 옮긴다. 옮긴 남은 항목은 다음 확인 리뷰가 brief를 받아 5에서 판정한다.
|
||||
|
||||
**발견 하나의 필드**
|
||||
|
||||
- 전체 리뷰: 가이드 36.3절 표 필드 전체(성격, 관련 관점, 근거, 발생 조건, 영향, 심각도, 확실성, 결정의 근거, 이해 비용, 최소 개선 방향, 대안 비교, 단순화의 보존 조건, 비용, 재검토 조건, 완료 기준, 검증 방법). 선택 비교가 필요 없는 단순 결함은 설계 선택 필드를 `적용 제외 — <이유 한 문장>`으로 둔다.
|
||||
@@ -266,6 +280,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
|
||||
- 영역 번호 자리에 `NN` 같은 자리표시자를 남기지 않는다. 리뷰가 끝난 뒤 영역 접두어를 바꾸지 않는다.
|
||||
- 영역 번호는 그 라운드 영역 표의 순번이다. 지난 라운드 번호와 맞추지 않아도 된다. 지난 라운드 영역 하나를 둘로 나누면 뒤에 새 번호를 잇고(04를 나누면 04·05), 「범위」 절에 지난 영역과의 대응을 적는다.
|
||||
- 한 라운드의 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