# 헥사고날 아키텍처 (hexagonal-architecture)

> 포트와 어댑터 구조로 시스템을 설계·구현·리팩터링해 비즈니스 로직을 프레임워크, 전송, 영속성 세부사항에서 분리합니다.

- 카테고리: [아키텍처 설계](https://www.myskills.tools/ko/categories/architecture/)
- 출처: 커뮤니티 · Affaan Mustafa
- 저장소: https://github.com/affaan-m/ECC/tree/main/skills/hexagonal-architecture (commit d29cf65)
- SKILL.md: https://github.com/affaan-m/ECC/blob/main/skills/hexagonal-architecture/SKILL.md
- 설치 명령: `npx skills add affaan-m/ECC --skill hexagonal-architecture`
- 라이선스: MIT
- 호환 도구: Claude Code, Codex, Cursor, Copilot, OpenCode
- 권한: read-repo ✓, write-files ✓, shell ✗, network ✗
- 상태: 스캔 통과
- 규칙 스캔으로 모든 위험을 찾을 수는 없습니다. 설치 전에 이 스킬의 SKILL.md를 읽고 권한을 확인하세요.

## 핵심 규칙

의존 방향은 항상 안쪽이며, 도메인은 외부에 의존하지 않고 어댑터가 가장자리에서 포트를 구현합니다.

## 실행 단계

1. **유스케이스 경계** — 하나의 유스케이스에 명확한 입출력 DTO 를 정하고, req 나 GraphQL context 같은 전송 세부사항은 경계 밖에 둡니다.
2. **아웃바운드 포트 먼저** — 영속성, 외부 호출, 로깅, 시계 등 모든 부수 효과를 포트로 모델링하며, 포트는 기술이 아니라 능력을 나타냅니다.
3. **유스케이스 구현** — 유스케이스는 생성자나 인자로 포트를 받아 불변식 검증, 도메인 규칙 조정, 단순 데이터 반환만 담당합니다.
4. **어댑터와 조립** — 가장자리에 인바운드·아웃바운드 어댑터를 구현해 매핑을 그 안에 두고, 의존성 조립은 하나의 컴포지션 루트에 모읍니다.
5. **경계별 테스트** — 유스케이스는 가짜 포트로 단위 테스트하고 어댑터는 실제 인프라로 통합 테스트합니다. 기존 시스템은 한 번에 갈아엎지 않고 조각 단위로 옮깁니다.

## 권한 설명 (SKILL.md 기준)

| 기능 | 필요 여부 | 설명 |
|---|---|---|
| 파일 쓰기 | 필요 | 도메인, 유스케이스, 포트, 어댑터, 컴포지션 루트, 테스트 코드를 만들거나 리팩터링합니다. |
| 명령 실행 | 필요 없음 | 명령 실행을 요구하지 않습니다. |
| 네트워크 송신 | 필요 없음 | 네트워크에 접근하지 않습니다. |

## SKILL.md 프런트매터(YAML)

```yaml
---
name: hexagonal-architecture
description: Design, implement, and refactor Ports & Adapters systems with clear domain boundaries, dependency inversion, and testable use-case orchestration across TypeScript, Java, Kotlin, and Go services. Use when introducing or refactoring toward Ports and Adapters, or when domain logic has become entangled with I/O.
metadata:
  origin: ECC
---
```

홈: https://www.myskills.tools/ko/ · URL: https://www.myskills.tools/ko/skills/hexagonal-architecture/