diff --git a/.claude/hooks/notification-hook.sh b/.claude/hooks/notification-hook.sh new file mode 100755 index 0000000..27820d5 --- /dev/null +++ b/.claude/hooks/notification-hook.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +# Claude Code - Notification 훅 +# Claude가 사용자 주의가 필요한 알림을 보낼 때 실행된다. +# +# stdin JSON 형식: {"session_id": "...", "message": "..."} + +set -euo pipefail + +HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +# stdin에서 JSON 읽기 +INPUT="$(cat)" + +MESSAGE="$(echo "$INPUT" | jq -r '.message // ""')" + +if [[ -z "$MESSAGE" ]]; then + exit 0 +fi + +TELEGRAM_MESSAGE="🔔 *Claude 알림* + +${MESSAGE}" + +"$HOOK_DIR/notify_telegram.sh" "$TELEGRAM_MESSAGE" diff --git a/.claude/hooks/notify_telegram.sh b/.claude/hooks/notify_telegram.sh new file mode 100755 index 0000000..574089b --- /dev/null +++ b/.claude/hooks/notify_telegram.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +# Telegram 메시지 발송 공통 유틸리티 +# 사용법: notify_telegram.sh "메시지 본문" +# +# 필요 환경변수: +# TELEGRAM_BOT_TOKEN - BotFather 발급 토큰 +# TELEGRAM_CHAT_ID - 알림을 받을 채팅 ID + +set -euo pipefail + +# 환경변수 미설정 시 .env 파일에서 로드 (Claude Code 훅 실행 환경 대응) +ENV_FILE="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/.env" +if [[ -f "$ENV_FILE" ]]; then + # export 구문을 포함한 .env 파일 소싱 + set -a + # shellcheck source=/dev/null + source "$ENV_FILE" + set +a +fi + +TELEGRAM_BOT_TOKEN="${TELEGRAM_BOT_TOKEN:-}" +TELEGRAM_CHAT_ID="${TELEGRAM_CHAT_ID:-}" +MESSAGE="${1:-}" + +# 환경변수 미설정 시 조용히 종료 (훅 실패로 Claude 작업 중단 방지) +if [[ -z "$TELEGRAM_BOT_TOKEN" || -z "$TELEGRAM_CHAT_ID" ]]; then + exit 0 +fi + +if [[ -z "$MESSAGE" ]]; then + exit 0 +fi + +curl -s -X POST \ + "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \ + -H "Content-Type: application/json" \ + -d "$(jq -n \ + --argjson chat_id "$TELEGRAM_CHAT_ID" \ + --arg text "$MESSAGE" \ + '{chat_id: $chat_id, text: $text, parse_mode: "Markdown"}')" \ + > /dev/null diff --git a/.claude/hooks/pre-tool-hook.sh b/.claude/hooks/pre-tool-hook.sh new file mode 100755 index 0000000..a6fa05f --- /dev/null +++ b/.claude/hooks/pre-tool-hook.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +# Claude Code - PreToolUse 훅 +# 툴 실행 직전에 실행되어 Telegram으로 알림을 보낸다. +# +# stdin JSON 형식: +# {"session_id": "...", "tool_name": "...", "tool_input": {...}} + +set -euo pipefail + +HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +INPUT="$(cat)" + +TOOL_NAME="$(echo "$INPUT" | jq -r '.tool_name // ""')" +TOOL_INPUT="$(echo "$INPUT" | jq -r '.tool_input // {} | to_entries | map("\(.key): \(.value)") | join(", ")')" + +if [[ -z "$TOOL_NAME" ]]; then + exit 0 +fi + +TELEGRAM_MESSAGE="⚙️ *툴 실행* + +🔧 \`${TOOL_NAME}\` +📝 ${TOOL_INPUT}" + +"$HOOK_DIR/notify_telegram.sh" "$TELEGRAM_MESSAGE" diff --git a/.claude/hooks/stop-hook.sh b/.claude/hooks/stop-hook.sh new file mode 100755 index 0000000..048f2ef --- /dev/null +++ b/.claude/hooks/stop-hook.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +# Claude Code - Stop 훅 +# Claude가 응답을 완료하고 멈출 때 실행된다. +# +# stdin JSON 형식: {"session_id": "...", "stop_hook_active": true} + +set -euo pipefail + +HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +# stdin에서 JSON 읽기 +INPUT="$(cat)" + +SESSION_ID="$(echo "$INPUT" | jq -r '.session_id // ""')" + +TELEGRAM_MESSAGE="✅ *Claude 작업 완료* + +세션 ID: \`${SESSION_ID}\`" + +"$HOOK_DIR/notify_telegram.sh" "$TELEGRAM_MESSAGE" diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 70308aa..9ed3a68 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -36,6 +36,17 @@ ] } ], + "PreToolUse": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-hook.sh" + } + ] + } + ], "Stop": [ { "matcher": "*", diff --git a/html/nuxt-fe-ai-wiki-report-v1.1_1.html b/html/nuxt-fe-ai-wiki-report-v1.1_1.html new file mode 100644 index 0000000..bc5f4e1 --- /dev/null +++ b/html/nuxt-fe-ai-wiki-report-v1.1_1.html @@ -0,0 +1,830 @@ + + + + + +Nuxt FE AI 표준화 로드맵 v1.1 + + + + + + +
+
퍼블리싱웹 FE Wiki
+

Nuxt FE AI Standardization

+

Claude Code Skills 기반 지능형 업무 매뉴얼 — FE 개발 프로세스 표준화 로드맵

+
+ 📋 Version 1.1 + 📅 2026.03.30 + 👥 퍼블리싱웹 FE + 🔒 팀 내부 공유용 +
+
+ + +
+

목차

+
    +
  1. 개요 및 배경
    2. +
  2. 전체 프로세스 Overview
    3. +
  3. Phase 1 — 요구사항 정의 및 플로우차트
    4. +
  4. Phase 2 — 마크업 & Tailwind 컨벤션
    5. +
  5. Phase 3 — Nuxt 컴포넌트 아키텍처
    6. +
  6. Phase 4 — API 연동 & Pinia 상태관리
    7. +
  7. Phase 5 — 성능 최적화 (Core Web Vitals)
    8. +
  8. Phase 6 — SEO · GEO · AEO 검증
    9. +
  9. Claude Code Skills 통합 체계
    10. +
  10. 실행 로드맵 & 일정
    11. +
+
+ + +
+
01
+

개요 및 배경 왜 AI 기반 FE 표준화가 필요한가

+
+ +

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

+ +

1.1 프로젝트 목적

+ + +

1.2 Claude Code Skills이란?

+

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

+ + + + + + + + + +
구성 요소설명예시
SKILL.md핵심 지시서 (500줄 이내 권장)트리거, 절차, 출력 포맷 정의
scripts/반복 작업 자동화 스크립트컴포넌트 생성기, 린트 검사기
references/도메인별 참조 문서Nuxt 컨벤션, API 패턴 가이드
assets/템플릿, 아이콘 등 리소스컴포넌트 보일러플레이트
+ +
+ + +
+
02
+

전체 프로세스 Overview 기획 → 디자인 → FE개발 → 검증 워크플로우

+
+ +

FE 개발의 전체 라이프사이클을 4개 대단계, 6개 세부 Phase로 구분하고, 각 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 검색 시대에 대응합니다.
+
+ + + + + + + + + + + + + + + + + + +
대단계Phase핵심 활동Claude Skill
기획Phase 1요구사항 정의, 플로우차트nuxt-requirement-analyzer/SKILL.md
nuxt-requirement-analyzer/references/
디자인Phase 2HTML 마크업, Tailwind 컨벤션markup/SKILL.md
markup/references/
Phase 2-1프로모션 HTML 마크업markup/promotion/SKILL.md
markup/promotion/references/
Phase 2-2EDM HTML 마크업markup/edm/SKILL.md
markup/edm/references/
FE개발Phase 3Nuxt 컴포넌트 아키텍처nuxt-component-architect
https://github.com/onmax/nuxt-skills/tree/main
Phase 3-1Nuxt 공식문서 기반 + 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
    • +
+
FE개발Phase 4API 연동, Pinia 상태관리nuxt-api-state-manager/SKILL.md
nuxt-api-state-manager/references/
검증Phase 5성능 최적화 (CWV)nuxt-perf-optimizer/SKILL.md
nuxt-perf-optimizer/references/
검증Phase 6 SEO · GEO · AEO 검증nuxt-seo-geo/SKILL.md
nuxt-seo-geo/references/
+ +
+ + +
+
03
+

Phase 1 — 요구사항 정의 및 플로우차트 기획 단계에서 개발 가능한 형태로 변환

+
+ +
+
+ nuxt-requirement-analyzer + Phase 1 · 기획 +
+

트리거: 요구사항, 기획서, 플로우차트, 화면정의서, 유저스토리

+

기획 문서를 분석하여 Nuxt 프로젝트에 적합한 구조화된 요구사항 명세(페이지 목록, 컴포넌트 트리, 라우팅 맵, 데이터 플로우)를 자동 생성합니다.

+
"이 기획서를 분석해서 Nuxt 페이지 구조와 컴포넌트 목록을 뽑아줘"
+
+ +

Skill 동작 절차

+
    +
  1. 입력 분석 — 기획서/PRD 문서를 파싱하여 기능 요구사항, 화면 목록, 사용자 플로우를 추출
    2. +
  2. 페이지 맵 생성 — Nuxt의 pages/ 디렉토리 구조에 맞는 라우팅 맵을 자동 설계
    3. +
  3. 컴포넌트 트리 도출 — Atomic Design 원칙에 따른 컴포넌트 분해
    4. +
  4. 데이터 플로우 정의 — 각 페이지/컴포넌트별 필요 데이터, API 엔드포인트 매핑
    5. +
  5. Mermaid 플로우차트 출력 — 화면 전환 흐름, 조건 분기를 시각화
    6. +
+ +
+
💬 프롬프트 템플릿
+
다음 기획서를 분석해서 Nuxt 3 프로젝트 구조를 설계해줘.
+
+[기획서 첨부 또는 내용 붙여넣기]
+
+출력 형식:
+1. pages/ 디렉토리 라우팅 구조
+2. components/ Atomic Design 기반 컴포넌트 트리
+3. 각 페이지별 필요 API 엔드포인트 목록
+4. Mermaid 플로우차트 (화면 전환 흐름)
+5. composables/ 에 필요한 공통 로직 목록
+
+ +
+ + +
+
04
+

Phase 2 — 마크업 & Tailwind 컨벤션 시멘틱 HTML 구조 확립 및 Tailwind CSS 스타일 표준화

+
+ +
+
+ markup + Phase 2 · 디자인→마크업 +
+

트리거: 마크업, HTML 구조, 시멘틱, Tailwind, 클래스 순서, 접근성, ARIA, SFC 구조, 반응형

+

디자인 시안을 Nuxt 컴포넌트의 시멘틱 HTML + Tailwind CSS로 변환합니다. 4개 참조 문서(시멘틱 HTML, Tailwind 컨벤션, 접근성, Nuxt SFC 패턴)를 도메인별로 선택 로드합니다.

+
"이 디자인을 시멘틱 마크업으로 변환하고 Tailwind 클래스를 적용해줘"
+
+ +

HTML 시멘틱 태그 가이드

+ + + + + + + + + + +
영역시멘틱 태그규칙
레이아웃<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>클릭 가능 요소는 반드시 시멘틱 태그
+ +

Tailwind 클래스 순서 컨벤션

+ + + + + + + + + + + +
순서카테고리대표 클래스기억법
1Layoutflex, grid, block, hidden"어떻게 배치?"
2Positionrelative, absolute, fixed, z-*"어디에 놓을까?"
3Box Modelw-*, h-*, p-*, m-*, gap-*"얼마나 크게?"
4Typographytext-*, font-*, leading-*"글자를 어떻게?"
5Visualbg-*, border-*, rounded-*, shadow-*"어떻게 보이게?"
6Statehover:*, focus:*, sm:*, md:*"상태가 바뀌면?"
7Motiontransition-*, duration-*, animate-*"움직임은?"
+ +
+
+ markup/promotion + Phase 2-1 · 프로모션 + NEW +
+

트리거: 프로모션, 랜딩페이지, 이벤트 페이지, 프로모션 마크업, 캠페인 페이지

+

프로모션 및 랜딩페이지에 특화된 HTML 마크업을 생성합니다. 캠페인 성격에 맞는 시멘틱 구조, 반응형 레이아웃, CTA 배치 패턴을 포함합니다.

+
"이 프로모션 디자인을 랜딩페이지 HTML 마크업으로 변환해줘"
+
+ +
+
+ markup/edm + Phase 2-2 · EDM + NEW +
+

트리거: EDM, 이메일, 뉴스레터, 메일 템플릿, 이메일 마크업

+

EDM(Email Direct Marketing) 및 뉴스레터용 HTML 마크업을 생성합니다. 이메일 클라이언트 호환성, 테이블 기반 레이아웃, 인라인 스타일 패턴을 포함합니다.

+
"이 디자인을 이메일 뉴스레터 HTML로 변환해줘"
+
+ +
+ + +
+
05
+

Phase 3 — Nuxt 컴포넌트 아키텍처 Nuxt 3 공식 가이드 기반 컴포넌트 설계 표준

+
+ +
+
+ nuxt-component-architect + Phase 3 · FE개발 +
+

트리거: Nuxt 컴포넌트, 페이지, composable, 레이아웃, 미들웨어, 플러그인

+

Nuxt 3 공식 가이드를 기반으로 컴포넌트를 설계합니다. auto-import, composables 패턴, server/ 디렉토리 활용, 레이아웃 전략을 포함한 전체 아키텍처를 제안합니다.

+
"이 기능을 Nuxt 3 Best Practice에 맞게 컴포넌트로 설계해줘"
+
+ +

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

+ + + + + + + + + + +
참조 파일Nuxt 공홈 출처로드 트리거
server.mdAPI routes, server middleware서버 API, 미들웨어 작업 시
middleware.mdMiddleware, File-based routing미들웨어, 라우팅 설계 시
plugins.mdPlugins, app lifecycle플러그인, 앱 라이프사이클 작업 시
nuxt-composables.mdNuxt composablescomposable 작성 시
nuxt-components.mdNuxtLink, NuxtImg, NuxtTimeNuxt 내장 컴포넌트 사용 시
nuxt-config.mdConfiguration, modules, auto-imports, layersNuxt 설정, 모듈 구성 시
+ +
+
+ nuxt + Phase 3-1 · Nuxt 공식문서 + NEW +
+

트리거: 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/ # 유틸리티 함수 +
+ +
+ + +
+
06
+

Phase 4 — API 연동 & Pinia 상태관리 데이터 페칭 패턴과 전역 상태 설계 표준화

+
+ +
+
+ nuxt-api-state-manager + Phase 4 · FE개발 +
+

트리거: 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 스토어 설계 규칙

+ + +
+ + +
+
07
+

Phase 5 — 성능 최적화 Core Web Vitals 달성 및 런타임 퍼포먼스 최적화

+
+ +

기존 Phase 5에서 성능 최적화 영역만 분리하여 전담 Skill로 구성합니다. 번들 최적화, 이미지 처리, 캐싱, 렌더링 전략 등 런타임 퍼포먼스에 집중합니다.

+ +
+
+ nuxt-perf-optimizer + Phase 5 · 성능 +
+

트리거: 성능, 최적화, 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<NuxtImg> sizes/format 자동 최적화
이미지Lazy Loadingloading="lazy", NuxtImg placeholder
네트워크API 캐싱useFetch의 key, getCachedData
네트워크서버 캐싱routeRules의 swr, isr 설정
렌더링SSR/SSG 전략routeRules로 페이지별 렌더링 모드 지정
렌더링Payload 최적화useAsyncData의 transform으로 불필요 데이터 제거
CWVLCP < 2.5scritical CSS 인라인, 폰트 프리로드, hero 이미지 우선
CWVCLS < 0.1이미지 width/height 명시, 스켈레톤 UI, font-display: swap
CWVINP < 200ms이벤트 핸들러 최적화, 메인 스레드 블로킹 제거
+ +
+
💬 프롬프트 템플릿
+
이 Nuxt 3 프로젝트의 성능을 감사하고 최적화 방안을 제시해줘.
+
+[프로젝트 경로 또는 주요 파일]
+
+감사 범위:
+- Core Web Vitals (LCP < 2.5s, CLS < 0.1, INP < 200ms)
+- 번들 사이즈 분석 (analyze: true로 리포트 확인)
+- 이미지 최적화 상태 (NuxtImg 활용 여부)
+- SSR/SSG/ISR 렌더링 전략 적정성
+- routeRules 캐싱 전략 검증
+- 불필요한 클라이언트 JS hydration 확인
+
+ +
+ + +
+
08
+

Phase 6 — SEO · GEO · AEO 검증 전통 검색 + AI 검색 + 답변 엔진 통합 최적화

+
+ +

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% 향상됩니다.
+
+ +
+
+ nuxt-seo-geo + Phase 6 · SEO·GEO·AEO + NEW +
+

트리거: 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 CarduseSeoMeta() 전역 + 페이지별 오버라이드
구조화 데이터JSON-LD Schema.org (Article, Product, FAQ 등)@nuxtjs/schema-org 모듈, useSchemaOrg()
사이트맵동적 sitemap.xml 생성@nuxtjs/sitemap 모듈
robotsrobots.txt + 크롤 제어@nuxtjs/robots 모듈 또는 server/routes
OG 이미지페이지별 동적 OG 이미지nuxt-og-image 또는 Satori 기반 server/api
Canonical중복 URL 방지useHead({ link: [{ rel: 'canonical' }] })
SSR검색엔진 크롤러 SSR 보장routeRules로 SSR/ISR 모드 지정
i18nhreflang 태그, lang 속성@nuxtjs/i18n 모듈
+ +

Layer 2 — AEO 체크리스트

+ + + + + + + + + + +
영역점검 항목구현 전략
질문형 구조H2를 실제 사용자 질문 형태로"제품 가격은?" 대신 "이 제품의 가격은 얼마인가요?"
즉답 패턴질문 직후 200자 이내 직접 답변TLDR-first 콘텐츠 구조 적용
FAQ SchemaFAQPage JSON-LDuseSchemaOrg([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가 최신 상태인가
+
+ +
+ + +
+
09
+

Claude Code Skills 통합 체계 Skills 폴더 구조, 네이밍, 설계 원칙

+
+ +

전체 Skills 폴더 구조

+ +
+ skill tree · v1.1 +nuxt-fe-skills/ +│ +├── nuxt-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 +│ ├── promotion/ # Phase 2-1: 프로모션 마크업 🆕 NEW +│ │ ├── SKILL.md +│ │ └── references/ +│ └── edm/ # Phase 2-2: EDM 마크업 🆕 NEW +│ ├── SKILL.md +│ └── references/ +│ +├── nuxt-component-architect/ # Phase 3: 컴포넌트 아키텍처 +│ └── SKILL.md +│ +├── nuxt/ # Phase 3-1: Nuxt 공식문서 기반 🆕 NEW +│ ├── SKILL.md +│ └── references/ +│ ├── server.md +│ ├── middleware.md +│ ├── plugins.md +│ ├── nuxt-composables.md +│ ├── nuxt-components.md +│ └── nuxt-config.md +│ +├── nuxt-api-state-manager/ # Phase 4: API·상태관리 +│ ├── SKILL.md +│ ├── scripts/ +│ │ └── generate-store.js +│ └── references/ +│ ├── pinia-patterns.md +│ └── api-error-handling.md +│ +├── nuxt-perf-optimizer/ # Phase 5: 성능 최적화 ⚡ CHANGED +│ ├── 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 🆕 NEW + ├── 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 폴더명{도메인} 또는 nuxt-{도메인}-{역할} kebab-casemarkup, nuxt, nuxt-seo-geo
SKILL.md대문자 고정, 폴더당 1개SKILL.md
참조 문서{도메인}-{주제}.md kebab-casegeo-optimization.md
스크립트{동사}-{대상}.js kebab-caseschema-validator.js
+ +

Skill 설계 3원칙

+ +
+ 📐 +
원칙 1: Progressive Disclosure (점진적 공개) — SKILL.md는 500줄 이내. 상세 내용은 references/에 분리. Claude는 컨텍스트에 따라 필요한 참조만 선택적으로 로드합니다.
+
+
+ 🎯 +
원칙 2: Pushy Description (적극적 트리거) — Skill description에 다양한 트리거 키워드를 포함하여 관련 상황에서 누락 없이 활성화. 언더트리거보다 오버트리거가 낫습니다.
+
+
+ 📋 +
원칙 3: Deterministic Output (결정적 출력) — 동일한 입력에 대해 일관된 구조의 출력을 보장. 출력 포맷(디렉토리 구조, 코드 패턴, 체크리스트)을 명확히 정의합니다.
+
+ +
+ + +
+
10
+

실행 로드맵 & 일정 단계별 도입 타임라인 및 마일스톤

+
+ +

도입 타임라인

+ + + + + + + + + + + + +
주차Phase핵심 활동산출물
W1–W2Phase 1요구사항 분석 Skill 개발 및 테스트nuxt-requirement-analyzer
W2–W3Phase 2 / 2-1 / 2-2마크업 컨벤션 + 프로모션·EDM Skill 개발markup, markup/promotion, markup/edm
W3–W5Phase 3 / 3-1Nuxt 컴포넌트 아키텍처 + 공식문서 참조 Skill 개발nuxt-component-architect, nuxt
W5–W7Phase 4API/Pinia 패턴 표준화 및 Skill 개발nuxt-api-state-manager
W7–W8Phase 5성능 최적화 Skill 개발 및 파일럿nuxt-perf-optimizer CHANGED
W8–W10Phase 6 NEWSEO·GEO·AEO 감사 Skill 개발nuxt-seo-geo
W10–W11통합전체 Skill 통합 테스트 및 팀 교육교육 자료, 온보딩 가이드
W12–운영실 프로젝트 적용 및 피드백 기반 개선Skill 버전 업데이트 로그
+ +

성공 지표 (KPI)

+ +
+
+
코드 리뷰 반려율
+
35%
+
→
+
15%↓
+
+
+
컴포넌트 재사용률
+
30%
+
→
+
70%↑
+
+
+
신규 온보딩 기간
+
3주
+
→
+
1주
+
+
+
Lighthouse 성능 점수
+
65~75
+
→
+
90+
+
+
+
SEO 메타 누락률
+
40%
+
→
+
5%↓
+
+
+
AI 검색 인용률 NEW
+
미측정
+
→
+
측정 체계 구축
+
+
+ +
+ +

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

+ + + diff --git a/telegram_bot.py b/telegram_bot.py new file mode 100644 index 0000000..d2c76b0 --- /dev/null +++ b/telegram_bot.py @@ -0,0 +1,236 @@ +""" +Telegram 봇 - FE AI 표준화 프로젝트 팀 업무 지원 봇 + +기능: + - 기본 에코 + - 스탠드업 리마인더 자동 발송 (매일 09:30 KST) + - 로드맵 태스크 상태 조회 + +필요 패키지: + pip install python-telegram-bot[job-queue] + +환경변수: + TELEGRAM_BOT_TOKEN - BotFather에서 발급받은 토큰 (필수) + STANDUP_CHAT_IDS - 스탠드업 리마인더를 받을 채팅 ID 목록 (쉼표 구분, 선택) + 예) STANDUP_CHAT_IDS=123456789,987654321 +""" + +import json +import logging +import os +from datetime import time +from pathlib import Path +from typing import Final + +from telegram import Update +from telegram.ext import ( + Application, + CommandHandler, + ContextTypes, + MessageHandler, + filters, +) + +# ── 로깅 설정 ───────────────────────────────────────────── +logging.basicConfig( + format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", + level=logging.INFO, +) +logger = logging.getLogger(__name__) + +# ── 설정 ───────────────────────────────────────────────── +BOT_TOKEN: Final[str] = os.environ.get("TELEGRAM_BOT_TOKEN", "") +TASKS_FILE: Final[Path] = Path(__file__).parent / "shrimp_data" / "tasks.json" + +# 스탠드업 리마인더 발송 시간 (KST = UTC+9) +STANDUP_HOUR: Final[int] = 9 +STANDUP_MINUTE: Final[int] = 30 + +# 환경변수로 사전 등록할 채팅 ID 목록 +STANDUP_CHAT_IDS: Final[list[int]] = [ + int(cid) + for cid in os.environ.get("STANDUP_CHAT_IDS", "").split(",") + if cid.strip() +] + +STATUS_LABELS: Final[dict[str, str]] = { + "pending": "⏳ 대기", + "in-progress": "🔄 진행중", + "completed": "✅ 완료", + "deferred": "⏸ 보류", + "cancelled": "❌ 취소", +} + + +# ── 유틸리티 ────────────────────────────────────────────── + +def load_tasks() -> list[dict]: + """shrimp_data/tasks.json에서 태스크 목록을 로드한다.""" + if not TASKS_FILE.exists(): + return [] + with TASKS_FILE.open(encoding="utf-8") as f: + data = json.load(f) + return data.get("tasks", []) + + +def format_task_line(task: dict) -> str: + """태스크 한 줄 요약을 반환한다.""" + status = STATUS_LABELS.get(task.get("status", ""), task.get("status", "")) + name = task.get("name", "(이름 없음)") + return f"{status} {name}" + + +# ── 커맨드 핸들러 ───────────────────────────────────────── + +async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: + """/start — 봇 소개 및 명령어 안내""" + text = ( + "안녕하세요! FE AI 표준화 프로젝트 봇입니다. 👋\n\n" + "사용 가능한 명령어\n" + "/tasks — 전체 태스크 목록\n" + "/tasks\\_pending — 대기 중인 태스크\n" + "/tasks\\_done — 완료된 태스크\n" + "/standup — 스탠드업 리마인더 구독\n" + "/help — 도움말" + ) + await update.message.reply_text(text, parse_mode="Markdown") + + +async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: + """/help — 도움말 (start와 동일)""" + await start(update, context) + + +async def tasks_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: + """/tasks — 전체 태스크를 상태별로 보여준다.""" + all_tasks = load_tasks() + if not all_tasks: + await update.message.reply_text("태스크 데이터를 불러올 수 없습니다.") + return + + total = len(all_tasks) + done = sum(1 for t in all_tasks if t.get("status") == "completed") + lines = [f"📋 *전체 태스크 ({done}/{total} 완료)*\n"] + for task in all_tasks: + lines.append(format_task_line(task)) + + await update.message.reply_text("\n".join(lines), parse_mode="Markdown") + + +async def tasks_pending_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: + """/tasks_pending — 대기 중인 태스크만 조회한다.""" + pending = [t for t in load_tasks() if t.get("status") == "pending"] + + if not pending: + await update.message.reply_text("✅ 대기 중인 태스크가 없습니다!") + return + + lines = [f"⏳ *대기 중인 태스크 ({len(pending)}개)*\n"] + for task in pending: + lines.append(format_task_line(task)) + + await update.message.reply_text("\n".join(lines), parse_mode="Markdown") + + +async def tasks_done_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: + """/tasks_done — 완료된 태스크만 조회한다.""" + done = [t for t in load_tasks() if t.get("status") == "completed"] + + if not done: + await update.message.reply_text("아직 완료된 태스크가 없습니다.") + return + + lines = [f"✅ *완료된 태스크 ({len(done)}개)*\n"] + for task in done: + lines.append(format_task_line(task)) + + await update.message.reply_text("\n".join(lines), parse_mode="Markdown") + + +async def standup_subscribe(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: + """/standup — 이 채팅을 스탠드업 리마인더 수신 대상으로 등록한다.""" + chat_id = update.effective_chat.id + registered: set[int] = context.bot_data.setdefault("standup_chats", set()) + + if chat_id in registered: + await update.message.reply_text("이미 등록된 채팅입니다.") + return + + registered.add(chat_id) + await update.message.reply_text( + f"✅ 스탠드업 리마인더에 등록되었습니다.\n" + f"매일 *{STANDUP_HOUR:02d}:{STANDUP_MINUTE:02d} KST*에 알림을 보내드립니다.", + parse_mode="Markdown", + ) + + +# ── 에코 핸들러 ─────────────────────────────────────────── + +async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: + """명령어가 아닌 텍스트 메시지를 그대로 반환한다.""" + await update.message.reply_text(update.message.text) + + +# ── 스케줄 작업 ─────────────────────────────────────────── + +async def send_standup_reminder(context: ContextTypes.DEFAULT_TYPE) -> None: + """등록된 모든 채팅에 스탠드업 리마인더를 발송한다.""" + message = ( + "🌅 *스탠드업 리마인더*\n\n" + "오늘의 스탠드업을 시작할 시간입니다!\n\n" + "1️⃣ *어제 한 일*:\n" + "2️⃣ *오늘 할 일*:\n" + "3️⃣ *블로커*:" + ) + + # 환경변수 등록 + 런타임 /standup 구독 채팅 합산 + target_chats: set[int] = set(STANDUP_CHAT_IDS) | context.bot_data.get( + "standup_chats", set() + ) + + for chat_id in target_chats: + try: + await context.bot.send_message( + chat_id=chat_id, + text=message, + parse_mode="Markdown", + ) + logger.info("스탠드업 리마인더 발송 완료 (chat_id=%s)", chat_id) + except Exception as e: + logger.error("스탠드업 리마인더 발송 실패 (chat_id=%s): %s", chat_id, e) + + +# ── 앱 빌드 & 실행 ──────────────────────────────────────── + +def main() -> None: + if not BOT_TOKEN: + raise ValueError( + "TELEGRAM_BOT_TOKEN 환경변수를 설정해주세요.\n" + "예) export TELEGRAM_BOT_TOKEN=your_token_here" + ) + + app = Application.builder().token(BOT_TOKEN).build() + + # 커맨드 핸들러 등록 + app.add_handler(CommandHandler("start", start)) + app.add_handler(CommandHandler("help", help_command)) + app.add_handler(CommandHandler("tasks", tasks_command)) + app.add_handler(CommandHandler("tasks_pending", tasks_pending_command)) + app.add_handler(CommandHandler("tasks_done", tasks_done_command)) + app.add_handler(CommandHandler("standup", standup_subscribe)) + + # 에코 핸들러 (명령어가 아닌 텍스트) + app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo)) + + # 매일 09:30 KST (UTC 00:30)에 스탠드업 리마인더 발송 + app.job_queue.run_daily( + send_standup_reminder, + time=time(hour=0, minute=30), # UTC 기준 (KST -9h) + ) + + logger.info("봇 시작 — polling 모드") + app.run_polling(allowed_updates=Update.ALL_TYPES) + + +if __name__ == "__main__": + main()