Nuxt FE AI Standardization

본 문서는 Nuxt 3 기반 FE 개발 프로세스를 Claude Code AI Skills과 통합하여 체계적인 표준화 체계를 구축하기 위한 로드맵입니다. 팀 전체가 동일한 품질과 패턴으로 개발할 수 있도록 각 단계별 지능형 업무 매뉴얼(Skills)을 정의합니다.

1.1 프로젝트 목적

• 개발 프로세스 전 단계(기획~검증)에 걸친 AI 어시스턴트 활용 체계 수립
• Claude Code Skills을 활용한 반복 작업 자동화 및 코드 품질 균일화
• 신규 인력의 빠른 온보딩 및 팀 간 일관된 코드 컨벤션 유지
• 개발 생산성 향상과 동시에 코드 리뷰 품질 확보

1.2 Claude Code Skills이란?

Claude Code Skills은 특정 작업 도메인에 대해 Claude가 전문적으로 수행할 수 있도록 구조화된 업무 지시서입니다. SKILL.md 파일을 중심으로, 트리거 조건·실행 절차·출력 포맷이 정의되어 있어 팀원 누구나 일관된 결과를 얻을 수 있습니다.

FE 개발 전체 라이프사이클의 각 Phase마다 전용 Claude Code Skill을 배치합니다.

Skill 동작 절차

1. 입력 분석 — 기획서/PRD 문서를 파싱하여 기능 요구사항, 화면 목록, 사용자 플로우를 추출
2. 페이지 맵 생성 — Nuxt의 pages/ 디렉토리 구조에 맞는 라우팅 맵을 자동 설계
3. 컴포넌트 트리 도출 — Atomic Design 원칙에 따른 컴포넌트 분해
4. 데이터 플로우 정의 — 각 페이지/컴포넌트별 필요 데이터, API 엔드포인트 매핑
5. Mermaid 플로우차트 출력 — 화면 전환 흐름, 조건 분기를 시각화

다음 기획서를 분석해서 Nuxt 3 프로젝트 구조를 설계해줘.

[기획서 첨부 또는 내용 붙여넣기]

출력 형식:
1. pages/ 디렉토리 라우팅 구조
2. components/ Atomic Design 기반 컴포넌트 트리
3. 각 페이지별 필요 API 엔드포인트 목록
4. Mermaid 플로우차트 (화면 전환 흐름)
5. composables/ 에 필요한 공통 로직 목록

HTML 시멘틱 태그 가이드

Tailwind 클래스 순서 컨벤션

Phase 3-1 — Nuxt 공식문서 참조 구조 (references/)

디렉토리 구조 표준

Phase 3-2 — 페이지·레이아웃·미들웨어 생성 v1.2

Skill 동작 절차

1. 기존 구조 탐색 — pages/, layouts/, middleware/ 디렉토리 확인
2. 라우트 구조 결정 — 파일 기반 라우팅 경로 확인, 동적 파라미터([id].vue), catch-all([...slug].vue)
3. 레이아웃 선택/생성 — 기존 레이아웃 재사용 우선, 필요 시 신규 생성
4. 페이지 생성 — <script setup lang="ts">, definePageMeta, useSeoMeta 적용
5. 미들웨어 추가 — Named middleware(middleware/auth.ts) 또는 인라인 방식
6. 검증 — TypeScript 오류 확인, 라우트 인식 확인

동적 라우트 패턴

Phase 3-3 — Vue 컴포넌트 신규 생성 v1.2

Skill 동작 절차

1. 요구사항 확인 — 컴포넌트 목적, props, emits, 사용 위치 파악
2. 기존 컴포넌트 탐색 — components/에서 유사 컴포넌트 확인, 재활용 검토
3. 파일 위치 결정 — base/ (Atoms), common/ (Molecules), domain/ (Organisms)
4. 인터페이스 설계 — defineProps<T>(), defineEmits<{}>() 제네릭 형태
5. 구현 — <script setup lang="ts">, Tailwind 유틸리티 클래스
6. 검증 — TypeScript 오류, 200줄 이내 확인

분리 기준

Phase 3-4 — Composable·데이터 페칭 v1.2

데이터 페칭 판단 기준표

데이터 페칭 패턴 가이드

Pinia 스토어 설계 규칙

• Setup Store 문법 사용 (Option Store 대비 composable 호환성 우수)
• 스토어 네이밍: use[Domain]Store (useAuthStore, useCartStore)
• 상태 최소화 원칙: 파생 가능한 값은 computed로 처리
• Action에서 API 호출 금지: composable(useApi)에서 호출 후 결과만 저장
• 스토어 간 의존성 최소화: 순환 참조 금지

Phase 4-1 — Pinia 스토어 생성 v1.2

Skill 동작 절차

1. 스토어 필요성 판단 — 서버 데이터 → composable, 로컬 상태 → ref, 공유 상태 → 스토어
2. 기존 스토어 탐색 — stores/ 디렉토리 확인, 중복 방지
3. 상태 설계 — TypeScript 인터페이스, 최소한의 원시 상태만 저장
4. Setup Store 구현 — state(ref), getters(computed), actions(함수)
5. 검증 — TypeScript 오류, SSR hydration 호환성

스토어 필요성 판단 가이드

Phase 4-2 — Nitro 서버 라우트 (BFF) v1.2

Skill 동작 절차

1. 라우트 목적 파악 — BFF 프록시, 데이터 변환, 인증, 서버 전용 로직
2. 기존 서버 라우트 탐색 — server/api/, server/utils/, server/middleware/ 확인
3. HTTP 메서드 및 파일 네이밍 — xxx.get.ts, xxx.post.ts, xxx.delete.ts
4. 요청/응답 타입 정의 — readBody<T>(), getQuery(), getRouterParam()
5. 핸들러 구현 — defineEventHandler, 입력 검증, createError 에러 처리
6. 클라이언트 연결 — composable에서 useFetch('/api/xxx') 연결 안내

서버 디렉토리 구조

Phase 5는 기획 요구사항 검증(5-1)과 성능 최적화(5-2)를 통합한 검증 단계입니다. Phase 1에서 정의한 요구사항 대비 실제 구현 결과를 비교 검증하고, 런타임 퍼포먼스를 최적화합니다.

Phase 5-1 — 기획 요구사항 검증

Phase 5-2 — 성능 최적화 (CWV)

성능 최적화 체크리스트

이 Nuxt 3 프로젝트의 성능을 감사하고 최적화 방안을 제시해줘.

[프로젝트 경로 또는 주요 파일]

감사 범위:
- Core Web Vitals (LCP < 2.5s, CLS < 0.1, INP < 200ms)
- 번들 사이즈 분석 (analyze: true로 리포트 확인)
- 이미지 최적화 상태 (NuxtImg 활용 여부)
- SSR/SSG/ISR 렌더링 전략 적정성
- routeRules 캐싱 전략 검증
- 불필요한 클라이언트 JS hydration 확인

2026년 현재, 전통적 SEO만으로는 디지털 가시성을 확보할 수 없습니다. Gartner는 전통 검색 볼륨이 25% 감소할 것으로 전망하며, ChatGPT·Perplexity·Google AI Overview가 새로운 검색 채널로 부상하고 있습니다. 이 Skill은 SEO + GEO + AEO 3계층 최적화를 통합합니다.

SEO · GEO · AEO 3계층 이해

Layer 1 — SEO 체크리스트

Layer 2 — AEO 체크리스트

Layer 3 — GEO 체크리스트

SEO 메타 자동화 패턴

// composables/usePageSeo.ts — SEO·GEO 통합 메타 자동화

GEO·AEO 감사 프롬프트

이 Nuxt 3 프로젝트의 SEO·GEO·AEO를 3계층으로 감사해줘.

[프로젝트 경로 또는 주요 파일]

Layer 1 — SEO 감사:
- useSeoMeta 적용 완성도 (title, description, OG, canonical)
- JSON-LD 구조화 데이터 (Schema.org 타입 적정성)
- sitemap.xml, robots.txt 설정
- OG 이미지 동적 생성 여부

Layer 2 — AEO 감사:
- H2 헤딩이 질문형으로 작성되었는가
- 각 섹션이 질문 직후 즉답(200자 이내)을 제공하는가
- FAQPage, HowTo, Breadcrumb 스키마 적용 여부

Layer 3 — GEO 감사:
- 통계·수치 데이터가 출처와 함께 포함되었는가
- 각 콘텐츠 블록이 독립적으로 AI에 인용 가능한 구조인가
- 저자(Author) 정보와 E-E-A-T 신호가 충분한가
- dateModified가 최신 상태인가

공식 Skills 폴더 구조 가이드 🔗 공식문서

Claude Code 공식문서에 따르면, Skill을 저장하는 위치에 따라 적용 범위가 결정됩니다.
우선순위: Enterprise > Personal > Project 순이며, Plugin Skills는 네임스페이스(plugin-name:skill-name)를 사용하므로 충돌하지 않습니다.

공식 Skill 디렉토리 구조

각 Skill은 SKILL.md를 진입점으로 하는 디렉토리입니다. SKILL.md만 필수이며, 나머지 파일은 선택적입니다.

공식 네이밍 규칙

전체 Skills 폴더 구조 (프로젝트 적용)

Skill 설계 3원칙

도입 타임라인

성공 지표 (KPI)

본 문서는 퍼블리싱웹 FE 내부 공유용이며, 프로젝트 진행에 따라 지속 업데이트됩니다.
문의: 퍼블리싱웹 FE · 최종 수정: 2026.04.23 · v1.2