AI-Driven Frontend Application
Development Methodology

A-FADM이란

A-FADM은 A-JADM의 프론트엔드 확장입니다.
백엔드가 openapi.yaml을 생성한 시점부터 프론트엔드 파이프라인이 시작됩니다.
반복적인 프롬프트 재작성 대신 스킬·계약 파일·슬래시 커맨드로 일관된 React/TypeScript 코드를 생성합니다.

A-JADM과의 연결 구조

[ A-JADM 백엔드 파이프라인 ]
implement-bc 완료
    ↓
/gen-openapi → openapi.yaml   ← 두 방법론의 연결 지점
    ↓
[ A-FADM 프론트엔드 파이프라인 시작 ]

세 가지 핵심 축

3대 설계 원칙

원칙의 전체 정의는 A-ADM Core → 설계 원칙을 참조하세요.
A-FADM은 Core 원칙 중 프론트엔드에 해당하는 세 가지를 적용합니다.

5단계 파이프라인

각 단계는 명확한 입력·산출물·게이트를 가집니다.
fe-prototype은 조건에 따라 선택적으로 실행합니다.

4개 스킬 상세

각 스킬은 독립적인 SKILL.md로 구성됩니다.
스킬끼리는 계약 파일로만 소통합니다.

계약 파일 체계

스킬 간 인터페이스를 파일로 명문화합니다.
fe-component-spec.md가 없으면 fe-to-skeleton이 즉시 중단합니다.

파일 간 흐름

UC명세서 + openapi.yaml
       ↓
prototype-{domain}.html   ← fe-prototype 산출 (선택, 검토 후 폐기)
       ↓ [검토 확정 — data-component 경계 추출]
fe-component-spec.md      ← fe-component-spec 산출 (계약 파일)
       ↓
컴포넌트 스켈레톤         ← fe-to-skeleton   (추론 없는 1:1 매핑)
       ↓
Step1 구조 → Step2 API 연동 → Step3 상태 처리  ← /implement-fe
       ↓
테스트 스위트             ← /fe-gen-test      (명세 1:1 추적)

프로토타이핑 — 가치와 한계

Claude Code 환경에서 프로토타이핑의 목적은 "재작업 비용 절감"이 아닙니다.
fe-component-spec.md 품질 확보와 이해관계자 소통이 목적입니다.

일반 개발:
  프로토타입(1일) + 구현(5일) = 6일
  바로 구현(5일) + 재작업(3일) = 8일
  → 프로토타입 ROI 명확

Claude Code:
  프로토타입(0.5일) + 구현(1일) = 1.5일
  바로 구현(1일) + 재작업(0.5일) = 1.5일
  → ROI 불명확 — 목적이 달라져야 함

본질적 한계 — 알고 사용할 것

fe-prototype 핵심 구현 패턴

<div data-component="RoomCard"
     data-props="room, nights, onBook">
  <!-- RoomCard 내용 -->
</div>

<div data-component="SearchSummaryBar"
     data-props="criteria">
  <!-- SearchSummaryBar 내용 -->
</div>

<div style="position:fixed;bottom:16px;right:16px;
  background:#1F2937;color:white;
  padding:12px;border-radius:8px;z-index:9999;">
  <div>상태 시뮬레이터</div>
  <button onclick="setUIState('loading')">로딩</button>
  <button onclick="setUIState('error')">에러</button>
  <button onclick="setUIState('empty')">빈 목록</button>
  <button onclick="setUIState('normal')">정상</button>
</div>

고정 스택 규칙

CLAUDE.md에 선언된 스택과 금지 규칙은 모든 스킬과 커맨드가 따릅니다.
A-JADM의 Lombok 금지 규칙과 동일한 역할입니다.

핵심 코딩 패턴

// ✅ 올바른 패턴
const { data } = useQuery({
  queryKey: ['orders', { page, status }],
  queryFn: () => orderApi.getList({ page, status }),
})

// ✅ mutation 후 invalidate
const mutation = useMutation({
  mutationFn: orderApi.cancel,
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['orders'] })
  },
})

// ✅ 올바른 순서
if (isPending) return <OrderListSkeleton />
if (isError) return (
  <ErrorState onRetry={() => refetch()} />
)
if (!data?.content.length) return <EmptyState />

// openapi 타입 사용 패턴
import type { components } from '@/types/api'
type Order = components['schemas']['OrderResponse']
type Summary = Pick<Order, 'orderId' | 'status'>

컴포넌트 파일 구조

src/
├── features/
│   └── {domain}/                      # 예: order, availability, booking
│       ├── components/
│       │   ├── {Domain}ListPage.tsx   # 페이지 컴포넌트 (라우팅 진입점)
│       │   ├── {Domain}Card.tsx       # 카드/행 렌더링
│       │   └── {Domain}Form.tsx       # 폼 컴포넌트
│       ├── hooks/
│       │   ├── use{Domain}List.ts     # useQuery 래퍼
│       │   └── use{Domain}Mutation.ts # useMutation 래퍼
│       ├── api/
│       │   └── {domain}.api.ts        # axios 호출 함수
│       ├── types/
│       │   └── {domain}.types.ts      # 로컬 타입 (openapi 타입 re-export)
│       └── fe-component-spec.md       # 계약 파일 (스킬 산출물)
├── shared/
│   ├── components/                    # 공통 UI (Button, Modal 등)
│   ├── stores/                        # Zustand stores
│   └── lib/
│       ├── axios.ts                   # axios 인스턴스
│       └── queryClient.ts             # TanStack Query 클라이언트
└── types/
    └── api.d.ts                       # openapi-typescript 자동 생성

슬래시 커맨드 레퍼런스

CLAUDE.md에 정의된 3개 커맨드가 셋업·구현·테스트를 자동화합니다.
모든 커맨드는 CLAUDE.md와 fe-component-spec.md를 읽어 추론 없이 실행합니다.

/setup-fe                # 기본 셋업
/setup-fe --gen-types    # 셋업 + openapi 타입 생성
/setup-fe --dry-run      # 실행 계획만 출력

/implement-fe order          # 전체 3단계 순차
/implement-fe order step1    # 구조만 (컴포넌트 + 타입)
/implement-fe order step2    # API 연동 (TanStack Query)
/implement-fe order step3    # 상태 처리 (로딩/에러/빈)
/implement-fe order --dry-run  # 생성 파일 목록만 출력

/fe-gen-test order              # 전체
/fe-gen-test order hooks        # hooks/ 단위 테스트만
/fe-gen-test order components   # 컴포넌트 렌더링만
/fe-gen-test order --contract   # API mock 계약 테스트

전체 커맨드 실행 시퀀스 — 호텔 예약 시스템 예시

# 사전 — 프로젝트 환경 구성 (최초 1회)
/setup-fe --gen-types         → Vite 설치 · 패키지 · 폴더 구조 · openapi 타입 생성

# 0단계 — 프로토타이핑 (화면 구조 불확실 + 이해관계자 승인 필요)
fe-prototype                  → prototype-availability.html (검토 후 폐기)
fe-prototype                  → prototype-booking.html      (검토 후 폐기)

# 1단계 — 컴포넌트 명세 (openapi.yaml + 프로토타입 검토 결과 반영)
fe-component-spec availability → fe-component-spec.md (search · availability · detail)
fe-component-spec booking      → fe-component-spec.md (booking form · confirm)

# 2단계 — 스켈레톤 생성
fe-to-skeleton availability    → types · api · hooks · components (stub)
fe-to-skeleton booking         → types · api · hooks · components (stub)

# 3단계 — 구현 (도메인 단위)
/implement-fe search step1     → SearchPage + DateRangePicker + GuestRoomCounter
/implement-fe search step2     → Zustand store (searchCriteria)
/implement-fe availability step1  → AvailabilityPage + RoomCard + PackageCard
/implement-fe availability step2  → useAvailability (TanStack Query)
/implement-fe availability step3  → 로딩 Skeleton · 에러 · 빈 상태
/implement-fe booking step1    → BookingFormPage + BookingSummaryCard
/implement-fe booking step2    → useCreateBooking (useMutation) · 409 충돌 처리
/implement-fe booking step3    → BookingConfirmPage

# 4단계 — 테스트
/fe-gen-test availability      → useAvailability · RoomCard · PackageCard 테스트
/fe-gen-test availability --contract  → API mock 계약 테스트
/fe-gen-test booking           → useCreateBooking · BookingFormPage 테스트

실행 환경

코드 생성 후 실제로 실행하기 위한 환경 구성 절차입니다.
/setup-fe 커맨드가 대부분을 자동화하며, 수동 개입이 필요한 단계를 명시합니다.

# CLAUDE.md 4개 값 수정 후
/setup-fe --gen-types

# 생성되는 파일들
src/shared/lib/axios.ts
src/shared/lib/queryClient.ts
src/app/routes.tsx
src/test/setup.ts
src/types/api.d.ts    # --gen-types 시
vite.config.ts
vitest.config.ts
.env.example

# 수동 단계
cp .env.example .env
# VITE_API_BASE_URL 수정

# 최초 생성
npm run gen:types

# API 변경 감지 모드
npm run gen:types:watch

# 생성된 타입 사용 패턴
import type { components } from '@/types/api'
type Room = components['schemas']['RoomAvailability']
type Booking = components['schemas']['BookingResponse']

# 개발 서버 실행
npm run dev  →  http://localhost:3000

# 프록시 동작
브라우저 → localhost:3000/api/rooms
  → Vite 프록시
    → localhost:8080/api/rooms (백엔드)

# vite.config.ts (자동 생성)
proxy: {
  '/api': {
    target: 'http://localhost:8080',
    changeOrigin: true,
  }
}

# 빌드 전 타입 최신화
npm run gen:types

# 프로덕션 빌드
npm run build   →  dist/

# 빌드 결과 로컬 확인
npm run preview  →  http://localhost:4173

# 환경별 .env
.env.development  VITE_API_BASE_URL=http://localhost:8080
.env.production   VITE_API_BASE_URL=https://api.example.com

# Nginx SPA 폴백 (배포 시 필수)
location / {
  try_files $uri $uri/ /index.html;
}

npm scripts 요약