create-claude-pipeline 0.1.0

package/template/.claude/skills/write-cicd/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: write-cicd
+description: "인프라 엔지니어가 GitHub Actions CI/CD 파이프라인을 작성할 때 참조하는 skill. CI(PR 검증)와 CD(자동 배포)를 분리하여 작성하며, 캐싱, 헬스체크, 롤백, 시크릿 관리 패턴을 제공한다. Infra Agent가 CI/CD 파이프라인을 새로 만들거나, 기존 워크플로우를 수정하거나, 배포 자동화를 설정할 때 반드시 사용한다. 'CI/CD 작성', 'GitHub Actions 설정', '배포 파이프라인', '자동 배포', 'PR 검증 워크플로우', 'Docker 배포', 'GHCR 푸시', '롤백 설정', 'ci.yml 작성', 'cd.yml 작성' 등의 상황에서 트리거된다."
+---
+
+# Write CI/CD
+
+인프라 엔지니어가 GitHub Actions CI/CD 파이프라인을 작성할 때 따르는 패턴이다.
+
+CI와 CD를 별도 워크플로우 파일로 분리한다. CI는 "코드가 안전한가"를 검증하고, CD는 "검증된 코드를 배포"한다. 이 분리가 중요한 이유는, CI는 모든 PR에서 빈번하게 실행되므로 가볍고 빨라야 하고, CD는 main 머지 후에만 실행되므로 Docker 빌드 같은 무거운 작업을 포함할 수 있기 때문이다.
+
+---
+
+## 파일 구조
+
+```
+.github/
+└── workflows/
+    ├── ci.yml     # PR 검증 — lint, typecheck, test, build
+    └── cd.yml     # 자동 배포 — Docker build, push, deploy, rollback
+```
+
+기존 프로젝트에 이미 워크플로우 파일이 있으면 기존 구조를 따른다.
+
+---
+
+## CI 워크플로우 (ci.yml)
+
+PR이 생성되거나 업데이트될 때 실행된다. 모든 검증이 통과해야 머지할 수 있다.
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      # 1. 코드 체크아웃
+      - uses: actions/checkout@v4
+
+      # 2. Node.js 설정 + 의존성 캐싱
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      # 3. 의존성 설치
+      - run: npm ci
+
+      # 4. 린트 검사
+      - run: npm run lint
+
+      # 5. 타입 체크
+      - run: npm run typecheck
+
+      # 6. 테스트 실행
+      - run: npm run test
+
+      # 7. 빌드 확인
+      - run: npm run build
+```
+
+### CI 설계 원칙
+
+**concurrency 설정**: 같은 PR에서 새 커밋이 푸시되면 이전 CI를 취소한다. 불필요한 리소스 낭비를 방지한다.
+
+**`npm ci` vs `npm install`**: `npm ci`는 `package-lock.json`을 그대로 사용하므로, 팀원 간 의존성 차이 없이 동일한 환경을 재현한다. CI에서는 항상 `npm ci`를 사용한다.
+
+**캐싱**: `actions/setup-node`의 `cache: 'npm'`이 `~/.npm` 디렉토리를 자동 캐싱한다. 매번 모든 패키지를 다운로드하지 않아 CI 시간이 단축된다.
+
+**단계 순서**: 빠르게 실패하는 검사를 먼저 실행한다. lint(초 단위) → typecheck(초 단위) → test(분 단위) → build(분 단위) 순서로, 빠른 검사에서 실패하면 느린 검사를 실행하지 않는다.
+
+**Branch protection**: CI를 GitHub의 Branch Protection Rule에 등록하여, CI 통과 없이는 머지할 수 없게 한다. 이것은 수동 설정이므로 워크플로우 파일로는 할 수 없고, 레포지토리 설정에서 직접 해야 한다.
+
+---
+
+## CD 워크플로우 (cd.yml)
+
+main 브랜치에 머지되면 자동으로 배포를 진행한다. 스테이징은 자동, 프로덕션은 수동 승인 후 배포된다.
+
+```yaml
+name: CD
+
+on:
+  push:
+    branches: [main]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  # ─── Docker 이미지 빌드 & 푸시 ───
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      image-tag: ${{ steps.meta.outputs.tags }}
+      image-digest: ${{ steps.build.outputs.digest }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=
+            type=raw,value=latest
+
+      - id: build
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  # ─── 스테이징 배포 (자동) ───
+  deploy-staging:
+    needs: build-and-push
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy to staging
+        run: |
+          # 배포 플랫폼에 맞게 수정한다
+          # 예: Docker Compose, Kubernetes, AWS ECS, Railway 등
+          echo "Deploying ${{ needs.build-and-push.outputs.image-tag }} to staging"
+          # ssh ${{ secrets.STAGING_HOST }} "docker pull ... && docker compose up -d"
+        env:
+          DEPLOY_HOST: ${{ secrets.STAGING_HOST }}
+          DEPLOY_KEY: ${{ secrets.STAGING_SSH_KEY }}
+
+      - name: Health check (staging)
+        run: |
+          for i in $(seq 1 30); do
+            STATUS=$(curl -s -o /dev/null -w "%{http_code}" "${{ secrets.STAGING_URL }}/health" || echo "000")
+            if [ "$STATUS" = "200" ]; then
+              echo "Staging health check passed"
+              exit 0
+            fi
+            echo "Attempt $i/30: status=$STATUS, retrying in 10s..."
+            sleep 10
+          done
+          echo "Staging health check failed after 30 attempts"
+          exit 1
+
+  # ─── 프로덕션 배포 (수동 승인) ───
+  deploy-production:
+    needs: [build-and-push, deploy-staging]
+    runs-on: ubuntu-latest
+    environment: production  # GitHub Environment로 수동 승인 게이트
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Save current version for rollback
+        id: current
+        run: |
+          # 현재 배포된 버전을 기록해둔다 (롤백에 필요)
+          CURRENT_TAG=$(curl -s "${{ secrets.PRODUCTION_URL }}/health" | jq -r '.version // "unknown"')
+          echo "current-tag=$CURRENT_TAG" >> "$GITHUB_OUTPUT"
+          echo "Current production version: $CURRENT_TAG"
+
+      - name: Deploy to production
+        id: deploy
+        run: |
+          echo "Deploying ${{ needs.build-and-push.outputs.image-tag }} to production"
+          # ssh ${{ secrets.PRODUCTION_HOST }} "docker pull ... && docker compose up -d"
+        env:
+          DEPLOY_HOST: ${{ secrets.PRODUCTION_HOST }}
+          DEPLOY_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
+
+      - name: Health check (production)
+        id: healthcheck
+        run: |
+          for i in $(seq 1 30); do
+            STATUS=$(curl -s -o /dev/null -w "%{http_code}" "${{ secrets.PRODUCTION_URL }}/health" || echo "000")
+            if [ "$STATUS" = "200" ]; then
+              echo "Production health check passed"
+              exit 0
+            fi
+            echo "Attempt $i/30: status=$STATUS, retrying in 10s..."
+            sleep 10
+          done
+          echo "Production health check failed"
+          exit 1
+
+      - name: Rollback on failure
+        if: failure() && steps.deploy.outcome == 'success'
+        run: |
+          echo "Rolling back to ${{ steps.current.outputs.current-tag }}"
+          # ssh ${{ secrets.PRODUCTION_HOST }} "docker pull <previous-image> && docker compose up -d"
+          # 롤백 후 헬스체크
+          sleep 15
+          STATUS=$(curl -s -o /dev/null -w "%{http_code}" "${{ secrets.PRODUCTION_URL }}/health" || echo "000")
+          if [ "$STATUS" = "200" ]; then
+            echo "Rollback successful"
+          else
+            echo "CRITICAL: Rollback also failed. Manual intervention required."
+            exit 1
+          fi
+```
+
+### CD 설계 원칙
+
+**이미지 태깅**: commit SHA를 태그로 사용한다. `latest`는 편의를 위해 추가하지만, 배포에는 항상 SHA 태그를 사용해야 어떤 커밋이 배포되었는지 추적할 수 있다.
+
+**빌드 캐시**: `cache-from/cache-to: type=gha`로 GitHub Actions의 캐시를 활용한다. Docker 레이어 캐시를 통해 변경이 없는 레이어는 다시 빌드하지 않아 빌드 시간이 크게 단축된다.
+
+**스테이징 → 프로덕션 순서**: 스테이징에서 먼저 검증한 후 프로덕션에 배포한다. `environment: production` 설정으로 GitHub에서 수동 승인을 요구하므로, 스테이징 검증 결과를 확인한 후 승인할 수 있다.
+
+**헬스체크**: 배포 후 `/health` 엔드포인트를 최대 5분(10초 × 30회) 동안 폴링한다. 서비스가 기동하는 데 시간이 걸리기 때문에 즉시 확인하면 실패할 수 있다.
+
+**자동 롤백**: 프로덕션 배포 후 헬스체크가 실패하면 이전 버전으로 자동 롤백한다. 배포 전에 현재 버전을 기록해두었다가 롤백에 사용한다. 롤백마저 실패하면 수동 개입이 필요함을 명시한다.
+
+---
+
+## 시크릿 관리
+
+모든 민감 정보는 GitHub Secrets에 저장하고, 코드에 직접 작성하지 않는다.
+
+### 필요한 시크릿 목록
+
+| 시크릿 이름 | 용도 | 설정 위치 |
+|------------|------|----------|
+| `GITHUB_TOKEN` | GHCR 로그인 (자동 제공) | 자동 |
+| `STAGING_HOST` | 스테이징 서버 주소 | Repository Secrets |
+| `STAGING_SSH_KEY` | 스테이징 SSH 키 | Repository Secrets |
+| `STAGING_URL` | 스테이징 URL (헬스체크용) | Repository Secrets |
+| `PRODUCTION_HOST` | 프로덕션 서버 주소 | Environment Secrets (production) |
+| `PRODUCTION_SSH_KEY` | 프로덕션 SSH 키 | Environment Secrets (production) |
+| `PRODUCTION_URL` | 프로덕션 URL (헬스체크용) | Environment Secrets (production) |
+
+**Repository Secrets vs Environment Secrets**: 프로덕션 관련 시크릿은 Environment Secrets에 저장한다. 이렇게 하면 `environment: production` 승인을 통과해야만 해당 시크릿에 접근할 수 있어서, 일반 워크플로우에서 프로덕션 크레덴셜이 노출되는 것을 방지한다.
+
+### 시크릿 사용 규칙
+
+- 워크플로우에서 `${{ secrets.NAME }}`으로 참조한다
+- 시크릿 값은 로그에 자동 마스킹된다
+- 새로운 시크릿이 필요하면 README나 주석에 어떤 시크릿을 설정해야 하는지 기록한다
+- `.env` 파일은 `.gitignore`에 포함되어 있는지 확인한다
+
+---
+
+## 배포 플랫폼별 커스터마이징
+
+CD 워크플로우의 배포 스텝은 플랫폼에 따라 달라진다. 위 템플릿의 배포 커맨드를 프로젝트에 맞게 교체한다.
+
+| 플랫폼 | 배포 방식 |
+|--------|----------|
+| Docker Compose (VPS) | `ssh + docker compose pull && docker compose up -d` |
+| Kubernetes | `kubectl set image deployment/app app=<image>` |
+| AWS ECS | `aws ecs update-service --force-new-deployment` |
+| Railway / Fly.io | 플랫폼 CLI 사용 (`railway up`, `fly deploy`) |
+| Vercel / Netlify | 별도 CD 불필요 (Git 연동으로 자동 배포) |
+
+Vercel/Netlify 같은 PaaS를 사용하는 프로젝트는 CD 워크플로우가 불필요할 수 있다. 이 경우 CI 워크플로우만 작성한다.
+
+---
+
+## 구현 순서 체크리스트
+
+1. [ ] 기존 `.github/workflows/` 확인 (이미 있으면 기존 패턴 유지)
+2. [ ] `ci.yml` 작성 — PR 트리거, lint/typecheck/test/build
+3. [ ] `cd.yml` 작성 — main 머지 트리거, Docker build/push/deploy
+4. [ ] Dockerfile 확인 (없으면 생성)
+5. [ ] `/health` 엔드포인트 확인 (없으면 BE에게 요청)
+6. [ ] GitHub Secrets 목록 정리 및 README에 기록
+7. [ ] GitHub Environment 설정 (staging, production) 안내
+8. [ ] Branch Protection Rule 설정 안내 (CI 통과 필수)

package/template/.claude/skills/write-design-spec/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: write-design-spec
+description: "디자이너 Agent가 FE Agent에게 전달할 디자인 명세(context/02_design_spec.md)를 작성할 때 포맷 기준으로 사용하는 skill. 디자인 토큰, 공통 컴포넌트(Props+상태), 화면별 레이아웃(ASCII+반응형), 인터랙션, 접근성 가이드 5개 섹션을 FE가 바로 구현할 수 있는 수준으로 작성한다. '디자인 명세 작성', '02_design_spec 생성', '화면 설계', '컴포넌트 정의', 'FE에게 전달할 디자인' 등의 상황에서 반드시 사용한다."
+---
+
+# Write Design Spec
+
+디자이너 Agent가 `context/02_design_spec.md`를 작성할 때 따르는 포맷 기준이다.
+
+이 명세의 독자는 FE 개발자다. FE가 이 문서 하나만 읽고 디자인 의도대로 구현할 수 있어야 한다. 그래서 모든 값은 구체적인 숫자로, 모든 상태는 빠짐없이, 모든 레이아웃은 시각적으로 표현한다.
+
+---
+
+## Step 1: 입력 확인
+
+아래 파일을 읽는다:
+- `context/00_requirements.md` — 프로젝트 현황, 기술 스택
+- `context/01_plan.md` — 화면 목록(S-xx), 기능 명세(F-xx)
+
+`01_plan.md`의 화면 목록이 이 명세의 범위를 결정한다. 기획안에 없는 화면을 임의로 추가하지 않는다.
+
+`explore-design-system` skill을 통해 기존 디자인 시스템 현황을 파악했다면 그 결과도 참고한다. 기존 토큰/컴포넌트가 있으면 재사용하고, 없는 것만 새로 정의한다.
+
+---
+
+## Step 2: 5개 섹션으로 명세 작성
+
+### 섹션 1: 디자인 토큰
+
+서비스 전체에서 일관되게 사용할 기본 값을 정의한다. 기존 디자인 시스템이 있으면 그것을 기반으로 확장하고, 없으면 새로 정의한다.
+
+```markdown
+## 1. 디자인 토큰
+
+### 색상 (Color)
+
+| 토큰명 | 값 | 용도 |
+|--------|------|------|
+| --color-primary | #3182ce | 주요 액션, 링크 |
+| --color-primary-hover | #2b6cb0 | Primary hover 상태 |
+| --color-secondary | #718096 | 보조 요소 |
+| --color-bg | #ffffff | 페이지 배경 |
+| --color-surface | #f7fafc | 카드/섹션 배경 |
+| --color-border | #e2e8f0 | 테두리 |
+| --color-error | #e53e3e | 에러 메시지, 유효성 |
+| --color-success | #38a169 | 성공 상태 |
+| --color-warning | #dd6b20 | 경고 |
+| --color-text-primary | #1a202c | 본문 텍스트 |
+| --color-text-secondary | #718096 | 보조 텍스트 |
+| --color-text-disabled | #a0aec0 | 비활성 텍스트 |
+
+### 타이포그래피 (Typography)
+
+| 토큰명 | Size | Weight | Line Height | 용도 |
+|--------|------|--------|-------------|------|
+| H1 | 28px | 700 | 1.3 | 페이지 제목 |
+| H2 | 22px | 600 | 1.35 | 섹션 제목 |
+| H3 | 18px | 600 | 1.4 | 서브 섹션 |
+| Body1 | 16px | 400 | 1.6 | 본문 |
+| Body2 | 14px | 400 | 1.5 | 보조 본문 |
+| Caption | 12px | 400 | 1.4 | 캡션, 힌트 |
+
+Font Family: `'Pretendard', -apple-system, sans-serif`
+
+### 간격 (Spacing)
+
+| 토큰명 | 값 |
+|--------|------|
+| --space-xs | 4px |
+| --space-sm | 8px |
+| --space-md | 16px |
+| --space-lg | 24px |
+| --space-xl | 32px |
+| --space-2xl | 48px |
+
+### 반경 (Border Radius)
+
+| 토큰명 | 값 |
+|--------|------|
+| --radius-sm | 4px |
+| --radius-md | 8px |
+| --radius-lg | 12px |
+| --radius-full | 9999px |
+
+### 그림자 (Shadow)
+
+| 토큰명 | 값 |
+|--------|------|
+| --shadow-sm | 0 1px 2px rgba(0,0,0,0.05) |
+| --shadow-md | 0 4px 6px rgba(0,0,0,0.07) |
+| --shadow-lg | 0 10px 15px rgba(0,0,0,0.1) |
+```
+
+위 값들은 예시다. 프로젝트에 맞는 실제 값을 사용한다. 핵심은 모든 값에 **토큰명 + 구체적 수치 + 용도**를 명시하는 것이다.
+
+---
+
+### 섹션 2: 공통 컴포넌트
+
+재사용되는 UI 컴포넌트를 정의한다. 각 컴포넌트는 아래 4가지를 포함한다:
+
+1. **TypeScript Props 타입**
+2. **상태별 스타일** (default / hover / focus / active / disabled / loading / error)
+3. **크기 변형** (sm / md / lg)
+4. **사용 예시**
+
+```markdown
+## 2. 공통 컴포넌트
+
+### Button
+
+\`\`\`typescript
+interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';
+  size: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  loading?: boolean;
+  leftIcon?: ReactNode;
+  rightIcon?: ReactNode;
+  fullWidth?: boolean;
+  children: ReactNode;
+  onClick?: () => void;
+}
+\`\`\`
+
+**크기별 스타일:**
+
+| Size | Height | Padding (H) | Font Size | Border Radius |
+|------|--------|-------------|-----------|---------------|
+| sm | 32px | 12px | 13px | --radius-sm |
+| md | 40px | 16px | 14px | --radius-md |
+| lg | 48px | 20px | 16px | --radius-md |
+
+**variant=primary 상태별 스타일:**
+
+| 상태 | Background | Text | Border | 기타 |
+|------|-----------|------|--------|------|
+| Default | --color-primary | #ffffff | none | cursor: pointer |
+| Hover | --color-primary-hover | #ffffff | none | — |
+| Focus | --color-primary | #ffffff | 2px solid #63b3ed | outline-offset: 2px |
+| Active | #2c5282 | #ffffff | none | — |
+| Disabled | #cbd5e0 | #a0aec0 | none | cursor: not-allowed, opacity: 0.6 |
+| Loading | --color-primary | — | none | spinner 표시, 텍스트 숨김 |
+```
+
+**반드시 정의할 컴포넌트 목록:**
+- Button
+- Input (text, password, search)
+- Select / Dropdown
+- Checkbox, Radio
+- Modal / Dialog
+- Toast / Alert
+- Loading Spinner
+- Empty State (데이터 없음)
+- Error State (에러 발생)
+- Skeleton (로딩 플레이스홀더)
+
+기획안의 기능에 따라 추가 컴포넌트를 정의한다. 예: Table, Card, Badge, Avatar, Tabs 등.
+
+---
+
+### 섹션 3: 화면별 레이아웃
+
+기획안의 화면 목록(S-xx)을 기준으로 각 화면의 레이아웃을 정의한다.
+
+각 화면은 아래 구조로 작성한다:
+
+```markdown
+## 3. 화면별 레이아웃
+
+### S-01: 로그인
+
+**경로:** `/login`
+**관련 기능:** F-01, F-02
+
+**Desktop (1280px+)**
+\`\`\`
+┌─────────────────────────────────────┐
+│              Header (64px)          │
+├─────────────────────────────────────┤
+│                                     │
+│    ┌─────────────────────┐          │
+│    │   Logo              │          │
+│    │   48px × 48px       │          │
+│    ├─────────────────────┤          │
+│    │   Email Input       │  400px   │
+│    │   Password Input    │  width   │
+│    │   [로그인 버튼]      │  center  │
+│    │   ───────────────   │          │
+│    │   소셜 로그인 영역   │          │
+│    └─────────────────────┘          │
+│                                     │
+└─────────────────────────────────────┘
+\`\`\`
+
+**Tablet (768px)**
+\`\`\`
+┌───────────────────────┐
+│     Header (56px)     │
+├───────────────────────┤
+│   Login Form (360px)  │
+│   center aligned      │
+└───────────────────────┘
+\`\`\`
+
+**Mobile (375px)**
+\`\`\`
+┌─────────────────┐
+│  Header (48px)  │
+├─────────────────┤
+│  Logo           │
+│  Email Input    │  padding:
+│  Password Input │  16px
+│  [로그인 버튼]   │  full-width
+│  소셜 로그인     │
+└─────────────────┘
+\`\`\`
+
+**컴포넌트 배치:**
+
+| 영역 | 컴포넌트 | Props |
+|------|---------|-------|
+| 이메일 | Input | type="email", size="lg", placeholder="이메일" |
+| 비밀번호 | Input | type="password", size="lg", placeholder="비밀번호" |
+| 로그인 | Button | variant="primary", size="lg", fullWidth |
+
+**화면 상태:**
+
+| 상태 | 설명 |
+|------|------|
+| Default | 빈 폼, 로그인 버튼 비활성 |
+| Filled | 두 필드 입력 완료, 로그인 버튼 활성 |
+| Loading | 로그인 버튼 loading 상태, 입력 disabled |
+| Error | Input error 상태 + 에러 메시지 표시 |
+```
+
+**반응형 기준점:**
+- Desktop: 1280px 이상
+- Tablet: 768px ~ 1279px
+- Mobile: 375px ~ 767px
+
+모든 화면에 3가지 해상도 레이아웃을 정의한다. 레이아웃이 변하지 않는 경우 "Desktop과 동일"로 표기해도 된다.
+
+---
+
+### 섹션 4: 인터랙션 & 애니메이션
+
+화면 전환, 컴포넌트 동작의 시각적 행동을 정의한다.
+
+```markdown
+## 4. 인터랙션 & 애니메이션
+
+### 전역 설정
+
+| 항목 | 값 |
+|------|------|
+| 기본 transition | 150ms ease-in-out |
+| 페이지 전환 | fade 200ms |
+| easing 함수 | cubic-bezier(0.4, 0, 0.2, 1) |
+
+### 컴포넌트별 애니메이션
+
+| 컴포넌트 | 트리거 | 애니메이션 | Duration |
+|---------|--------|-----------|----------|
+| Modal | 열기 | fade-in + scale(0.95→1) | 200ms |
+| Modal | 닫기 | fade-out + scale(1→0.95) | 150ms |
+| Toast | 표시 | slide-down from top | 300ms |
+| Toast | 사라짐 | fade-out | 200ms, 3초 후 자동 |
+| Dropdown | 열기 | fade-in + slide-down(4px) | 150ms |
+| Skeleton | 대기 | pulse (opacity 0.4↔1) | 1.5s infinite |
+
+### 스크롤 동작
+
+| 화면 | 방식 | 비고 |
+|------|------|------|
+| 목록형 | 무한 스크롤 / 페이지네이션 | (기획안 기준) |
+| 상세 | 일반 스크롤 | — |
+
+### 로딩 전략
+
+| 상황 | 처리 |
+|------|------|
+| 페이지 초기 로딩 | Skeleton 표시 |
+| 버튼 액션 후 | 버튼 loading 상태 |
+| 목록 추가 로딩 | 하단 spinner |
+| 이미지 로딩 | blur placeholder → fade-in |
+```
+
+---
+
+### 섹션 5: 접근성 가이드
+
+```markdown
+## 5. 접근성 가이드
+
+### 색상 대비
+
+| 조합 | 대비 비율 | WCAG AA |
+|------|----------|---------|
+| text-primary / bg | 최소 4.5:1 | 통과 |
+| text-secondary / bg | 최소 3:1 | 통과 |
+| primary button / white text | 최소 4.5:1 | 통과 |
+
+### 포커스 스타일
+
+모든 인터랙티브 요소에 visible focus indicator를 제공한다:
+- `outline: 2px solid --color-primary`
+- `outline-offset: 2px`
+- `:focus-visible`만 적용 (마우스 클릭 시 미표시)
+
+### 키보드 네비게이션
+
+| 컴포넌트 | 키 | 동작 |
+|---------|------|------|
+| Modal | Escape | 닫기 |
+| Modal | Tab | 내부 포커스 트랩 |
+| Dropdown | ArrowDown/Up | 항목 이동 |
+| Dropdown | Enter | 선택 |
+| Dropdown | Escape | 닫기 |
+
+### 스크린리더
+
+| 컴포넌트 | aria 속성 |
+|---------|-----------|
+| Modal | role="dialog", aria-modal="true", aria-labelledby |
+| Toast | role="alert", aria-live="polite" |
+| Loading | aria-busy="true", aria-label="로딩 중" |
+| Icon Button | aria-label (텍스트 없는 버튼) |
+```
+
+---
+
+## Step 3: 저장 및 보고
+
+완성된 명세를 `context/02_design_spec.md`에 저장한다.
+
+저장 후 보고:
+
+```
+[디자인 명세 완성]
+- 저장 위치: context/02_design_spec.md
+- 디자인 토큰: 색상 N개, 타이포 N개, 간격 N개
+- 공통 컴포넌트: N개 (각 상태/크기 정의 완료)
+- 화면 레이아웃: N개 (반응형 3단계)
+- 인터랙션: N개 정의
+- 접근성: WCAG AA 기준 적용
+```
+
+---
+
+## 품질 체크리스트
+
+저장 전 점검한다:
+
+- [ ] 모든 색상이 hex 코드인가? (`#3182ce` O, `blue` X)
+- [ ] 모든 크기에 단위가 있는가? (`16px` O, `16` X)
+- [ ] 모든 duration에 단위가 있는가? (`200ms` O, `빠르게` X)
+- [ ] 모호한 표현이 없는가? (`적당히`, `자연스럽게`, `예쁘게` X)
+- [ ] 모든 컴포넌트에 Props 타입이 TypeScript로 정의되었는가?
+- [ ] 모든 컴포넌트에 최소 default/hover/focus/disabled 상태가 있는가?
+- [ ] 모든 화면에 Desktop/Tablet/Mobile 레이아웃이 있는가?
+- [ ] 기획안의 화면 목록(S-xx)을 모두 커버하는가?
+- [ ] 기획안에 없는 화면을 임의 추가하지 않았는가?