docs(verification): 회고 교훈 2건 반영 (20260629 세션)

- 버그범주 표: HTTP 상태/예외 매핑 변경 → L1 + 런타임 스모크 의무
- 구조교훈: HTTP 상태변경 런타임 스모크(전역 핸들러 가림 주의) + multi-worker advisor 산출 git diff 교차검증

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K3FeMrbtxfTScjrwUukyHD
This commit is contained in:
이정수 2026-06-29 19:24:22 +09:00
parent f6617a951d
commit 7047e06791
1 changed files with 13 additions and 0 deletions

View File

@ -24,6 +24,7 @@
| 순수 도메인 로직 (외부 의존 없음) | L1 | | 순수 도메인 로직 (외부 의존 없음) | L1 |
| MyBatis 매퍼 신규/SQL alias·집계 뷰 정의·변경 (DB-방언 계약) | L1 + L2 (dev DB contract) | | MyBatis 매퍼 신규/SQL alias·집계 뷰 정의·변경 (DB-방언 계약) | L1 + L2 (dev DB contract) |
| 인프라 설정 (container/env/compose) | L1 + 수동 스모크 | | 인프라 설정 (container/env/compose) | L1 + 수동 스모크 |
| HTTP 상태코드/예외 매핑 변경 (404/403 등, 전역 `@ExceptionHandler` 경유) | L1 + 런타임 스모크 |
**회귀 테스트 의무**: 버그 수정 커밋은 해당 버그를 재현하는 테스트를 같이 포함한다. revert 시 테스트가 실패하고, 수정 후엔 통과해야 한다. **회귀 테스트 의무**: 버그 수정 커밋은 해당 버그를 재현하는 테스트를 같이 포함한다. revert 시 테스트가 실패하고, 수정 후엔 통과해야 한다.
@ -238,3 +239,15 @@ SSRF·zip-slip·경로 boundary·sanitize 같은 보안핵심은 verification-ad
- **verification-advisor 체크리스트**: 보안 거부 단위테스트는 정상경로 성공(present) 테스트와 쌍으로 차별 입증(distinguishing assertion) 확인 조항. 근거: W3-3 vacuous PASS. - **verification-advisor 체크리스트**: 보안 거부 단위테스트는 정상경로 성공(present) 테스트와 쌍으로 차별 입증(distinguishing assertion) 확인 조항. 근거: W3-3 vacuous PASS.
- **orchestrator scope-fence 조항(구조적)**: 단일기능 표시면이 선행기능 컨트롤러에 의존할 때 cross-feature display wiring fence 예외 선언 또는 deferral 분리. 근거: W4 배지 표시 AC 갭. - **orchestrator scope-fence 조항(구조적)**: 단일기능 표시면이 선행기능 컨트롤러에 의존할 때 cross-feature display wiring fence 예외 선언 또는 deferral 분리. 근거: W4 배지 표시 AC 갭.
- **design-advisor 조항**: 트레이드오프 concern 은 1차 권장안 + 조건부 전환 기준까지 선결정으로 좁힘. 근거: W3-3 SSRF IP핀닝 오선택. - **design-advisor 조항**: 트레이드오프 concern 은 1차 권장안 + 조건부 전환 기준까지 선결정으로 좁힘. 근거: W3-3 SSRF IP핀닝 오선택.
### HTTP 상태/예외 매핑 변경은 런타임 스모크 의무 (L1 통과로 충분치 않음)
컨트롤러가 던지는 예외의 HTTP 상태(404/403 등)를 바꾸거나 신규 예외를 도입할 때, 전역 `@RestControllerAdvice`/`@ExceptionHandler(Exception.class)` 가 더 구체적 핸들러보다 먼저 잡아 의도한 상태를 **삼킬 수 있다**(예: `ResponseStatusException(404)` 이 광역 Exception 핸들러에서 500으로 변환). 컴파일·단위(L1)는 "예외를 던진다"까지만 검증하고 실제 HTTP 응답 코드는 미검증 → L1 GREEN 으로 끝내지 말고 **런타임 스모크(`curl -w '%{http_code}'`)** 로 실제 상태코드를 가드한다. 회귀 가드는 (a) 컨트롤러가 올바른 예외를 던지는 단위테스트 + (b) advice 핸들러가 상태를 보존하는 검증, 둘 다 둔다.
> 근거: B2·B4·FE 세션(20260629) — `gameDetail` 404 전환이 mvn test 361 PASS 후에도 런타임 500 반환(전역 Exception 핸들러가 ResponseStatusException 가림). 브라우저 스모크에서 발견 → advice 에 `@ExceptionHandler(ResponseStatusException)` 추가로 해소.
### multi-worker advisor 산출은 orchestrator git diff 교차검증
implementation-advisor 가 여러 code-writer worker 로 파일을 분산 수정한 뒤 반환하는 완료 summary 는 worker 상태 추적 혼선으로 **실제 변경과 불일치**할 수 있다("Worker C만 완료" 보고했으나 실제 4파일 적용 등). orchestrator 는 advisor summary 를 그대로 신뢰하지 말고 `git diff --stat` / 대상 파일 grep 으로 **실변경을 교차검증**한 뒤 다음 단계로 진행한다.
> 근거: B2·B4·FE 세션(20260629) — FE implementation-advisor 가 불완전 summary 반환, git diff 로 4파일 적용 확인 후 진행. profile 미변경은 "입력 컨트롤 없음=정상"으로 판별.