AI-Driven Go Application
Development Methodology

A-GADM v2란

A-JADM의 핵심 무기 — 계약 파일 기반 파이프라인, 1:1 추적성, 커맨드 자동 실행 — 을 Go 패키지 중심 설계에 맞게 재구성한 방법론.
v1에서 대화 내 블록으로 관리하던 설계 상태를 영속적인 계약 파일로 전환합니다.

v1 → v2 주요 변경

5대 설계 원칙

5대 원칙의 전체 정의는 A-ADM Core → 설계 원칙을 참조하세요.
Go 어댑터에서 추가되는 원칙 하나를 포함합니다.

5단계 워크플로

각 단계는 명확한 입력·산출물·게이트를 가집니다.
A-JADM 5 Phase 구조와 동일한 프레임워크.

7개 스킬 파이프라인

각 스킬은 독립적인 SKILL.md 오케스트레이터 + 참조 파일로 구성됩니다.
스킬 간 직접 호출 없이 계약 파일로만 소통합니다.

스킬 ↔ 커맨드 관계

계약 파일 체계

스킬 간 인터페이스를 파일로 명문화. 소비자 커맨드는 파일 없이는 실행하지 않습니다.

파일 간 흐름

features.md (개발자 작성 — 파이프라인의 원천)
       ↓
/go-domain-init              → 도메인 사전 + 패키지 후보 + UC 도출 계획   ← 검토·수정
       ↓
/go-usecase-spec             → UC명세서.md + openapi.yaml 초안        ← 검토·수정
       ↓
domain-context.md     ← /go-domain-modeling 산출 (패키지·인터페이스·에러값·UL)
       ↓
arch-decisions.md     ← /go-arch-design 산출 (패키지 구조·스택·금지 규칙·wire-up)
       ↓
Go 스켈레톤              ← /go-skeleton (추론 없는 1:1 매핑)
       ↓
패키지별 구현            ← /go-implement (레이어 순서 강제)
       ↓
테스트 스위트            ← /go-gen-test — go-gen-test 스킬 (UC↔테스트 1:1 추적)
       ↓
openapi.yaml 확정      ← /gen-openapi (초안 drift 검증 → A-FADM 전달)

domain-context.md 스키마 (YAML 블록)

## Interfaces                            # 핵심 — IDD 매핑의 원천
```yaml
interfaces:
  - name: StockChecker
    package: order                        # 소비자 패키지
    methods:
      - "IsAvailable(ctx context.Context, productID string, qty int) (bool, error)"
    consumed-by: [order.OrderService]
    uc-mapping: "UC-001 Step 1"           # ← 추적성 원천
```

## Error Values                          # sentinel 에러
```yaml
error-values:
  order:
    - name: ErrNotFound
      sentinel: 'errors.New("order not found")'
    - name: ErrInsufficientStock
      sentinel: 'errors.New("insufficient stock")'
```

## Service Methods                       # UC Step 매핑
```yaml
service-methods:
  - package: order
    struct: OrderService
    methods:
      - name: PlaceOrder
        signature: "(ctx context.Context, req PlaceOrderReq) (OrderID, error)"
        uc-step: "UC-001 기본 흐름"
        uses-interfaces: [StockChecker, PaymentRequester, OrderSaver]
        error-cases: [ErrInsufficientStock, ErrPaymentFailed]
```

arch-decisions.md 스키마 (YAML 블록)

## Package Layout
```yaml
package-layout:
  tree:
    - "cmd/server/main.go"
    - "internal/order/"          # 도메인 (외부 import 없음)
    - "internal/postgres/"       # 인프라 구현체
    - "internal/handler/"        # chi router
    - "pkg/money/"               # 공유 VO
  dependency-direction: "handler → order; postgres → order (구현); order ← 외부 없음"
```

## Infra Mapping                         # 인터페이스 → 구현체 확정
```yaml
infra-mapping:
  - interface: OrderFinder
    consumer-pkg: order
    implementation: "postgres.OrderRepo"
    impl-pkg: "internal/postgres"
```

## Wire-up Strategy                      # cmd/main 코드 순서
```yaml
wire-up:
  location: "cmd/server/main.go"
  order: [pgxpool, repos, services, handlers, router]
```

추적성 규칙

UC Step → 인터페이스 → 테스트 케이스까지 1:1 매핑 강제.
A-JADM의 Gherkin↔@Test를 Go 테이블 드리븐으로 재해석.

UC-001: 고객이 상품을 주문한다
  Step 1: 재고 확인  → StockChecker.IsAvailable()  → {name:"UC001_Step1_재고충분"}, {name:"UC001_Step1_재고부족"}
  Step 2: 결제 요청  → PaymentRequester.Request()   → {name:"UC001_Step2_결제성공"}, {name:"UC001_Step2_결제실패"}
  Step 3: 주문 저장  → OrderSaver.Save()            → {name:"UC001_Step3_저장성공"}
  Step 4: 이벤트 발행 → EventPublisher.Publish()     → {name:"UC001_Step4_발행성공"}

interfaces:
  - name: StockChecker
    uc-mapping: "UC-001 Step 1"  # ← 추적 원천

service-methods:
  - name: PlaceOrder
    uc-step: "UC-001 기본 흐름"
    error-cases: [ErrInsufficientStock]
    # ← 에러 케이스가 테스트 테이블 행 근거

tests := []struct {
    name string  // ← UC Step 추적
}{
    {name: "UC001_Step1_재고충분"},
    {name: "UC001_Step1_재고부족"},
    {name: "UC001_Step2_결제성공"},
    {name: "UC001_Step2_결제실패"},
}
// go test -run "UC001_Step1" 가능

고정 스택 · 금지 규칙

arch-decisions.md에 선언. 모든 스킬과 커맨드가 추론 없이 따릅니다.

11개 슬래시 커맨드

CLAUDE.md에 정의된 커맨드가 전 단계를 자동화합니다.
모든 커맨드는 계약 파일을 읽어 추론 없이 실행합니다.

Phase 1 — 요구사항

/go-domain-init                # features.md 자동 읽기
/go-domain-init features.md    # 파일 경로 지정

/go-usecase-spec "고객이 주문한다" --pkg order

Phase 2 — 설계 (계약 파일 생성) 스킬 연동

/go-domain-modeling
# UC명세서 없으면 중단 → /go-usecase-spec 안내

/go-arch-design
# domain-context.md 없으면 중단

/go-skeleton
# 두 계약 파일 모두 필요. 하나라도 없으면 중단.

Phase 3 — 구현

/go-implement order            # 전체 (all)
/go-implement order domain     # 레이어 지정
/go-implement order service
/go-implement order --dry-run  # 실행 계획만

/add-interface order
/add-interface order --uc UC-001

Phase 4 — 테스트 · 검증

/go-gen-test order                 # 전체 (scope=service)
/go-gen-test order --uc UC-001     # 특정 UC
/go-gen-test order --scope handler # HTTP 핸들러 테스트
/go-gen-test order --scope all     # service + handler

/review-deps
/review-deps --pkg order

/check-design
/check-design --phase 2

Phase 5 — OpenAPI 확정

/gen-openapi
/gen-openapi --pkg order

전체 커맨드 실행 시퀀스 — 쇼핑몰 예시

# Phase 1 — 요구사항 분석
# features.md 작성 (개발자) — 프로젝트 개요 + 액터 + 기능 목록 + 비즈니스 규칙 + 외부 의존성 + 기술 제약

/go-domain-init                     # features.md 읽기 → 도메인 사전 + 패키지 후보 + UC 도출 계획
# → 검토 후 UC 도출 계획에 따라 /go-usecase-spec 실행
/go-usecase-spec "고객이 상품을 주문한다" --pkg order
/go-usecase-spec "주문을 취소하고 환불한다" --pkg order
# → UC명세서.md + 협력 인터페이스 + openapi.yaml 초안

# Phase 2 — 설계 (계약 파일 파이프라인)
/go-domain-modeling       → domain-context.md (v1.0.0)
/go-arch-design           → arch-decisions.md
/go-skeleton              → internal/{order,payment,postgres,handler}/ + cmd/

# Phase 3 — 구현 (레이어 순서 강제)
/go-implement order domain     # struct + errors + 생성자
/go-implement order service    # UseCase 구현 (UC 흐름 순서)
/go-implement order infra      # postgres Repo (pgx SQL)
/go-implement order handler    # chi HTTP 핸들러
/go-implement order wire-up    # cmd/main 조합 루트
/go-implement payment          # 다음 패키지 전체

# Phase 4 — 테스트 · 검증
/go-gen-test order                 # UC↔테스트 1:1 테이블 드리븐
/go-gen-test order --scope handler # HTTP 핸들러 테스트
/go-gen-test payment
/review-deps                    # 순환 · 방향 위반
/check-design                   # 추적성 + Forbidden Rules

# Phase 5 — OpenAPI 확정
/gen-openapi                    # 초안 drift 검증 → 확정 → A-FADM 전달

# 도메인 모델 변경 시
/go-domain-modeling             # domain-context.md (v1.1.0)
/go-skeleton                    # 영향 범위 재생성
/go-implement order service    # 변경 레이어만 재실행
/go-gen-test order                 # 테스트 업데이트