Files
clean-architecture-frontend…/docs/improvement/appendix-defect-patterns.md
T
DongHyeonka e9d9c3694f docs: 리뷰 절차가 merge 단계 게이트 전부를 ci:gate로 돌린다
문제: CLAUDE.md 전체 리뷰 절차 2단계가 돌릴 명령 11개를 손으로
적는다. 이 목록은 merge 단계 명령 87개 중 10개만 돌리고, merge
게이트 14개 중 7개(001, 008, 009, 011, 012, 013, 020)는 전혀 돌지
않는다. 명령을 직접 부르면 ci:gate가 하는 로그·증거 검사, 음성
fixture의 기대 실패, workflow env도 빠진다. 2026-11-03 리뷰가 실제
CI에서 항상 실패하던 merge 게이트 둘(1103/11-06, 12-09)을 놓친 경로다.

고른 방법: 2단계를 "config/ci/gates.json의 merge 단계 gateIds 전부를
workflow env로 ci:gate 하나씩, verify:documentation은 따로"로 바꾸고
목록을 손으로 적지 않는다. 자세한 방법은 개선 매뉴얼 07장 3절을
가리킨다. 매뉴얼 01·07장과 부록 P-01에서 옛 목록을 전제로 쓴 문장을
같이 고친다. 줄 수는 그대로라 매뉴얼의 CLAUDE.md 줄 참조는 맞다.
버린 대안: 목록에 빠진 명령을 더 적기(다음에 게이트가 바뀌면 다시
갈라진다). merge 단계를 읽는 명령(ci:gate:stage merge)은 이 작업
범위 밖이라 더하지 않았다.

위험·한계: 리뷰 시작 비용이 커진다(FE-GATE-020만 약 20분). 실행
위치와 잠금은 매뉴얼 07장 7절을 따른다. 추적하지 않는 AGENTS.md는
이 변경을 받지 않는다.

검증: 로컬 정적 대조(매뉴얼의 경로·script·FE-GATE ID 문제 0건).
desktop의 verify:documentation과 문서 unit 테스트는 이 커밋을 보내
돌린다.

Refs: 1105/12-03
2026-11-05 22:33:03 +09:00

18 KiB

부록. 결함 패턴 카탈로그

핵심

2026-09-24 src 리뷰와 성숙도 리뷰 다섯 라운드(0925·0929·1101·1103·1105)에서 같은 모양으로 두 번 이상 나온 결함을 모았다. 리뷰 전에 이 목록을 훑으면, 지난 라운드가 이미 본 모양을 빨리 알아본다. 고칠 때는 「막는 기준」 칸의 장을 따른다.

  • ID는 이 부록의 번호 P-NN이다. 다른 장이 이 번호로 가리킨다.
  • 대표 발견은 리뷰 ID(MMDD/NN-MM)다. 같은 발견을 두 행의 대표로 쓰지 않았다. 다른 행과 겹치면 그 행을 적었다.
  • 관점은 대표 발견들의 리뷰 문서 「관련 관점」 칸에서 많이 나온 번호다. 칸이 없으면 비웠다.
  • 「막는 기준」이 「없음」이면 지난 리뷰에서 일반 기준이 정해지지 않았다는 뜻이다. 그 행을 다시 보면 리뷰는 기준을 제안해야 한다.
  • 출처: 2026-11-05에 두 서브에이전트가 리뷰 문서에서 뽑고 줄 번호를 확인한 목록. 1103 이전은 0924·0925·0929·1101 README와 High 영역 문서, 1103·1105는 README와 영역 문서 전부를 읽었다.

Critical은 다섯 라운드 모두 0건이다. 패턴에 들지 않은 High는 0929/09-01(= 1101/09-01, 공개 API가 세션 상태 때문에 전송되지 않음) 하나다.

1. 게이트·CI·검증 절차

ID 패턴 모양 대표 발견 막는 기준 관점
P-01 돌리는 게이트 목록이 stage 전체가 아니거나, 게이트가 늦은 단계에서만 돈다 리뷰·드릴이 손으로 적은 명령 목록을 돌려 merge 게이트 일부가 빠진다. release 단계 게이트를 아무도 안 돌린다. CI가 꺼져 있다 0925/12-01, 0925/12-02, 1101/15-01, 1103/12-02, 1105/12-03 07장 2·3절. 리뷰 절차의 게이트 목록은 merge 단계 gateIds 전부를 ci:gate로 돌리는 것으로 바꿨다(CLAUDE.md 27줄, 1105/12-03) 21, 10, 26
P-02 게이트·수정 확인이 템플릿 원래 상태와 작은 입력만 본다 기능 0개, 제품 파일이 빈 상태, 객체 0~1개에서만 맞다. 기능을 더하거나 제품 파일을 채운 다운스트림에서 깨진다 0925/09-01, 1103/12-01, 1103/16-09, 1105/09-01, 1105/16-03 01장 2절 5단계, 05장 3.3절 10, 21, 25, 3, 20
P-05 workflow env에서만 나는 게이트 실패 CI=true·빌드 식별값이 테스트 기대값·dev server·테스트 안 빌드로 새어 실제 CI에서만 실패 1103/11-06, 1103/11-07, 1103/11-08 07장 3·4절, 04장 6절 21, 10, 18, 19
P-06 고정 출력 경로·포트·추적 파일에 쓴다 dist/, artifacts/, 고정 포트, 커밋된 파일에 써서 한 checkout의 두 실행이 부딪히고 추적 파일이 바뀐다 1105/12-04, 1103/12-08, 1105/16-01, 0929/14-01, 0925/00-01 실행 격리는 결정 대기(08장 5.1절 D6). 그동안 09장 4절 방식으로 하나씩 돈다. 실행 뒤 git status가 비어야 한다 20, 25, 12, 10
P-07 사전 점검·앞 단계는 PASS인데 본 단계가 실패한다 점검이 본 단계와 다른 방법으로 확인해, 전제가 깨진 곳에서 PASS 뒤 원인 없는 원문 오류가 난다 1103/11-04, 1105/12-01, 0929/06-01, 1101/09-06 07장 5절 21, 20, 8, 18
P-08 게이트가 호스트·checkout 조건을 말없이 가정한다 글꼴 패키지, 옆 백엔드 checkout, user namespace를 적지도 확인하지도 않아 기계마다 결과가 다르다 1103/11-02, 1105/12-02, 1101/11-02 05장 4절, 07장 6절 21, 20, 19, 17
P-09 거짓 PASS — 검사가 실제 대상과 비교하지 않는다 검사가 자기 산출물, 이전 release, 상수 true, 오류 화면, fixture 전용 규칙을 보고 통과한다 0925/11-01, 1101/13-01, 1103/11-01, 1103/12-04, 1103/13-01, 1105/11-01, 1105/06-02 확인 못 한 판정은 UNVERIFIED(SPEC.md D-14). 05장 3.4절 21, 18, 10, 5
P-10 정적 검사가 문자열·정규식·이름 모양으로 판정한다 코드 구조 대신 정규식·접두어·파일 목록으로 판정해 오탐·미탐이 난다 0929/08-02, 0929/07-06, 1101/12-01, 1101/12-03 import 규칙은 그래프 규칙으로(SPEC.md D-12). 문구 검사는 ESLint 구문 규칙으로(1101 README 14.1절 0929/08-02 행) 21, 10, 23, 24
P-11 검사기 자신을 지키는 음성 fixture가 없다 규칙을 통째로 꺼도 게이트가 통과한다. 검사기가 0개 모듈을 보고 통과한다 1101/12-02, 0925/12-05, 0929/11-08, 1101/14-05 통제는 통과 fixture와 거절 fixture가 둘 다 있어야 검증된다(docs/testing/taxonomy.md 108~110줄) 21, 10, 24
P-12 항상 실패하거나 통과할 수 없는 게이트를 방치한다 main에서 항상 실패하지만 CI가 꺼져 있어 아무도 막히지 않고 라운드를 넘긴다 0929/11-01, 1101/11-01, 0929/11-02, 1103/12-09 사용자 피해가 없어도 Medium·P1로 매겨 첫 묶음에 넣는다(02장 2절) 21, 10, 26
P-24 제거 드릴이 제거와 무관하게 실패하거나 제거 뒤 상태를 안 본다 드릴마다 복사·제외 목록을 따로 들어 문서를 빠뜨린다. 예제를 지운 상태는 아무 게이트도 돌지 않는다 1103/02-06, 1103/14-04, 1103/16-02, 1105/14-01 제외 목록 하나(scripts/lib/removal-fixture.ts). 03장 6절 27, 21, 10, 20
P-25 게이트 출력·로그에 실패 원인이 남지 않는다 "실패"만 남고 넘은 한도·reason·로그는 버려지거나 올라가지 않는다 0925/12-11, 1101/14-06, 1103/14-06, 1103/15-03, 1105/13-01 예산 검사는 넘은 항목·값·초과량을 출력한다. release job 로그 업로드는 미조치(1105/13-01) 8, 20, 5
P-26 수정이 새 결함을 만든다 고친 커밋이 새 가정(빈 제품 파일, CI env 없음)을 들이거나 다른 검사를 약하게 한다 1103/11-08, 1105/09-01, 1105/09-02, 1105/14-03 04장 9절 21, 10, 3
P-27 완료 기준을 돌리지 않고 "고침"으로 닫는다 코드가 들어가면 완료 기준 실행 없이 "고침"으로 적는다. 다음 라운드에 "일부"로 정정된다. 1103 조치의 "고침" 13건이 그랬다 1103/05-01, 1103/16-01, 1103/11-02, 1103/11-03 가이드 35.6절. 02장 5절, 09장 5.1절 10, 21

2. 테스트

ID 패턴 모양 대표 발견 막는 기준 관점
P-13 규칙을 지워도·결함을 고쳐도 테스트가 그대로 통과한다 보호 규칙을 지우는 변이, 판정 경계를 바꾸는 변이가 살아남는다. 커버리지 100%인 곳도 있다 1101/07-06, 1101/02-04, 1103/10-02, 1103/07-02, 1105/02-04, 1105/01-04 RED 먼저(SPEC.md 29~30줄), 변이 확인(05장 3.2절). 판정 규칙의 변이 도구는 미조치(1105/10-03) 10, 21, 6
P-15 단언이 대상에 닿지 않아 항상 참이다 fixture가 비어 첫 줄에서 return하거나 전제를 만들지 않는다. 로딩 화면·fixture 자신을 검사한다 1101/10-01, 1101/10-02, 0925/08-05, 0925/11-05 05장 3.4절. 전역 expect.hasAssertions()는 제안만 됐다 10, 21, 24
P-16 시간·속도·준비 상태를 가정한 테스트 기본 대기, 짧은 상한, 실제 시계, 짧은 전이 상태 폴링에 기대 부하가 있는 호스트에서 실패한다 0929/10-01, 1103/10-01, 1103/11-03, 1103/11-05, 0929/11-04 공통 대기 기한은 tests/setup.ts 한 곳. 05장 5절 10, 21, 12
P-17 브라우저의 추정에 기댄다 WebKit이 load 3초 뒤 한 번 하는 preload 추정에 기대 곧 쓰일 preload로 실패하고, 정말 안 쓴 preload는 놓친다. 같은 원리로 두 spec이 떨어졌다 1103/11-09 추정 대신 확인하려는 사실을 직접 검사한다(05장 5.3절) 10, 21
P-18 그리는 중인 화면을 누른다 앱 뒤에 붙인 버튼이 렌더링 중 밀려 클릭이 닿지 않는다. 같은 파일의 두 test가 떨어졌다 1103/11-10 테스트가 붙이는 조작 요소는 고정 층에(05장 5.3절) 10, 21
P-19 테스트 대역이 실제 상대와 다르다 메모리 IndexedDB, fake, 백엔드 문서에서 옮긴 MSW 응답이 실제와 달라 결함을 숨긴다 0925/05-08, 0925/06-01, 1103/05-04, 1103/16-01, 1105/01-01 실제 짝 백엔드 응답으로 맞추기는 미조치(1105 README 9절) 10, 17, 12
P-20 플랫폼 테스트가 샘플·특정 파일·예시 이름에 묶인다 샘플을 지우면 테스트가 같이 사라지거나 게이트가 깨진다. 템플릿 테스트의 글자가 매뉴얼 예시 기능 이름과 부딪힌다 0925/14-01, 0929/10-02, 1101/16-02, 1105/10-01, 1105/16-04 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(05장 2절). 탐침 이름은 예약 접두어 typecheck-probe-* 27, 10, 21, 20
P-21 빠른 계층에 느린 테스트가 섞인다 unit에 프로세스를 띄우는 도구 테스트, 실제 시계로 기다리는 테스트가 섞이고 같은 파일을 두 번 돈다 1101/10-05, 1101/10-06, 1101/10-07, 1101/15-04 없음. 05장 6절 14, 20, 10
P-22 깨끗한 clone·다른 호스트에서 실패한다 gitignore된 생성물, 기준선을 만든 CPU, 실행기가 넣는 npm 환경변수에 기댄다 0924 6.0절, 0925/10-01, 0925/11-03, 1101/15-05 한 파일 실행도 scripts/run-vitest.ts로(07장 1절). merge 판정은 깨끗한 checkout에서(07장 3절) 10, 21, 20
P-23 지우거나 바꾼 코드가 지키던 검사·테스트를 같이 잃는다 삭제·이름 변경이 실행 동작만 옮기고, 지운 행·테스트가 지키던 규칙은 옮기지 않는다 1103/07-01, 1103/10-04, 1105/04-01, 1105/10-01 04장 5절 10, 21, 17

3. 코드

ID 패턴 모양 대표 발견 막는 기준 관점
P-28 실패를 다른 종류로 분류해 복구 경로가 닫힌다 status 하나나 표 밖 기본값으로 판정해 업무 거절·입력 오류·일시 오류·서버 장애가 뒤섞인다 0925/03-02, 0929/03-05, 1103/03-01, 1105/01-01, 1105/04-02, 1105/03-02 04장 2절 6, 17, 8, 24
P-29 결과 불명 쓰기를 무방비로 다시 보낸다 적용됐을 수 있는 쓰기를 키 없이, 새 키로 다시 보내는 입구가 남는다. 고칠 때마다 다른 입구에서 나온다 0925/03-01, 0929/03-01, 0929/03-03, 1103/03-03, 1103/04-01, 1105/01-02, 1105/03-01 04장 2절, docs/manual/02-decision-tables.md 3·4절 6, 17, 12, 28
P-30 오지 않을 신호를 기다리며 멈춘다 재시도 상태 기계가 그 상황에서 오지 않는 신호(새 online 이벤트, 예산 재충전)를 기다려 재시도도 종료도 없이 멈춘다 0925/04-01, 0929/04-01, 0929/04-04 04장 3절 6, 28, 5
P-31 손상 한 건이 목록·작업 전체를 멈춘다 행 하나가 손상되면 목록 읽기·purge·GC가 그 뒤로 계속 같은 곳에서 실패한다 0925/05-02, 0925/05-05, 0929/05-01, 0929/02-01 04장 3절 6, 28, 11
P-32 결과·상태를 실제와 다르게 보고한다 다 하지 못했는데 COMPLETED·verified·active를 보고한다. 겹치는 작업 사이 틈을 놓친다 0929/05-02, 0925/02-05, 1101/09-07, 1103/05-01, 1103/02-04 04장 3절 24, 11, 12, 5
P-33 실패가 원인·추적값을 버린다 서로 다른 실패를 같은 reason으로 남기거나 traceId·effect를 싣지 않는다. 새 모듈에서 같은 누락이 다시 생긴다 0925/09-04, 1101/02-05, 1103/03-05, 1103/03-06, 1105/01-03, 1105/02-01 04장 3절 8, 24, 7
P-34 router base path를 무시한 URL 하위 경로에 배포하면 /부터 조립한 URL이 앱 밖을 가리킨다. 한 곳을 고치면 다른 소비자에서 나온다 0925/13-07, 0929/06-02, 1101/06-01 04장 6절 19, 18, 23
P-35 같은 설정을 경로마다 다르게 읽는다 번들·빌드 스크립트·SW 빌드가 같은 설정을 다른 출처에서 읽는다 0925/09-02, 0925/06-10, 0929/13-02 04장 6절 19, 18, 23
P-36 여러 탭·동시 실행 경쟁 두 탭이 같은 저장소·구독·잠금을 건드려 진행 중 데이터를 지우거나 잠금을 무기한 쥔다 0925/05-01, 0925/06-02, 0925/05-07, 1103/05-02 04장 7절, SPEC.md D-3·D-4 12, 6, 11
P-37 이름 하나가 여러 뜻, 뜻 하나가 여러 이름 같은 이름이 다른 모양·뜻을 가리키거나 한 개념을 여러 이름으로 적는다 0929/09-04, 1101/07-01, 1101/07-05, 1101/04-02 04장 5절(@deprecated 별칭) 24, 23, 4
P-38 실패·복구 전이 뒤 화면이 다음 행동을 잃는다 한 전이에서 고친 포커스·안내를 다른 전이에 쓰지 않아 키보드 사용자가 위치를 잃거나 버튼이 무반응으로 남는다 1103/08-02, 1105/08-01, 1105/08-02, 1105/08-04, 1103/09-11 04장 3절 1, 6, 24, 28

4. 구조

ID 패턴 모양 대표 발견 막는 기준 관점
P-03 같은 사실을 repo 안 여러 곳에 손으로 적는다 스키마 메타, 레지스트리 행, 허용 키, 빌드 입력 목록을 원본과 따로 적고 대조 검사가 없다 1101/07-02, 0929/07-05, 1103/16-04, 1103/13-04, 1105/15-03, 1105/05-01 04장 4절 23, 17, 3, 21
P-04 두 템플릿 사이 계약을 문서 문장·손 사본으로 맞춘다 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 프론트 문서·JSON·문자열로 옮기고 게이트가 어긋남을 알리지 않는다 1103/01-01, 1103/12-06, 1103/04-02, 1105/07-01, 1105/16-02 04장 4절, 1103 결정 D6 17, 26, 21
P-14 갈라진 중복 복사본 같은 로직·fixture·helper·port를 두 벌 이상 두고 이미 규칙이 서로 다르다 0924 5.1절, 0925/09-12, 0929/05-03, 1101/07-03, 1101/10-08 CLAUDE.md 19줄, 03장 2절, 04장 4절 9, 23, 22
P-39 제품이 템플릿 소유 파일을 고쳐야 한다 제품마다 다른 것이 템플릿 소유 파일에만 있어 동기화마다 충돌한다 0929/09-02, 0929/14-03, 1103/02-01, 1103/12-07, 1105/13-02 04장 8절. 1101 결정 「확장 지점을 템플릿이 연다」 3, 25, 22
P-40 경계·kernel 예외가 실제 쓰임보다 넓다 예외가 필요한 것보다 넓게 열려 있거나 공유 메커니즘이 아닌 파일이 kernel 예외를 받는다 0925/12-07, 0929/02-06, 1101/05-04 CLAUDE.md 21줄, 03장 2절 2, 22, 21
P-41 연결된 두 모듈의 약속이 어긋난다 모듈마다 테스트는 있지만 한쪽이 보내는 결과를 다른 쪽이 다른 뜻으로 받는다 0929/04-02, 1101/04-01, 1101/03-04 없음. 04장 8절 17, 22, 4

5. 문서

ID 패턴 모양 대표 발견 막는 기준 관점
P-42 문서의 주장·숫자·상태가 코드와 갈라진다 운영 문서가 없는 동작을 안내하거나, 손으로 적은 기준선·상한·상태가 다음 변경에서 낡는다 0925/06-03, 1101/01-01, 1103/15-02, 1103/14-01, 1105/04-03 숫자는 한 곳에 두고 문서는 그곳을 가리킨다(06장 5절). verify:documentation은 경로·이름만 본다(07장 6절) 9, 5, 24, 26
P-43 file:line·이력 문서 참조가 낡는다 줄 번호 참조가 코드 변경으로 밀려 다른 코드를 가리킨다. 결정 근거를 지워도 되는 이력 문서로만 가리킨다 0929/02-04, 1101/05-05, 1101/14-01 현재 계약 문서는 이력 문서에 기대지 않는다(03장 4절). 이 매뉴얼의 표기 원칙은 README 「근거 표기」 9, 4, 24
P-44 매뉴얼·안내를 그대로 따르면 게이트가 실패한다 매뉴얼 예시, CHANGELOG 이행 단계, 오류 안내를 글자 그대로 따라 한 제품이 merge 게이트에서 실패한다 1105/14-02, 1103/14-02, 1103/09-07 매뉴얼만 보는 기능 추가 재실험(1103 README 14.6절). 문서 예시를 게이트가 실행하는 기준은 없음 20, 19, 9
P-45 CHANGELOG [계약] 표시가 실제 변경과 다르다 [계약] 행이 실제 경로·대상과 다르거나 게이트를 좁힌 변경에 표시가 없다 0929/02-03, 0929/07-07, 0929/14-04, 1101/14-02 리뷰 ID 형식은 tests/unit/changelog-review-ids.test.ts. [계약] 표시 기준은 없음 9, 17, 26

6. 성능

ID 패턴 모양 대표 발견 막는 기준 관점
P-46 예산 여유가 바닥이고, 한도·허용치를 여유와 비교하지 않는다 예산을 직전 측정값으로 올려 증가를 묻는 신호가 사라진다. 대조 허용치가 남은 여유보다 크다 0929/05-04, 1103/15-04, 1105/15-02 레시피 예산은 측정값 + 3%, 3% 초과는 커밋 본문에 이유(1101 README 14.1절). 06장 5절 14, 21, 13
P-47 성능 측정이 화면 하나·조건 하나만 본다 lab이 한 화면, /의 CLS, 스크롤바를 숨긴 Chromium만 재고 release 단계에서만 돈다 1103/15-01, 1105/15-04, 1105/15-01, 1105/15-05 06장 2절·6절 14, 21, 13
P-48 필요 없는 코드가 초기 청크에 실린다 첫 화면에 필요 없는 코드가 배럴·side effect 판정 때문에 초기 청크에 들어간다 0925/13-14, 1101/08-08 design-system side effect 없음 선언, 기능 선언과 실행부 분리(1101 README 14.1절) 14, 13, 22
P-49 작은 변경이 캐시·청크 전체를 다시 받게 한다 build id 하나, 파일 하나 변경이 큰 청크·캐시 전체를 무효화한다 0929/13-03, 1101/06-05 react-dom 청크 분리(docs/operations/performance-evidence.md 「build id와 재방문 캐시」) 14, 13

7. 이 목록을 고칠 때

  • 리뷰 라운드가 끝나면 새 반복 모양을 행으로 더한다. 한 번만 나온 것은 넣지 않는다.
  • 번호는 다시 매기지 않는다. 다른 장이 번호로 가리킨다. 번호 순서와 절 순서가 다른 행(예: 1절의 P-24, 4절의 P-03)은 처음 묶을 때 생긴 것이다. 새 행은 마지막 번호 다음을 쓴다.
  • 막는 기준이 생기면 그 기준은 해당 장(04·05·06·07)에 쓰고 이 표는 그 장을 가리킨다.

지금 이해하면 되는 것

  • 결함은 같은 모양으로 돌아온다. 리뷰 전에 이 표를 훑는다.
  • 가장 많이 돌아온 것은 게이트가 틀린 답을 내는 모양(P-01·02·05·07·09·12)과 판정 규칙의 빈틈(P-13·28·29)이다.
  • 「막는 기준: 없음」인 행이 다음 개선 후보다.