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

AI Skills로 Vue 개발하기 (1) - 프로젝트 셋업과 코딩 컨벤션

2025년 12월 18일9 min read
#Vue#Claude Code#AI#ESLint#pnpm
목차 보기
시리즈 목차 보기1 / 6

AI Skills로 Vue 개발하기

1 / 6

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

시리즈를 시작하며

이 시리즈는 Claude Code의 스킬 시스템을 활용해 Vue 프로젝트를 효율적으로 개발하는 과정을 다룬다.

AI 에이전트한테 코드를 시키면 보통 generic한 결과물이 나온다. 세미콜론을 쓸지 말지, Options API를 쓸지 Composition API를 쓸지, 이런 판단을 AI가 알아서 해주길 기대하기는 어렵다. 결국 매번 프롬프트에 "세미콜론 빼줘", "script setup 써줘" 같은 말을 반복하게 된다.

스킬은 이 문제를 해결한다. 프로젝트의 규약을 .claude/skills/ 디렉토리에 정의해두면, AI가 코드를 생성할 때 해당 컨벤션을 자동으로 따른다. 한 번 설정해두면 매번 같은 말을 반복할 필요가 없어진다.

이번 시리즈에서는 그 스킬들이 실제 개발에서 어떻게 동작하는지 하나씩 살펴본다.

Antfu 컨벤션이란

Anthony Fu는 Vue, Vite, Nuxt, UnoCSS 코어 팀 멤버이자 수백 개 오픈소스 프로젝트의 저자다. Vue 생태계에서 사실상 표준처럼 쓰이는 도구들을 만들어온 사람이라, 그의 코딩 컨벤션은 Vue 개발자들 사이에서 꽤 영향력이 있다.

그의 opinionated conventions 핵심 철학은 세 가지로 정리할 수 있다.

단일 책임 원칙 - 하나의 파일은 하나의 책임만 진다. 파일이 비대해지면 분할한다. composable 하나에 하나의 관심사만 담는 식이다.

명시적 타입 - 함수의 반환 타입을 항상 명시한다. 복합 타입은 인라인으로 쓰지 않고 별도로 선언한다. TypeScript를 쓰는 이상 타입 추론에만 의존하지 않는다는 원칙이다.

Self-explanatory 코드 - 주석은 "why"만 남기고 "how"는 코드 자체가 설명하게 한다. 변수명과 함수명이 충분히 의미를 전달해야 한다.

Claude Code에 antfu 스킬을 설치하면 이 컨벤션들이 코드 생성 시 자동으로 적용된다. 따로 지시하지 않아도 싱글쿼트, 세미콜론 없음, Composition API 같은 스타일이 일관되게 유지된다.

pnpm과 ni 명령어

패키지 매니저는 pnpm을 쓴다. npm이나 yarn 대비 디스크 효율이 좋고, 의존성 관리가 strict해서 phantom dependency 같은 문제가 발생하지 않는다.

antfu가 만든 ni는 패키지 매니저를 추상화하는 CLI 도구다. 프로젝트의 lockfile을 감지해서 적절한 패키지 매니저 명령어로 변환해준다.

bash
ni          # pnpm install / npm install / yarn install
nr dev      # pnpm run dev / npm run dev / yarn dev
nu          # pnpm upgrade / npm update / yarn upgrade
nci         # pnpm install --frozen-lockfile (CI 환경)

pnpm에는 Named Catalogs라는 기능이 있다. 모노레포에서 의존성을 용도별로 분류해서 관리할 수 있다.

yaml
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

catalogs:
  prod:
    vue: ^3.5.0
    pinia: ^2.2.0
    vue-router: ^4.4.0

  dev:
    typescript: ^5.6.0
    vite: ^6.0.0
    vitest: ^2.1.0

  frontend:
    '@vueuse/core': ^11.0.0
    unocss: ^0.64.0

각 패키지의 package.json에서 catalog:prod처럼 참조하면 버전을 한 곳에서 통합 관리할 수 있다. 모노레포에서 버전 불일치 문제를 원천 차단하는 셈이다.

ESLint flat config

ESLint 9부터 flat config가 기본이 됐다. 기존 .eslintrc 방식은 cascading 규칙이 복잡하고 설정 파일이 여러 군데 흩어지는 문제가 있었는데, flat config는 하나의 배열로 모든 규칙을 명시적으로 관리한다.

antfu의 @antfu/eslint-config를 쓰면 Prettier가 필요 없어진다. 포맷팅까지 ESLint가 처리하기 때문이다. 설정 파일 하나로 린팅과 포맷팅을 동시에 해결할 수 있다는 점이 꽤 매력적이었다.

ts
// eslint.config.ts
import antfu from '@antfu/eslint-config'

export default antfu({
  vue: true,
  typescript: true,
  stylistic: {
    quotes: 'single',
    semi: false,
  },
  formatters: {
    css: true,
    markdown: true,
  },
})

이 설정 하나로 싱글쿼트 강제, 세미콜론 제거, Vue SFC 린팅, CSS/Markdown 포맷팅까지 전부 처리된다. Prettier config, .prettierignore, ESLint와 Prettier 충돌 해결 — 이런 삽질을 더 이상 하지 않아도 된다.

Git hooks와 자동화

코드 품질을 커밋 시점에서 잡아주는 게이트가 필요하다. simple-git-hooks와 lint-staged 조합이 가볍고 설정도 간단하다.

json
{
  "simple-git-hooks": {
    "pre-commit": "npx lint-staged"
  },
  "lint-staged": {
    "*": "eslint --fix"
  }
}

husky보다 설정이 단순하다. simple-git-hooks는 package.json에 선언만 하면 되고, 별도의 .husky/ 디렉토리나 스크립트 파일이 필요 없다. 초기 설정 후 npx simple-git-hooks를 한 번 실행하면 끝이다.

이렇게 해두면 커밋할 때마다 변경된 파일에 대해 ESLint가 자동으로 돌아간다. 포맷팅이 안 맞는 코드가 레포에 들어가는 걸 원천 차단할 수 있다.

스킬의 효과: 비교

같은 프롬프트를 던졌을 때 스킬 유무에 따라 결과가 얼마나 달라지는지 비교해봤다. 프롬프트는 "사용자 프로필 카드 컴포넌트 만들어줘"였다.

스킬 없이 생성된 코드:

vue
<script lang="ts">
import { defineComponent } from "vue";

export default defineComponent({
  props: {
    name: String,
    email: String,
  },
  setup(props) {
    return { props };
  },
});
</script>

antfu 스킬 적용 후 생성된 코드:

vue
<script setup lang="ts">
// 사용자 프로필 정보를 표시하는 카드 컴포넌트
interface Props {
  name: string
  email: string
  avatarUrl?: string
}

const props = withDefaults(defineProps<Props>(), {
  avatarUrl: '/default-avatar.png',
})
</script>

차이가 확연하다. Options API 대신 script setup을 사용하고, 더블쿼트 대신 싱글쿼트, 세미콜론 제거, interface로 props 타입을 명시적으로 선언했다. withDefaults로 기본값 처리까지 해줬다. 매번 "Composition API 써줘", "세미콜론 빼줘"라고 말할 필요가 없어진 것이다.

스킬이 하는 일은 결국 컨벤션의 자동화다. 사람이 코드 리뷰에서 잡아야 했던 스타일 이슈를 AI가 생성 단계에서 미리 맞춰주는 셈이다.

정리

이번 편에서는 Vue 프로젝트의 기반을 다졌다. antfu 컨벤션의 철학을 이해하고, pnpm + ni로 패키지 관리 환경을 구성하고, ESLint flat config로 린팅과 포맷팅을 통합하고, Git hooks로 커밋 시점 품질 게이트를 만들었다. 그리고 이 모든 것이 Claude Code 스킬을 통해 코드 생성 시 자동으로 반영된다는 걸 확인했다.

다음 편에서는 Vue 스킬을 활용한 컴포넌트 설계와 Composition API를 다룬다.

검색...

검색...