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:
DongHyeonka
2026-11-07 07:02:09 +09:00
parent 51230caf62
commit 3eb3b06755
9 changed files with 151 additions and 27 deletions
+9
View File
@@ -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. 새 결정을 기록하는 법