Claude Code로 Astro 개발 가속화하기: 콘텐츠 사이트 가이드

Claude Code로 Astro 개발 가속화하기

Astro는 “아일랜드 아키텍처”를 통한 높은 성능과 콘텐츠 우선 설계로 주목받는 프레임워크입니다. Claude Code를 활용하면 Astro의 고유 문법과 콘텐츠 컬렉션 설계를 원활하게 진행할 수 있습니다.

프로젝트 셋업

> Astro 프로젝트를 만들어줘.
> 요구사항:
> - TypeScript strict
> - Tailwind CSS
> - MDX 지원
> - 사이트맵 자동 생성

Claude Code는 astro.config.mjs 설정과 함께 필요한 인테그레이션 추가 명령도 알려줍니다.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',
  integrations: [tailwind(), mdx(), sitemap()],
  markdown: {
    shikiConfig: {
      theme: 'github-dark',
    },
  },
});

콘텐츠 컬렉션 설계

스키마 정의

> 블로그 글용 Content Collection 스키마를 만들어줘.
> title, description, pubDate, tags, draft, coverImage를 포함해줘.

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

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string().max(100),
    description: z.string().max(200),
    pubDate: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    coverImage: z.string().optional(),
  }),
});

export const collections = { blog };

아일랜드 아키텍처 활용

Astro의 최대 특징인 아일랜드 아키텍처에서는 인터랙티브한 컴포넌트에만 JavaScript를 로드합니다.

---
// 정적 부분은 서버에서 렌더링
import Header from '../components/Header.astro';
import SearchBar from '../components/SearchBar.tsx';
import Footer from '../components/Footer.astro';
---

<Header />
<!-- client:visible로 뷰포트에 들어왔을 때만 하이드레이션 -->
<SearchBar client:visible />
<Footer />

Claude Code에 “이 컴포넌트는 client:load와 client:visible 중 어느 것이 적절해?”라고 물으면 유스케이스에 맞는 최적의 디렉티브를 제안해 줍니다.

동적 라우팅과 페이지 생성

> 태그별 글 목록 페이지를 동적으로 생성해줘.
> 페이지네이션도 포함해줘.

---
// src/pages/tag/[tag]/[...page].astro
import { getCollection } from 'astro:content';
export async function getStaticPaths({ paginate }) {
  const posts = await getCollection('blog', ({ data }) => !data.draft);
  const tags = [...new Set(posts.flatMap(post => post.data.tags))];

  return tags.flatMap(tag => {
    const filtered = posts.filter(post => post.data.tags.includes(tag));
    return paginate(filtered, { params: { tag }, pageSize: 10 });
  });
}
const { page } = Astro.props;
---

성능 최적화

Astro는 기본적으로 빠르지만, 이미지 최적화와 프리페치 설정으로 더욱 개선할 수 있습니다. Claude Code에 “Lighthouse 점수를 100으로 만들고 싶어”라고 전달하면 구체적인 최적화 포인트를 제안해 줍니다.

정리

Claude Code를 활용하면 Astro의 고유 문법과 콘텐츠 컬렉션 설계를 빠르게 익히고 고성능 사이트를 구축할 수 있습니다. SSR/SSG 비교 가이드와 SEO 최적화도 함께 참고하세요.

Astro에 대한 자세한 내용은 Astro 공식 문서를 참고하세요.