Communitygithub.com

xfoundries/software-architecture-skills

소스 인지형 아키텍처 가이드로, 도메인 주도 설계, 계층형 아키텍처, 양파 아키텍처, 헥사고날 아키텍처(포트와 어댑터), CQRS를 사용하여 비즈니스 도메인 시스템을 구축합니다.

software-architecture-skills란 무엇인가요?

이 스킬은 JFoundry 프레임워크를 기반으로 한 비즈니스 애플리케이션 구축 시, 프레임워크가 의도한 아키텍처를 유지하도록 돕습니다. 주로 Java 21, Maven, 헥사고날 아키텍처를 기본값으로 하며, 사용자의 명시적 선택이 있을 때만 스프링 부트 또는 양파 아키텍처를 사용합니다. 이 스킬은 프로젝트 구조, 아키텍처 스타일 선택부터 의존성 관리, 아키텍처 테스트 템플릿 적용까지 단계별 워크플로우를 제공합니다. 또한 도메인 코드의 순수성 유지, 포트와 어댑터 패턴 적용, 아웃박스/인박스 패턴을 통한 안정적인 이벤트 발행 및 메시지 소비 등 실무에서 중요한 아키텍처 규칙을 제시하여, 개발자가 비즈니스 도메인에 집중하면서도 프레임워크와의 결합도를 낮출 수 있도록 지원합니다. Claude Code, Cursor, Codex와 같은 AI 도구에서 활용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add xfoundries/software-architecture-skills

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

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

문서

JFoundry 사용하기

목적

이 스킬은 JFoundry에서 비즈니스 애플리케이션을 구축할 때 프레임워크가 의도한 아키텍처를 벗어나지 않도록 사용합니다. 이 스킬은 애플리케이션 프로젝트를 위한 것이며, JFoundry 프레임워크 내부를 변경하기 위한 것이 아닙니다.

사용자가 명시적으로 Onion을 선택하지 않는 한 새로운 Java 21 Maven 프로젝트는 헥사고날 아키텍처(Hexagonal Architecture)를 기본값으로 사용합니다. 런타임 프레임워크를 Spring Boot로 기본 설정하지 마십시오; 사용자가 Spring Framework, Spring Boot 또는 Spring 관련 스타터를 선택한 경우에만 Spring을 선택하십시오. 번들 템플릿을 먼저 복사한 후 이름과 패키지를 조정하는 것을 선호합니다.

첫 사용 워크플로우

  1. 프로젝트 형태를 확인합니다: 단일 애플리케이션 모듈, 멀티 모듈 Maven 앱, 또는 분리된 도메인/애플리케이션/인프라 모듈. 일반 DDD 프로젝트에는 멀티 모듈 Maven을 선호합니다.
  2. 하나의 기본 아키텍처 스타일을 선택합니다. 새로운 비즈니스 프로젝트에는 헥사고날을 선호하고, 사용자가 요청하거나 코드베이스가 이미 사용 중인 경우에만 Onion을 선택합니다. 동일한 ArchUnit 분석 범위 내에서 헥사고날과 Onion을 혼합하지 마십시오.
  3. references/dependencies.md를 읽고 런타임별 BOM을 선택한 후 assets/templates/maven/에서 일치하는 Maven 템플릿 스니펫을 복사합니다.
  4. references/architecture.md를 읽고 assets/templates/structure/에서 일치하는 패키지 구조를 복사합니다.
  5. assets/templates/java/에서 하나의 아키텍처 테스트 템플릿을 복사하고 PACKAGE_NAME을 대체한 후 비즈니스 프로젝트의 테스트 소스 세트에 추가합니다.
  6. 애그리게이트 리포지토리, 읽기 측 포트, 쿼리 포트, 조회 포트, 읽기 모델 또는 유지보수 포트를 만들기 전에 references/repository-and-ports.md를 읽습니다.
  7. AggregateData, DataConverter, MyBatis-Plus 데이터 객체 또는 MapStruct 컨버터를 구현하기 전에 references/persistence-data-converters.md를 읽습니다.
  8. 프로젝트에 안정적인 외부 이벤트 발행 또는 멱등성 메시지 소비가 필요한 경우에만 references/outbox-inbox.md를 읽습니다.
  9. 가장 작은 관련 Maven 검증 명령(보통 mvn test) 또는 모듈 범위의 mvn -pl <module> test를 실행합니다.

핵심 규칙

  • 도메인 코드에 Spring, MyBatis, 영속성 모델, 메시지 브로커 클라이언트, 프레임워크 수명 주기 API를 포함시키지 마십시오.
  • 규칙과 불변 조건이 의미 있는 경우 도메인에서 비즈니스 동작을 모델링하고, 복잡도가 낮은 영역에서는 단순한 CRUD 또는 트랜잭션 스크립트를 사용하십시오.
  • 중요한 도메인 동작의 경우 코딩 전에 애그리게이트, 명령, 불변 조건, 이벤트, 리포지토리 및 읽기 측 포트 가정을 확인하고, 열린 도메인 질문을 숨기지 마십시오.
  • Spring Boot 스타터는 부트/런타임 어셈블리 모듈에만 배치하고, 도메인 또는 애플리케이션 모듈에는 절대 배치하지 마십시오.
  • 유스 케이스 오케스트레이션과 트랜잭션 중심 워크플로우는 애플리케이션 계층에 배치하십시오.
  • 외부 요구사항을 2차 포트(secondary ports)로 표현하십시오. MyBatis, JPA, Redis, HTTP 클라이언트, MQ 클라이언트 및 기타 기술 세부 사항은 인프라 어댑터에 배치하십시오.
  • JFoundry 헥사고날 또는 Onion 프로젝트에서 컨트롤러, 메시지 리스너, CLI 명령, 스케줄러와 같은 1차 어댑터는 2차 어댑터가 아닌 1차 포트 또는 애플리케이션 서비스를 호출해야 합니다.
  • 애그리게이트 수명 주기와 명령 측 애그리게이트 로딩에는 애그리게이트 리포지토리를 사용하십시오. 비 애그리게이트 읽기의 경우 읽기 측 포트를 선호하고, 프로젝트에 도움이 될 때만 조회/읽기 모델/유지보수 역할로 분할하십시오.
  • 영속성 데이터 컨버터를 인프라 로컬로 유지하십시오. INSTANCE가 있는 MapStruct @Mapper 인터페이스를 선호하고, toEntity(...)를 명시적으로 작성하며 애그리게이트 restore(...)를 호출하십시오.
  • 아웃박스는 외부 프로세스나 브로커에 안정적으로 발행할 때만 활성화하십시오. 이벤트가 프로세스 내에 머무를 때는 로컬 도메인 이벤트 디스패치를 사용하십시오.
  • 인박스는 소비자가 중복 전달을 안전하게 처리해야 할 때만 활성화하십시오.
  • ArchUnit 테스트는 초기에 추가하십시오. 이는 프로젝트 스켈레톤의 일부이며, 늦은 정리 작업이 아닙니다.

번들 템플릿

템플릿을 기억에서 다시 작성하지 말고 복사하십시오:

  • assets/templates/java/HexagonalArchitectureTest.java
  • assets/templates/java/OnionSimpleArchitectureTest.java
  • assets/templates/maven/dependency-management-core.xml
  • assets/templates/maven/dependency-management-spring.xml
  • assets/templates/maven/domain-module-dependencies.xml
  • assets/templates/maven/application-module-dependencies.xml
  • assets/templates/maven/infrastructure-mybatis-plus-dependencies.xml
  • assets/templates/maven/architecture-test-dependencies.xml
  • assets/templates/maven/spring-boot-app-dependencies.xml
  • assets/templates/maven/spring-boot-mybatis-plus-dependencies.xml
  • assets/templates/maven/outbox-dependencies.xml
  • assets/templates/maven/outbox-mybatis-plus-dependencies.xml
  • assets/templates/maven/inbox-dependencies.xml
  • assets/templates/maven/inbox-mybatis-plus-dependencies.xml
  • assets/templates/maven/broker-dependencies.xml
  • assets/templates/structure/hexagonal-package-structure.txt
  • assets/templates/structure/onion-simple-package-structure.txt

PACKAGE_NAME 및 JFOUNDRY_VERSION과 같은 플레이스홀더를 대체하십시오. 선택적 스니펫은 선택 사항으로 유지하십시오. 유스 케이스에 필요하지 않으면 Outbox, Inbox, MyBatis-Plus 또는 브로커 스타터를 추가하지 마십시오.

참조 라우팅

  • references/first-use.md는 사용자가 새 프로젝트를 시작하거나 이 스킬을 호출하는 방법을 물을 때 읽습니다.
  • references/architecture.md는 패키지 역할, 어노테이션, 의존성 방향 및 아키텍처 스타일 선택을 위해 읽습니다.
  • references/dependencies.md는 스타터 선택 및 Maven 스니펫을 위해 읽습니다.
  • references/repository-and-ports.md는 영속성, 애그리게이트 리포지토리, 읽기 모델 또는 쿼리 포트를 모델링하기 전에 읽습니다.
  • references/persistence-data-converters.md는 DataConverter 구현, 영속성 데이터 객체 또는 MapStruct 매핑 규칙을 작성하기 전에 읽습니다.
  • references/outbox-inbox.md는 이벤트 외부화, 브로커 어댑터, Outbox 테이블, 디스패처 또는 소비자 멱등성을 추가하기 전에 읽습니다.
  • references/testing.md는 아키텍처 테스트를 추가하거나 변경하기 전에 읽습니다.

일반적인 첫 프롬프트

새 프로젝트를 안내할 때는 기본 패키지, 프로젝트/모듈 형태, 런타임 스택, 영속성 선택 및 외부 메시징 필요 여부를 먼저 질문하십시오. 사용자가 선호하는 것이 없으면 다음을 진행하십시오:

  • Java 21
  • Maven
  • 아직 결정되지 않은 런타임 프레임워크
  • 헥사고날 아키텍처
  • jfoundry-dependencies BOM
  • jfoundry-domain-starter
  • jfoundry-application-starter
  • JFoundryRules.hexagonalStrict() 및 JFoundryRules.jmoleculesDdd()

새 비즈니스 프로젝트를 위한 제안 사용자 프롬프트:

Use $use-jfoundry to create the initial architecture for a new Java 21 business project.
Base package: com.example.order
Project shape: multi-module Maven
Runtime: undecided
Persistence: MyBatis-Plus
Messaging: Kafka later, not in the initial skeleton
Architecture: default unless you need to choose

세부 정보가 누락된 경우 간결한 질문을 하나 하거나 위의 기본값을 선택해도 위험이 낮을 때 해당 기본값을 진행하십시오.

관련 스킬