Community코딩 & 개발github.com

헥사고날 아키텍처 마이그레이션 (To Hexagonal Architecture)

기존 코드베이스를 분석하여 헥사고날 아키텍처(포트와 어댑터)로의 단계적 리팩토링 계획을 수립합니다. 기존 계약을 유지하면서 서비스, API, 모놀리스를 리팩토링하거나 마이그레이션할 때 사용합니다.

헥사고날 아키텍처 마이그레이션 (To Hexagonal Architecture)란 무엇인가요?

이 스킬은 모든 언어나 프레임워크의 기존 코드베이스를 분석하여 **헥사고날 아키텍처(포트와 어댑터)**로의 안전하고 단계적인 마이그레이션 계획을 수립합니다. 주요 목표는 기존 외부 계약(HTTP 라우트, 페이로드 스키마, 오류 형식 등)을 전혀 변경하지 않으면서 비즈니스 로직을 웹 프레임워크, ORM, 데이터베이스, 메시지 브로커, 외부 SDK로부터 분리하는 것입니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트에서 사용할 수 있도록 설계되었으며, **계획 모드(Plan Mode)**로 작동합니다. 먼저 코드베이스를 탐색하여 스택, 진입점, 종속성을 파악한 후, 다섯 단계로 구성된 실행 계획(특성화 테스트 → 도메인 추출 → 애플리케이션 구현 → 어댑터 및 오류 변환 → 레거시 정리)을 제공합니다. 각 단계는 자동화된 검증 체크포인트를 포함하여 점진적인 안전성을 보장합니다. TypeScript, Python, Go, Java/Kotlin, C#, Rust 등 다양한 생태계에 맞게 디렉토리 구조, 명명 규칙, 테스트 방법을 조정합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gabrandalisse/skills/tree/HEAD/skills/to-hexagonal-architecture

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

헥사고날 아키텍처로 전환하기 (To Hexagonal Architecture)

기존 리포지토리를 심층 분석하여 **헥사고날 아키텍처(포트와 어댑터)**로의 원자적이고 단계적인 리팩토링 계획을 설계합니다. 외부 계약이나 관찰 가능한 동작을 전혀 변경하지 않습니다.

사용자 요청과 동일한 언어로 응답합니다. **계획 모드(Plan Mode)**로 엄격하게 작동합니다: 먼저 코드베이스를 검사하고, 파일을 수정하기 전에 완전한 계획을 전달합니다.

사용 시기

  • 사용자가 기존 프로젝트를 헥사고날 아키텍처 또는 포트와 어댑터로 마이그레이션하거나 리팩토링하도록 요청할 때
  • 사용자가 비즈니스 로직을 웹 프레임워크, ORM, 데이터베이스, 메시지 브로커, 외부 SDK로부터 분리하고자 할 때
  • 사용자가 기존 동작을 전혀 변경하지 않는 안전하고 점진적인 아키텍처 리팩토링 계획을 요청할 때

핵심 원칙

  1. 제로 브레이킹 체인지(황금 규칙): 모든 기존 외부 계약을 유지합니다. 라우트, HTTP 메서드, 상태 코드, 요청/응답 페이로드 스키마, 헤더, 오류 형식, CLI 플래그, 큐 메시지 형식이 동일해야 합니다.
  2. 리팩토링 전 특성화: 자동화된 계약/특성화 테스트가 기존 엔드포인트 또는 진입점을 커버할 때까지 프로덕션 로직을 이동하거나 삭제하지 않습니다.
  3. 엄격한 종속성 규칙: 소스 코드 종속성은 항상 내부의 domain을 향해야 합니다. 도메인 계층은 웹 프레임워크, 데이터베이스 드라이버, ORM, 직렬화 라이브러리, 외부 SDK에서 임포트가 없어야 합니다.
  4. 스택 관용적 적응: 디렉토리 경로, 명명 규칙, 타이핑 구조, 테스트 러너를 프로젝트의 감지된 언어와 생태계(예: TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust)에 맞게 조정합니다.

워크플로우

1단계: 코드베이스 탐색

폴더 트리 또는 마이그레이션 단계를 제안하기 전에 리포지토리를 스캔합니다:

  1. 스택 및 도구: 종속성 매니페스트, 컴파일러/린터 설정, 테스트 러너를 검사하여 언어, 프레임워크, 유효성 검사 라이브러리, ORM/쿼리 빌더, 의존성 주입 접근 방식을 식별합니다.
  2. 진입점 및 계약: 모든 구동 진입점(HTTP 라우트, GraphQL 리졸버, gRPC 서비스, 메시지 컨슈머, 크론 잡), 그 유효성 검사 스키마, 미들웨어/인터셉터, 전역 오류 핸들러를 인벤토리화합니다.
  3. 외부 종속성: 모든 구동 부작용(데이터베이스, 캐시, HTTP/RPC 클라이언트, 큐, 파일 저장소, 환경 설정, 로거)을 인벤토리화합니다.
  4. 현재 실행 흐름: 데이터가 진입점에서 지속성/외부 호출로 어떻게 흐르고 돌아오는지 추적하며, 비즈니스 규칙이 전송 또는 지속성 세부 사항과 혼합된 부분을 기록합니다.

2단계: 대상 헥사고날 레이아웃 설계

세 가지 동심원 레이어를 프로젝트의 관용적 소스 루트(예: TypeScript/Rust의 src/, Go의 internal/, JVM의 src/main/<lang>/, Python의 메인 패키지 디렉토리)에 매핑합니다:

  • domain/ (순수 비즈니스 코어 – 프레임워크나 I/O 종속성 없음):
    • entities/ 및 value-objects/: 비즈니스 규칙, 불변 조건, 자체 검증을 캡슐화하는 도메인 모델
    • ports/in/: 유스 케이스 계약을 정의하는 구동 포트 인터페이스
    • ports/out/: 리포지토리, 외부 서비스, 이벤트 퍼블리셔, LoggerPort 계약을 정의하는 구동 포트 인터페이스
    • errors/: 의미 있는 도메인 예외 (예: ResourceNotFoundError, DomainValidationError, ConflictError)
  • application/ (유스 케이스 오케스트레이션):
    • use-cases/: ports/in을 구현하며 도메인 엔티티와 ports/out을 조정
    • dtos/: 전송 페이로드 및 지속성 엔티티로부터 분리된 불변 입력/출력 데이터 구조
  • infrastructure/ (기술 세부 사항 및 어댑터):
    • adapters/in/: 구동 어댑터(HTTP 컨트롤러/핸들러, 컨슈머 핸들러), 전송 유효성 검사 스키마, 매퍼(TransportInput -> InputDTO, OutputDTO -> TransportOutput), domain/errors를 정확한 레거시 오류 응답으로 변환하는 전역 오류 매퍼
    • adapters/out/: ports/out의 구체적인 구현(데이터베이스 리포지토리, HTTP 클라이언트, 브로커) 및 지속성/외부 매퍼로 ORM 모델이나 SDK 유형이 domain으로 누출되지 않도록 함
    • config/: 환경 변수 및 런타임 설정의 엄격한 로딩 및 시작 유효성 검사
    • di/ (구성 루트): 생성자 주입을 통해 구동 어댑터, 유스 케이스, 구동 어댑터를 명시적으로 연결하며, 숨겨진 싱글톤이나 서비스 로케이터를 피함
  • 부트스트랩 분리: 애플리케이션 구성(buildApp / 격리된 통합 테스트를 위한 팩토리 함수)을 서버/프로세스 시작(main / listen)과 분리

3단계: 계획에 엔지니어링 표준 적용

계획의 각 단계에서 다음을 강제합니다:

  • 강력한 타이핑 및 불변성: 타입되지 않은 이스케이프(예: any, 타입 구조가 적용되어야 하는 곳에서 원시 타입되지 않은 맵)를 금지하고 불변 DTO 및 값 객체(readonly, 동결 데이터클래스, 레코드, 값 유형)를 선호합니다.
  • SOLID 및 생성자 주입: 클래스와 함수를 작고 단일 책임으로 유지하고, 생성자를 통해 인터페이스를 주입합니다.
  • 결합 없는 관찰 가능성: 구조화된 로깅과 요청 상관 관계 컨텍스트를 유지하면서도 domain/과 application/이 LoggerPort를 통해 특정 로깅 라이브러리로부터 분리되도록 합니다.
  • 피라미드 테스트:
    • domain/(순수 불변 조건) 및 application/(ports/out 모킹)을 위한 단위 테스트
    • 스택의 네이티브 인메모리 테스트 클라이언트(예: fastify.inject, SuperTest, FastAPI TestClient, Spring MockMvc, Go httptest)를 사용하여 실제 구동 어댑터를 애플리케이션 와이어링에 대해 검증하는 통합/계약 테스트

출력 형식 (계획 모드)

응답을 다음 정확한 섹션으로 구성하여 전달합니다:

  1. 현재 아키텍처 진단: 감지된 스택, 진입점/엔드포인트, 외부 종속성, 주요 결합 핫스팟의 간결한 인벤토리
  2. 대상 디렉토리 트리: 리포지토리에서 찾은 실제 모듈 및 기능 이름을 사용한 제안된 폴더 구조 전체
  3. 단계별 실행 계획: 5개의 원자적이고 검증 가능한 단계:
    • 1단계 – 특성화 테스트 및 기본 스캐폴딩: 현재 동작을 잠그는 계약 테스트 생성, 대상 폴더, 구성 로더, 구성 루트(di/) 생성
    • 2단계 – 도메인 추출: 엔티티, 값 객체, 도메인 오류, ports/in + ports/out 인터페이스를 단위 테스트와 함께 추출
    • 3단계 – 애플리케이션 유스 케이스 및 구동 어댑터: 유스 케이스, DTO, adapters/out 리포지토리/클라이언트, 지속성 매퍼 구현
    • 4단계 – 구동 어댑터 및 오류 변환: 컨트롤러/핸들러를 리팩토링하여 매퍼를 통해 유스 케이스에 위임하고, 전역 오류 변환을 연결하며, di/ 연결
    • 5단계 – 레거시 정리 및 최종 검증: 사용되지 않는 파일 제거, 전체 테스트 스위트, 린터, 타입 체커 실행, 제로 계약 이탈 확인
  4. 검증 체크포인트: 각 단계 종료 시 아무것도 깨지지 않았음을 증명하는 명시적 명령 또는 검사

주의사항

  • 코드를 조기에 편집하지 마세요: 사용자가 명시적으로 1단계를 즉시 실행하도록 요청하지 않는 한, 계획만 먼저 출력하여 모듈 경계를 검토할 수 있도록 합니다.
  • 단순 CRUD에 대한 과도한 추상화 피하기: 여전히 domain, application, infrastructure를 깔끔하게 분리하지만, 통과형 유스 케이스는 간결하게 유지하고 인위적인 도메인 복잡성을 만들지 않습니다.
  • 레거시 특이사항 일치: 기존 엔드포인트가 비표준 상태 코드나 오류 필드 이름을 반환하는 경우 1단계에서 문서화하고 infrastructure 오류 매퍼에서 유지하여 기존 클라이언트가 깨지지 않도록 합니다.

관련 스킬