35 KiB
title, source, author, published, created, description, tags
| title | source | author | published | created | description | tags | |
|---|---|---|---|---|---|---|---|
| Nuxt FE AI 표준화 로드맵 v1.2 | https://sandbox-item.smilegatemegaport.com/Webdev01_UI/fe/fe-ai.html | 2026-04-23 |
|
Nuxt FE AI Standardization
Claude Code Skills 기반 지능형 업무 매뉴얼 — FE 개발 프로세스 표준화 로드맵
본 문서는 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 파일을 중심으로, 트리거 조건·실행 절차·출력 포맷이 정의되어 있어 팀원 누구나 일관된 결과를 얻을 수 있습니다.
| 구성 요소 | 설명 | 예시 |
|---|---|---|
| SKILL.md | 핵심 지시서 (500줄 이내 권장) | 트리거, 절차, 출력 포맷 정의 |
| scripts/ | 반복 작업 자동화 스크립트 | 컴포넌트 생성기, 린트 검사기 |
| references/ | 도메인별 참조 문서 | Nuxt 컨벤션, API 패턴 가이드 |
FE 개발 전체 라이프사이클의 각 Phase마다 전용 Claude Code Skill을 배치합니다.
🔄
v1.1 변경사항: 기존 Phase 5(성능+SEO)를 Phase 5(성능) 과 Phase 6(SEO·GEO·AEO) 로 분리했습니다. SEO Skill에 Generative Engine Optimization(GEO)과 Answer Engine Optimization(AEO)을 추가하여 AI 검색 시대에 대응합니다.
v1.2 변경사항: FE개발 단계(Phase 3~4)에 5개 서브 단계를 추가했습니다. Phase 3-2(페이지·레이아웃·미들웨어), Phase 3-3(Vue 컴포넌트 생성), Phase 3-4(Composable·데이터 페칭), Phase 4-1(Pinia 스토어), Phase 4-2(Nitro 서버 라우트)로 실제 개발 워크플로우를 세분화합니다.
| 대단계 | Phase | 핵심 활동 | Claude Skill |
|---|---|---|---|
| 기획 | Phase 1 | 요구사항 정의, 플로우차트 | requirement-analyzer/SKILL.md requirement-analyzer/references/ |
| 마크업 | Phase 2 | HTML 마크업, Tailwind 컨벤션 | markup/SKILL.md markup/references/ |
| Phase 2-0 | PSD -> 피그마 컨버팅 | SKILL 검토 중 Codia AI 디자인 (PSD to Figma) PSD Importer for Figma |
|
| Phase 2-1 | 피그마 HTML 마크업 | markup/SKILL.md markup/references/ |
|
| Phase 2-2 | 프로모션 HTML 마크업 | markup-promotion/SKILL.md markup-promotion/references/ |
|
| Phase 2-3 | EDM HTML 마크업 | markup-edm/SKILL.md markup-edm/references/ |
|
| FE개발 | Phase 3 | Nuxt 컴포넌트 아키텍처 | component-architect https://github.com/onmax/nuxt-skills/tree/main |
| Phase 3-1 | Nuxt 공식문서 기반 | nuxt/SKILL.md references/ - server.md - API routes, server middleware - middleware.md - middleware, File-based routing - plugins.md - plugins, app lifecycle - nuxt-composables.md - Nuxt composables - nuxt-components.md - NuxtLink, NuxtImg, NuxtTime - nuxt-config.md - Config, modules, auto-imports, layers |
|
| Phase 3-2 | 페이지·레이아웃·미들웨어 생성 | nuxt-page-layout/SKILL.md |
|
| Phase 3-3 | Vue 컴포넌트 신규 생성 | vue-component-create/SKILL.md |
|
| Phase 3-4 | Composable·데이터 페칭 | nuxt-composable/SKILL.md |
|
| FE개발 | Phase 4 | API 연동 | api-manager/SKILL.md api-manager/references/ |
| Phase 4-1 | Pinia 스토어 생성 | pinia-store/SKILL.md |
|
| Phase 4-2 | Nitro 서버 라우트(BFF) | nuxt-api-route/SKILL.md |
|
| 검증 | Phase 5 | 검증 | |
| Phase 5-1 | Phase 1 기획 요구사항 검증 | requirement-optimizer/SKILL.md requirement-optimizer/references/ |
|
| Phase 5-2 | 성능 최적화 (CWV) | perf-optimizer/SKILL.md perf-optimizer/references/ |
|
| 검증 | Phase 6 | SEO · GEO · AEO 검증 | seo-geo/SKILL.md seo-geo/references/ |
트리거: 요구사항, 기획서, 플로우차트, 화면정의서, 유저스토리
기획 문서를 분석하여 Nuxt 프로젝트에 적합한 구조화된 요구사항 명세(페이지 목록, 컴포넌트 트리, 라우팅 맵, 데이터 플로우)를 자동 생성합니다.
"이 기획서를 분석해서 Nuxt 페이지 구조와 컴포넌트 목록을 뽑아줘"
Skill 동작 절차
- 입력 분석 — 기획서/PRD 문서를 파싱하여 기능 요구사항, 화면 목록, 사용자 플로우를 추출
- 페이지 맵 생성 — Nuxt의 pages/ 디렉토리 구조에 맞는 라우팅 맵을 자동 설계
- 컴포넌트 트리 도출 — Atomic Design 원칙에 따른 컴포넌트 분해
- 데이터 플로우 정의 — 각 페이지/컴포넌트별 필요 데이터, API 엔드포인트 매핑
- Mermaid 플로우차트 출력 — 화면 전환 흐름, 조건 분기를 시각화
💬 프롬프트 템플릿
다음 기획서를 분석해서 Nuxt 3 프로젝트 구조를 설계해줘.
[기획서 첨부 또는 내용 붙여넣기]
출력 형식:
1. pages/ 디렉토리 라우팅 구조
2. components/ Atomic Design 기반 컴포넌트 트리
3. 각 페이지별 필요 API 엔드포인트 목록
4. Mermaid 플로우차트 (화면 전환 흐름)
5. composables/ 에 필요한 공통 로직 목록
트리거: 마크업, HTML 구조, 시멘틱, Tailwind, 클래스 순서, 접근성, ARIA, SFC 구조, 반응형
디자인 시안을 Nuxt 컴포넌트의 시멘틱 HTML + Tailwind CSS로 변환합니다. 4개 참조 문서(시멘틱 HTML, Tailwind 컨벤션, 접근성, Nuxt SFC 패턴)를 도메인별로 선택 로드합니다.
"이 디자인을 시멘틱 마크업으로 변환하고 Tailwind 클래스를 적용해줘"
트리거: PSD, 피그마 변환, PSD to Figma, 디자인 컨버팅, PSD 임포트
PSD 디자인 파일을 Figma로 변환하는 프로세스를 지원합니다. Codia AI 디자인(PSD to Figma) 및 PSD Importer for Figma 도구를 활용하여 레이어 구조를 유지하며 Figma 포맷으로 컨버팅합니다.
⚠️ SKILL 검토 중 — 도구 안정성 및 레이어 정합성 평가 진행 중
"이 PSD 파일을 Figma로 변환해서 마크업 작업 준비해줘"
트리거: 피그마, Figma, 피그마 마크업, 피그마 HTML, 디자인 시안 마크업, Figma to HTML
피그마 디자인 시안을 HTML 마크업으로 변환하는 데 특화된 Skill입니다. markup Skill을 기반으로 피그마 레이어 구조 해석, 컴포넌트 매핑, 반응형 브레이크포인트 추출을 포함합니다.
"이 피그마 디자인 시안을 HTML 마크업으로 변환해줘"
HTML 시멘틱 태그 가이드
| 영역 | 시멘틱 태그 | 규칙 |
|---|---|---|
| 레이아웃 | , , , | 페이지 대구조 정의, div 남용 금지 |
| 섹션 | 의미 단위 그룹핑, aria-label 필수 | |
| 제목 | ~ |
페이지당 h1 1개, 건너뛰기 금지 |
| 목록 |
|
나열형 데이터는 반드시 리스트 태그 |
| 폼 | , , | 모든 input에 label 연결 필수 |
| 인터랙티브 | , , | 클릭 가능 요소는 반드시 시멘틱 태그 |
Tailwind 클래스 순서 컨벤션
| 순서 | 카테고리 | 대표 클래스 | 기억법 |
|---|---|---|---|
| 1 | Layout | flex, grid, block, hidden | "어떻게 배치?" |
| 2 | Position | relative, absolute, fixed, z-* | "어디에 놓을까?" |
| 3 | Box Model | w-*, h-*, p-*, m-*, gap-* | "얼마나 크게?" |
| 4 | Typography | text-*, font-*, leading-* | "글자를 어떻게?" |
| 5 | Visual | bg-*, border-*, rounded-*, shadow-* | "어떻게 보이게?" |
| 6 | State | hover:*, focus:*, sm:*, md:* | "상태가 바뀌면?" |
| 7 | Motion | transition-*, duration-*, animate-* | "움직임은?" |
트리거: 프로모션, 랜딩페이지, 이벤트 페이지, 프로모션 마크업, 캠페인 페이지
프로모션 및 랜딩페이지에 특화된 HTML 마크업을 생성합니다. 캠페인 성격에 맞는 시멘틱 구조, 반응형 레이아웃, CTA 배치 패턴을 포함합니다.
"이 프로모션 디자인을 랜딩페이지 HTML 마크업으로 변환해줘"
트리거: EDM, 이메일, 뉴스레터, 메일 템플릿, 이메일 마크업
EDM(Email Direct Marketing) 및 뉴스레터용 HTML 마크업을 생성합니다. 이메일 클라이언트 호환성, 테이블 기반 레이아웃, 인라인 스타일 패턴을 포함합니다.
"이 디자인을 이메일 뉴스레터 HTML로 변환해줘"
트리거: Nuxt 컴포넌트, 페이지, composable, 레이아웃, 미들웨어, 플러그인
Nuxt 3 공식 가이드를 기반으로 컴포넌트를 설계합니다. auto-import, composables 패턴, server/ 디렉토리 활용, 레이아웃 전략을 포함한 전체 아키텍처를 제안합니다.
"이 기능을 Nuxt 3 Best Practice에 맞게 컴포넌트로 설계해줘"
Phase 3-1 — Nuxt 공식문서 참조 구조 (references/)
| 참조 파일 | Nuxt 공홈 출처 | 로드 트리거 |
|---|---|---|
server.md |
API routes, server middleware | 서버 API, 미들웨어 작업 시 |
middleware.md |
Middleware, File-based routing | 미들웨어, 라우팅 설계 시 |
plugins.md |
Plugins, app lifecycle | 플러그인, 앱 라이프사이클 작업 시 |
nuxt-composables.md |
Nuxt composables | composable 작성 시 |
nuxt-components.md |
NuxtLink, NuxtImg, NuxtTime | Nuxt 내장 컴포넌트 사용 시 |
nuxt-config.md |
Configuration, modules, auto-imports, layers | Nuxt 설정, 모듈 구성 시 |
트리거: Nuxt 공식문서, Nuxt 가이드, Nuxt API, NuxtLink, NuxtImg, definePageMeta, useFetch, server/api
Nuxt 공식문서를 기반으로 Best Practice에 맞는 코드를 생성합니다. 6개 참조 문서(server, routing, middleware-plugins, composables, components, config)를 컨텍스트에 따라 선택적으로 로드합니다.
"Nuxt 공식 가이드 기반으로 이 기능을 구현해줘"
디렉토리 구조 표준
project structure project-root/ ├── app.vue # 루트 컴포넌트 ├── nuxt.config.ts # Nuxt 설정 ├── pages/ # 파일 기반 라우팅 ├── components/ # Auto-import 컴포넌트 │ ├── base/ # Atoms (BaseButton, BaseInput) │ ├── common/ # Molecules (SearchBar, Card) │ └── domain/ # Organisms (ProductList) ├── composables/ # Auto-import 로직 ├── layouts/ # 레이아웃 템플릿 ├── middleware/ # 라우트 미들웨어 ├── plugins/ # 플러그인 ├── server/ # 서버 API (Nitro) ├── stores/ # Pinia 스토어 ├── types/ # TypeScript 타입 └── utils/ # 유틸리티 함수
Phase 3-2 — 페이지·레이아웃·미들웨어 생성
트리거: 페이지 만들어줘, 레이아웃 추가, 미들웨어 작성, 라우트 추가, 새 페이지, page, layout, middleware
Nuxt 3의 파일 기반 라우팅 체계에 맞춰 페이지, 레이아웃, 미들웨어를 생성합니다. definePageMeta로 layout·middleware를 연결하고, useSeoMeta로 SEO 메타태그를 설정합니다.
"새 페이지를 만들고 레이아웃과 인증 미들웨어를 연결해줘"
Skill 동작 절차
- 기존 구조 탐색 —
pages/,layouts/,middleware/디렉토리 확인 - 라우트 구조 결정 — 파일 기반 라우팅 경로 확인, 동적 파라미터(
[id].vue), catch-all([...slug].vue) - 레이아웃 선택/생성 — 기존 레이아웃 재사용 우선, 필요 시 신규 생성
- 페이지 생성 —
<script setup lang="ts">,definePageMeta,useSeoMeta적용 - 미들웨어 추가 — Named middleware(
middleware/auth.ts) 또는 인라인 방식 - 검증 — TypeScript 오류 확인, 라우트 인식 확인
동적 라우트 패턴
| 파일명 | 라우트 | 예시 URL |
|---|---|---|
pages/users/[id].vue |
/users/:id |
/users/123 |
pages/posts/[...slug].vue |
/posts/:slug(.*) |
/posts/2026/04/hello |
pages/[[optional]].vue |
/:optional? |
/ 또는 /about |
⚠️ definePageMeta에는 정적/직렬화 가능한 값만 허용. 런타임 표현식 사용 불가.
Phase 3-3 — Vue 컴포넌트 신규 생성
트리거: 컴포넌트 만들어줘, 새 컴포넌트, UI 컴포넌트 추가, 버튼 만들어줘, 카드 컴포넌트
팀 컨벤션에 맞는 새로운 Vue 3 컴포넌트를 생성합니다. vue-component-review skill과의 역할 구분: review는 기존 코드 점검, create는 새 파일 생성입니다.
"사용자 프로필 카드 컴포넌트를 만들어줘"
Skill 동작 절차
- 요구사항 확인 — 컴포넌트 목적, props, emits, 사용 위치 파악
- 기존 컴포넌트 탐색 —
components/에서 유사 컴포넌트 확인, 재활용 검토 - 파일 위치 결정 —
base/(Atoms),common/(Molecules),domain/(Organisms) - 인터페이스 설계 —
defineProps<T>(),defineEmits<{}>()제네릭 형태 - 구현 —
<script setup lang="ts">, Tailwind 유틸리티 클래스 - 검증 — TypeScript 오류, 200줄 이내 확인
분리 기준
| 상황 | 조치 |
|---|---|
| 파일 200줄 초과 | 하위 컴포넌트로 분리 |
| script 로직 30줄 초과 | composable로 추출 |
| Props 5개 초과 | 객체 prop으로 그룹핑 |
| 동일 패턴 3회 이상 반복 | 공통 컴포넌트로 추출 |
Phase 3-4 — Composable·데이터 페칭
트리거: composable 만들어줘, useFetch 패턴, 데이터 페칭, useAsyncData, 커스텀 훅, 로직 추출
Nuxt 3의 composable 함수와 데이터 페칭 패턴을 생성합니다. 데이터 페칭 composable(서버 상태)과 로직 composable(UI 상태/행동)을 구분합니다.
"유저 프로필 데이터를 가져오는 composable을 만들어줘"
데이터 페칭 판단 기준표
| 시나리오 | 추천 방식 | 이유 |
|---|---|---|
| 단순 REST GET | useFetch |
자동 key 중복 방지, 간결 |
| 커스텀 key·transform 필요 | useAsyncData |
캐싱/변환 세밀 제어 |
| 이벤트 핸들러 내 POST/PUT/DELETE | $fetch |
SSR 불필요, fire-and-forget |
| 의존 쿼리 (체이닝) | useAsyncData + watch |
실행 순서 제어 |
⚠️ $fetch를 <script setup>에서 직접 사용하면 SSR 시 서버/클라이언트 양쪽에서 실행되어 이중 요청 발생. 반드시 useFetch 또는 useAsyncData로 감싸야 합니다.
트리거: API 연동, useFetch, useAsyncData, Pinia, 스토어, 상태관리, 에러 핸들링
Nuxt 3의 데이터 페칭 유틸리티와 Pinia 스토어를 조합한 표준 패턴을 생성합니다.
"이 API를 Nuxt에서 연동하고 Pinia 스토어로 상태관리해줘"
데이터 페칭 패턴 가이드
| 패턴 | 사용 시점 | 특징 |
|---|---|---|
useFetch() |
컴포넌트에서 직접 API 호출 | SSR 지원, 자동 캐싱, key 기반 중복 방지 |
useAsyncData() |
복잡한 데이터 변환 필요 시 | 커스텀 fetch 로직, transform 지원 |
$fetch() |
이벤트 핸들러 내 API 호출 | 클라이언트 사이드만, SSR 미지원 |
server/api/ |
BFF 패턴, 서버 사이드 로직 | Nitro 기반, API 키 보호 |
Pinia 스토어 설계 규칙
- Setup Store 문법 사용 (Option Store 대비 composable 호환성 우수)
- 스토어 네이밍: use[Domain]Store (useAuthStore, useCartStore)
- 상태 최소화 원칙: 파생 가능한 값은 computed로 처리
- Action에서 API 호출 금지: composable(useApi)에서 호출 후 결과만 저장
- 스토어 간 의존성 최소화: 순환 참조 금지
Phase 4-1 — Pinia 스토어 생성
트리거: 스토어 만들어줘, Pinia 스토어, 전역 상태, store 추가, 상태관리, useAuthStore, useCartStore
앱 전역에서 공유하는 상태를 Pinia 스토어로 관리합니다. Setup Store(Composition API) 문법을 기본으로 사용하며, 서버 데이터는 composable(useFetch)이 담당합니다.
"인증 상태를 관리하는 Pinia 스토어를 만들어줘"
Skill 동작 절차
- 스토어 필요성 판단 — 서버 데이터 → composable, 로컬 상태 → ref, 공유 상태 → 스토어
- 기존 스토어 탐색 —
stores/디렉토리 확인, 중복 방지 - 상태 설계 — TypeScript 인터페이스, 최소한의 원시 상태만 저장
- Setup Store 구현 — state(
ref), getters(computed), actions(함수) - 검증 — TypeScript 오류, SSR hydration 호환성
스토어 필요성 판단 가이드
| 상태의 성격 | 해결 방법 | 예시 |
|---|---|---|
| 서버 데이터 (API 응답) | composable + useFetch |
상품 목록, 유저 프로필 |
| 앱 전역 공유 상태 | Pinia 스토어 | 인증, 테마, 사이드바 |
| 단일 페이지 폼 상태 | 로컬 ref/reactive |
회원가입 폼 |
| 부모↔자식 공유 상태 | props/emits, provide/inject |
아코디언 그룹 |
| URL 기반 상태 | 라우트 쿼리/파라미터 | 필터, 정렬, 페이지 |
⚠️ SSR hydration 주의: 스토어 상태는 HTML로 직렬화됨. 함수, DOM 참조, 클래스 인스턴스 등 직렬화 불가능한 값 저장 금지.
Phase 4-2 — Nitro 서버 라우트 (BFF)
트리거: API 라우트 만들어줘, 서버 라우트, server/api, BFF, 프록시 API, 서버 미들웨어, Nitro, defineEventHandler
Nuxt 3의 Nitro 서버 라우트를 생성합니다. BFF 프록시 패턴, API 엔드포인트, 서버 미들웨어, 서버 유틸리티를 포함합니다.
"유저 조회 API 라우트를 BFF 프록시 패턴으로 만들어줘"
Skill 동작 절차
- 라우트 목적 파악 — BFF 프록시, 데이터 변환, 인증, 서버 전용 로직
- 기존 서버 라우트 탐색 —
server/api/,server/utils/,server/middleware/확인 - HTTP 메서드 및 파일 네이밍 —
xxx.get.ts,xxx.post.ts,xxx.delete.ts - 요청/응답 타입 정의 —
readBody<T>(),getQuery(),getRouterParam() - 핸들러 구현 —
defineEventHandler, 입력 검증,createError에러 처리 - 클라이언트 연결 — composable에서
useFetch('/api/xxx')연결 안내
서버 디렉토리 구조
server/
├── api/
│ ├── auth/
│ │ ├── login.post.ts
│ │ └── logout.post.ts
│ └── users/
│ ├── index.get.ts # GET /api/users
│ ├── index.post.ts # POST /api/users
│ └── [id].get.ts # GET /api/users/:id
├── middleware/
│ └── auth.ts # 모든 요청에 적용
└── utils/
└── api-client.ts # 공유 유틸리티
⚠️ 비밀키는 useRuntimeConfig() 서버 전용 필드로만 접근. 클라이언트에 노출 금지. 서버 라우트는 Nitro(Node.js) 컨텍스트이므로 Vue 반응성(ref, computed)과 브라우저 API 사용 불가.
Phase 5는 기획 요구사항 검증(5-1) 과 성능 최적화(5-2) 를 통합한 검증 단계입니다. Phase 1에서 정의한 요구사항 대비 실제 구현 결과를 비교 검증하고, 런타임 퍼포먼스를 최적화합니다.
Phase 5-1 — 기획 요구사항 검증
트리거: 요구사항 검증, 기획 대비 구현 비교, 기능 누락 확인, 스펙 검증, 구현 완성도
Phase 1에서 정의한 요구사항 명세와 실제 구현 결과를 비교 검증합니다. 기능 누락, 스펙 불일치, 미구현 항목을 자동으로 식별하고 개선 방안을 제시합니다.
"기획서 대비 현재 구현 상태를 검증하고 누락된 기능을 찾아줘"
Phase 5-2 — 성능 최적화 (CWV)
트리거: 성능, 최적화, Lighthouse, Core Web Vitals, LCP, CLS, INP, 번들, 로딩 속도, 캐싱, lazy loading
Nuxt 3 프로젝트의 성능 병목을 분석하고 최적화합니다. 코드 스플리팅, 이미지 최적화, SSR/ISR 렌더링 전략, API 캐싱, Payload 최적화를 포함합니다.
"이 페이지 LCP가 3초 넘는데 성능 최적화 방안 제시해줘"
성능 최적화 체크리스트
| 카테고리 | 최적화 항목 | Nuxt 3 적용 방법 |
|---|---|---|
| 번들 | 코드 스플리팅 | defineAsyncComponent, lazy 접두사 컴포넌트 |
| 번들 | 트리 쉐이킹 | nuxt.config의 build.transpile, 사이드이펙트 제거 |
| 이미지 | NuxtImg | sizes/format 자동 최적화 |
| 이미지 | Lazy Loading | loading="lazy", NuxtImg placeholder |
| 네트워크 | API 캐싱 | useFetch의 key, getCachedData |
| 네트워크 | 서버 캐싱 | routeRules의 swr, isr 설정 |
| 렌더링 | SSR/SSG 전략 | routeRules로 페이지별 렌더링 모드 지정 |
| 렌더링 | Payload 최적화 | useAsyncData의 transform으로 불필요 데이터 제거 |
| CWV | LCP < 2.5s | critical CSS 인라인, 폰트 프리로드, hero 이미지 우선 |
| CWV | CLS < 0.1 | 이미지 width/height 명시, 스켈레톤 UI, font-display: swap |
| CWV | INP < 200ms | 이벤트 핸들러 최적화, 메인 스레드 블로킹 제거 |
💬 프롬프트 템플릿
이 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 (Search Engine Optimization)
전통 검색엔진(Google, Bing) 결과 페이지에서 상위 노출. 메타태그, 구조화 데이터, 사이트맵, 기술적 SEO(Core Web Vitals, crawlability)가 핵심.
💬 Layer 2 — AEO (Answer Engine Optimization)
Featured Snippet, Google AI Overview, 음성 검색 등 "직접 답변" 영역에 콘텐츠를 노출. FAQ 구조, 질문형 H2 헤딩, 간결한 정의 문장이 핵심.
🤖 Layer 3 — GEO (Generative Engine Optimization)
ChatGPT, Perplexity, Claude, Gemini 등 AI 생성형 답변에서 콘텐츠가 인용(citation)되도록 최적화. 통계 데이터, 전문가 인용, 구조화된 정보 블록, 원본 리서치가 핵심.
💡
3계층은 상호 보완적입니다. 탄탄한 SEO 기반 위에 AEO 구조를 얹고, GEO 최적화를 추가하는 것이 가장 효과적입니다. Princeton 연구에 따르면 GEO 최적화 기법(통계 인용, 출처 명시, 전문가 인용문)을 적용하면 AI 검색 가시성이 30~40% 향상됩니다.
트리거: SEO, 메타태그, 구조화 데이터, Schema.org, sitemap, OG태그, GEO, AI 검색, 인용 최적화, AEO, Featured Snippet, FAQ, 음성 검색, useSeoMeta, useSchemaOrg
Nuxt 3 프로젝트의 SEO·GEO·AEO를 3계층으로 감사하고 최적화합니다. 메타태그 자동화, JSON-LD 구조화 데이터, AI 인용 친화적 콘텐츠 구조, FAQ 스키마, OG 이미지 자동 생성을 포함합니다.
"이 사이트의 SEO 메타태그, GEO 인용 최적화, AEO FAQ 구조를 검증해줘"
Layer 1 — SEO 체크리스트
| 영역 | 점검 항목 | Nuxt 3 구현 |
|---|---|---|
| 메타태그 | title, description, canonical, OG, Twitter Card | useSeoMeta() 전역 + 페이지별 오버라이드 |
| 구조화 데이터 | JSON-LD Schema.org (Article, Product, FAQ 등) | @nuxtjs/schema-org 모듈, useSchemaOrg() |
| 사이트맵 | 동적 sitemap.xml 생성 | @nuxtjs/sitemap 모듈 |
| robots | robots.txt + 크롤 제어 | @nuxtjs/robots 모듈 또는 server/routes |
| OG 이미지 | 페이지별 동적 OG 이미지 | nuxt-og-image 또는 Satori 기반 server/api |
| Canonical | 중복 URL 방지 | useHead({ link: [{ rel: 'canonical' }] }) |
| SSR | 검색엔진 크롤러 SSR 보장 | routeRules로 SSR/ISR 모드 지정 |
| i18n | hreflang 태그, lang 속성 | @nuxtjs/i18n 모듈 |
Layer 2 — AEO 체크리스트
| 영역 | 점검 항목 | 구현 전략 |
|---|---|---|
| 질문형 구조 | H2를 실제 사용자 질문 형태로 | "제품 가격은?" 대신 "이 제품의 가격은 얼마인가요?" |
| 즉답 패턴 | 질문 직후 200자 이내 직접 답변 | TLDR-first 콘텐츠 구조 적용 |
| FAQ Schema | FAQPage JSON-LD | useSchemaOrg([defineFAQPage(...)]) |
| HowTo Schema | 단계별 가이드 구조화 | useSchemaOrg([defineHowTo(...)]) |
| Breadcrumb | 탐색 경로 구조화 | useSchemaOrg([defineBreadcrumb(...)]) |
| 정의 문장 | 핵심 용어의 명확한 정의 문장 | "[용어]는 [정의]입니다" 패턴으로 시작 |
Layer 3 — GEO 체크리스트
| 영역 | 점검 항목 | 최적화 전략 |
|---|---|---|
| 통계 인용 | 구체적 수치 데이터 포함 | "매출 20% 증가" → AI가 인용할 확률 ↑ |
| 출처 명시 | 데이터·인사이트의 원본 출처 표기 | 신뢰도 향상 → AI 엔진이 선호 |
| 전문가 인용 | 업계 전문가의 직접 인용문 | blockquote + 전문가 Schema 활용 |
| 추출 가능한 블록 | 독립적으로 의미가 완결되는 정보 단위 | 각 섹션이 독립적으로 인용 가능하도록 구성 |
| E-E-A-T 신호 | 경험(Experience), 전문성, 권위, 신뢰 | 저자 프로필, 리뷰 날짜, 인증 배지 |
| 최신성 유지 | 정기적 콘텐츠 업데이트 | AI 인용 콘텐츠의 50%가 13주 이내 게시된 것 |
| 토픽 중심 | 키워드 → 토픽 타겟팅 전환 | 주제를 포괄적으로 다루는 pillar 콘텐츠 |
| 브랜드 언급 | 웹 전체에서 브랜드 언급 확대 | 외부 인용, 리뷰, 포럼 활동 |
SEO 메타 자동화 패턴
💬 useSeoMeta + useSchemaOrg 통합 패턴
// composables/usePageSeo.ts — SEO·GEO 통합 메타 자동화
GEO·AEO 감사 프롬프트
💬 SEO + 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)를 사용하므로 충돌하지 않습니다.
| 위치 | 경로 | 적용 대상 |
|---|---|---|
| Enterprise | 관리 설정(Managed Settings) 참조 | 조직의 모든 사용자 |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md |
모든 프로젝트에서 사용 가능 |
| Project | .claude/skills/<skill-name>/SKILL.md |
해당 프로젝트에서만 사용 |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md |
플러그인이 활성화된 위치 |
공식 Skill 디렉토리 구조
각 Skill은 SKILL.md 를 진입점으로 하는 디렉토리입니다. SKILL.md 만 필수이며, 나머지 파일은 선택적입니다.
official structure my-skill/ ├── SKILL.md # 주요 지침 (필수) ├── template.md # Claude가 채울 템플릿 ├── examples/ │ └── sample.md # 예상 형식을 보여주는 예제 출력 └── scripts/ └── validate.sh # Claude가 실행할 수 있는 스크립트
공식 네이밍 규칙
| 대상 | 규칙 | 비고 |
|---|---|---|
| name 필드 | 소문자, 숫자, 하이픈만 사용 (최대 64자) | /slash-command 로 호출 시 사용 |
| 폴더명 | name 미지정 시 디렉토리 이름이 기본 name | kebab-case 권장 |
| SKILL.md | 대문자 고정, 폴더당 1개 (필수) | 500줄 이내 권장 |
| 지원 파일 | SKILL.md에서 참조하여 필요 시 로드 | 상세 내용은 references/로 분리 |
📖
공식문서 참조: .claude/commands/ 의 기존 파일도 계속 작동하며 동일한 frontmatter를 지원합니다. 단, Skills가 지원 파일 등 추가 기능을 제공하므로 Skills 형식이 권장 됩니다. Skill과 명령어가 같은 이름을 공유하면 Skill이 우선합니다.
전체 Skills 폴더 구조 (프로젝트 적용)
skill tree · v1.2 nuxt-fe-skills/ │ ├── requirement-analyzer/ # Phase 1: 요구사항 분석 │ ├── SKILL.md │ ├── scripts/ │ │ └── generate-flowchart.js │ └── references/ │ └── requirement-template.md │ ├── markup/ # Phase 2: 마크업 컨벤션 │ ├── SKILL.md │ ├── references/ │ │ ├── semantic-html.md │ │ ├── tailwind-convention.md │ │ ├── accessibility.md │ │ └── nuxt-sfc-pattern.md ├── markup-promotion/ # Phase 2-2: 프로모션 마크업 🆕 v1.1 │ ├── SKILL.md │ ├── references/ ├── markup-edm/ # Phase 2-3: EDM 마크업 🆕 v1.1 │ ├── SKILL.md │ ├── references/ │ ├── nuxt-component-architect/ # Phase 3: 컴포넌트 아키텍처 │ └── SKILL.md │ ├── nuxt/ # Phase 3-1: Nuxt 공식문서 기반 🆕 v1.1 │ ├── SKILL.md │ └── references/ │ ├── server.md │ ├── middleware.md │ ├── plugins.md │ ├── nuxt-composables.md │ ├── nuxt-components.md │ └── nuxt-config.md │ ├── nuxt-page-layout/ # Phase 3-2: 페이지·레이아웃·미들웨어 🆕 v1.2 │ └── SKILL.md │ ├── vue-component-create/ # Phase 3-3: Vue 컴포넌트 신규 생성 🆕 v1.2 │ └── SKILL.md │ ├── nuxt-composable/ # Phase 3-4: Composable·데이터 페칭 🆕 v1.2 │ └── SKILL.md │ ├── nuxt-api-state-manager/ # Phase 4: API·상태관리 │ ├── SKILL.md │ ├── scripts/ │ │ └── generate-store.js │ └── references/ │ ├── pinia-patterns.md │ └── api-error-handling.md │ ├── pinia-store/ # Phase 4-1: Pinia 스토어 생성 🆕 v1.2 │ └── SKILL.md │ ├── nuxt-api-route/ # Phase 4-2: Nitro 서버 라우트(BFF) 🆕 v1.2 │ └── SKILL.md │ ├── requirement-optimizer/ # Phase 5-1: 요구사항 검증 🆕 v1.1 │ ├── SKILL.md │ └── references/ │ └── requirement-checklist.md │ ├── perf-optimizer/ # Phase 5-2: 성능 최적화 ⚡ v1.1 │ ├── SKILL.md │ ├── scripts/ │ │ └── lighthouse-runner.js # Lighthouse CI 자동 실행 │ └── references/ │ ├── cwv-checklist.md # Core Web Vitals 체크리스트 │ ├── bundle-optimization.md # 번들 최적화 전략 │ ├── image-optimization.md # NuxtImg 활용 가이드 │ └── caching-strategy.md # routeRules 캐싱 가이드 │ └── nuxt-seo-geo/ # Phase 6: SEO·GEO·AEO 🆕 v1.1 ├── SKILL.md ├── scripts/ │ ├── seo-meta-checker.js # 메타태그 완성도 자동 검사 │ └── schema-validator.js # JSON-LD 구조화 데이터 검증 └── references/ ├── seo-meta-guide.md # useSeoMeta 패턴 가이드 ├── schema-org-guide.md # useSchemaOrg JSON-LD 가이드 ├── aeo-patterns.md # AEO: FAQ, HowTo, 즉답 패턴 ├── geo-optimization.md # GEO: AI 인용 최적화 전략 └── og-image-generation.md # 동적 OG 이미지 자동 생성
Skill 설계 3원칙
📐
원칙 1: Progressive Disclosure (점진적 공개) — SKILL.md는 500줄 이내. 상세 내용은 references/에 분리. Claude는 컨텍스트에 따라 필요한 참조만 선택적으로 로드합니다.
🎯
원칙 2: Pushy Description (적극적 트리거) — Skill description에 다양한 트리거 키워드를 포함하여 관련 상황에서 누락 없이 활성화. 언더트리거보다 오버트리거가 낫습니다.
📋
원칙 3: Deterministic Output (결정적 출력) — 동일한 입력에 대해 일관된 구조의 출력을 보장. 출력 포맷(디렉토리 구조, 코드 패턴, 체크리스트)을 명확히 정의합니다.
도입 타임라인
| 주차 | Phase | 핵심 활동 | 산출물 |
|---|---|---|---|
| W1–W2 | Phase 1 | 요구사항 분석 Skill 개발 및 테스트 | requirement-analyzer |
| W2–W3 | Phase 2 / 2-0 / 2-1 / 2-2 / 2-3 | 마크업 컨벤션 + PSD→Figma·피그마 마크업·프로모션·EDM Skill 개발 | markup, markup-promotion, markup-edm |
| W3–W5 | Phase 3 / 3-1 / 3-2 / 3-3 / 3-4 | Nuxt 컴포넌트 아키텍처 + 공식문서 참조 + 페이지·컴포넌트·Composable Skill 개발 | nuxt-component-architect, nuxt, nuxt-page-layout, vue-component-create, nuxt-composable |
| W5–W7 | Phase 4 / 4-1 / 4-2 | API/Pinia 패턴 표준화 + Pinia 스토어 + Nitro 서버 라우트 Skill 개발 | nuxt-api-state-manager, pinia-store, nuxt-api-route |
| W7–W8 | Phase 5 검증 (5-1) | 요구사항 검증 Skill 개발 | requirement-optimizer NEW |
| W8–W9 | Phase 5-2 | 성능 최적화 Skill 개발 및 파일럿 | perf-optimizer CHANGED |
| W9–W10 | Phase 6 NEW | SEO·GEO·AEO 감사 Skill 개발 | nuxt-seo-geo |
| W11–W12 | 통합 | 전체 Skill 통합 테스트 및 팀 교육 | 교육 자료, 온보딩 가이드 |
| W13– | 운영 | 실 프로젝트 적용 및 피드백 기반 개선 | Skill 버전 업데이트 로그 |
성공 지표 (KPI)
코드 리뷰 반려율
35%
→
15%↓
컴포넌트 재사용률
30%
→
70%↑
신규 온보딩 기간
3주
→
1주
Lighthouse 성능 점수
65~75
→
90+
SEO 메타 누락률
40%
→
5%↓
AI 검색 인용률 NEW
미측정
→
측정 체계 구축
본 문서는 퍼블리싱웹 FE 내부 공유용이며, 프로젝트 진행에 따라 지속 업데이트됩니다.
문의: 퍼블리싱웹 FE · 최종 수정: 2026.04.23 · v1.2