design-api

Files (3)

• SKILL.md
• pseudocode.md · templates/
• request-response.md · templates/

SKILL.md (first lines)

# Skill: Design API

## 목적

도메인의 **API 명세**를 작성하고 입출력과 처리 흐름 정의

**철학**: "추상적 설계 말고, 정확한 명세"

---

## 입력

- 도메인 이름 (예: "users")
- Phase 2 결과 (SESSION.md의 도메인 정의)
- Phase 3 결과 (domain-model.md)

---

## 출력

- `ai-context/domain-books/{domain}/api-spec.md`
- API 목록 + Request/Response + 수도코드 (복잡한 로직만)

---

## 작동 방식

### 1. API 목록 추출

SESSION.md와 domain-model.md의 생명주기(생성/수정/삭제)와 비즈니스 룰을 읽고 필요한 API를 도출한다:

```
domain-model.md → users 도메인:
  생성: 회원가입
  조회: 프로필 조회
  수정: 프로필 수정
  삭제: 회원 탈퇴 (Cascade → 복잡도 "보통")
```

### 2. 복잡도 판단

각 API가 수도코드가 필요한지 판단한다:

| 복잡도 | 판단 기준 | 수도코드 |
|-------|---------|--------|
| 단순 | 단순 CRUD, 검증만 있음 | ❌ 불필요 |
| 보통 | Cascade, 다단계 검증, 조건부 로직 | ✅ 필요 |
| 복잡 | 상태 전이, 복잡한 계산, 외부 호출 | ✅ 필수 |

### 3. Request/Response 작성

domain-model.md의 용어와 제약 조건을 그대로 활용해 필드 테이블을 작성한다.
- 필드명: camelCase
- 타입: 한글 (문자열, 숫자, 불린, 날짜시간, 배열, 객체)
- 오류 메시지: 반드시 한글

### 4. 수도코드 작성 (복잡한 로직만)

단계별 번호와 들여쓰기로 처리 흐름을 자연어로 표현한다.

---

## api-spec.md 구조

```markdown
# {domain} API 명세

> 생성일: {오늘 날짜}
> Phase: 4 (API Designer)
> 상태: ✅ 완료

---

## API 목록

| 번호 | API 이름 | 설명 | 복잡도 |
|------|----------|------|--------|
| 1 | 회원가입 | 새 사용자 생성 | 단순 |
| 2 | 프로필 조회 | 사용자 정보 조회 | 단순 |
| 3 | 프로필 수정 | 사용자 정보 변경 | 단순 |
| 4 | 회원 탈퇴 | 사용자 삭제 (Cascade) | 보통 |

---

## 1. 회원가입

### Request (요청)

| 필드명 | 타입 | 필수 | 설명 | 예시 | 검증 규칙 |
|--------|------|------|------|------|-----------|
| email | 문자열 | O | 로그인용 이메일 주소 | user@example.com | 이메일 형식, 중복 불가, 최대 255자 |
| displayName | 문자열 | O | 사용자 닉네임 | 여행러버 | 최소 1자, 최대 50자 |
| profileImage | 문자열 | X | 프로필 사진 URL | https://example.com/photo.jpg | URL 형식 |
| preferredLanguage | 문자열 | X | 선호 언어 | ko | 'ko' 또는 'en' (기본값: 'en') |

### Response (응답)

#### 성공 (200)

| 필드명 | 타입 | 설명 | 예시 |
|--------|------|------|------|
| id | 문자열 | 생성된 사용자 ID | u_123abc |
| email | 문자열 | 이메일 주소 | user@example.com |
| displayName | 문자열 | 표시 이름 | 여행러버 |
| profileImage | 문자열 | 프로필 사진 URL | https://example.com/photo.jpg |
| preferredLanguage | 문자열 | 선호 언어 | ko |
| createdAt | 날짜시간 | 가입 시각 | 2026-01-28T10:30:00Z |

#### 오류

| 상태 | 조건 | 메시지 | 필드 예시 |
|------|------|--------|-----------|
| 409 | 이메일 중복 | 이미 가입된 이메일입니다 | {"email": "user@example.com"} |
| 400 | 필드 검증 실패 | 이메일 형식이 올바르지 않습니다 | {"email": "invalid-email"} |
| 400 | 필수 필드 누락 | 필수 필드가 누락되었습니다 | {"displayName": null} |
| 400 | 언어 코드 오류 | 지원하지 않는 언어입니다 | {"preferredLanguage": "fr"} |

---

From ureca-corp/claude, MIT.

More from ureca-corp/claude