HomeBlogPortfolioLab
Contact
목록으로
AI Skills로 Vue 개발하기

AI Skills로 Vue 개발하기 (6) - VitePress 문서화와 스킬 시스템 회고

2026년 03월 05일13 min read
#Vue#Claude Code#AI#VitePress#Documentation
목차 보기
시리즈 목차 보기6 / 6

AI Skills로 Vue 개발하기

6 / 6

  1. 프로젝트 셋업과 코딩 컨벤션
  2. 컴포넌트 설계와 Composition API
  3. Pinia 상태 관리와 Vue Router
  4. Vite, Vitest, 그리고 테스트 자동화
  5. Nuxt 3로 풀스택 전환하기
  6. VitePress 문서화와 스킬 시스템 회고

이전 편 요약

5편에서는 Nuxt 3로 풀스택 영역까지 확장하고, Design 스킬을 적용해 UI 품질을 끌어올렸다. 서버 API 라우트, composable 기반의 데이터 페칭, 레이아웃 시스템까지 갖춰진 상태다. 프로젝트가 여기까지 오면 코드만으로는 전체 구조를 파악하기 어려워진다. 마지막 편에서는 VitePress로 프로젝트를 문서화하고, 지난 3개월간의 스킬 활용을 돌아본다.

코드만으로는 부족하다

프로젝트 초기에는 코드가 곧 문서였다. 파일 수가 적고 구조가 단순하니까 코드만 읽으면 됐다. 그런데 편이 거듭되면서 컴포넌트, composable, store, API 엔드포인트가 늘어났고, "이 Props에 뭘 넘겨야 하지?", "이 store의 상태 구조가 어떻게 되지?" 같은 질문이 코드만으로 해결되지 않는 시점이 왔다.

특히 팀 프로젝트에서는 이 문제가 더 심하다. 본인이 만든 컴포넌트라도 2주만 지나면 Props 인터페이스를 까먹는다. 다른 팀원이 만든 store라면 말할 것도 없다. 문서가 필요했다.

VitePress를 선택한 이유는 명확했다. Vue 생태계 공식 도구이고, Markdown 안에서 Vue 컴포넌트를 직접 렌더링할 수 있고, Vite 기반이라 HMR이 빠르다. 컴포넌트 라이브러리 문서화에는 이만한 선택지가 없었다.

VitePress 프로젝트 셋업

VitePress 스킬이 가이드하는 설정은 세 가지에 집중한다. 사이드바 구조, 네비게이션, 그리고 검색이다. 처음부터 완벽한 구조를 잡으려 하지 않아도 된다. 가이드, 컴포넌트, API 세 섹션으로 나누고 로컬 검색을 붙이면 기본 골격은 완성이다.

ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '프로젝트 문서',
  description: 'Vue 컴포넌트 라이브러리 문서',
  themeConfig: {
    nav: [
      { text: '가이드', link: '/guide/' },
      { text: '컴포넌트', link: '/components/' },
      { text: 'API', link: '/api/' },
    ],
    sidebar: {
      '/guide/': [
        { text: '시작하기', link: '/guide/getting-started' },
        { text: '프로젝트 구조', link: '/guide/structure' },
      ],
      '/components/': [
        { text: 'DataTable', link: '/components/data-table' },
        { text: 'StatCard', link: '/components/stat-card' },
      ],
    },
    search: { provider: 'local' },
  },
})

search.provider를 local로 설정하면 별도의 Algolia 설정 없이도 전문 검색이 동작한다. 문서 규모가 작은 프로젝트에서는 이것만으로 충분했다. 사이드바는 섹션별로 분리해서 사용자가 현재 어떤 카테고리를 탐색하고 있는지 명확하게 만들었다.

Markdown 안에서 Vue 사용하기

VitePress의 진짜 장점은 Markdown이 곧 Vue SFC라는 점이다. .md 파일 안에서 <script setup>을 쓸 수 있고, Vue 컴포넌트를 직접 임포트해서 렌더링할 수 있다. 문서에 정적 스크린샷을 붙이는 게 아니라, 실제 동작하는 컴포넌트를 보여줄 수 있다는 뜻이다.

md
# DataTable

정렬, 필터링을 지원하는 데이터 테이블 컴포넌트.

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| items | `T[]` | Yes | 테이블에 표시할 데이터 배열 |
| columns | `Column<T>[]` | Yes | 컬럼 정의 배열 |

## 사용 예시

<script setup>
import DataTableDemo from '../demos/DataTableDemo.vue'
</script>

<DataTableDemo />

Props 테이블 아래에 실제 동작하는 데모 컴포넌트가 렌더링된다. 사용자는 문서를 읽으면서 바로 동작을 확인할 수 있다. 이게 단순 Markdown 문서 도구와 VitePress의 결정적인 차이다.

API 문서 자동 생성

컴포넌트에 JSDoc 주석을 성실하게 작성해두면, 그 정보를 기반으로 VitePress 문서 페이지를 자동 생성할 수 있다. Props의 타입, 기본값, 설명을 JSDoc으로 정의하고, Emits와 Slots도 동일한 패턴으로 문서화한다.

vue
<script setup lang="ts">
/**
 * 정렬, 필터링을 지원하는 데이터 테이블 컴포넌트
 * @displayName DataTable
 */

interface Props {
  /** 테이블에 표시할 데이터 배열 */
  items: Record<string, unknown>[]
  /** 컬럼 정의 배열 */
  columns: Column[]
  /** 페이지당 표시할 행 수 */
  pageSize?: number
}

const props = withDefaults(defineProps<Props>(), {
  pageSize: 10,
})

/** 정렬 상태가 변경될 때 발생 */
const emit = defineEmits<{
  sort: [key: string, direction: 'asc' | 'desc']
}>()
</script>

Claude Code에 "이 컴포넌트의 VitePress 문서 페이지를 만들어줘"라고 요청하면, VitePress 스킬을 참조해서 Props 테이블, Emits 목록, 사용 예시가 포함된 .md 파일을 생성해준다. JSDoc이 정확할수록 자동 생성되는 문서의 품질도 올라간다. 결국 좋은 문서의 시작은 좋은 타입 정의와 주석이었다.

스킬 시스템 회고

6편에 걸쳐 다양한 스킬을 활용했다. 각 스킬이 어떤 맥락에서 효과적이었는지 정리해봤다.

스킬적용 편핵심 효과체감 점수
Antfu1편일관된 코딩 스타일 자동 적용5/5
Vue2, 3편Composition API best practices5/5
Build-tooling1, 4편빌드/테스트 설정 자동화4/5
Design5편AI slop 탈출, UI 품질 향상4/5
Nuxt5편풀스택 확장 가이드4/5
VitePress6편문서 구조 자동 생성3/5

가장 효과적이었던 조합

Antfu + Vue 스킬 조합이 압도적이었다. Antfu 스킬이 코딩 스타일(싱글쿼트, 세미콜론 없음, 네이밍 컨벤션)을 잡아주고, Vue 스킬이 Composition API, <script setup>, defineEmits 같은 프레임워크 레벨 best practices를 적용해줬다. 두 스킬이 동시에 로드되면 생성되는 코드가 처음부터 리뷰 통과 수준이었다.

Build-tooling 스킬도 실무에서 체감이 컸다. 4편에서 다뤘던 Vitest 설정에서 Pinia setActivePinia 격리 패턴이 자동으로 포함되는 건, 스킬 없이는 매번 까먹고 디버깅하게 되는 부분이었다.

한계

스킬이 만능은 아니었다. 프로젝트 특화 도메인 로직, 예를 들어 "우리 서비스에서 주문 상태는 어떤 흐름으로 전이되는가" 같은 비즈니스 규칙은 스킬이 커버할 수 없다. 스킬은 범용적인 기술 컨벤션과 best practices를 다루는 도구이지, 비즈니스 로직을 대체하는 도구가 아니다.

VitePress 스킬의 체감 점수가 상대적으로 낮은 이유도 여기에 있다. 문서 구조를 잡아주는 건 좋았지만, 실제 문서 내용은 결국 개발자가 작성해야 했다. config 파일 생성에는 유용했으나, 프로젝트의 맥락을 반영한 가이드 문서는 스킬만으로 해결되지 않았다.

AI 도구와 개발자의 역할

3개월간 스킬 시스템을 활용하면서 AI가 잘하는 영역과 개발자가 판단해야 하는 영역이 꽤 명확하게 나뉘었다.

AI가 잘하는 것은 보일러플레이트 생성, 컨벤션 준수, best practices 적용, 테스트 코드 생성이었다. 반복적이고 규칙 기반인 작업에서 스킬의 효과가 극대화됐다. Vite config를 매번 처음부터 작성하는 대신, 스킬이 프로젝트 구조에 맞는 설정을 즉시 생성해주는 식이다.

반면 아키텍처 결정, 비즈니스 로직 설계, UX 감각, 코드 리뷰의 최종 판단은 여전히 개발자의 영역이었다. "이 컴포넌트를 분리해야 하는가?", "이 상태는 store에 둬야 하는가 composable에 둬야 하는가?" 같은 판단은 프로젝트 맥락을 이해하는 사람만 내릴 수 있다.

결국 스킬은 "AI에게 프로젝트의 규칙을 가르치는 도구"였다. 그리고 좋은 스킬을 만드는 것은 좋은 코딩 가이드라인을 만드는 것과 본질적으로 같은 작업이었다. 명확하고 구체적인 규칙을 정의할수록, AI가 생성하는 코드의 품질이 올라갔다. 모호한 가이드라인에서 좋은 코드가 나오지 않듯이, 모호한 스킬에서도 좋은 결과물은 나오지 않았다.

시리즈를 마치며

6편에 걸쳐 프로젝트 셋업부터 문서화까지 전 과정을 다뤘다.

사용한 스킬들은 vue-skills 저장소에서 확인할 수 있다.

돌아보면 이 시리즈의 핵심 메시지는 하나로 수렴한다. 스킬을 어떻게 구조화하느냐에 따라 AI 도구의 효율이 꽤 달라진다는 것이다. 잘 정리된 스킬 셋은 결국 잘 정리된 개발 프로세스의 반영이다. AI 도구를 잘 쓰려면 먼저 자신의 개발 원칙을 명확히 해야 한다. 그게 이 시리즈를 쓰면서 얻은 가장 큰 교훈이었다.

검색...

검색...