ADR-09: Phase 1 V1 품질 개선 아키텍처

🇺🇸 English Version

날짜	작성자	레포지토리
2026-02-04	@KubrickCode	worker

Context

문제 상황

AI 기반 SpecView 생성 파이프라인(ADR-14)은 테스트 분류에 Gemini 사용. 그러나 원시 LLM 출력에 품질 이슈 존재:

품질 이슈	설명	사용자 영향
도메인 명명 변동	동일 개념이 "Auth", "Authentication", "AuthService"로 표시	도메인 그룹 파편화
고아 테스트	도메인 할당 없이 반환된 테스트	누락된 스펙
약어 불일치	"db", "DB", "Database"가 다른 도메인으로 처리	중복 도메인 출력
구조적 오류	간헐적 JSON 응답 형식 오류	파이프라인 실패
품질 사각지대	분류 품질에 대한 메트릭 부재	개선 측정 불가

실험적 대안

V1 개선으로 회귀하기 전 두 가지 대안 아키텍처 탐색:

아키텍처	접근 방식	결과
V2 2단계	분류 전 별도 도메인 추출	폐기 - 품질 향상 대비 복잡도 오버헤드
V3 순차 배치	앵커 전파와 함께 배치 순차 처리	폐기 - 일관성 이점 대비 지연 증가

두 방식 모두 기능 플래그로 비활성화(SPECVIEW_PHASE1_V2=false, SPECVIEW_PHASE1_V3=false), 코드 제거 완료.

요구사항

요구사항	설명
하위 호환성	기존 ADR-14 파이프라인 위에 레이어링
낮은 지연 영향	청크당 후처리 오버헤드 < 100ms
관측 가능성	품질 모니터링용 메트릭 제공
결정론적	동일 입력 시 일관된 도메인 할당

Decision

V1 단일 패스 분류 아키텍처에 분류 결과를 검증, 정규화, 복구하는 후처리 파이프라인 추가.

후처리 파이프라인

LLM 분류 출력
         │
         ▼
┌─────────────────────────────────────────────────────┐
│              Phase1PostProcessor                     │
├─────────────────────────────────────────────────────┤
│  1. JSON 검증            → 형식 오류 거부           │
│  2. 도메인 정규화        → 유사 이름 병합           │
│  3. 약어 확장            → auth → Authentication    │
│  4. 고아 감지            → 미분류 플래그            │
│  5. 경로 기반 폴백       → 파일 경로에서 도메인 추출│
└─────────────────────────────────────────────────────┘
         │
         ▼
    정규화된 분류 결과
         │
         ▼
┌─────────────────────────────────────────────────────┐
│           Quality Metrics Collector                  │
├─────────────────────────────────────────────────────┤
│  - 고아 테스트 수                                   │
│  - 정규화 빈도                                      │
│  - 폴백 사용률                                      │
│  - 도메인 분포                                      │
└─────────────────────────────────────────────────────┘

컴포넌트 책임

컴포넌트	책임	트리거
Phase1PostProcessor	LLM 분류 출력 검증 및 정규화	모든 분류 응답
Domain Normalization	의미적으로 동등한 도메인명 병합	도메인명 추출 시
Domain Abbreviation Expand	일반적인 약어를 전체 이름으로 확장	도메인명 추출 시
Path-based Fallback	고아 테스트에 대해 파일 경로에서 도메인 추출	테스트에 도메인 없을 때
Orphaned Test Detection	분류 실패 테스트 식별 및 플래그	정규화 후
Quality Metrics Collector	분류 품질 메트릭 추적	각 배치 후

정규화 규칙

도메인명 병합:

변형	정규화 결과
Auth, AuthService, AuthModule	Authentication
User, UserService, UserMgmt	UserManagement
Pay, Payments, PaymentService	Payment
DB, Database, DataAccess	Database

약어 확장:

약어	확장
auth	Authentication
db	Database
ui	UserInterface
api	API
http	HTTP

경로 기반 폴백 전략:

test/services/payment/checkout_test.go
         │
         ▼
추출: "payment" (경로에서)
         │
         ▼
확장: "Payment" 도메인

Options Considered

Option A: V1 후처리 개선 (선택)

ADR-14의 단일 패스 분류 아키텍처 유지하면서 LLM 응답 후 검증, 정규화, 폴백 레이어 추가.

측면	평가
아키텍처 영향	추가적 - 핵심 LLM 파이프라인 변경 없음
지연	청크당 +10-50ms (후처리)
품질 개선	중간 - 명명 일관성 해결
구현	명확한 책임을 가진 6개 집중 컴포넌트
롤백	컴포넌트별 기능 플래그 가능

선택 근거:

V2/V3 실험에서 추가 LLM 호출이 품질을 비례적으로 향상시키지 않음 확인
후처리가 API 비용 증가 없이 관찰된 품질 이슈 해결
V1 파이프라인의 검증된 신뢰성 특성 유지
아키텍처 리스크 없이 점진적 개선 가능

Option B: V2 2단계 Taxonomy 아키텍처 (폐기)

분류 전 전용 LLM 호출로 도메인 추출 분리.

측면	평가
API 호출	2x (도메인 추출 + 분류)
복잡도	높음 - 2단계 조정
품질 향상	테스트에서 미미함
비용 영향	Phase 1 Gemini API 비용 2배
상태	폐기 - `SPECVIEW_PHASE1_V2=false`

거부 근거:

경험적 테스트에서 도메인 일관성이 비례적으로 향상되지 않음
사용자에게 보이는 품질 개선 없이 API 비용 2배
실패 모드 및 디버깅 복잡도 추가

Option C: V3 순차 배치 아키텍처 (폐기)

배치 간 명시적 컨텍스트 전달과 함께 테스트 배치 순차 처리.

측면	평가
지연	증가 - 순차 처리로 병렬성 제거
복잡도	높음 - 배치 순서 및 상태 관리
품질 향상	미미한 일관성 개선
상태	폐기 - `SPECVIEW_PHASE1_V3=false`

거부 근거:

순차 처리로 전체 처리 시간 크게 증가
V1의 앵커 전파가 이미 청크 간 일관성 제공
품질 향상 대비 복잡도 정당화 불가

Consequences

Positive

영역	이점
도메인 일관성	정규화로 명명 변동에 의한 중복 도메인 제거
테스트 커버리지	경로 기반 폴백으로 고아 테스트 복구
관측 가능성	메트릭 수집으로 품질 모니터링 및 회귀 감지 가능
지연	추가 API 호출 없음 - 후처리는 로컬 계산
유지보수성	각 개선 사항이 격리되고 독립적으로 테스트 가능
아키텍처 단순성	기존 파이프라인 개선으로 V2/V3 복잡도 회피

Negative

영역	트레이드오프
품질 상한	단일 패스 LLM 분류로 달성 가능한 최대 품질 제한
정규화 규칙	도메인 동의어 매핑에 수동 큐레이션 필요
경로 폴백 정확도	파일 경로가 비즈니스 도메인을 정확히 반영하지 않을 수 있음
메트릭 오버헤드	품질 메트릭으로 약간의 처리 및 저장 오버헤드 추가

기술적 영향

측면	영향
파이프라인 위치	PostProcessor는 LLM 응답 파싱 후 동기적으로 실행
에러 처리	정규화 실패 시 경고 로그만 남기고 파이프라인 실패 안 함
메트릭 저장	품질 메트릭은 구조화된 로깅으로 기록 (DB 미사용)
설정	정규화 규칙은 코드 변경 없이 설정 가능
테스트	정규화 동작에 대한 골든 스냅샷 테스트

References

ADR-14: AI 기반 스펙 문서 생성 파이프라인
ADR-08: SpecView Worker 바이너리 분리
Core ADR-16: 도메인 힌트 추출 시스템
관련 커밋 - Phase1PostProcessor, MetricsCollector 구현

ADR-09: Phase 1 V1 품질 개선 아키텍처 ​

Context ​

문제 상황 ​

실험적 대안 ​

요구사항 ​

Decision ​

후처리 파이프라인 ​

컴포넌트 책임 ​

정규화 규칙 ​

Options Considered ​

Option A: V1 후처리 개선 (선택) ​

Option B: V2 2단계 Taxonomy 아키텍처 (폐기) ​

Option C: V3 순차 배치 아키텍처 (폐기) ​

Consequences ​

Positive ​

Negative ​

기술적 영향 ​

References ​