문제: 2026-11-07 합친 브랜치 전체 게이트를 매뉴얼만 보고 돌리게 했더니
(1회차 수정 전 매뉴얼) 여섯 곳에서 답이 없었다.
- gates.md 3절 묶음에 main job(configuration-cache, compose smoke,
http3, notification pr)과 경로 필터 PR lane이 없어 "workflow와 같은
명령"이 아니었다
- 합친 트리가 어떤 경로 필터 lane을 켜는지 정하는 절차가 없었다
- 집계 태스크 전체가 실제로 돌았음을 보이는 법이 없었다(--rerun은
앞 태스크 하나만)
- lychee 대체 명령(--links docs)이 lychee 범위보다 좁았고, buf와
dependency review는 대체 안내가 없었다
- compose bind mount가 tmp/heap-dumps를 root로 만들어 git worktree
remove가 실패했다
- 결과 기록 형식이 게이트 하나 = Gradle 명령 하나를 가정했다
고른 방법:
- gates.md 3절을 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것,
(다) 로컬 도구가 없는 것으로 나눈다. (가)에 workflow의 run 줄을
더하고, (나)는 git diff --name-only를 on.pull_request.paths(glob)와
pr-adapters.yml emit 줄(정규식)에 맞추는 절차로, (다)는 job마다
로컬 대체와 대체가 못 보는 것을 적은 표로 둔다
- 실제 실행 증명: 새 worktree와 --no-build-cache, 로그의 FROM-CACHE 0
- 링크 검사 대체는 lychee와 같은 glob을 git ls-files로 넘긴다
- operate.md 4.1에 compose down과 root 폴더 지우기 한 줄
- gates.md 4절은 한 줄 = 명령 하나, 여러 명령 job은 순번, 「실제
실행」 칸
- 처리 표(evidence.md 9절)에 T6 여섯 행
버린 대안: workflow의 모든 job 명령을 gates.md에 옮겨 적기. workflow가
정본이라 옮긴 사본이 낡는다. 경로 필터 lane은 절차만 둔다.
위험·한계:
- (가)의 명령은 workflow의 사본이다. workflow를 바꾸면 이 블록도 고쳐야
한다
- 경로 필터 맞추기는 손으로 한다. glob을 기계로 맞추는 도구는 없다
- 같은 범위 링크 검사는 지금 rc=1이다. src/README.md와 fileserver·
objectstorage README의 상대 링크 3건이 기준 커밋부터 깨져 있다(이번
범위 밖)
검증:
- python3 scripts/check-work-docs.py rc=0. improve.md 141/150,
delegate.md 121/150, operate.md 131/150, 진입 경로 최대 290/350,
본문 이력 0줄
- 바꾼 문서를 읽는 테스트: grep 결과 0(delivery-evidence.md 이름만
걸림)
- desktop: 바꾼 것을 패치로 73d39212 위에 얹어 이 커밋과 같은 트리
7e28874c를 만들고, flock 아래 :app-bootstrap:documentContractTest
--rerun --no-build-cache rc=0, 66건 실패 0 건너뜀 0, FROM-CACHE 0,
직전 1분 부하 5.64. 같은 트리에서 check-work-docs.py rc=0,
--history docs/manual 16줄 rc=1(기대대로)
(desktop ~/manual-gap-fix-2-logs/final-*.log)
- 링크 검사(lychee와 같은 범위) rc=1, 깨진 3건은 위 위험·한계의 것
(desktop ~/manual-gap-fix-2-logs/links-lychee-scope.log)
225 lines
33 KiB
Markdown
225 lines
33 KiB
Markdown
# 근거와 이력
|
|
|
|
`docs/work/` 본문은 지난 리뷰를 모르는 사람도 읽을 수 있게 썼다. 그래서 규칙이 나온 사건과 지난 리뷰 ID는 본문에 넣지 않고 여기에 모았다. 본문을 따르는 데 이 문서는 필요 없다. 규칙의 이유를 확인하거나 규칙을 바꾸려 할 때 읽는다.
|
|
|
|
표기: `1101/05-01`은 `docs/reviews/2026-11-01-maturity-review/`의 발견 05-01이다. `1103/RR6-01-05`는 `docs/reviews/2026-11-03-rereview/`의 발견이다. 접두어와 문서: `RR-`는 1차 재리뷰(폴더 바로 아래 `01`~`07` 영역 문서)와 round2의 `01`~`03` 영역 문서(1차 번호를 이어 썼다), `RR2-`는 round2의 `04` 영역 문서, `RR3-`~`RR7-`는 round3~round7이다. `1101` README, `1103` README는 각 폴더의 `README.md`다. 「결정 N」은 `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」의 N번이다.
|
|
|
|
## 1. 이 매뉴얼이 나온 곳
|
|
|
|
- 조사와 설계: design-docs `delegation-loop/01-research.md`(1~5단계), `delegation-loop/02-design.md`(6단계, 4·5·6·7·10절). 2026-11-06 소유자가 결정 D1~D14를 모두 권하는 안대로 승인했다.
|
|
- 공통 정본: design-docs `conventions/work-thinking-order.md`(작업 사고 순서), `conventions/delegation-loop.md`(위임 루프 운영).
|
|
- 재료: 옛 개선 매뉴얼 브랜치 `claude/improvement-manual-6ae516`(커밋 `3b66358e`, `319cff91`, `06477350`, 2026-11-05). 병합하지 않고 설계 10절 표대로 옮겼다(결정 D12).
|
|
- 옛 매뉴얼을 버린 이유(2026-11-06 소유자 판정): 조사 없이 만들었다, 범위가 리뷰·수정뿐이다, 본문 159줄에 지난 리뷰 ID가 있다, 진입 분량이 717줄이다, 시험한 적이 없다.
|
|
|
|
옛 매뉴얼에서 옮긴 곳:
|
|
|
|
| 옛 위치 | 새 위치 |
|
|
| --- | --- |
|
|
| README 「정본 표」, 적용 범위 | `docs/work/README.md` 1·7절, 각 playbook |
|
|
| 결정 M-5(저장소 밖 문서는 코드 표기), M-6(소유자 환경 규칙은 한 절에만) | `docs-writing.md` 4절, `operate.md` 4.1절 |
|
|
| 결정 M-3(심각도 두 체계) | `reference/review-criteria.md` 3절 |
|
|
| 결정 M-4(결정 표는 색인) | `reference/decisions.md` 머리말 |
|
|
| 결정 M-7(커밋 정책은 두고 예외만) | `docs/work/README.md` 4절, `AGENTS.md` 커밋 문장 |
|
|
| 결정 M-8(개선 제안도 닫는다) | `reference/review-criteria.md` 1절 |
|
|
| 결정 M-9(분업과 "Minor도 고친다"의 저장소 안 정본) | `improve.md` 4.5절, `delegate.md` |
|
|
| 결정 M-1(위치 `docs/improvement/`), M-2(프론트와 장 번호 맞추기) | 버림. 위치는 `docs/work/`, 두 repo는 장 번호 대신 같은 playbook 파일 이름을 쓴다 |
|
|
| 01장 판정표, 0절 공통 단계, 1~6절 | `docs/work/README.md` 3절, `improve.md` |
|
|
| 02장 | `reference/review-criteria.md`(지난 예는 이 문서 5절) |
|
|
| 03장 | `reference/review-criteria.md` 9절 |
|
|
| 04장 P1~P11 | `reference/defect-patterns.md` 「막는 기준」 |
|
|
| 05장 | `reference/review-criteria.md` 7절, `improve.md` 4.2·4.3절 |
|
|
| 06장 | `reference/review-criteria.md` 8절, `reference/gates.md` 5절, 기준선은 이 문서 6절 |
|
|
| 07장 | `reference/gates.md`, `operate.md` |
|
|
| 08장 | `reference/decisions.md` |
|
|
| 09장 | `delegate.md`, `improve.md` 4.4·4.5절, design-docs `conventions/delegation-loop.md` |
|
|
| 부록 결함 패턴 | `reference/defect-patterns.md` + 이 문서 4절 |
|
|
|
|
## 2. 규칙과 사건
|
|
|
|
| 규칙(본문 위치) | 사건 | 근거 |
|
|
| --- | --- | --- |
|
|
| 무거운 실행은 desktop에서, 공유 잠금으로 (`operate.md` 4.1) | 2026-11-05 하위 세션 넷이 노트북에서 Gradle을 돌려 노트북 부하가 22까지 올랐다 | `1103` README 17.1절, design-docs `delegation-loop/01-research.md` 4.2절 |
|
|
| 진입 분량 상한, 본문 이력 ID 금지 (`docs/work/README.md` 8절) | 옛 개선 매뉴얼은 진입 717줄, 이력 ID가 든 본문 159줄 | `01-research.md` 4.1절 |
|
|
| 색인은 기계로 대조한다 (`improve.md` 4.1) | 원래 리뷰 색인이 119건이었다. 06 영역 문서의 `NN-10`~`NN-14` 5건이 색인과 모든 수정 묶음에서 빠졌다. 실제는 124건 | `1101` README 12절 정정, `1103` README 1절, `1103/RR-05-10` |
|
|
| 「새로 가정하는 것」 칸, 수정 묶음 크기 상한 (`improve.md` 4.4, 8절) | round6 발견 25건 중 17건(68%)을 직전 수정 커밋이 만들었다. 짝 프론트 1106 리뷰도 25건 중 16건(64%) | `01-research.md` 4.3절, design-docs `delegation-loop/02-design.md` 4.3절 |
|
|
| 보고한 태스크가 로그에 있는지 확인 (`improve.md` 9절, `gates.md` 4절) | 묶음 보고가 없는 태스크 `:adapter:outbound:persistence-jpa:documentContractTest`를 적었다 | `1103` README 17.2절 |
|
|
| 성능 lane은 상한을 매번 단언하고, 끄는 값은 테스트 전에 실패한다 (`gates.md` 5절) | r10 desktop 게이트의 `performanceCheck`가 `-Pperformance.assertions.enabled=true` 없이 돌아, httpclient 시간 단언 없이 통과했다. 그 전에는 JPA pool lane이 같은 속성 뒤에 숨어 상한을 비교하지 않았다(`PoolLaneClaimTest`). 2026-11-06 빌드가 강제하게 바꿨다 | desktop `~/r10-logs/gates.sh`, `docs/testing/TESTING_STRATEGY.md` PERFORMANCE 문단, 커밋 `e6b6e18e` |
|
|
| 캐시에서 가져온 결과는 지금 통과한다는 증거가 아니다. 기준 상태와 시간·환경에 민감한 테스트는 `--rerun`으로 (`operate.md` 9절, `gates.md` 6절) | 2026-11-06 B3 desktop `ci` rc=0은 캐시 결과였다(태스크 701개 중 403개를 캐시에서). 그 사이 httpclient `CircuitBreakerStatusAccountingTest` 2건은 기준 커밋 `3d73b6f1`에서도 10번 중 10번 실패하고 있었다 | desktop `~/b3-logs/ci.log`, 2026-11-06 총괄 전달 |
|
|
| 묶음을 너무 크게 만들지 않는다 (`delegate.md` 4.2) | 알림·파일 서버를 한 묶음(r2-05a)으로 묶었다가 마감 안에 검증 보고가 오지 않아 합치지 못했다. 다음 라운드(r3-a)에 다시 올려 합쳤다 | `1101` README 14.3절, 16절 |
|
|
| 두 묶음이 같은 파일을 건드리지 않게 (`delegate.md` 4.2) | 2라운드 묶음 r2-06이 10개 파일 충돌로 처음부터 다시 작업했다 | `1101` README 14.1절 |
|
|
| 전 leaf import를 바꾸는 묶음은 마지막에 혼자 (`improve.md` 6절, `delegate.md` 4.2) | r3-G | `1101` README 15.1절 |
|
|
| 묶음마다 그 시점 최신 기준에서 시작 (`delegate.md` 4.2) | 3라운드가 2라운드보다 충돌이 적었다 | `1101` README 16.1절 |
|
|
| 합친 트리는 따로 검증 (`improve.md` 4.4, `gates.md` 3절) | 두 묶음의 수정이 한 트리에서 처음 만나 `BC_IMPOSSIBLE_INSTANCEOF`가 생겼다. 최종 게이트에서 드러난 2건 | `1101` README 16.1절, `1103` README 6.1절 |
|
|
| 캐시로 통과한 것은 그렇게 적는다 (`gates.md` 4절) | `ci`가 434초에서 51초로 준 것은 캐시 재사용이었다 | `1101` README 16.2절 |
|
|
| 같은 결함은 한 묶음에만 (`delegate.md` 4.2) | 같은 runbook 문장을 두 리뷰가 적어 한 번 고쳤다(`1103/RR6-01-07`, `1103/RR6-02-03`) | `1103` README 17절 |
|
|
| RED가 머신에 따라 통과하지 않게 (`improve.md` 7절) | watchdog RED 테스트가 공용 풀 병렬도 1인 머신에서 옛 코드도 통과시켰다 | `1103/RR4-03-01`, `1103` README 16절 r9-b |
|
|
| 실 vendor 결함은 실 vendor에서 RED (`improve.md` 4.2) | 새 실 PostgreSQL 테스트 3개의 수정 전 실패를 실 PostgreSQL로 확인하지 않았다 | `1101` README 14절 r2-04 |
|
|
| Agent 도구를 쓰지 않는다 (`delegate.md` 4.3) | 하위 세션 시작이 막히자 Agent 하위 에이전트로 우회했다. 지난 라운드는 사용량 한도 때문에도 하위 에이전트 없이 진행했다 | `01-research.md` 4.2절, `1101` README 16절, `1103` README 6절 |
|
|
| 예전 멈춤 기준을 거둠 (`improve.md` 4.5) | 2026-11-05 소유자 지시 "보고할 때 남은 문제가 없어야 한다". "새 Important 0이면 멈춤"(9.1절), "Minor는 기록만"(11.1절)을 거뒀다 | `1103` README 16절 |
|
|
| 종료 조건은 repo마다 (`improve.md` 4.5) | 2026-11-05 소유자 원문 "각자 유지" | 2026-11-05 총괄 세션 전달 |
|
|
|
|
## 3. 수정 묶음 크기 (`improve.md` 4.4)
|
|
|
|
추가 줄은 `git show --shortstat`의 insertions다(테스트·문서 포함).
|
|
|
|
| 수정 커밋 | 고친 것 | 추가 줄 | 다음 확인 리뷰 | 그 리뷰의 발견 |
|
|
| --- | --- | --- | --- | --- |
|
|
| `01a8a2a70..5786126c`(커밋 3개) | 원래 리뷰 발견 | +60,167 | 1차 재리뷰 | Important 27, Minor 41 |
|
|
| `bbe944bd` | 1차 재리뷰 발견 + 색인에서 빠졌던 5건 | +13,479 | round2 | Important 7, Minor 22 |
|
|
| `1885bf8d` | 2차 재리뷰 결함 29건 | +5,495 | round3 | Important 0, Minor 19 |
|
|
| `f40c03c6` | Minor 19건(영역 묶음 4개) | +1,877 | round4 | Important 0, Minor 7 |
|
|
| `70fb80bf` | 소유자가 다시 정한 기본값 3가지 | +906 | round5 | Important 0, Minor 9 |
|
|
| `45d2a478` | 기록만 했던 결함 전부(영역 묶음 4개) | +5,420 | round6 | Important 2, Minor 23(17건은 이 커밋이 만듦) |
|
|
| `6e992970` | round6 결함 25건(영역 묶음 4개) | +5,143 | 아직 없음 | — |
|
|
|
|
읽는 법: 추가 2,000줄 아래 두 번은 다음 발견이 7·9건, 5,000줄 위 네 번은 19·25·29·68건이었다. 상한(묶음 8건, 확인 리뷰당 1,500줄)은 이 표에서 정한 판단 값이다. 위임 루프 지표(라운드당 새 결함, 수정이 만든 결함 비율)로 다시 맞춘다.
|
|
|
|
## 4. 결함 패턴의 근거 (`reference/defect-patterns.md`)
|
|
|
|
| 패턴 | 근거 |
|
|
| --- | --- |
|
|
| A1 갈라진 복사본 | `1101/01-03`, `1101/01-07`, `1101/04-06`, `1101/05-09`, `1101/07-06`, `1101/01-11`, `1103/RR-01-14`, `1101` README 16.3절(템플릿 패키지 목록 두 곳), `1103` README 16절 r9-c(버전 정규식 사본) |
|
|
| A2 문서와 코드 불일치 | `1101/02-01`, `1101/07-11`, `1101/03-04`, `1101/06-11`, `1103/RR-01-03`, `1103/RR-01-11`, `1103/RR5-01-01`, `1103/RR6-02-05`, `1103/RR6-03-05`, `1103/RR6-04-05` |
|
|
| A3 선언과 실행이 떨어져 있다 | `1101/05-15`, `1101/03-11`, `1101/02-03`, `1101/07-06`, `1103/RR-06-01`, `1103/RR2-04-03`, `1103` README 6.1절(`redis.capability.*` 6개) |
|
|
| A4 결과 불명을 확실함으로 | `1101/05-01`, `1101/04-01`, `1101/06-01`, `1101/05-17`, `1101/05-11`, `1103/RR-02-03`, `1103/RR-01-11`, `1101` README 4절 원인 1 |
|
|
| A5 중복·경쟁을 코드 순서로 | `1101/09-02`, `1101/04-08`, `1101/04-02`, `1101/03-10`, `1101/04-13`, `1103/RR-03-01`, `1103/RR-02-04` |
|
|
| A6 주장하는 것을 보지 않는 테스트 | `1101/05-08`, `1101/02-02`, `1101/01-05`, `1103` README 14절(`CountDownLatch` 7건), `1103/RR4-03-01`, `1103/RR6-01-08`, `1103/RR6-02-02` |
|
|
| A7 거짓 통과 게이트 | `1101/08-01`, `1101/04-04`, `1101/03-12`, `1103/RR-06-02`, `1103/RR-06-03`, `1103/RR-04-05`, `1103` README 14절(테스트 SpotBugs 53개), `1103/RR3-04-02`, `1103/RR6-04-01`, r10 desktop `performanceCheck`(2절) |
|
|
| A8 로그로 새는 입력값·원인 | `1103/RR6-01-05`, `1103/RR6-01-06`, `1103` README 16절 r9-a, `1101/02-11`, `1101/01-04` |
|
|
| A9 이름만 보는 허용·거부 | `1103/RR-07-02`, `1103/RR2-04-02`, `1103/RR2-04-01`, `1101/07-14` |
|
|
| A10 글로만 있는 규칙 | `1103/RR-01-02`, `1101/04-03`, `1101/05-16` |
|
|
| A11 샘플·fixture가 운영과 다르게 조립 | `1101/07-03`, `1101/09-03`, `1101/09-08`, `1101/07-04`, `1101/01-02`, `1101/07-09` |
|
|
| A12 수정이 새 결함을 만든다 | `1103` README 1절(Important 27), 9절, `1103/RR6-01-01`(회귀), `1101` README 16.1절, `1103` README 6.1절, round6 68%(2절) |
|
|
| A13 합치는 과정의 누락 | `1101` README 12절 정정, `1101` README 14.1절(충돌 처리 목록) |
|
|
| A14 타이밍에 기댄 약속 | `1103` README 16.1절(`ClientRuntimeRegistry.close`), `1103/RR3-03-01`, `1101/05-06` |
|
|
| A15 사라지는 외부 공급원 | `1101/05-09`, `1101/08-04` |
|
|
| A16 상한 없는 자원 | `1101/03-06`, `1101/03-09`, `1101/04-10`, `1101/02-09`, `1101/04-12` |
|
|
|
|
## 5. 리뷰 기준의 예 (`reference/review-criteria.md`)
|
|
|
|
**결함의 모양(1절)**: 이름과 다른 동작 `1101/05-03`(`ONLY_IF_SOURCE_REVISION_NEWER`가 조건 없이 덮어씀), HARD-STOP 위반 `1101/07-08`(기본 조립 루트가 선택 capability를 앎), 갈라진 복사본 `1101/01-03`(`TenantId` 3벌)·`1101/04-06`(SQLState 표 2벌), 막지 못하는 게이트 `1101/05-08`(소유자 검사를 지워도 442개 통과)·`1101/08-01`(어떤 workflow도 돌리지 않는 strict lane 14개), 틀린 조치를 시키는 문서 `1103/RR-05-01`(DEAD 재발행 SQL을 따르면 다시 DEAD), 기본값 뒤에 숨은 위험 `1101/02-03`(JWT audience가 비면 검증을 건너뜀).
|
|
|
|
**성격(2절)**: 구조적 위험 `1101` README 6절, 미검증 `1103` README 10.3절(CI runner가 꺼져 있다).
|
|
|
|
**심각도(3절)**: 전체 리뷰 체계는 `1101` README 12절. High 예 `1101/05-01`, `1101/04-02`, `1101/02-03`. Medium 예 `1101/04-06`, `1101/04-05`. Low 예 `1101/07-11`. 확인 리뷰 체계는 `1103` README 2절 이후 모든 round, Important 기준은 `1103` README 11절, Minor 예는 `1103/round4/review.md`·`round6/`. "이번 커밋 / 이전부터"는 `1103/round6/04-build-logic.md` 「결론」. Minor도 고친다는 규칙은 `1103` README 16절, High·Important 재확인은 `1101` README 2절.
|
|
|
|
**증거 수준(4절)**: 이전 결과를 쓰지 않은 예 `1101/09-performance-measurement.md` 1절, 섞인 증거 수준 표기 예 `1103/round6/03-persistence.md` RR6-03-01.
|
|
|
|
**통제 수준(5절)**: M0 예 2026-11-01 시점 JPA 양방향 연관관계 금지(`1101/04-03`), M1 예 `@SystemInvoked`를 bean으로 등록하지 말라는 주석(`1103/RR-01-02`), M4 예 DB 유일 제약(`1101/09-02` 수정 뒤).
|
|
|
|
**28개 관점(6절)의 지난 예**: 1 `1101/05-03` · 2 `1101/07-08`, `1101/08-05` · 3 `1101/01-07` · 4 `1101/01-01`, `1101/07-09` · 5 `1101/02-03`, `1103/RR-07-02` · 6 `1101/04-01`, `1101/06-01`, `1101/05-01` · 7 `1103/RR-05-01`, `1103` README 6.1절 · 8 `1103` README 16절 r9-a, `1101/01-04` · 9 `1101/04-06`, `1101/07-11` · 10 `1101/05-08`, `1101/02-02` · 11 `1101/09-02`, `1103/RR-02-09` · 12 `1101/04-02`, `1101/03-10` · 13 `1101/03-06`, `1101/03-09` · 14 `1101/09-01`, `1101/09-02` · 15 `1101/02-03`, `1101/07-03`, `1103/RR6-01-05` · 16 `1101/05-09`, `1101/09-09` · 17 `1101/02-01`, `1101/02-02` · 18 `1101/07-04`, `1101/06-02` · 19 `1101/05-15`, `1101/07-06` · 20 `1103/RR-01-01`, `1103/RR-01-03` · 21 `1101/08-01`, `1103/RR-06-02`, `1103` README 14절 · 22 `1101/04-13` · 23 `1101/01-03`, `1101/01-12` · 24 `1101/05-21` · 25 `1101/01-10` · 26 `1101/04-16` · 27 `1101/07-08`, `1101/05-19` · 28 `1101/03-10`, `1101/06-03`.
|
|
|
|
**시나리오(6절)의 지난 추적**: `1101/01-core-and-feature-pattern.md` 4.1·4.2·4.4절, `1101/09-performance-measurement.md` 5.1~5.3절, `1101/05-05`·`05-06`·`05-01`, `1101/04-01`·`04-05`, `1103/RR-03-03`, `1101/06-01`, `1103/RR-03-02`, `1103/RR-02-09`·`RR-02-10`, `1101/04-02`·`03-10`, `1101/05-08`, `1101/03-01`·`02-09`, `1101/06-02`·`07-07`, `1101/08-build-ci-test.md` 4절.
|
|
|
|
**테스트 점검표(7절)**: `1103/RR6-01-08`, `1101/02-02`, `1101/05-08`, `1103` README 14절, `1103/RR6-02-02`, `1103/RR6-01-03`, `1103` README 17절 r10-01, `1103` README 16.1절. fake 예 `1103/RR-01-04`, `1103` README 17절 r10-02(손 사본 20건 삭제, skip 17 → 0).
|
|
|
|
**리뷰 문서 양식(10절)**: 전체 리뷰 README는 `1101` README 절 순서, 영역 문서는 `1101/01-core-and-feature-pattern.md`, 확인 리뷰 문서는 `1103/round6/*.md`, 확인 리뷰 발견 필드는 `1103/round6/03-persistence.md` RR6-03-01, 전체 리뷰 발견 필드는 `1101/08-build-ci-test.md` 08-01.
|
|
|
|
## 6. 성능 기준선 (`improve.md` 4.3)
|
|
|
|
잰 커밋과 함께만 쓴다. 현재 HEAD에서 다시 잰 값이 아니다. 성능 작업을 시작하면 현재 커밋에서 다시 재고 이 표와 비교한다.
|
|
|
|
| 측정 | 값 | 커밋·출처 |
|
|
| --- | --- | --- |
|
|
| 기본 조합 bootJar / 기동 중앙값 / 빈 수 | 41.4 MB / 3.44 s / 407 | `01a8a2a70`, `1101/09-performance-measurement.md` 3.1절 |
|
|
| 샘플 bootJar / 기동 중앙값 / 빈 수 | 99.0 MB / 8.05 s / 603 | 같음 |
|
|
| 필터 체인만 지나는 요청 | 27,130 rps, p50 0.51 ms | 같은 문서 3.4절 (d) |
|
|
| 샘플 단건 조회 | 5,521 rps, p50 2.70 ms, SQL 7개 | 같은 문서 3.2·3.3절 |
|
|
| 샘플 목록 20건 | 829 rps, p50 15.54 ms, SQL 46개 | 같음(수정 전) |
|
|
| 샘플 목록 20건(수정 뒤) | SQL 46 → 6, 765 → 2,528 rps | `1101` README 14절 r2-09(묶음 보고 — E0, 다시 재지 않음) |
|
|
| 관측 기능 비용 | 처리량 약 3% | 같은 문서 3.4절 (b) |
|
|
| 가상 스레드 | 처리량 차이 없음(병목은 커넥션 10개와 DB 왕복) | 같은 문서 3.3절 |
|
|
| 설정만 바꾼 실험 | `hibernate.default_batch_fetch_size=100`만으로 목록 처리량 2.9배 | 같은 문서 3.4절 |
|
|
| 게이트 시간(desktop, 12코어·31GB) | `ci`+`verifyDependencyLocks` 5분 42초, `mainCheck` 8분 8초, `integrationCheck` 17분 10초 | `2c692554`, `1103` README 17.2절 |
|
|
|
|
측정 스크립트(`run-app.sh`, `Load.java`, `sqlcount.sh`)는 그때 scratchpad에 두었고 repo에는 없다. 다시 재려면 `1101/09-performance-measurement.md` 「측정 명령 (다시 돌리는 법)」으로 다시 만든다.
|
|
|
|
## 7. 리뷰 색인 대조 결과 (2026-11-06)
|
|
|
|
`scripts/check-review-index.py`를 지난 리뷰 폴더 두 곳에 돌린 결과다(기준 커밋 `3d73b6f1`).
|
|
|
|
| 폴더 | 명령 | 영역 문서 발견 | 색인에 있음 | 없음 | rc |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| `docs/reviews/2026-11-01-maturity-review/` | `--index-heading "12. 발견 색인"` | 124 | 124 | 0 | 0 |
|
|
| `docs/reviews/2026-11-03-rereview/` | README 전체 | 157 | 135 | 22 | 1 |
|
|
|
|
- 2026-11-01 폴더: 지금은 모두 있다. 같은 검사를 사고 시점 커밋 `34565130`의 폴더에 돌리면 `NN-10`~`NN-14` 5건을 "자리표시자 영역"으로 잡고 rc=1로 실패한다. 이 검사가 그 사고를 막았을 것이다.
|
|
- 2026-11-03 폴더의 22건은 처리되지 않은 발견이 아니라 README가 ID로 적지 않은 발견이다.
|
|
- `RR-05-10`(색인 누락 5건 자체에 대한 발견)은 README 1절 정정과 6.1절이 내용으로 다룬다.
|
|
- `RR-07-05`(CSRF 제외 규칙의 이유)는 README 6절 r4-f 행이 내용으로 다룬다.
|
|
- 나머지 20건은 round6 Minor다(`RR6-01-02`~`06`·`08`·`09`, `RR6-02-02`·`04`·`05`, `RR6-03-02`~`05`, `RR6-04-01`~`06`). README 17절은 영역별 건수만 적었고, r10 묶음이 영역 단위로 고쳤다.
|
|
- 이 검사는 "색인에 이름이 있나"만 본다. 고쳤는지는 처리 표와 확인 리뷰가 본다. 앞으로의 리뷰 README는 모든 ID를 이름으로 적는다(`improve.md` 4.1절 7단계).
|
|
|
|
## 8. `docs/manual/`에서 걷어낸 이력 ID (2026-11-06)
|
|
|
|
`docs/manual/` 본문에서 리뷰 ID와 번호만 쓴 결정을 걷어냈다. 문장의 뜻은 그대로이고, 괄호 안 근거만 여기로 옮겼다. 줄 번호는 걷어내기 전 기준 커밋 `06f520e6`의 줄이다.
|
|
|
|
| 원래 위치 | 원래 괄호 | 지금 본문 | 근거 |
|
|
| --- | --- | --- | --- |
|
|
| `docs/manual/05-idempotency.md:57` | "재리뷰 2026-11-04 RR5-01-05, 라운드6 RR6-02-05, 정본 `docs/web/http-contract.md` 2절" | 정본 가리킴만 남겼다 | `1103/RR5-01-05`(PostgreSQL 기본 모양에서는 lease 상황이 생기지 않는다, `round5/review.md`), `1103/RR6-02-05`(매뉴얼 첫 문장이 PostgreSQL 항목과 어긋났다, `round6/02-idempotency-outbound.md`) |
|
|
| `docs/manual/05-idempotency.md:78` | "라운드6 RR6-02-01" | "2026-11-05 확인 리뷰가 찾아 고쳤다" | `1103/RR6-02-01`(`LEASE_EXPIRED`로 거절당한 attempt를 다시 보내도 503만 받았다, `round6/02-idempotency-outbound.md`). 수정 커밋 `6e992970`(2026-11-05), `1103` README 17절 r10-02 |
|
|
| `docs/manual/05-idempotency.md:81` | "재리뷰 2026-11-04 RR-01-11·RR-03-11" | `IdempotencyStoreContract` 가리킴만 남겼다 | `1103/RR-01-11`(lease가 지난 실행 기록을 Redis가 넘겨받아 다시 실행했다, `round2/01-core-app-inbound.md`), `1103/RR-03-11`(replay TTL이 lease보다 짧으면 key가 lease 도중 사라졌다, `round2/03-outbound.md`). 수정 커밋 `1885bf8d`(2026-11-04) |
|
|
| `docs/manual/05-idempotency.md:84` | "RR3-03-02, 2026-11-04 소유자 결정" | "2026-11-04 소유자 결정" | `1103/RR3-03-02`(서버가 기억하는 기간 문서가 `failure-retention`을 빠뜨렸다, `round3/03-outbound.md`) |
|
|
| `docs/manual/07-authorization.md:98`, `:115` | "D4 문단", "D4 실패" | "권한 선언 검사 문단", "쓰기 유스케이스의 권한 선언 검사 실패" | D4는 인증·인가 계약 설계(`feature-authentication-authorization-contract`)의 결정 번호로, 규칙 `MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`을 가리킨다. 그 설계 문서는 이 repo에 없다. `ApplicationBoundaryArchitectureTest`의 주석 "D1 / D4"와 `1101/01-core-and-feature-pattern.md` 「ArchUnit D4」가 같은 번호다 |
|
|
| `docs/manual/08-testing.md:38` | "소유자 결정 5" | "2026-09-25 소유자 결정" | `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」 5번(`@DisplayName`은 한국어) |
|
|
| `docs/manual/09-outbox-events.md:78` | "재리뷰 2차 RR-02-10" | runbook 가리킴만 남겼다 | `1103/RR-02-10`(tenant scope가 바뀌는 배포의 rolling 구간에서 새 번호가 옛 버전이 쓴 번호보다 작다, `round2/02-persistence-messaging.md`) |
|
|
| `docs/manual/09-outbox-events.md:89` | "재리뷰 RR-05-03" | runbook 가리킴만 남겼다 | `1103/RR-05-03`(끝나지 않는 재시도 행을 운영자가 구분·처분할 수단이 없었다, `05-messaging.md`) |
|
|
|
|
- `RR-01-11`·`RR-02-10`·`RR-03-11`은 2차 재리뷰(`round2/`) 문서의 발견이다. 그 문서들은 1차 번호에 이어 `RR-` 접두어를 그대로 썼다(머리말 「표기」).
|
|
|
|
## 9. cold-read 시험 1회차 빈틈 처리 (2026-11-06~07)
|
|
|
|
2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을 시켰다(기준선 1개는 옛 매뉴얼). 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 1~9건씩 나와 모두 불합격이었다. 아래는 시험 기록(design-docs `delegation-loop/trials/2026-11-06-*.md`)의 「질문」·「위반」 표와 각 세션 공유 노트(`~/.config/Claude/side-session-notes/local_fcd89c34-c754-4c5b-a38f-fa322834286f/`)의 「매뉴얼에서 답을 못 찾은 곳」을 한 줄씩 처리한 결과다. 기준 커밋 `2c8a359d`. 2026-11-07 운영 playbook 시험(T6, `trials/2026-11-07-integration-gates.md`, 1회차 수정 전 매뉴얼로 돌림)의 빈틈 6건을 T6 행으로 더했다.
|
|
|
|
- 세션: T1 `c-t1-r10-review`(확인 리뷰), B `c-t1-baseline`(같은 리뷰를 옛 매뉴얼로, 기준선), T2 `c-t2-circuit-breaker`(결함 수정), T3 `c-t3-error-codes`(조사·설계 → 구현), T4 `c-t4-manual-ids`(문서), T5 `c-t5-idempotency-opid`(결함 수정), T6 `c-t6-integration-gates`(합친 브랜치 전체 게이트).
|
|
- 출처 칸: `기록 N`은 시험 기록 「질문」 표의 N번, `노트 N`은 공유 노트의 N번이다. T3 노트는 1단계 `1-N`, 2단계 `2-N`이다.
|
|
- 처리 칸: 고침(고친 곳) / 고치지 않음(이유) / 소유자 결정 필요. 기준선(B)은 새 매뉴얼에도 해당하는 것만 고쳤다.
|
|
|
|
| # | 출처 | 빈틈 | 처리 |
|
|
| --- | --- | --- | --- |
|
|
| T1-1 | 기록 1, 노트 1 | 상한을 넘어 나눈 확인 리뷰를 한 세션이 차례로 해도 되나 | 고침 — `improve.md` 4.4절: 나누는 것은 맡긴 쪽, brief 하나로 받으면 차례로, 단위마다 문서 하나 |
|
|
| T1-2 | 노트 2 | 영역 pathspec이 파일 단위로 안 갈림, 수정 커밋 안의 리뷰 기록을 상한에서 빼나 | 고침 — `improve.md` 4.4절: 리뷰 기록 `docs/reviews/**` 제외, 테스트 파일은 지키는 코드의 영역 |
|
|
| T1-3 | 기록 2, 노트 3 | 수정 보고에 「새로 가정하는 것」 칸이 없을 때 | 고침 — `improve.md` 4.1절 2단계: 커밋 본문 「위험·한계」와 처리 표 「결정」에서 뽑고 뽑은 곳을 적는다 |
|
|
| T1-4 | 기록 3, 노트 4 | 지난 라운드 색인 누락으로 색인 검사가 처음부터 rc=1 | 고침 — `improve.md` 4.1절 8단계: 이번 색인 절에 「색인 보완」 한 줄 |
|
|
| T1-5 | 기록 4, 노트 5 | 리뷰 README를 누가 쓰나: `delegate.md`(총괄)와 `improve.md`(리뷰어)가 다름 — **모순** | 고침 — `improve.md` 4.1절 7단계, `delegate.md` 4.2절 표, `reference/decisions.md` 2.1 「리뷰 README 분담」: 리뷰어는 자기 라운드 색인 절 하나, 나머지는 총괄 |
|
|
| T1-6 | 기록 5, 노트 6 | 지난 라운드 영역을 나눌 때 영역 번호 | 고침 — `reference/review-criteria.md` 10절 「ID」: 그 라운드 영역 표의 순번, 나누면 뒤에 새 번호, 「범위」에 대응 |
|
|
| T1-7 | 기록 6, 노트 7 | 클래스 이름으로 고르는 strict lane에서 탐침 돌리기 | 고침 — `improve.md` 9절(자주 하는 실수): 기존 클래스에 메서드로, `-Werror` 주의 |
|
|
| T1-8 | 기록 7, 노트 8 | `--rerun`이 바로 앞 태스크에만 걸림 | 고침 — `operate.md` 9절, `reference/gates.md` 6절: 태스크마다 붙인다 |
|
|
| T1-9 | 노트 9 | 지난 라운드 Declined 30건이 닫힌 기록 없음, 확인 리뷰어가 다시 판정하나 | 고침 — `improve.md` 4.1절 9단계(brief가 맡겼을 때만), `delegate.md` 4.1절(확인 리뷰 brief에 적는다) |
|
|
| T1-10 | 기록 8, 노트 10 | 같은 범위를 두 리뷰가 같은 라운드 ID로 씀 | 고침 — `reference/review-criteria.md` 10절 「ID」(정본 리뷰 하나, 다른 쪽은 새 ID와 대응표), `delegate.md` 9절 |
|
|
| T1-11 | 기록 9, 노트 11 | 다른 브랜치 병합을 기다리는 Declined는 닫힌 것인가 | 고침 — `improve.md` 4.5절 2: 합친 트리에서 확인할 때까지 열림 |
|
|
| B-1 | 기록 1, 노트 1 | 한 리뷰어가 모든 영역을 볼 때 문서 모양 | 고침 — `reference/review-criteria.md` 10절 「위치」: `roundN/NN-<영역>.md`, 영역마다 하나 |
|
|
| B-2 | 기록 2, 노트 2 | 리뷰어가 리뷰 README에 쓰나 | 고침 — T1-5와 같은 곳 |
|
|
| B-3 | 기록 3, 노트 3 | strict lane 탐침, 탐침에도 `-Werror` | 고침 — T1-7과 같은 곳 |
|
|
| B-4 | 기록 4, 노트 4 | 확인 리뷰에 넣을 「이전부터」 결함의 경계 | 고침 — `improve.md` 4.1절 3단계: 읽은 주변 코드에서 본 것은 적고, 그 밖을 찾아 나서지 않는다 |
|
|
| B-5 | 기록 5, 노트 5 | 앞 라운드 Declined가 닫히지 않은 채 시작 | 고침 — T1-9와 같은 곳 |
|
|
| B-6 | 기록 6, 노트 6 | 리뷰 스킬은 하위 에이전트를 쓰라 하고 매뉴얼은 금지 — 모순 | 고치지 않음 — 새 매뉴얼에 답이 있다: `improve.md` 3절 끝 줄, `delegate.md` 4.3절. 새 매뉴얼로 같은 리뷰를 한 T1은 묻지 않았다 |
|
|
| B-7 | 기록 7, 노트 7 | 리뷰 기록 문서도 document-contract lane 대상인가 | 고침 — `reference/gates.md` 2절, `docs-writing.md` 4절 9단계: 읽는 테스트를 파일·폴더로 찾고, 없으면 돌리지 않고 grep 결과를 적는다 |
|
|
| T2-1 | 기록 1 | push한 커밋은 못 고치고 desktop은 push된 것만 받는다. 커밋 본문에 desktop 결과를 넣으려면 | 고침 — `operate.md` 2절·4.1절 「push 전에 검증하기」(패치와 트리 해시)·9절, design-docs `conventions/delegation-loop.md` 11절 「실행 위치」 |
|
|
| T3-1 | 기록 1, 노트 1-1 | 「파일 하나여도 큼」 표면에 대한 설계 메모만 쓰는 일의 크기 | 고침 — design-docs `conventions/work-thinking-order.md` 2.1절, `research-design.md` 3절, 스킬 `research-first` |
|
|
| T3-2 | 기록 5, 노트 1-2 | push 허용: `docs/work/README.md` 4절·`decisions.md`는 "커밋·push", 정본 11절은 "push는 소유자" — **모순** | 고침 — 커밋과 push를 brief 7절이 따로 허용한다: `docs/work/README.md` 4절, `reference/decisions.md` 2.1, `delegate.md` 2·4.1·6절, 루트 `CLAUDE.md` 5절, design-docs `conventions/delegation-loop.md` 2·3·4.1·11절, 스킬 `delegate` |
|
|
| T3-3 | 기록 2, 노트 1-3 | 탐침을 생략해도 되는 기준 | 고침 — `research-design.md` 4절 3단계 |
|
|
| T3-4 | 기록 3, 노트 1-4 | 파생 서비스 영향을 어떻게 확인하나 | 고침 — `research-design.md` 4절 5단계, design-docs `conventions/delegation-loop.md` 11절 「세션」(파생 서비스 위치) |
|
|
| T3-5 | 기록 4, 노트 1-5 | 조사·설계에서 범위 밖 결함을 어디에 적나 | 고침 — `docs/work/README.md` 6절: 모든 보고에 「범위 밖에서 본 것」 |
|
|
| T3-6 | 기록 4, 노트 1-6 | 하위 세션이 Slack 브리핑을 하나 | 고침 — design-docs `conventions/delegation-loop.md` 4.1절 7절 칸·11절 「보고」, `reference/decisions.md` 2.1 「하위 세션 보고」: 전역 규칙 그대로, brief가 "Slack 말고"면 안 보냄 |
|
|
| T3-7 | 기록 4, 노트 2-1 | push 전에 RED를 보려면 desktop에 무엇을 보내나 | 고침 — `operate.md` 4.1절 「push 전에 검증하기」 RED 줄 |
|
|
| T3-8 | 기록 4, 노트 2-2 | 커밋 본문 「검증」 칸과 push 순서 | 고침 — T2-1과 같은 곳 |
|
|
| T3-9 | 기록 4, 노트 2-3 | `git add -p` 없이 한 파일을 두 커밋으로 나눠 stage | 고침 — design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」(패치 hunk를 지우고 `git apply --cached`) |
|
|
| T4-1 | 기록 1, 노트 「스크립트가 못 잡는 이력 ID」 | `--history`가 "리뷰 NN-NN"·"N라운드 NN-NN"을 못 잡아 0이 나와도 16줄 남음 | 고침 — `scripts/check-work-docs.py` 패턴 셋, `docs-writing.md` 9절. 새로 드러난 `docs/manual/` 16줄은 고치지 않음 — 이번 범위 밖, 2회차 시험 과제 |
|
|
| T4-2 | 기록 2 | 바꾼 문서를 읽는 테스트가 없을 때 무엇을 돌리나 | 고침 — B-7과 같은 곳 |
|
|
| T4-3 | 기록 3 | 이 문서 머리말의 ID 표기가 실제(2차 재리뷰도 `RR-`)와 다름 — **모순** | 고침 — 이 문서 머리말 「표기」(접두어별 문서), 8절 끝 줄 |
|
|
| T4-4 | 기록 4 | 원래 문서가 repo에 없는 결정 번호 | 고침 — `docs-writing.md` 4절 6단계 |
|
|
| T4-5 | 기록 5 | 하위 세션이 Slack 브리핑을 하나 | 고침 — T3-6과 같은 곳 |
|
|
| T5-1 | 기록 1 | 설계서 둘과 포트 Javadoc이 서로 다를 때 무엇을 따르나 | 고침 — `improve.md` 7절: 결정이 없으면 고르지 않고 양쪽 근거로 묻는다 |
|
|
| 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절. 훅으로는 막지 않는다(보고 문장은 도구 호출이 아니라 훅이 볼 수 없다) |
|
|
| T6-1 | 기록 1, 노트 1 | `reference/gates.md` 3절 묶음에 경로 필터 PR lane과 main job(configuration-cache, compose smoke, http3, notification)이 없어 "workflow와 같은 명령"이 성립하지 않음 | 고침 — `reference/gates.md` 3절 (가) 늘 도는 것(main job·optional 빌드·태그 단계 명령 더함) |
|
|
| T6-2 | 기록 2, 노트 2 | 합친 트리가 어떤 경로 필터 lane을 켜는지 정하는 절차, "바뀐 영역의 lane"의 정의 | 고침 — `reference/gates.md` 3절 (나): `git diff --name-only`를 `on.pull_request.paths`(glob)와 `pr-adapters.yml` `emit` 줄(정규식)에 맞춘다 |
|
|
| T6-3 | 기록 3, 노트 3 | 집계 태스크 전체가 실제로 돌았음을 보이는 법(`--rerun`은 앞 태스크 하나만) | 고침 — `reference/gates.md` 3절 「실제로 돌았음을 보이기」(새 worktree, `--no-build-cache`, FROM-CACHE 0)·6절, `operate.md` 9절 |
|
|
| T6-4 | 기록 4, 노트 4 | lychee 대체 명령이 lychee 범위보다 좁음, buf·dependency review 대체 안내 없음 | 고침 — `reference/gates.md` 2절 링크 검사(lychee와 같은 glob을 `git ls-files`로), 3절 (다) 로컬 도구가 없는 job 표 |
|
|
| T6-5 | 기록 5, 노트 5 | compose bind mount가 `tmp/heap-dumps`를 root 소유로 만들어 `git worktree remove`가 실패 | 고침 — `operate.md` 4.1절(compose `down` 뒤 컨테이너로 폴더를 지운다) |
|
|
| T6-6 | 기록 6, 노트 6 | `reference/gates.md` 4절 기록 형식이 "게이트 하나 = Gradle 명령 하나"를 가정 | 고침 — `reference/gates.md` 4절(한 줄 = 명령 하나, 여러 명령 job은 순번, 「실제 실행」 칸) |
|
|
|
|
- 기준선과 새 매뉴얼의 리뷰 발견은 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).
|