Core ADR-16: 도메인 힌트 추출 시스템

🇺🇸 English Version

날짜	작성자	리포지토리
2026-01-18	@KubrickCode	core

배경

도메인 분류 문제

AI 기반 SpecView 생성 파이프라인(ADR-14)은 테스트를 비즈니스 도메인(인증, 결제, 사용자 관리 등)으로 그룹화하기 위한 도메인 분류 필요. 테스트 대상 코드에 대한 컨텍스트 없이는 AI 모델이 의미 있는 분류 불가.

도전 과제: 다음 조건을 만족하며 AI에 시맨틱 컨텍스트 제공:

전체 소스 파일 전송 지양 (과도한 토큰 소비)
분류 신호를 희석시키는 노이즈 제외
12개 이상 지원 언어별 별도 추출기 구축 방지

요구사항

요구사항	설명
신호 밀도	의미 있는 도메인 지표 대 토큰 비율 최대화
토큰 효율성	품질 유지하면서 AI 입력 토큰 최소화
크로스 언어	모든 언어에 걸친 통합 추출 방식
노이즈 내성	범용 및 언어별 비도메인 패턴 필터링
AST 정확성	코드와 주석/문자열 구분

제약사항

제약사항	영향
Tree-sitter 의존	기존 AST 인프라와 통합 필수
병렬 스캐닝	추출이 워커 풀 성능 저해 금지
메모리 예산	대규모 리포지토리에서 전체 AST 로드 불가

결정

Imports + Calls 이중 필드 추출 모델 채택, 공격적 노이즈 필터링과 2-세그먼트 호출 정규화 적용.

type DomainHints struct {
    Imports []string  // 중복 제거된 임포트 경로
    Calls   []string  // 2 세그먼트로 정규화 (a.b.c() → a.b)
}

핵심 설계 선택

Imports: 외부 의존성과 도메인의 직접적 지표
Calls: 도메인 엔티티와의 상호작용 패턴 노출
2-세그먼트 정규화: stripe.customers.create() → stripe.customers
Variables 필드 제외: 실험 결과 분류 개선 없음 확인 후 제거

토큰 영향

지표	이전	이후	개선
토큰 볼륨	600K	90K	85% ↓
분류 품질	기준선	동등	유지

아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                    도메인 힌트 추출                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  테스트 파일 → Tree-sitter 파싱 → 언어별 추출기                 │
│                                       │                          │
│              ┌────────────────────────┼────────────────────────┐│
│              │                        │                        ││
│              ▼                        ▼                        ▼│
│         Import 추출             Call 추출              노이즈 필터│
│         - ES6 import            - 메서드 호출          - 범용    │
│         - CommonJS require      - 2-세그먼트 정규화    - 언어별  │
│         - Go import             - 체인 평탄화                   │
│         - Python import                                         │
│              │                        │                         │
│              └────────────┬───────────┘                         │
│                           ▼                                     │
│                    DomainHints{Imports, Calls}                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

언어별 추출기

언어	Import 패턴	Call 추출
Go	`import "pkg"`, `import ("pkg")`	함수 호출, 메서드
JavaScript/TS	`import x from`, `require()`	메서드 체인
Python	`import x`, `from x import y`	함수/메서드 호출
Java/Kotlin	`import package.Class`	정적/인스턴스 메서드
C#	`using Namespace;`	정적/인스턴스 메서드
Ruby	`require`, `require_relative`	메서드 호출
PHP	`use Namespace\Class`	함수/메서드 호출
Rust	`use crate::module`	함수/메서드 호출
Swift	`import Module`	함수/메서드 호출
C++	`#include <header>`	함수/메서드 호출

Call 정규화

입력:  stripe.customers.subscriptions.create()
출력:  stripe.customers

입력:  authService.validateToken()
출력:  authService.validateToken

입력:  db.query()
출력:  db.query

근거: 2 세그먼트가 도메인 엔티티 관계 보존하면서 토큰 폭발 방지.

노이즈 필터링

범용 필터:

패턴	예시	이유
빈 문자열	`""`	신호 없음
선행 대괄호	`[item`	스프레드 배열 아티팩트
URL	`http://...`	테스트 픽스처
인라인 주석	`// comment`	파서 누출
짧은 식별자	`a`, `fn`, `x`	범용적, 도메인 신호 없음

언어별 필터:

언어	필터링 패턴
Go	`fmt`, `os`, `io`, `context`, `make`, `append`
Rust	`Ok`, `Err`, `Some`, `None`, `unwrap`
Java	`toString`, `equals`, `hashCode`, `getClass`
Kotlin	`listOf`, `mapOf`, `emptyList`, `setOf`
C#	`System.*`, `nameof`
JavaScript	`console.`, `JSON.`

검토한 옵션

Option A: 이중 필드 추출 (선택)

Import 문과 함수 호출만 추출, 공격적 필터링 적용.

측면	평가
신호 밀도	최고 - imports와 calls가 가장 강력한 지표
토큰 비용	전체 추출 대비 85% 절감
구현	12개 언어 추출기 + 공유 필터
트레이드오프	정규화로 인한 일부 컨텍스트 손실

Option B: 전체 AST 추출

모든 식별자, 변수, 문자열 리터럴, 주석 추출.

측면	평가
컨텍스트	최대 정보 캡처
토큰 비용	Option A 대비 6-7배 더 많은 토큰
신호 품질	노이즈로 인해 저하 (루프 변수, 제네릭)
기각 사유	Variables 필드 테스트에서 분류 개선 없음 확인

Option C: Regex 기반 패턴 매칭

정규식으로 import/require 문 추출.

측면	평가
단순성	Tree-sitter 의존성 없음
정확성	주석/문자열에서 오탐
유지보수	언어당 패턴당 정규식
기각 사유	통합 AST 아키텍처(ADR-03)와 상충

결과

긍정적

영역	이점
토큰 효율성	85% 절감으로 대규모 비용 효율적 AI 가능
분류 품질	높은 신호 대 노이즈 비율로 AI 정확도 향상
크로스 언어	12개 언어에 걸친 통합 패턴
통합	Tree-sitter 인프라와 깔끔한 인터페이스
진화	Variables 제거가 데이터 기반 반복 설계 입증

부정적

영역	트레이드오프
컨텍스트 손실	문자열 리터럴과 주석 미캡처
정규화	깊은 호출 체인의 구체성 손실
유지보수	12개 추출기가 문법 버전 업데이트 필요
Tree-sitter	경량 추출 폴백 없음

기술적 시사점

측면	시사점
API 표면	`DomainHints`는 공개 API; 변경 시 Worker에 영향
테스팅	언어별 추출 동작에 대한 골든 스냅샷 필요
성능	파일당 ~1-2ms; 병렬 컨텍스트에서 무시 가능
향후	AI 요구 시 추가 필드 추가 가능

Core ADR-16: 도메인 힌트 추출 시스템 ​

배경 ​

도메인 분류 문제 ​

요구사항 ​

제약사항 ​

결정 ​

핵심 설계 선택 ​

토큰 영향 ​

아키텍처 ​

언어별 추출기 ​

Call 정규화 ​

노이즈 필터링 ​

검토한 옵션 ​

Option A: 이중 필드 추출 (선택) ​

Option B: 전체 AST 추출 ​

Option C: Regex 기반 패턴 매칭 ​

결과 ​

긍정적 ​

부정적 ​

기술적 시사점 ​

참조 ​