AI-Driven Java Application
Development Methodology

UC 명세서 작성 스킬 (Section 3 `흐름` 컬럼)

도메인 설명을 Usecase 2.0 형식의 구조화된 명세서로 작성.
수준(--level)에 따라 Brief / Casual / Fully-dressed 산출.
핵심: Section 3 협력 인터페이스 테이블에 흐름 컬럼 신설 — 모든 인터페이스 호출을 main · alt:A{n} · exc:E{n} 중 하나로 태깅.
UC 명세는 spec-version 1.3 으로 작성한다.

SBE 시나리오 스킬

usecases/ 디렉토리의 UC 파일을 읽어 features/에 Gherkin .feature 파일로 변환.
domain-modeling과 병렬 실행 후 수렴 체크.

DDD 도메인 모델링 스킬 (Schema 3.3 + Flow-Complete + Step 3.1.5)

Step 1 BC 식별 → Step 2 Aggregate 설계 → Step 3 Command/Event 매핑 → Step 4 interfaces[] · error-values[] · service-methods[] 도출 (main / alt / exc 3종 흐름 전부) → Step 5 UL 사전 + 수렴 검증 (K1~K9).
--bc 옵션으로 특정 BC만 증분 갱신 가능. UC Section 3 협력 인터페이스를 흐름 컬럼과 함께 interfaces[].uc-mapping[{uc, step, flow}] 에 1:1 매핑.

아키텍처 설계 스킬 (YAML Schema 1.1 + id/monetary/temporal-strategy)

Step 1 모듈 구조 → Step 2 BC 간 통신 → Step 3 adapter-classes[] 자동 도출 → Step 4 공유 커널 위치.
Markdown → YAML 형식. domain-context.md의 interfaces[].name 패턴 매칭으로 어댑터 클래스 자동 생성. parameters 에 id-strategy/monetary-strategy/temporal-strategy 3개 블록 포함.

비기능 요구사항 명세 스킬 (YAML 병합)

성능·보안·가용성·운영성 4개 카테고리를 대화로 도출하고 arch-decisions.md의 nfr: YAML 블록으로 병합.
코드 생성 지시를 AUTO(자동 생성)와 TODO(태그 주석)로 분류.
NFR 신규 Err*(CircuitOpen·RetryExhausted·Timeout·AuthInvalid·Forbidden)을 domain-context.md error-values[]에 자동 제안.

DB 스키마 생성 스킬 (schema 1.1 — pk-id-spec/sequences)

domain-context.md의 aggregates[]와 arch-decisions.md의 persistence 파라미터를 읽어 DDL 및 ERD 생성.
schemas-decisions.md(schema 1.1)에 테이블 메타 YAML을 저장해 uc-to-skeleton/implement-bc가 참조.

스켈레톤 생성 스킬 (S1~S9 게이트 + VO 6종 케이스)

5개 계약 파일을 입력으로 클래스/패키지 스켈레톤과 PlantUML 시퀀스 다이어그램 생성.
NFR AUTO 항목 클래스 포함. 추론 없는 1:1 매핑.
v1.8 부터 alt-primary 메소드 · 비승격 alt 흐름의 if-else 분기 · 예외 흐름의 try-catch 보상 블록까지 자동 전개.
S7 게이트: Service 생성자 파라미터 순서 = flatten(uses-interfaces + alt-flows[] + compensation-flows[]) (중복 제거 1회).

BC 구현 스킬 (V1~V11 게이트)

UC Step 순서 → Service 본문 호출 순서 1:1 매핑.
compensation-flows[] 를 직접 소비하여 try-catch 본문을 결정론 구현하며, catch 타입은 trigger-error 의 exception-class 역참조로 결정.
중첩 보상 · 보상의 보상(manual queue) 패턴 자동 적용.

테스트 생성 스킬 (T0~T7 게이트)

반드시 별도 세션에서 실행 (T0 게이트).
Gherkin 성공(@UC-S) · 대안(@UC-A) · 예외(@UC-E) 전 Scenario ↔ @Test 1:1 변환.
@Mock 순서 = flatten(uses-interfaces 전 흐름).
InOrder.verify 로 호출 순서 검증.
ArgumentCaptor 로 main + alt + compensation 이벤트 필드 검증.
compensation-flows 트리거별 보상 호출 검증 @Test 자동 생성 (T7 신규).

72개 정합성 게이트 (★ v1.12) 통합 감사 스킬 (★ v1.10 — Architecture 산출물 분리 + N9 + 결정론적 명명 + ID·Money·Temporal)

v1.10 에서 72개 정합성 게이트 (★ v1.12)를 자동화 (★ N9 신규).
Phase 1 (C1~C10) + Phase 2 (K1~K9, S1~S9, N1~N6, D1~D6) + Phase 3 (V1~V7, T0~T7) 전체 재검증.
bash + grep + sed + Python(AST 기반 V7 만) 로 정적 검증 가능.
CI 통합 시 PR 단위 드리프트 감지.
--gates flow-completeness 옵션으로 흐름 완전성 9개만 집중 검증 가능.

Phase 1 매칭

domain-modeling v2.4

uc-to-skeleton v6.1

nfr-spec v2 / arch-design v2.1

gen-schema v2.1

implement-bc v3.2

✅ 드리프트 방지 효과

• LLM이 "InsufficientStockException" 대신 "OutOfStockException" 같은 유사어를 쓰는 사고를 원천 차단
• 명세 Err ID 하나가 바뀌면 모든 레이어가 깨지므로 즉시 발견
• UC를 수정하면 전체 파이프라인을 재실행해서 정합성 회복
• check-spec V1 / S4 / K6 / T2 게이트가 각 전환 지점을 정적 검증

🔧 실전 운영 팁

• Err ID 네이밍 컨벤션: Err{PascalCase명사} (예: ErrRoomNotFound)
• NFR에서 도입되는 인프라 Err*(CircuitOpen 등)도 동일 체인을 따름
• 보상 트랜잭션의 보상(BR-07)은 별도 Err ID 할당 (ErrPaymentCancelFailed 등)
• 국제화(i18n)가 필요하면 사용자 메시지만 별도 관리, Err ID는 유지

동기 ACL 패턴

즉각 응답이 필요한 BC 간 호출.
포트 인터페이스는 호출 BC의 application 레이어에 선언, 구현체는 구현 BC의 adapter 레이어에 위치. (Hexagonal 아키텍처 기준)
pom.xml에서 상호 직접 참조 없음.

// order/application/port/output/
public interface InventoryPort {
    void checkStock(ProductId id, int qty);
}

// inventory/adapter/outbound/
public class InventoryPortAdapter
    implements InventoryPort { ... }

비동기 Event 패턴

결과적 일관성으로 충분한 BC 간 통신.
Domain Event를 Kafka/RabbitMQ/Spring Events로 발행.
수신 BC는 ACL Translator로 자신의 도메인 모델로 변환.

// order → OrderPlaced → Kafka
// notification이 order.placed 구독

@KafkaListener(topics = "order.placed")
public void onOrderPlaced(
    OrderPlacedMessage msg) { ... }

UC 명세서 작성 커맨드

도메인 설명을 Usecase 2.0 형식으로 구조화.
전체 도메인을 분석하여 식별된 UC를 usecases/ 디렉토리에 UC별 개별 파일로 분할 저장.
기본 흐름·대안 흐름·예외 흐름·비기능 요구사항 포함.
/usecase-by-example의 필수 선행 커맨드.

/usecase "주문 관리 시스템"            # 기본값: casual → usecases/ 분할 저장
/usecase "주문 관리" --level casual
/usecase "주문 관리" --level fully-dressed

Gherkin 시나리오 변환 커맨드

usecases/ 디렉토리를 읽어 features/에 .feature 파일 생성.
파일 지정 시 해당 UC만 변환, 생략 시 디렉토리 전체 순회.
usecases/ 디렉토리가 없으면 /usecase 실행을 안내하고 중단.

/usecase-by-example                         # usecases/ 전체 순회
/usecase-by-example usecases/UC001-주문생성.md  # 특정 UC만 변환

DDD 도메인 모델링 커맨드

usecases/*.md (v1.3) + features/*.feature를 읽어 domain-context.md (schema 3.3) 생성.
BC 식별 → Aggregate → Command/Event → interfaces[] · service-methods[] 전 흐름(main/alt/exc) 도출.
6가지 실행 모드 — UC 규모별 진입 경로 분기.

/domain-modeling                          # 모드 1 — 전체 UC 분석 (UC < 20)
/domain-modeling --bc order               # 모드 2 — Order BC 만 증분 갱신
/domain-modeling --bc order --uc UC001,UC005  # 모드 2 — 특정 UC 만 반영
/domain-modeling --bc new                 # 모드 3 — 미할당 UC → 신규 BC 제안
/domain-modeling --split-waves            # 모드 4 — 사후 Wave 분할 (3.3 → 3.4)

# ★ v1.8.1 신규 — 대규모 시스템 진입 경로
/domain-modeling --discover-only          # 모드 5 — Phase 2.0 BC Discovery
                                          #   UC 본문 미독해 → bc-plan.md 초안 (비용 ~10~15%)
/domain-modeling --init-waves             # 모드 6 — 선제 Wave 모드
                                          #   bc-plan.md 부터 schema 3.4 직접 생성
/domain-modeling --init-waves --wave 1 --bc Order
                                          # Wave 별 분할 호출 (세션 분산)

아키텍처 설계 커맨드

domain-context.md를 읽어 arch-decisions.md (schema 1.1 YAML) 생성.
interfaces[].name 패턴 매칭으로 adapter-classes[] 자동 도출.
architecture · persistence 파라미터가 하위 스킬 동작 전체를 결정.

/arch-design                        # 아키텍처 설계 전체 실행
/arch-design --check                # 기존 파일 정합성 검증만

비기능 요구사항 명세 커맨드

성능 · 보안 · 가용성 · 운영성 4개 카테고리를 도출하여 arch-decisions.md의 nfr: YAML 블록으로 병합.
NFR 신규 Err*(CircuitOpen · RetryExhausted · Timeout)를 domain-context.md error-values[]에 자동 제안.

/nfr-spec               # 대화식 도출 후 arch-decisions.md 병합
/nfr-spec --merge       # 기존 NFR을 arch-decisions.md에 병합만

Java 스켈레톤 생성 커맨드

5개 계약 파일을 읽어 클래스/패키지 스켈레톤 + PlantUML 시퀀스 다이어그램(docs/diagrams/) 생성.
v1.8 부터 alt-primary 메소드 · 비승격 alt if-else 분기 · exc try-catch 보상 블록까지 자동 전개.
S7 게이트: 생성자 파라미터 순서 = flatten(uses-interfaces + alt-flows[] + compensation-flows[]).

/uc-to-skeleton              # 전체 BC 스켈레톤 생성
/uc-to-skeleton --bc order   # 특정 BC만
/uc-to-skeleton --dry-run    # 생성 계획만 출력

DB 스키마 생성 커맨드

arch-decisions.md ## Persistence 섹션을 읽어 Mermaid ERD(erd.mmd)와 DDL SQL(schema.sql)을 자동 생성합니다.
domain-context.md의 Aggregate → 테이블 매핑 규칙을 적용합니다.
persistence=jpa+jdbc 시 Command 테이블에 [Command Side] JPA @Entity, Query Row에 [Query Side] JdbcTemplate Row 주석을 삽입합니다 — codegen 없음.
persistence=jpa+jooq 시 schema.sql을 jOOQ codegen 입력으로 사용하여 Query Side Java 클래스를 빌드 타임에 생성합니다.

/gen-schema                   # 전체 BC ERD + DDL 생성
/gen-schema --bc order        # 특정 BC만 생성
/gen-schema --update          # 변경 내용만 반영 (MAJOR/MINOR)
/gen-schema --format flyway   # Flyway V1__init.sql 형식
/gen-schema --format liquibase # Liquibase XML 형식
/gen-schema --dry-run         # 생성 계획만 출력

Aggregate → JpaEntity 매핑 규칙

BC 구현 커맨드

bc-plan.md + domain-context.md + arch-decisions.md를 읽어 Wave 순서대로 구현.
arch-decisions.md의 architecture 값(hexagonal|layered)에 따라 레이어 구조가 결정됨.
파일 없으면 즉시 중단.

/implement-bc order          # 전체
/implement-bc order domain   # 레이어 지정 
                              (hexagonal: domain|application|adapter)
/implement-bc --wave 2       # Wave 일괄
/implement-bc --dry-run      # 실행 계획만
/implement-bc --check-plan   # 순환 의존 검사

테스트 생성 커맨드

Gherkin 시나리오 1:1 추적.
.feature 없으면 domain-context.md 에러 케이스 컬럼에서 도출.
arch-decisions.md의 messaging 파라미터를 읽어 계약 테스트 도구를 자동 선택.

/gen-test order              # 전체
/gen-test order application  # 레이어 지정
/gen-test order --contract   # BC 간 계약 테스트 
                                  (동기→SCC, 비동기→Pact 자동 분기)
/gen-test order --pbt        # Property-Based Testing 
                                  (Jqwik, domain 레이어만)
/gen-test --e2e              # E2E 통합 시나리오
/gen-test --wave 2           # Wave 일괄

명세 ↔ 코드 드리프트 검증

domain-context.md YAML ↔ 실제 코드를 정적 대조.
정방향(구현 누락) + 역방향(미등록 항목) 양방향 스캔.
Service 메서드 레벨까지 검증. 산출물 변경 없이 리포트만 출력.

/check-spec                    # 전체 BC 대조
/check-spec --bc order         # 특정 BC만
/check-spec --section commands # Command ↔ Service만
/check-spec --verbose          # 파일:라인 포함

버전 동기화 확인

domain-context.md consumers 섹션과 content-version 비교.
재생성 필요 소비자 목록과 최소 실행 순서 출력.

로컬 실행 커맨드

arch-decisions.md를 읽어 필요한 인프라를 Docker Compose로 기동하고 Spring Boot를 시작한다.
persistence/messaging 파라미터에 따라 compose 파일을 자동 구성한다.

/run-local                  # 전체 기동 (인프라 + 앱)
/run-local --infra-only     # Docker Compose만 기동
/run-local --bc order       # 특정 BC 모듈만 기동
/run-local --profile local  # 프로파일 명시 (기본값)

실행 상태 검증 커맨드

기동된 애플리케이션의 Run Gate 조건을 순서대로 확인한다.
실패 항목과 수정 방향을 함께 출력한다.

/run-check                  # 전체 Gate 확인
/run-check --verbose        # 상세 응답 포함 출력

모듈 마이그레이션 커맨드

현재 아키텍처 구조를 진화시키는 3-Gate 커맨드.
분석 리포트 → 개발자 승인 → 실행 순으로 진행하며 arch-decisions.md 업데이트와 migration-log.md 생성을 자동 처리한다.

/migrate-module single-to-multi           # single → Maven 멀티모듈
/migrate-module split-bc {bc} {bc1} {bc2} # BC 분리
/migrate-module --dry-run single-to-multi  # 분석 리포트만
/migrate-module --status                   # 진행 상태 확인

지원 시나리오 및 산출물

대규모 시스템 및 레거시 DB 대응

ERP급 도메인이 많은 시스템 개발 전략과 레거시 DB 리버스 엔지니어링 방법론.
Part I: 1 프로젝트 = 1~소수 BC 원칙, Wave 위상 정렬, BC 간 통신 패턴, 세션 운영.
Part II: 레거시 DB A/B/C/D 진단 프레임, legacy-db-context.md 계약 파일, 유형별 Strangler 전략.

Subagent & Agent Teams 통합 전략

Claude Code의 subagent 기능으로 세션 분리를 자동화하면서 계약 파일 철학과 순환논리 방지 원칙을 유지하는 전략.
bc-implementer · ddd-modeler · spec-checker 에이전트 템플릿 제공.
Phase 4 고급 패턴으로 Agent Teams(Wave 병렬, DDD 수렴, Competing Hypotheses) 도입 시나리오 분석.