Files
clean-architecture-backend-…/docs/improvement/appendix-defect-patterns.md
T
DongHyeonka 3b66358e52 docs(improvement): 리뷰·개선 작업 매뉴얼을 만든다
문제: 이 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에서 돌린다.
2026-11-05 21:59:44 +09:00

5.7 KiB

부록. 결함 패턴 카탈로그

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"으로 적는다.