Communitygithub.com

asolis87/vera-sesiom-skills

Vera Sesiom의 랜딩 페이지, 콘텐츠 사이트 및 SSG 프로젝트를 위한 Astro 컨벤션입니다. 기본적으로 Zero JS, Vue Islands를 통한 상호작용, 콘텐츠 우선 아키텍처를 제공합니다.

vera-sesiom-skills란 무엇인가요?

이 스킬은 Vera Sesiom 팀이 랜딩 페이지, 마케팅 사이트, 블로그, 문서 등 콘텐츠 중심의 정적 사이트를 구축할 때 사용하는 Astro 개발 컨벤션을 정의합니다. 핵심 철학은 **Zero JS by Default**로, Astro가 필요할 때만 JavaScript를 전송하여 최고의 성능과 SEO를 보장합니다. 콘텐츠 컬렉션(Content Collections)을 통해 블로그 포스트나 문서 같은 구조화된 콘텐츠를 Zod 스키마로 검증하고, 상호작용이 필요한 부분에만 Vue 컴포넌트를 'Island' 형태로 추가하는 **Islands Architecture**를 사용합니다. 스타일링은 Tailwind CSS를 사용하며, 프로젝트 구조는 'Screaming Architecture'를 따라 폴더 이름이 도메인(예: `sections/`, `content/`, `interactive/`)을 나타냅니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트가 프로젝트를 만들거나 유지보수할 때 자동으로 참조하여 일관된 아키텍처를 적용할 수 있도록 돕습니다. 스킬은 Astro의 클라이언트 디렉티브(client:visible, client:load 등) 결정 트리, 레이아웃 패턴, SEO 패턴, 이미지 최적화 규칙을 상세히 설명하며, 대시보드나 SPA 같은 웹 앱에는 Vue 프론트엔드(vue-frontend)를 사용할 것을 명확히 구분합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/asolis87/vera-sesiom-skills/tree/HEAD/skills/astro-landing

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

사용 시기

  • 랜딩 페이지 및 마케팅 사이트
  • 기업 웹사이트
  • 콘텐츠 중심 사이트 (블로그, 문서)
  • SEO와 성능이 중요한 모든 프로젝트
  • 상호작용이 거의 없는 정적 콘텐츠 위주 사이트
  • 빠른 초기 로딩과 Core Web Vitals가 필요한 사이트

풀 웹 앱에는 사용하지 마세요 — 대화형 애플리케이션(대시보드, CRUD 앱, 실시간 앱)에는 vue-frontend를 사용하세요.


중요한 규칙

  1. 기본적으로 Zero JS — Astro는 client: 디렉티브를 추가하지 않으면 JavaScript를 전혀 보내지 않습니다.
  2. 항상 TypeScript 사용 — 모든 Vera Sesiom 프로젝트와 마찬가지로 strict 모드를 사용합니다.
  3. 구조화된 콘텐츠에는 Content Collections 사용 — 블로그 포스트, 문서, 사례 연구 등.
  4. Islands Architecture — 상호작용이 필요한 부분에서만 Vue/React 컴포넌트를 사용합니다.
  5. 기본 출력은 정적(SSG) — 동적 콘텐츠가 필요한 경우에만 SSR을 사용합니다.
  6. 스타일링은 Tailwind CSS — Vue 프론트엔드와 동일합니다.
  7. Screaming Architecture — 폴더 이름은 프레임워크가 아닌 도메인을 나타냅니다.

결정 기준: Astro vs Vue

Astro 사용 시기Vue 사용 시기
랜딩 페이지, 마케팅 사이트웹 애플리케이션 (대시보드, 관리자)
콘텐츠 중심 (블로그, 문서)고도로 상호작용적인 UI
SEO가 중요한 경우실시간 기능이 필요한 경우
대부분 정적 콘텐츠복잡한 상태 관리
최소한의 상호작용 (폼, 캐러셀)전체 SPA 탐색
Zero JS가 장점인 경우Vue 생태계의 이점이 중요한 경우

규칙: 사이트가 사람들이 읽는 콘텐츠라면 → Astro. 사람들이 사용하는 앱이라면 → Vue.


프로젝트 구조 (Screaming Architecture)

apps/landing/   (또는 apps/website/)
├── src/
│   ├── pages/                    # 파일 기반 라우팅 (.astro 파일)
│   │   ├── index.astro           # 홈페이지
│   │   ├── about.astro           # 소개 페이지
│   │   ├── pricing.astro         # 가격 페이지
│   │   ├── blog/
│   │   │   ├── index.astro      # 블로그 목록
│   │   │   └── [slug].astro      # 블로그 포스트 (동적)
│   │   └── contact.astro
│   ├── layouts/                  # 페이지 레이아웃
│   │   ├── BaseLayout.astro      # 기본 HTML 구조
│   │   ├── BlogLayout.astro      # 블로그 포스트 레이아웃
│   │   └── LandingLayout.astro   # 랜딩 페이지 레이아웃
│   ├── components/               # Astro 컴포넌트 (기본적으로 정적)
│   │   ├── sections/             # 페이지 섹션
│   │   │   ├── Hero.astro
│   │   │   ├── Features.astro
│   │   │   ├── Pricing.astro
│   │   │   ├── Testimonials.astro
│   │   │   └── CTA.astro
│   │   ├── ui/                   # 재사용 가능한 UI 원자 요소
│   │   │   ├── Button.astro
│   │   │   ├── Card.astro
│   │   │   ├── Badge.astro
│   │   │   └── Input.astro
│   │   └── interactive/          # Vue/React Islands
│   │       ├── ContactForm.vue   # 유효성 검사가 있는 폼
│   │       ├── Carousel.vue      # 이미지 캐러셀
│   │       └── MobileMenu.vue    # 모바일 내비게이션
│   ├── content/                  # 콘텐츠 컬렉션
│   │   ├── blog/                 # Markdown/MDX 블로그 포스트
│   │   │   ├── post-1.md
│   │   │   └── post-2.mdx
│   │   └── config.ts             # 컬렉션 스키마 (Zod)
│   ├── styles/                   # 전역 스타일
│   │   └── global.css            # Tailwind 임포트
│   ├── assets/                   # 최적화된 이미지, 폰트
│   │   ├── images/
│   │   └── fonts/
│   └── utils/                    # 헬퍼 함수
│       ├── date-format.ts
│       └── seo.ts
├── public/                       # 정적 자산 (처리 없음)
│   ├── favicon.ico
│   ├── robots.txt
│   └── fonts/
├── astro.config.mjs              # Astro 설정
├── tailwind.config.mjs           # Tailwind 설정
├── tsconfig.json
└── package.json

Astro 컴포넌트 패턴

모든 .astro 파일은 두 부분으로 구성됩니다: 프런트매터(Frontmatter, 서버 측)와 템플릿(HTML).

---
// src/components/ui/Button.astro
// 프런트매터: 서버 측에서 실행, 브라우저 JS 없음

export interface Props {
  variant?: 'primary' | 'secondary' | 'outline'
  size?: 'sm' | 'md' | 'lg'
  href?: string
}

const {
  variant = 'primary',
  size = 'md',
  href,
  ...rest
} = Astro.props

const baseClasses = 'inline-flex items-center justify-center font-medium rounded-lg transition-colors'
const variantClasses = {
  primary: 'bg-blue-600 text-white hover:bg-blue-700',
  secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
  outline: 'border-2 border-blue-600 text-blue-600 hover:bg-blue-50'
}
const sizeClasses = {
  sm: 'px-3 py-1.5 text-sm',
  md: 'px-4 py-2 text-base',
  lg: 'px-6 py-3 text-lg'
}

const classes = `${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]}`
---

{href ? (
  <a href={href} class={classes} {...rest}>
    <slot />
  </a>
) : (
  <button class={classes} {...rest}>
    <slot />
  </button>
)}

핵심 포인트:

  • 프런트매터는 빌드 시 (또는 SSR의 경우 요청 시) 실행됩니다.
  • export default가 필요 없습니다 — 템플릿 자체가 export입니다.
  • <slot />은 자식 콘텐츠를 위한 자리입니다.
  • Props는 TypeScript 인터페이스로 타입이 지정됩니다.

레이아웃 패턴

---
// src/layouts/BaseLayout.astro
import Nav from '../components/Nav.astro'
import Footer from '../components/Footer.astro'

export interface Props {
  title: string
  description?: string
  image?: string
}

const { title, description = '', image = '/og-default.png' } = Astro.props
const canonicalURL = new URL(Astro.url.pathname, Astro.site)
---

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="canonical" href={canonicalURL} />
    <title>{title}</title>
    <meta name="description" content={description} />
    
    <!-- OpenGraph -->
    <meta property="og:title" content={title} />
    <meta property="og:description" content={description} />
    <meta property="og:image" content={image} />
    <meta property="og:url" href={canonicalURL} />
    <meta property="og:type" content="website" />
    
    <!-- Twitter -->
    <meta name="twitter:card" content="summary_large_image" />
    
    <slot name="head" />
  </head>
  <body class="bg-white text-gray-900 antialiased">
    <Nav />
    <main>
      <slot />
    </main>
    <Footer />
  </body>
</html>

사용법:

---
// src/pages/index.astro
import BaseLayout from '../layouts/BaseLayout.astro'
import Hero from '../components/sections/Hero.astro'
---

<BaseLayout title="Vera Sesiom - Software Development" description="We build software that matters.">
  <Hero />
</BaseLayout>

콘텐츠 컬렉션 패턴

Zod 스키마 검증으로 구조화된 콘텐츠를 정의합니다.

// src/content/config.ts
import { defineCollection, z } from 'astro:content'

const blogCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    author: z.string().default('Vera Sesiom'),
    image: z.object({
      url: z.string(),
      alt: z.string()
    }).optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false)
  })
})

export const collections = {
  blog: blogCollection
}
---
title: "Why We Chose Astro for Landing Pages"
description: "Performance and developer experience matter. Here's why Astro is our go-to for content sites."
pubDate: 2024-01-15
author: "Tech Lead"
image:
  url: "/images/blog/astro-landing.jpg"
  alt: "Astro logo on a modern website"
tags: ["astro", "performance", "architecture"]
---

Content goes here...
---
// src/pages/blog/index.astro
import { getCollection } from 'astro:content'
import BaseLayout from '../../layouts/BaseLayout.astro'

const posts = (await getCollection('blog'))
  .filter(post => !post.data.draft)
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf())
---

<BaseLayout title="Blog" description="Latest articles from Vera Sesiom">
  <h1>Blog</h1>
  <ul>
    {posts.map(post => (
      <li>
        <a href={`/blog/${post.slug}`}>
          <h2>{post.data.title}</h2>
          <p>{post.data.description}</p>
          <time>{post.data.pubDate.toLocaleDateString()}</time>
        </a>
      </li>
    ))}
  </ul>
</BaseLayout>
---
// src/pages/blog/[slug].astro
import { getCollection } from 'astro:content'
import BaseLayout from '../../layouts/BaseLayout.astro'

export async function getStaticPaths() {
  const posts = await getCollection('blog')
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post }
  }))
}

const { post } = Astro.props
const { Content } = await post.render()
---

<BaseLayout title={post.data.title} description={post.data.description}>
  <article>
    <header>
      <h1>{post.data.title}</h1>
      <time>{post.data.pubDate.toLocaleDateString()}</time>
      <p>By {post.data.author}</p>
    </header>
    <Content />
  </article>
</BaseLayout>

Islands Architecture (Vue 컴포넌트)

대화형 컴포넌트는 필요할 때만 JS를 제공합니다. client: 디렉티브를 사용하여 하이드레이션을 제어합니다.

<!-- src/components/interactive/ContactForm.vue -->
<script setup lang="ts">
import { ref, computed } from 'vue'

const form = ref({
  name: '',
  email: '',
  message: ''
})

const errors = ref<Record<string, string>>({})

const isValid = computed(() => {
  return form.value.name && 
         form.value.email.includes('@') && 
         form.value.message.length > 10
})

async function submitForm() {
  if (!isValid.value) return
  
  // Submit to API
  const response = await fetch('/api/contact', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(form.value)
  })
  
  if (response.ok) {
    // Handle success
    form.value = { name: '', email: '', message: '' }
  }
}
</script>

<template>
  <form @submit.prevent="submitForm" class="space-y-4">
    <div>
      <label for="name">Name</label>
      <input v-model="form.name" type="text" id="name" required />
    </div>
    <div>
      <label for="email">Email</label>
      <input v-model="form.email" type="email" id="email" required />
    </div>
    <div>
      <label for="message">Message</label>
      <textarea v-model="form.message" id="message" rows="4" required />
    </div>
    <button type="submit" :disabled="!isValid">
      Send Message
    </button>
  </form>
</template>

Astro에서 사용하기:

---
// src/pages/contact.astro
import BaseLayout from '../layouts/BaseLayout.astro'
import ContactForm from '../components/interactive/ContactForm.vue'
---

<BaseLayout title="Contact Us">
  <h1>Get in Touch</h1>
  <p>We'd love to hear from you.</p>
  
  <!-- client:visible = 스크롤되어 보일 때 하이드레이션 (BEST PRACTICE) -->
  <ContactForm client:visible />
</BaseLayout>

클라이언트 디렉티브 결정 트리

디렉티브사용 시기JS 제공 시점
디렉티브 없음정적 콘텐츠, 상호작용 없음Zero JS
client:visible스크롤 아래 상호작용 (폼, 캐러셀) — 기본값화면에 보일 때
client:load스크롤 위 중요한 상호작용즉시
client:idle중요하지 않은 기능 (분석, 채팅)페이지가 유휴 상태일 때
client:media반응형 조건 (모바일 내비게이션)미디어 쿼리 일치 시
client:onlySPA 스타일 컴포넌트 (SSR 건너뛰기)즉시, SSR 없음

모범 사례:

  • 기본적으로 디렉티브 없음 — 순수 정적
  • 상호작용이 필요할 때 기본적으로 client:visible 사용
  • client:load는 중요한 스크롤 위 콘텐츠에만 제한적으로 사용
  • client:idle은 블로킹되지 않는 기능에 사용
---
<!-- 좋은 예시 -->
import Hero from './Hero.astro'                    <!-- 정적, JS 없음 -->
import Carousel from './Carousel.vue'             
import MobileMenu from './MobileMenu.vue'         
import Chat from './Chat.vue'                     
import Stats from './Stats.astro'                  <!-- 정적 카운터 = CSS -->

<Hero />                                          <!-- 정적, 하이드레이션 없음 -->
<Carousel client:visible />                       <!-- 보일 때 하이드레이션 -->
<MobileMenu client:media="(max-width: 768px)" />  <!-- 모바일 전용 -->
<Chat client:idle />                               <!-- 페이지 정착 후 -->
<Stats />                                          <!-- 순수 CSS 애니메이션, JS 필요 없음 -->

이미지 최적화

자동 최적화를 위해 astro:assets를 사용하세요.

---
// src/pages/index.astro
import { Image } from 'astro:assets'
import heroImage from '../assets/images/hero.png'
---

<Image 
  src={heroImage} 
  alt="Hero image" 
  width={800} 
  height={600}
  loading="lazy"
  format="webp"
/>

CMS 또는 외부 소스의 이미지의 경우:

---
import { Image } from 'astro:assets'
---

<Image 
  src="https://example.com/image.jpg" 
  alt="External image" 
  width={800}
  height={600}
/>

규칙:

  • CLS 방지를 위해 항상 width와 height를 지정하세요.
  • 스크롤 아래 이미지에는 loading="lazy"를 사용하세요.
  • webp 또는 avif 형식을 선호하세요.
  • 히어로 이미지는 최적화되고 적절한 크기로 유지하세요.

SEO 패턴

---
// src/components/SEO.astro
export interface Props {
  title: string
  description: string
  image?: string
  article?: boolean
  publishedTime?: Date
  author?: string
  tags?: string[]
}

const { 
  title, 
  description, 
  image = '/og-default.png',
  article = false,
  publishedTime,
  author,
  tags = []
} = Astro.props

const canonicalURL = new URL(Astro.url.pathname, Astro.site)
const imageURL = new URL(image, Astro.site)
---

<!-- Primary Meta Tags -->
<title>{title}</title>
<meta name="title" content={title} />
<meta name="description" content={description} />
<link rel="canonical" href={canonicalURL} />

<!-- Open Graph -->
<meta property="og:type" content={article ? 'article' : 'website'} />
<meta property="og:url" content={canonicalURL} />
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
<meta property="og:image" content={imageURL} />

<!-- Twitter -->
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content={title} />
<meta name="twitter:description" content={description} />
<meta name="twitter:image" content={imageURL} />

<!-- Article specific -->
{article && (
  <>
    <meta property="article:published_time" content={publishedTime?.toISOString()} />
    <meta property="article:author" content={author} />
    {tags.map(tag => (
      <meta property="article:tag" content={tag} />
    ))}
  </>
)}

관련 스킬