A-ADM Core 방법론의 Claude Code + Java 21 구현 어댑터.
Spring Boot 3.x · 헥사고날 아키텍처 · 14개 슬래시 커맨드로 SDLC 전 단계를 자동화.
A-JADM은 A-ADM Core의 Claude Code 구현 어댑터입니다.
Java 21 + Spring Boot + 아키텍처 (헥사고널 | 레이어드) 스택으로,
SKILL.md 9개 정규 + 1개 위성과 슬래시 커맨드 14개로 SDLC 전 단계를 자동화합니다.
이 문서는 A-ADM Core의 Claude Code + Java 21 구현 어댑터입니다.
설계 원칙 · 계약 파일 스키마 · 추적성 규칙 · Wave 토폴로지 등 방법론 본질은 Core 문서를 참조하세요.
A-JADM은 백엔드 파이프라인을 담당하고, A-FADM은 프론트엔드(React/TypeScript) 파이프라인을 담당합니다.
두 방법론의 연결 지점은 /gen-openapi 커맨드가 생성하는 openapi.yaml입니다.
[ A-JADM — 백엔드 파이프라인 ]
/usecase → /domain-modeling → /arch-design → /implement-bc → /gen-test → /run-local
│
/gen-openapi → openapi.yaml ← 연결 지점
│
[ A-FADM — 프론트엔드 파이프라인 시작 ]
openapi.yaml → /fe-spec → /fe-scaffold → /fe-implement → /fe-test
openapi.yaml 초안을 기반으로 프론트엔드 파이프라인을 병렬로 진행할 수 있습니다.
A-ADM의 핵심 패러다임 전환과 계약 파일이 필요한 이유는 A-ADM Core 문서에 상세히 설명되어 있습니다.
이 섹션에서는 Claude Code 환경에서의 실제 적용 포인트를 정리합니다.
각 스킬은 SKILL.md 파일 하나로 완결됩니다.
Claude Code가 파일을 읽고 실행 — 세션마다 프롬프트 재작성 불필요.
domain-context.md가 없으면 스킬이 즉시 중단합니다.
계약 없는 추론 실행은 허용되지 않습니다.
CLAUDE.md에 정의된 14개 커맨드로 SDLC 전 단계를 한 줄로 실행.
BC 단위 점진적 구현이 기본 전략입니다.
5대 원칙의 전체 정의는 A-ADM Core → 설계 원칙을 참조하세요.
Claude Code 어댑터 관점에서의 적용 방식을 정리합니다.
company, domain, base-package, java-version만 바꾸면 새 프로젝트에 즉시 적용됩니다.
gen-test 스킬이 시나리오 ID 주석과 1:1 @Test를 자동 생성합니다.
arch-decisions.md 없이 /implement-bc를 실행하면 즉시 에러. 추론 모드 폴백 없음.
usecase-by-example ∥ domain-modeling 수렴 후 bc-plan.md Wave 순서로 구현.
요구사항 분석부터 실행까지, 각 단계는 명확한 입력·산출물·게이트를 가집니다.
gen-class-diagram(v1, v1.6.1 신규)을 제공합니다. domain-context.md → PlantUML 클래스 다이어그램 3종(docs/class-diagrams/) 생성. | --level | 분량 | 용도 |
|---|---|---|
| brief | 2~5줄 | 파이프라인 사용 금지 |
| casual | ~1페이지 | 기본값 — 내부 팀용 |
| fully-dressed | 3~5페이지 | 외부 이해관계자·복잡 예외 |
usecases/ 디렉토리에 분할 저장. usecases/ 디렉토리의 UC 파일을 읽어 features/ 디렉토리에 .feature 파일로 변환한다. usecases/ 디렉토리가 없으면 중단하고 /usecase 실행을 안내한다.| UC 명세서 항목 | Gherkin 변환 |
|---|---|
| 사전조건 | Given |
| 기본 흐름 행위 (액터) | When |
| 기본 흐름 응답 (시스템) | Then |
| 대안 흐름 | Scenario 추가 |
| 예외 흐름 | 에러 케이스 Scenario |
usecases/UC001-주문생성.md → features/UC001-주문생성.feature 1:1 대응/gen-test --pbt
@Property — 불변식 위반 경계값 자동 탐색@ForAll @Positive — 수치 범위 제약 자동 적용Arbitrary<T> — 복합 도메인 객체 생성기/gen-test --contract
arch-decisions.md의 messaging 파라미터를 읽어 도구를 자동 선택.--profile local 자동 적용.local — Docker Compose 인프라, 디버그 로그. test — Testcontainers 자동 기동, 격리 DB. prod — 외부 인프라 연결, 최소 로그.| 프로파일 | DB | Kafka | 기동 방법 |
|---|---|---|---|
| local | Docker | Docker | docker compose up |
| test | TC | TC | mvn verify 시 자동 |
| prod | 외부 | 외부 | 환경 변수 주입 |
GET /actuator/health → 200 OKservices:
postgres:
image: postgres:16-alpine
ports: ["5432:5432"]
environment:
POSTGRES_DB: appdb
services:
kafka:
image: bitnami/kafka:3.7
ports: ["9092:9092"]
environment:
KAFKA_CFG_NODE_ID: 0
spring:
profiles:
active: local
datasource:
url: jdbc:postgresql://
localhost:5432/appdb
/gen-schema 산출물(schema.sql)을 jOOQ codegen이 읽어 Java 클래스 자동 생성.pom.xml에 jOOQ codegen 플러그인 추가 필요 (arch-decisions.md 기반 자동 구성).
각 스킬은 프로젝트 루트의 .claude/skills/ 디렉토리에 SKILL.md 파일로 저장됩니다.
슬래시 커맨드 실행 시 Claude Code가 해당 파일을 읽고 계약 파일을 참조하여 산출물을 생성합니다.
세션 간 상태 유지는 계약 파일이 담당하므로 스킬 자체는 무상태(stateless)입니다.
각 스킬은 독립적인 SKILL.md 오케스트레이터 + 참조 파일로 구성됩니다.
Phase 1은 순차 파이프라인, Phase 2 이후는 계약 파일로만 소통합니다.
check-spec은 파이프라인 외부에서 수시로 독립 실행하는 진단 스킬이며,
gen-class-diagram은 Phase 2 모델링 검토 보조 위성 스킬입니다.
domain-modeling v2.1 직후 (선택적) gen-class-diagram → docs/class-diagrams/*.puml. 55 게이트 무관, 빠져도 정상 동작.
흐름 컬럼 · domain-modeling(v2.1) alt-flows[]/compensation-flows[]/flow-type/promoted-from 필드 신설. compensation-flows[] 를 직접 소비하여 try-catch 본문을 결정론 구현 (catch 타입 = trigger-error 의 exception-class 역참조). nfr: YAML 블록으로 병합. gen-schema 는 schemas-decisions.md 계약 파일 생성. 49개 게이트 자동화.도메인 설명을 Usecase 2.0 형식의 구조화된 명세서로 작성.
수준(--level)에 따라 Brief / Casual / Fully-dressed 산출.
v1.7 핵심: Section 3 협력 인터페이스 테이블에 흐름 컬럼 신설 — 모든 인터페이스 호출을 main · alt:A{n} · exc:E{n} 중 하나로 태깅.
/usecase --migrate-to 1.3 으로 v1.2 UC 자동 마이그레이션.
brief는 파이프라인 사용 금지 — Gherkin 변환에 정보 부족--level casual
usecases/ 디렉토리의 UC 파일을 읽어 features/에 Gherkin .feature 파일로 변환.
domain-modeling과 병렬 실행 후 수렴 체크.
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 매핑.
interfaces[].uc-mapping[] 이 {uc, step, flow} 객체 배열로 확장 (v3.1 필수)service-methods[].flow-type — main | alt-primaryservice-methods[].alt-flows[] — 비승격 alt (entry-condition + uses-interfaces, if-else 분기)service-methods[].compensation-flows[] — exc 보상 (trigger-error + uses-interfaces + raises-events, try-catch)service-methods[].promoted-from — alt-primary 승격 추적 (uc / alt-flow / promotion-criteria)
transaction-boundary-independent · authorization-boundary-independent · time-boundary-independent · api-entry-independent
(옵션 없음): 전체 분석 — usecases/ 전체 순회--bc {name}: 해당 BC만 증분 갱신 — source-uc로 관련 UC 자동 식별--bc {name} --uc UC005,UC024: 명시한 UC만 해당 BC에 반영--bc new: 미할당 UC 분석 → 신규 BC 후보 제안
Step 1 모듈 구조 → Step 2 BC 간 통신 → Step 3 adapter-classes[] 자동 도출 → Step 4 공유 커널 위치.
v1.6부터 Markdown → YAML 전환. domain-context.md의 interfaces[].name 패턴 매칭으로 어댑터 클래스 자동 생성.
architecture: hexagonal | layered — 레이어 구조 결정module: single | multi — Maven 모듈 분리 여부persistence: jpa | jpa+jdbc | jpa+jooq | jdbcexception-style: unchecked | checked — Exception 템플릿 선택 (v1.6 신규)
성능·보안·가용성·운영성 4개 카테고리를 대화로 도출하고 arch-decisions.md의 nfr: YAML 블록으로 병합.
코드 생성 지시를 AUTO(자동 생성)와 TODO(태그 주석)로 분류.
NFR 신규 Err*(CircuitOpen·RetryExhausted·Timeout·AuthInvalid·Forbidden)을 domain-context.md error-values[]에 자동 제안.
nfr: 블록 + content-version MINOR 증가domain-context.md의 aggregates[]와 arch-decisions.md의 persistence 파라미터를 읽어 DDL 및 ERD 생성.
schemas-decisions.md(schema 1.0)에 테이블 메타 YAML을 저장해 uc-to-skeleton/implement-bc가 참조.
REFERENCES 금지 (UUID-only, 런타임 ACL)cross-bc-ref 메타로 추적성만 확보
4개 계약 파일을 입력으로 클래스/패키지 스켈레톤과 PlantUML 시퀀스 다이어그램 생성.
NFR AUTO 항목 클래스 포함. 추론 없는 1:1 매핑.
v1.7 부터 alt-primary 메소드 · 비승격 alt 흐름의 if-else 분기 · 예외 흐름의 try-catch 보상 블록까지 자동 전개.
S7 게이트: Service 생성자 파라미터 순서 = flatten(uses-interfaces + alt-flows[] + compensation-flows[]) (중복 제거 1회).
UC Step 순서 → Service 본문 호출 순서 1:1 매핑.
v1.7 부터 compensation-flows[] 를 직접 소비하여 try-catch 본문을 결정론 구현하며, catch 타입은 trigger-error 의 exception-class 역참조로 결정.
중첩 보상 · 보상의 보상(manual queue) 패턴 자동 적용.
반드시 별도 세션에서 실행 (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 신규).
v1.7에서 55개 정합성 게이트를 자동화.
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개만 집중 검증 가능.
C UC↔Gherkin (8 → 10 +C9/C10) K modeling (8 → 9 +K9) S skeleton (8 → 9 +S9) N nfr (6) D schema (6) V implement (6 → 7 +V7) T test (7 → 8 +T7)
Phase 2 모델링 산출물 검토를 보조하는 위성 스킬.
domain-context.md (schema 3.0/3.1) 단일 입력으로 PlantUML 클래스 다이어그램 3종을 결정론적으로 생성.
/domain-modeling 직후 즉시 실행 가능, arch-decisions.md · 코드 산출물 의존 0.
class-overview.puml — BC × Aggregate Root 조감도 + cross-bc 점선class-bc-{name}.puml (N개) — BC별 상세 (Aggregate · Entity · VO · Command · Event + invariants)class-interfaces.puml — Hexagonal Port 의존도 + «uses» [n] 순서 보존docs/
├── class-diagrams/ ← gen-class-diagram
│ ├── class-overview.puml
│ ├── class-bc-{name}.puml
│ └── class-interfaces.puml
└── diagrams/ ← uc-to-skeleton
└── UC{nnn}-skeleton.puml
| 항목 | 정규 스킬 | 위성 (본 스킬) |
|---|---|---|
| 계약 파일 산출 | 신규 계약 생성 | ❌ .puml만 |
| consumers 등록 | domain-context.md 등록 | ❌ 미등록 (의존 그래프 미오염) |
| 55 게이트 편입 | check-spec 통합 | ❌ 자체 D1~D6 분리 |
| 하류 스킬 의존 | 다른 스킬 입력 | ❌ 사용자만 소비 (검토용) |
스킬 간 인터페이스를 파일로 명문화합니다.
소비자 커맨드는 파일 없이는 추론 모드로 실행하지 않습니다.
v1.6에서 schemas-decisions.md가 추가되어 계약 파일이 4개로 확장되었습니다.
--split-waves) (v1.5 추가)도메인 설명 (자연어)
↓
/usecase [--level] → usecases/ ← UC별 분할 저장 + Section 3 협력 인터페이스
├── UC001-주문생성.md
├── UC002-주문취소.md
└── ...
↓
/usecase-by-example → features/ ← Scenario UC{NNN}-S/E{nn} 1:1 변환
├── UC001-주문생성.feature
└── ...
↓
domain-context.md ← domain-modeling v2.1 (schema 3.1)
BC · Aggregate · VO · Command · Event · UL
+ interfaces[] (uc-mapping[{uc, step, flow}]) ◀ v1.7 흐름 보존
+ error-values[] + service-methods[] ◀ v1.6 신규
· flow-type · alt-flows[] · compensation-flows[] ◀ v1.7 신규
· promoted-from ◀ v1.7 신규
│
├┄┄┄┄ (선택, 위성) → docs/class-diagrams/ ← gen-class-diagram v1 ◀ v1.6.1 위성
│ class-overview.puml + class-bc-{name}.puml(N) + class-interfaces.puml
│ (D1~D6 게이트, 55 게이트 무관, 검토 보조)
↓
arch-decisions.md ← arch-design v2 (schema 1.0 YAML)
parameters · adapter-classes[] 자동 도출 · shared-kernel
↓
arch-decisions.md ← nfr-spec v2 병합
nfr: { performance · security · availability · operability }
↓
schemas-decisions.md + erd.mmd + schema.sql ← gen-schema v2
tables[] · saver-interface · cross-bc-references
↓
bc-plan.md ← 개발자 작성 (Wave · 통신 · 순환검사)
↓
Java 스켈레톤 ← uc-to-skeleton v5 (S1~S9 게이트: + alt-primary · if-else · try-catch 뼈대)
↓
BC별 구현 ← /implement-bc v3 (V1~V7 게이트: 전 흐름 호출 · 보상 try-catch AST) ◀ 세션 A
↓
테스트 스위트 ← /gen-test v3 (T0~T7 게이트: 전 Scenario · 보상 @Test 자동 생성) ◀ 세션 B
↓
55-gate 감사 ← /check-spec v4 전체 정합성 재검증 (흐름 완전성 포함)
gen-class-diagram의 D1~D6 은 Diagram 게이트로 의미가 다르며, 55 게이트와 별개의 자체 검증 카탈로그입니다.7개 카테고리 55개 게이트가 UC ↔ Gherkin ↔ domain-context ↔ 코드 ↔ 테스트 전 구간 정합성 + 전 흐름(main + alt + exc) 커버리지 + 보상 트랜잭션 구조를 보장합니다.
모든 게이트는 추론 없이 정적 매칭으로 통과 여부가 결정됩니다.
v1.7 신규 6개: C9, C10, K9, S9, V7, T7. v1.7 확장 3개: C2, K5, T1.
도메인: 주문 생성 (UC-001 placeOrder) · 시뮬레이션 범위: 흐름 완전성 핵심 9개 게이트 (v1.7 신규 6 + 확장 3)
v1.6 까지는 ErrPersistence 발생 시 paymentCanceller.cancel() 호출이 구현에서 누락되어도
49개 게이트 모두 PASS 가 가능했습니다 (보상 트랜잭션 구현 손실).
v1.7 은 이를 4단계로 정적 차단:
catch (PersistenceException e) { paymentCanceller.cancel(...); } AST 강제verify(paymentCanceller).cancel(...) 보상 @Test 강제
OrderService.placeOrder() 본문은 outer try-catch(PersistenceException) 가
inner try-catch(StockDeductFailedException) 을 감싸고, outer 내부에 추가
try-catch(PaymentCancelFailedException) 이 보상의 보상(manualPaymentCancelQueue escalation) 을 처리.
이 구조가 compensation-flows[].trigger-error 와 .error-cases 필드만으로
결정론적으로 생성됨을 확인.
e2e-sim-v1.7/ 38 파일 (UC · Feature · domain-context · Java · Test · SIMULATION-REPORT.md)
오류가 UC 명세에서 정의되면 Gherkin · domain-context · Java Exception · DomainExceptionHandler · 테스트까지
문자열 수준에서 완벽히 동일한 ID로 전파됩니다.
중간에 이름이 변경되면 check-spec V1/S4 게이트가 즉시 포착합니다.
L1. UC 명세 (Section 4 Error Values)
├── Err ID: "ErrPaymentFailed"
├── HTTP: 402
└── 사용자 메시지: "결제에 실패했습니다"
↓ [C6 게이트]
L2. Gherkin feature (Scenario UC001-E03)
└── 에러 "ErrPaymentFailed"가 반환된다
↓ [K6 게이트]
L3. domain-context.md error-values[]
└── { name: ErrPaymentFailed,
exception-class: PaymentFailedException,
http-status: 402,
raised-by-interfaces: [PaymentRequester] }
↓ [S3, S4 게이트]
L4. Java Exception 클래스
└── public class PaymentFailedException extends RuntimeException {
public static final String ERROR_ID = "ErrPaymentFailed";
public static final int HTTP_STATUS = 402;
private final String errorId;
public String getErrorId() { return errorId; }
}
↓ [V1 게이트]
L5. DomainExceptionHandler (@RestControllerAdvice)
└── @ExceptionHandler({..., PaymentFailedException.class, ...})
→ errorId = exception.getErrorId() // "ErrPaymentFailed"
→ HTTP = Exception.HTTP_STATUS // 402
↓ [T2 게이트]
L6. 단위 테스트 (@Test UC001-E03)
└── assertThat(ex.getErrorId()).isEqualTo("ErrPaymentFailed");
assertThat(PaymentFailedException.HTTP_STATUS).isEqualTo(402);
Err{PascalCase명사} (예: ErrRoomNotFound)여러 Bounded Context를 가진 프로젝트의 구현 순서, BC 간 통신, 공유 커널을 체계적으로 관리합니다.
즉각 응답이 필요한 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 { ... }
결과적 일관성으로 충분한 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) { ... }
/check-domain-version 커맨드 동작을 설명합니다.
v1.6부터 domain-context.md (schema 3.0) · arch-decisions.md (schema 1.0) · schemas-decisions.md (schema 1.0) 세 계약 파일이 각자 schema-version 과 content-version 을 독립 관리합니다.
소비자는 source.{file}-version 으로 의존 버전을 추적하며, /check-domain-version 이 동기화 필요 여부를 자동 계산합니다.
## Meta
```yaml
schema-version: "3.1"
content-version: "1.2.0"
generated-at: 2026-04-22T13:30:00+09:00
generated-by: domain-modeling
change-summary: "1.1.0: 보상의 보상 추가
(ManualPaymentCancelQueue, ErrPaymentCancelFailed).
1.2.0: NFR 신규 Err* 5개 반영 +
alt-flows/compensation-flows 신설 (v1.7)."
source: # v1.6 신규
ucs: # 소비자가 의존하는 입력 (v1.3 형식)
- { id: UC-001, file: usecases/UC001.md }
- { id: UC-002, file: usecases/UC002.md }
consumers: # 6개 소비자 (v1.7 버전 상승)
arch-design: "2.0.0"
nfr-spec: "2.0.0"
gen-schema: "2.0.0"
uc-to-skeleton: "5.0.0" # ◀ v1.7
implement-bc: "3.0.0" # ◀ v1.7
gen-test: "3.0.0" # ◀ v1.7
check-spec: "4.0.0" # ◀ v1.7
```
| 변경 유형 | change-type | arch-design v2 | nfr-spec v2 | gen-schema v2 | uc-to-skeleton v5 | implement-bc v3 | gen-test v3 |
|---|---|---|---|---|---|---|---|
| BC 추가/삭제 | major | 전면 재실행 | 대상 변경 | 테이블 추가/삭제 | 전체 BC | bc-plan 재검토 | 전체 재생성 |
| Aggregate Root 이름 변경 | major | adapter-classes 갱신 | 불필요 | 테이블명 변경 | 해당 BC 전체 | 도메인 레이어 | 해당 BC 전체 |
| interface[].name 변경 | major | adapter-classes 재도출 | target-interfaces 갱신 | 불필요 | Port 재생성 | Service 본문 | @Mock 선언 |
| Err* ID 변경 ★ | major | DomainExceptionHandler.handles | 불필요 | violation-error-id | Exception 클래스 | throw 지점 | getErrorId() 검증 |
| 새 Command/Event 추가 | minor | 불필요 | 불필요 | 불필요 | 영향 BC만 | 서비스 레이어 | 영향 BC만 |
| 새 interface/service-method 추가 | minor | adapter-class 1개 | 불필요 | 불필요 | Port 1개 | 생성자/본문 | @Mock/@Test 추가 |
| 새 error-value 추가 | minor | handles 추가 | 불필요 | 불필요 | Exception 1개 | throw 추가 | @Test 추가 |
| NFR 신규 Err* (CircuitOpen 등) | minor | handles 추가 | 제안 생성 | 불필요 | Exception 1개 | 불필요 | 불필요 |
| VO 추가 | minor | 불필요 | 불필요 | 컬럼 추가 | domain만 | domain만 | domain 테스트 |
| 불변식 설명 수정 | patch | 불필요 | 불필요 | 불필요 | 주석만 | 불필요 | 불필요 |
| UL·Gherkin·user-message 수정 | patch | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | @DisplayName만 |
슬래시 커맨드는 A-ADM Core의 5단계 워크플로를 Claude Code 환경에서 실행하는 진입점입니다.
CLAUDE.md에 정의하며, 다른 AI 도구 어댑터에서는 동등한 트리거 메커니즘으로 대체합니다.
CLAUDE.md에 정의된 커맨드가 전 단계를 자동화합니다.
모든 커맨드는 계약 파일을 읽어 추론 없이 실행합니다.
도메인 설명을 Usecase 2.0 형식으로 구조화.
전체 도메인을 분석하여 식별된 UC를 usecases/ 디렉토리에 UC별 개별 파일로 분할 저장.
기본 흐름·대안 흐름·예외 흐름·비기능 요구사항 포함.
/usecase-by-example의 필수 선행 커맨드.
/usecase "주문 관리 시스템" # 기본값: casual → usecases/ 분할 저장 /usecase "주문 관리" --level casual /usecase "주문 관리" --level fully-dressed
usecases/UC001-주문생성.mdusecases/UC002-주문취소.mdusecases/UC003-결제처리.mdUC{nnn}-{한글이름}.md — 번호 자동 채번, 정렬 보장
usecases/ 디렉토리를 읽어 features/에 .feature 파일 생성.
파일 지정 시 해당 UC만 변환, 생략 시 디렉토리 전체 순회.
usecases/ 디렉토리가 없으면 /usecase 실행을 안내하고 중단.
/usecase-by-example # usecases/ 전체 순회 /usecase-by-example usecases/UC001-주문생성.md # 특정 UC만 변환
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 # 상세 응답 포함 출력
GET /actuator/health → 200 OKbc-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-modeling Step 4 관할/check-domain-version 관할/check-spec 관할
domain-context.md consumers 섹션과 content-version 비교.
재생성 필요 소비자 목록과 최소 실행 순서 출력.
/usecase — UC 명세서 작성 (Usecase 2.0)/usecase-by-example — usecases/*.md → features/*.feature 변환/domain-modeling — domain-context.md 생성/갱신 (--bc 증분 갱신, --split-waves Wave 분할 지원)/gen-class-diagram ★ 위성 — domain-context.md → PlantUML 클래스 다이어그램 3종 (docs/class-diagrams/). --bc {name} 증분 모드 지원. 55 게이트 무관, 검토 보조용./arch-design — arch-decisions.md 생성/nfr-spec — NFR 도출 → arch-decisions.md ## NFR 섹션 추가/gen-schema — Persistence → erd.mmd (Mermaid ERD) + schema.sql (DDL) 생성/uc-to-skeleton — Java 스켈레톤 + PlantUML 시퀀스 다이어그램 (docs/diagrams/) 생성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 # 생성 계획만 출력
arch-decisions.md ## Persistence 섹션 존재domain-context.md aggregates 섹션 존재erd.mmd — Mermaid ERD (GitHub/GitLab 바로 렌더링)schema.sql — 표준 DDL (Flyway/Liquibase 입력)V{n}_init_schema.sql — --format flyway 옵션 시target/generated-sources/jooq/ — persistence=jpa+jooq 시 자동 생성현재 아키텍처 구조를 진화시키는 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 # 진행 상태 확인
domain-context.md는 직접 수정하지 않음 — /domain-modeling 재실행 권장
# Phase 1 — 요구사항 (순차 파이프라인)
/usecase "온라인 쇼핑몰: 주문·결제·재고·알림"
# → usecases/ 디렉토리에 UC별 분할 저장 (기본값: --level casual)
# usecases/UC001-주문생성.md
# usecases/UC002-주문취소.md
# usecases/UC003-결제처리.md
# usecases/UC004-재고확인.md
# usecases/UC005-알림발송.md
# ↑ 검토·수정 후 다음 커맨드 실행
/usecase-by-example
# → usecases/ 전체 순회 → features/ 디렉토리에 UC별 1:1 .feature 생성
/usecase-by-example usecases/UC001-주문생성.md
# → 특정 UC만 변환 (수정 후 개별 재생성)
# Phase 2 — 설계 (병렬 실행 후 수렴)
/domain-modeling → domain-context.md (v1.0.0)
/gen-class-diagram → (선택, 위성) docs/class-diagrams/ — 모델 시각 검토
/arch-design → arch-decisions.md (consumers.arch-design: "1.0.0")
/nfr-spec → arch-decisions.md에 ## NFR 섹션 추가
AUTO: JWT, BCrypt, MDC, Actuator, Pageable
TODO: [NFR-CACHE] [NFR-CB] [NFR-RETRY]
/gen-schema → erd.mmd (Mermaid ERD) + schema.sql (DDL)
Aggregate → JpaEntity 매핑 규칙 적용
BC 간 FK 금지 — ID 참조만 허용
/uc-to-skeleton → Java 스켈레톤 + PlantUML 시퀀스 (docs/diagrams/, NFR AUTO 클래스 포함)
# Phase 3 — 구현 (Wave 순서)
/implement-bc --wave 0 → shared 구현 (Money, Address)
/implement-bc --wave 1 → inventory 구현
/implement-bc --wave 2 → order + payment 병렬 구현 (NFR TODO 주석 삽입)
/implement-bc --wave 3 → notification 구현
# Phase 4 — 테스트
/gen-test --wave 2 → order + payment 테스트
/gen-test order --contract → BC 간 계약 테스트 (Kafka → Pact 자동 선택)
/gen-test order --pbt → Aggregate 불변식 Property-Based Testing
/gen-test --e2e → 전체 E2E 시나리오
# 테스트 후 테스트 커버리지 확인 (bash)
mvn jacoco:report
# Phase 5 — 실행
/run-local → Docker Compose 기동 + Spring Boot 시작
/run-check → Run Gate 전체 확인 (health·DB·포트·토픽)
# 수시 — 명세 ↔ 코드 드리프트 검증 (Phase 3~4 반복 중 언제든, 큰 작업이라 BC별로 진행 추천)
/check-spec → 전체 BC 대조 (domain-context.md ↔ 코드)
/check-spec --bc order → 특정 BC만 빠르게 확인
/check-spec --section commands → Command ↔ Service 메서드만 대조
# 도메인 모델 변경 시 (v1.3: --bc 증분 갱신)
/domain-modeling --bc order → order BC만 재모델링 (source-uc 역참조로 관련 UC 자동 식별)
/domain-modeling --bc order --uc UC005,UC024 → 신규 UC 추가 시 해당 BC에 반영
/domain-modeling --bc new → 미할당 UC 분석 → 신규 BC 후보 제안
/gen-class-diagram --bc order → (선택) order BC 다이어그램만 갱신, 비대상 BC 보존
/check-domain-version → 재생성 필요 목록 확인
/implement-bc order application → 영향 레이어만 재실행
/gen-test order application → 테스트 업데이트
# 대규모 프로젝트 — Wave 분할 전환 (v1.5: 1회성, BC 8개 또는 1500줄 초과 시)
/domain-modeling --split-waves → schema 2.0 → 2.1 전환 (단일 → Wave 단위 다중 파일)
원본은 domain-context.md.backup으로 보존
bounded-contexts[].wave 필드 기반으로 wave별 파일 자동 분배
/check-spec → 전환 후 정합성 검증 권장
/implement-bc voucher → STEP 0이 schema 2.1 자동 감지 → 필요한 wave 파일만 선택 로딩
# 진화적 설계 — 아키텍처 마이그레이션
/migrate-module --dry-run single-to-multi → 분석 리포트 (파일 변경 없음)
/migrate-module single-to-multi → Gate 1 분석 → 승인 → Gate 2 준비 → 승인 → Gate 3 실행
/migrate-module --status → 진행 중인 마이그레이션 상태 확인
# BC 분리 시나리오
/migrate-module --dry-run split-bc order order-core fulfillment
/migrate-module split-bc order order-core fulfillment
# → Gate 3 완료 후 필수 후속 작업:
/domain-modeling --bc order-core → order-core BC 모델링 (source-uc 자동 매핑)
/domain-modeling --bc fulfillment --uc UC010,UC011 → fulfillment BC 신규 모델링
/check-domain-version → consumers 동기화
/implement-bc order-core application → FulfillmentPort 호출 코드 완성
/gen-test order-core --contract → 포트 계약 테스트 재생성
A-JADM 본체(v1.7)는 범용 파이프라인에 집중하고, 실전 시나리오별 심화 전략은 확장 문서 체계로 분리했습니다.
본체를 가볍게 유지하면서 고급 주제를 선택적으로 참조할 수 있도록 구성한 2-레이어 구조입니다.
대규모 시스템 · 레거시 DB · 에이전트 기반 자동화 같은 고급 주제는 별도 확장 문서로 관리합니다.
각 확장 문서는 독립 버전을 가지며 실전 검증을 거쳐 정식 통합 여부를 결정합니다.
ERP급 도메인이 많은 시스템 개발 전략과 레거시 DB 리버스 엔지니어링 방법론.
Part I: 1 프로젝트 = 1~소수 BC 원칙, Wave 위상 정렬, BC 간 통신 패턴, 세션 운영.
Part II: 레거시 DB A/B/C/D 진단 프레임, legacy-db-context.md 계약 파일, 유형별 Strangler 전략.
legacy-db-context.mdreverse-schema, legacy-uc-extract
Claude Code의 subagent 기능으로 세션 분리를 자동화하면서 계약 파일 철학과 순환논리 방지 원칙을 유지하는 전략.
bc-implementer · ddd-modeler · spec-checker 에이전트 템플릿 제공.
Phase 4 고급 패턴으로 Agent Teams(Wave 병렬, DDD 수렴, Competing Hypotheses) 도입 시나리오 분석.
.claude/agents/gen-test는 별도 부모 세션 전용 (순환논리 방지)
[ A-JADM 본체 v1.7 ] ← 이 문서
├─ SDLC 5단계 범용 파이프라인
├─ 9개 정규 SKILL.md + 1개 위성 (gen-class-diagram) · 14개 슬래시 커맨드
├─ 계약 파일 체계 · 버저닝 · 멀티 BC 오케스트레이션
│
├─→ [ A-JADM Extension v0.1 ] 실전 시나리오 심화
│ ├─ ERP급 대규모 시스템 설계
│ └─ 레거시 DB 리버스 엔지니어링
│
└─→ [ A-JADM Agents v0.2 ] 자동화 고도화
├─ Subagent 기반 세션 분리 자동화
└─ Agent Teams 고급 협업 패턴 (Phase 4)
service-method 로 추출되어, 대안(A*) · 예외(E*) 흐름의 인터페이스 호출이 domain-modeling 단계에서 누락. 49개 게이트가 모두 PASS 여도 결제 승인 후 저장 실패 시 결제 취소 로직이 구현에서 사라지는 구조적 결함. v1.7 은 UC Section 3 흐름 컬럼과 alt-flows[]/compensation-flows[] 필드로 흐름별 인터페이스 호출을 보존하고 6개 신규 게이트(C9/C10/K9/S9/V7/T7)로 누락을 정적 검증.
흐름 컬럼 추가 (main | alt:A{n} | exc:E{n}). v1.2 UC 는 /usecase --migrate-to 1.3 으로 main 일괄 태깅.service-methods[] 에 flow-type (main | alt-primary), alt-flows[] (비승격 alt — entry-condition + uses-interfaces, 내부 if-else 분기), compensation-flows[] (exc 보상 — trigger-error + uses-interfaces + raises-events, try-catch 블록), promoted-from (alt-primary 승격 추적) 신설. interfaces[].uc-mapping[] 이 {uc, step, flow} 객체 배열로 확장.transaction-boundary-independent / authorization-boundary-independent / time-boundary-independent / api-entry-independent. 하나라도 만족 시 flow-type: alt-primary 로 승격되어 독립 메소드 + 전용 Command Record 생성.public 메소드 + 전용 Command Record. 비승격 alt 는 원본 메소드 본문의 if-else 분기. exc 는 try-catch 블록 — catch 타입 = trigger-error 의 exception-class 역참조. 생성자 파라미터는 main + alt + comp uses-interfaces flatten 후 중복 제거. 중첩 보상(E3 ⊃ E4 등) 자동 처리.compensation-flows[] 직접 소비로 try-catch 본문 추론 없이 구현. 중첩 보상 · 보상의 보상(manual queue) 패턴 자동 적용. V2 확장(전 흐름 커버리지) + V7 신규(try-catch AST 검증).@UC-S + @UC-A + @UC-E) ↔ @Test 1:1 (T1 확장). compensation-flows[].trigger-error 당 보상 호출 검증 @Test 자동 생성 (T7 신규 — thenThrow + isInstanceOf + verify 템플릿). alt-primary 는 @Nested 클래스로 분리. T0 세션 분리 판정 조건 4개로 강화.--gates flow-completeness 옵션으로 9개만 집중 검증 가능.skills/domain-modeling/references/domain-context-template.md 에 전체 YAML 스키마 + 필드 스펙 + check-spec v4 게이트 매핑 + 마이그레이션 가이드 문서화 (약 1,000줄)./usecase --migrate-to 1.3 + /domain-modeling --bc {name} 순서로 전환.domain-context.md schema 3.0/3.1) 검토 보조 도구. PlantUML 클래스 다이어그램 3종(조감도 · BC별 상세 · interfaces 의존도) 결정론적 생성. 산출 위치 docs/class-diagrams/ — uc-to-skeleton 시퀀스 다이어그램(docs/diagrams/)과 docs/ 하위 정렬. --bc {name} 증분 모드 지원하여 /domain-modeling --bc 워크플로와 정합.«uses» [n] 라벨이 uc-to-skeleton의 S7 게이트(Application Service 생성자 파라미터 순서 = uses-interfaces 순서)와 시각적으로 정렬. 검토자가 다이어그램만 봐도 생성자 순서 위반을 즉시 인지 가능..puml 만), ② domain-context.md consumers 블록 미등록(의존 그래프 미오염), ③ 49 게이트 미편입, ④ 하류 스킬 의존 없음. 빠지더라도 A-JADM 파이프라인 정상 동작.interfaces[].uc-mapping으로 1:1 매핑되어 결정론적 도출 경로 확보.## NFR 섹션이 아닌 nfr: YAML 블록으로 병합. adapter-classes[] 가 interfaces[].name 패턴 매칭으로 자동 도출./domain-modeling --migrate-to 3.0 명시적 실행 시에만 전환. Wave 분할 모드는 schema 3.1로 이전 개념 유지.--split-waves)domain-context.md가 비대해질 때 Wave 단위 다중 파일 구조로 전환. schema-version 2.0(단일) / 2.1(분할) 이중 모드 지원. 임계값: BC 8개 또는 1,500줄 초과 시 검토 권장.implement-bc STEP 0 BC 컨텍스트 추출 신설domain-context.md의 YAML 키를 check-spec 검증 대상과 문서화/추적 목적으로 명시 분리. 템플릿에 분류 주석 추가.--split-waves 실행 시에만 전환.bc-implementer 레퍼런스 구현 제공.