문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때 기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰 기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가 가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰 문서 여러 곳에 흩어져 있다. 방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은 다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md, TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다. 정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함 정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션 분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에 「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와 docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다. 버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용 가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접 쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다). 위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지 않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소 밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드 표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로 넣기)는 [제안]으로 표시했다. 검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절 번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖 가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는 DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로 둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
33 lines
5.7 KiB
Markdown
33 lines
5.7 KiB
Markdown
# 부록. 결함 패턴 카탈로그
|
|
|
|
2026-11-01 성숙도 리뷰부터 2026-11-05 round6까지 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고,
|
|
리뷰 문서의 「반복되는 원인」에 이 번호를 붙인다. 근거 ID 표기는 README 「근거 표기」를 따른다.
|
|
|
|
출발점은 `1101` README 4절 「반복되는 원인」 다섯 가지다(A3·A4·A5·A11·A1). 그 뒤 재리뷰와 확인 리뷰에서 나온 모양을 더했다.
|
|
|
|
| # | 패턴 | 어떻게 보이나 | 근거 | 막는 기준 |
|
|
| --- | --- | --- | --- | --- |
|
|
| 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(버전 정규식 사본) | 04장 P1 |
|
|
| A2 | 문서와 코드 불일치 | 계약·runbook·매뉴얼·README·Javadoc·실패 메시지가 현재 동작과 다르다 | `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` | 04장 P2 |
|
|
| A3 | 선언과 실행이 떨어져 있다 | 설정 키는 바인딩되지만 동작하지 않는다. 선언한 설정 bean이 조용히 바인딩되지 않는다. 레지스트리 행·지표를 아무 코드도 쓰지 않는다 | `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개) | 04장 P3 |
|
|
| A4 | 결과 불명을 확실함으로 | 외부 효과의 결과를 모르는데 "시작 안 함"·"재시도 가능"·"확정 거부"로 기록한다(또는 반대로 부풀린다) | `1101/05-01`, `1101/04-01`, `1101/06-01`, `1101/05-17`, `1101/05-11`, `1103/RR-02-03`, `1103/RR-01-11` | 04장 P4 |
|
|
| A5 | 중복·경쟁을 코드 순서로 | 조회 후 insert, 찾고 없으면 넣기, 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim | `1101/09-02`, `1101/04-08`, `1101/04-02`, `1101/03-10`, `1101/04-13`, `1103/RR-03-01`, `1103/RR-02-04` | 04장 P5 |
|
|
| A6 | 주장하는 것을 보지 않는 테스트 | 이름이 말한 성질을 단언하지 않는다. 지키려는 코드를 지워도 통과한다. 시간 제한 대기의 결과를 버린다. 계약 케이스를 skip한다 | `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` | 05장 4·5절 |
|
|
| A7 | 거짓 통과 게이트 | 어떤 단계도 돌리지 않는 lane·검사, 캐시가 옛 결과로 통과, 실패를 막지 못하는 workflow 명령을 실행으로 셈 | `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` | 07장 5절 |
|
|
| A8 | 로그로 새는 입력값·원인 | 클라이언트 입력·SQL 원인이 로그 메시지에 실린다. 서버 실패를 남기지 않거나 클라이언트 실패를 ERROR로 남긴다 | `1103/RR6-01-05`, `1103/RR6-01-06`, `1103` README 16절 r9-a(STOMP SQL 원인, gRPC 무기록), `1101/02-11`, `1101/01-04` | 04장 P8 |
|
|
| A9 | 이름만 보는 허용·거부 | 프로필·환경 이름 하나가 다르면 위험한 기능이 열린다. 허용한 값으로는 실제로 동작하지 않는다 | `1103/RR-07-02`, `1103/RR2-04-02`, `1103/RR2-04-01`, `1101/07-14` | 04장 P6 |
|
|
| A10 | 글로만 있는 규칙 | "하지 마라"·"반드시"가 주석·문서에만 있고 막는 장치가 없다(통제 M0~M1) | `1103/RR-01-02`, `1101/04-03`, `1101/05-16` | 04장 P7 |
|
|
| A11 | 샘플·fixture가 운영과 다르게 조립 | 샘플이 자동 설정을 빼거나 런타임 기본값이 다르다. "따라 할 모양"이 기동하지 않는다 | `1101/07-03`, `1101/09-03`, `1101/09-08`, `1101/07-04`, `1101/01-02`, `1101/07-09` | 04장 P9 |
|
|
| A12 | 수정이 새 결함을 만든다 | 고친 커밋에서 새 Important·회귀가 나온다. 두 수정이 한 트리에서 처음 만나 새 결함이 생긴다 | `1103` README 1절(Important 27), 9절(새 Important), `1103/RR6-01-01`(회귀), `1101` README 16.1절(`BC_IMPOSSIBLE_INSTANCEOF`), `1103` README 6.1절(최종 게이트에서 드러난 2건) | 09장 5절, 07장 3절 |
|
|
| A13 | 합치는 과정의 누락 | 색인을 손으로 옮기다 발견이 빠진다. 손으로 푼 충돌이 한쪽 변경을 지운다 | `1101` README 12절 정정(06-10~14 다섯 건), `1101` README 14.1절(충돌 처리 목록) | 01장 1절 8단계, 09장 2절 |
|
|
| A14 | 타이밍에 기댄 약속 | "스레드를 남기지 않는다"·"시간 안에 끊는다"가 공용 풀이나 "보통은 끝나 있음"에 기댄다 | `1103` README 16.1절(`ClientRuntimeRegistry.close`), `1103/RR3-03-01`, `1101/05-06` | 04장 P10 |
|
|
| A15 | 사라지는 외부 공급원 | 고정한 컨테이너 이미지를 더는 받을 수 없어 다른 lane 결과까지 가린다 | `1101/05-09`, `1101/08-04` | 07장 5절 |
|
|
| A16 | 상한 없는 자원 | 연결·구독·동시 호출·본문 크기·트랜잭션 시간에 상한이 없거나 코드에 드러나지 않는다 | `1101/03-06`, `1101/03-09`, `1101/04-10`, `1101/02-09`, `1101/04-12` | 04장 P11 |
|
|
|
|
## 패턴을 더하는 법
|
|
|
|
- 새 라운드에서 **두 건 이상**이 같은 모양이면 행을 더한다. 한 건이면 그 라운드 README에만 둔다.
|
|
- 행에는 모양(코드에서 어떻게 보이나)과 근거 ID를 적는다. 원인 추측이 아니라 실제로 본 모양을 쓴다.
|
|
- 막는 기준이 생기면 04·05·07장에 기준을 쓰고 이 표의 「막는 기준」 칸에서 가리킨다.
|
|
- 번호는 다시 매기지 않는다. 지운 패턴은 행을 남기고 "합침 → A<n>"으로 적는다.
|