2-file rule 적용으로 SDK 업데이트 영향 범위를 31개 파일에서 2개로 축소

Stop scattering LLM SDK/API calls across your codebase. Here is the 2-file rule that fixed mine

Babak Abbaschian2026년 5월 23일7분intermediate

AI 요약

Context

비즈니스 로직 전반에 LLM SDK 호출이 산재하여 SDK 버전 업데이트 시 수십 개의 파일에서 런타임 오류가 발생하는 의존성 오염 발생. 모델 변경 시마다 임포트 경로와 타입 시그니처를 수동으로 수정해야 하는 아키텍처적 병목 지점 노출.

Technical Solution

Hexagonal Architecture 기반의 Ports and Adapters 패턴을 도입하여 LLM SDK 의존성을 특정 두 파일(Adapter, Provider Registry)로 완전히 격리
SDK-agnostic한 TypeScript Interface를 정의하여 애플리케이션 계층이 구체적인 Provider나 SDK 타입을 인지하지 못하도록 설계
반복되는 LLM 호출 패턴을 7가지 핵심 Cognitive Operations로 정의하고 이를 Capability Factory로 추상화하여 프롬프트 관리 효율성 증대
구성 정보(Config)에 기반한 정책 결정 구조를 통해 비즈니스 로직 수정 없이 모델 교체 및 라우팅이 가능한 구조 구현
Zod를 활용한 Schema 정의를 Capability Factory에 결합하여 LLM 응답의 타입 안정성 및 Validation Recovery 확보

실천 포인트

- LLM SDK 임포트가 비즈니스 로직 파일에 직접 포함되어 있는지 확인 - 반복되는 프롬프트 패턴을 분석하여 공통 Capability로 추출 가능한지 검토 - 모델 변경 시 코드 수정 없이 설정 파일(Config)만으로 제어 가능한 구조인지 평가 - LLM 응답값에 대해 Zod 등 타입 검증 라이브러리를 통한 강한 타입 가드 적용 여부 확인

태그

#Capability Factory #Dependency Inversion #Type Safety #Hexagonal Architecture #Ports-and-adapters

원문 읽기