Claude Code Skills 기반 지능형 업무 매뉴얼 — FE 개발 프로세스 표준화 로드맵
본 문서는 Nuxt 3 기반 FE 개발 프로세스를 Claude Code AI Skills과 통합하여 체계적인 표준화 체계를 구축하기 위한 로드맵입니다. 팀 전체가 동일한 품질과 패턴으로 개발할 수 있도록 각 단계별 지능형 업무 매뉴얼(Skills)을 정의합니다.
Claude Code Skills은 특정 작업 도메인에 대해 Claude가 전문적으로 수행할 수 있도록 구조화된 업무 지시서입니다. SKILL.md 파일을 중심으로, 트리거 조건·실행 절차·출력 포맷이 정의되어 있어 팀원 누구나 일관된 결과를 얻을 수 있습니다.
| 구성 요소 | 설명 | 예시 |
|---|---|---|
| SKILL.md | 핵심 지시서 (500줄 이내 권장) | 트리거, 절차, 출력 포맷 정의 |
| scripts/ | 반복 작업 자동화 스크립트 | 컴포넌트 생성기, 린트 검사기 |
| references/ | 도메인별 참조 문서 | Nuxt 컨벤션, API 패턴 가이드 |
FE 개발 전체 라이프사이클의 각 Phase마다 전용 Claude Code Skill을 배치합니다.
| 대단계 | Phase | 핵심 활동 | Claude Skill |
|---|---|---|---|
| 기획 | Phase 1 | 요구사항 정의, 플로우차트 | requirement-analyzer/SKILL.md |
| 마크업 | Phase 2 | HTML 마크업, Tailwind 컨벤션 | markup/SKILL.md |
| Phase 2-0 | PSD -> 피그마 컨버팅 | SKILL 검토 중 |
|
| Phase 2-1 | 피그마 HTML 마크업 | markup/SKILL.md | |
| Phase 2-2 | 프로모션 HTML 마크업 | markup-promotion/SKILL.md | |
| Phase 2-3 | EDM HTML 마크업 | markup-edm/SKILL.md | |
| FE개발 | Phase 3 | Nuxt 컴포넌트 아키텍처 | component-architect |
| Phase 3-1 | Nuxt 공식문서 기반 |
nuxt/SKILL.md |
|
| FE개발 | Phase 4 | API 연동 | api-manager/SKILL.md |
| 검증 | Phase 5 | 검증 | |
| Phase 5-1 | Phase 1 기획 요구사항 검증 | requirement-optimizer/SKILL.md | |
| Phase 5-2 | 성능 최적화 (CWV) | perf-optimizer/SKILL.md | |
| 검증 | Phase 6 | SEO · GEO · AEO 검증 | seo-geo/SKILL.md |
트리거: 요구사항, 기획서, 플로우차트, 화면정의서, 유저스토리
기획 문서를 분석하여 Nuxt 프로젝트에 적합한 구조화된 요구사항 명세(페이지 목록, 컴포넌트 트리, 라우팅 맵, 데이터 플로우)를 자동 생성합니다.
다음 기획서를 분석해서 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 패턴)를 도메인별로 선택 로드합니다.
트리거: PSD, 피그마 변환, PSD to Figma, 디자인 컨버팅, PSD 임포트
PSD 디자인 파일을 Figma로 변환하는 프로세스를 지원합니다. Codia AI 디자인(PSD to Figma) 및 PSD Importer for Figma 도구를 활용하여 레이어 구조를 유지하며 Figma 포맷으로 컨버팅합니다.
⚠️ SKILL 검토 중 — 도구 안정성 및 레이어 정합성 평가 진행 중
트리거: 피그마, Figma, 피그마 마크업, 피그마 HTML, 디자인 시안 마크업, Figma to HTML
피그마 디자인 시안을 HTML 마크업으로 변환하는 데 특화된 Skill입니다. markup Skill을 기반으로 피그마 레이어 구조 해석, 컴포넌트 매핑, 반응형 브레이크포인트 추출을 포함합니다.
| 영역 | 시멘틱 태그 | 규칙 |
|---|---|---|
| 레이아웃 | <header>, <nav>, <main>, <aside>, <footer> | 페이지 대구조 정의, div 남용 금지 |
| 섹션 | <section>, <article> | 의미 단위 그룹핑, aria-label 필수 |
| 제목 | <h1>~<h6> | 페이지당 h1 1개, 건너뛰기 금지 |
| 목록 | <ul>, <ol>, <dl> | 나열형 데이터는 반드시 리스트 태그 |
| 폼 | <form>, <fieldset>, <label> | 모든 input에 label 연결 필수 |
| 인터랙티브 | <button>, <a>, <dialog> | 클릭 가능 요소는 반드시 시멘틱 태그 |
| 순서 | 카테고리 | 대표 클래스 | 기억법 |
|---|---|---|---|
| 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 배치 패턴을 포함합니다.
트리거: EDM, 이메일, 뉴스레터, 메일 템플릿, 이메일 마크업
EDM(Email Direct Marketing) 및 뉴스레터용 HTML 마크업을 생성합니다. 이메일 클라이언트 호환성, 테이블 기반 레이아웃, 인라인 스타일 패턴을 포함합니다.
트리거: Nuxt 컴포넌트, 페이지, composable, 레이아웃, 미들웨어, 플러그인
Nuxt 3 공식 가이드를 기반으로 컴포넌트를 설계합니다. auto-import, composables 패턴, server/ 디렉토리 활용, 레이아웃 전략을 포함한 전체 아키텍처를 제안합니다.
| 참조 파일 | 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)를 컨텍스트에 따라 선택적으로 로드합니다.
트리거: API 연동, useFetch, useAsyncData, Pinia, 스토어, 상태관리, 에러 핸들링
Nuxt 3의 데이터 페칭 유틸리티와 Pinia 스토어를 조합한 표준 패턴을 생성합니다.
| 패턴 | 사용 시점 | 특징 |
|---|---|---|
useFetch() | 컴포넌트에서 직접 API 호출 | SSR 지원, 자동 캐싱, key 기반 중복 방지 |
useAsyncData() | 복잡한 데이터 변환 필요 시 | 커스텀 fetch 로직, transform 지원 |
$fetch() | 이벤트 핸들러 내 API 호출 | 클라이언트 사이드만, SSR 미지원 |
server/api/ | BFF 패턴, 서버 사이드 로직 | Nitro 기반, API 키 보호 |
Phase 5는 기획 요구사항 검증(5-1)과 성능 최적화(5-2)를 통합한 검증 단계입니다. Phase 1에서 정의한 요구사항 대비 실제 구현 결과를 비교 검증하고, 런타임 퍼포먼스를 최적화합니다.
트리거: 요구사항 검증, 기획 대비 구현 비교, 기능 누락 확인, 스펙 검증, 구현 완성도
Phase 1에서 정의한 요구사항 명세와 실제 구현 결과를 비교 검증합니다. 기능 누락, 스펙 불일치, 미구현 항목을 자동으로 식별하고 개선 방안을 제시합니다.
트리거: 성능, 최적화, Lighthouse, Core Web Vitals, LCP, CLS, INP, 번들, 로딩 속도, 캐싱, lazy loading
Nuxt 3 프로젝트의 성능 병목을 분석하고 최적화합니다. 코드 스플리팅, 이미지 최적화, SSR/ISR 렌더링 전략, API 캐싱, Payload 최적화를 포함합니다.
| 카테고리 | 최적화 항목 | Nuxt 3 적용 방법 |
|---|---|---|
| 번들 | 코드 스플리팅 | defineAsyncComponent, lazy 접두사 컴포넌트 |
| 번들 | 트리 쉐이킹 | nuxt.config의 build.transpile, 사이드이펙트 제거 |
| 이미지 | NuxtImg | <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, 메타태그, 구조화 데이터, Schema.org, sitemap, OG태그, GEO, AI 검색, 인용 최적화, AEO, Featured Snippet, FAQ, 음성 검색, useSeoMeta, useSchemaOrg
Nuxt 3 프로젝트의 SEO·GEO·AEO를 3계층으로 감사하고 최적화합니다. 메타태그 자동화, JSON-LD 구조화 데이터, AI 인용 친화적 콘텐츠 구조, FAQ 스키마, OG 이미지 자동 생성을 포함합니다.
| 영역 | 점검 항목 | 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 모듈 |
| 영역 | 점검 항목 | 구현 전략 |
|---|---|---|
| 질문형 구조 | H2를 실제 사용자 질문 형태로 | "제품 가격은?" 대신 "이 제품의 가격은 얼마인가요?" |
| 즉답 패턴 | 질문 직후 200자 이내 직접 답변 | TLDR-first 콘텐츠 구조 적용 |
| FAQ Schema | FAQPage JSON-LD | useSchemaOrg([defineFAQPage(...)]) |
| HowTo Schema | 단계별 가이드 구조화 | useSchemaOrg([defineHowTo(...)]) |
| Breadcrumb | 탐색 경로 구조화 | useSchemaOrg([defineBreadcrumb(...)]) |
| 정의 문장 | 핵심 용어의 명확한 정의 문장 | "[용어]는 [정의]입니다" 패턴으로 시작 |
| 영역 | 점검 항목 | 최적화 전략 |
|---|---|---|
| 통계 인용 | 구체적 수치 데이터 포함 | "매출 20% 증가" → AI가 인용할 확률 ↑ |
| 출처 명시 | 데이터·인사이트의 원본 출처 표기 | 신뢰도 향상 → AI 엔진이 선호 |
| 전문가 인용 | 업계 전문가의 직접 인용문 | blockquote + 전문가 Schema 활용 |
| 추출 가능한 블록 | 독립적으로 의미가 완결되는 정보 단위 | 각 섹션이 독립적으로 인용 가능하도록 구성 |
| E-E-A-T 신호 | 경험(Experience), 전문성, 권위, 신뢰 | 저자 프로필, 리뷰 날짜, 인증 배지 |
| 최신성 유지 | 정기적 콘텐츠 업데이트 | AI 인용 콘텐츠의 50%가 13주 이내 게시된 것 |
| 토픽 중심 | 키워드 → 토픽 타겟팅 전환 | 주제를 포괄적으로 다루는 pillar 콘텐츠 |
| 브랜드 언급 | 웹 전체에서 브랜드 언급 확대 | 외부 인용, 리뷰, 포럼 활동 |
// composables/usePageSeo.ts — SEO·GEO 통합 메타 자동화
이 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가 최신 상태인가
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.md를 진입점으로 하는 디렉토리입니다. SKILL.md만 필수이며, 나머지 파일은 선택적입니다.
| 대상 | 규칙 | 비고 |
|---|---|---|
| name 필드 | 소문자, 숫자, 하이픈만 사용 (최대 64자) | /slash-command로 호출 시 사용 |
| 폴더명 | name 미지정 시 디렉토리 이름이 기본 name | kebab-case 권장 |
| SKILL.md | 대문자 고정, 폴더당 1개 (필수) | 500줄 이내 권장 |
| 지원 파일 | SKILL.md에서 참조하여 필요 시 로드 | 상세 내용은 references/로 분리 |
.claude/commands/의 기존 파일도 계속 작동하며 동일한 frontmatter를 지원합니다. 단, Skills가 지원 파일 등 추가 기능을 제공하므로 Skills 형식이 권장됩니다. Skill과 명령어가 같은 이름을 공유하면 Skill이 우선합니다.| 주차 | 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 | Nuxt 컴포넌트 아키텍처 + 공식문서 참조 Skill 개발 | nuxt-component-architect, nuxt |
| W5–W7 | Phase 4 | API/Pinia 패턴 표준화 및 Skill 개발 | nuxt-api-state-manager |
| 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 버전 업데이트 로그 |
본 문서는 퍼블리싱웹 FE 내부 공유용이며, 프로젝트 진행에 따라 지속 업데이트됩니다.
문의: 퍼블리싱웹 FE · 최종 수정: 2026.03.30 · v1.1