fe-agent-new/rules/framework-rules.md

프레임워크 / 라이브러리 사용 규칙

Vue 3 / Nuxt

컴포넌트 작성

• <script setup lang="ts"> 사용을 기본으로 합니다. Options API는 신규 코드에서 사용하지 않습니다.
• 컴포넌트는 단일 책임 원칙을 지키며, 200줄을 넘으면 분리를 검토합니다.
• Props는 defineProps<T>() 제네릭 형태로 타입을 명시합니다.
• Emits는 defineEmits<{ ... }>() 제네릭 형태로 선언합니다.
• ref vs reactive: 원시값과 단일 객체는 ref, 복잡한 상태 트리는 reactive를 고려합니다. 일관성을 위해 팀 내에서 가능한 ref를 우선합니다.

상태 관리

• 컴포넌트 내 로컬 상태: ref / reactive
• 여러 컴포넌트가 공유하는 상태: Pinia 사용
• 서버 상태: Nuxt useFetch / useAsyncData 사용, 직접 fetch 호출은 지양합니다.

라우팅

• Nuxt의 파일 기반 라우팅을 사용합니다. 수동 라우트 정의는 특수한 경우에만 허용됩니다.
• 동적 라우트 파라미터는 [param].vue 형식을 사용합니다.

Composable

• 재사용 가능한 로직은 composables/ 디렉토리의 useXxx 함수로 추출합니다.
• Composable은 부수효과를 최소화하고, 반환 객체에 상태와 메서드를 함께 묶어 반환합니다.

TypeScript

• strict: true를 유지합니다.
• 공용 타입은 types/ 또는 각 도메인의 types.ts에 모아둡니다.
• 외부 API 응답은 반드시 타입을 정의하여 사용합니다.

Tailwind CSS

• 유틸리티 클래스 우선 사용. 공통 패턴은 컴포넌트로 추출합니다.
• @apply는 꼭 필요한 경우에만 사용하고, 가능한 유틸리티를 직접 나열합니다.
• 임의값 클래스(w-[123px])는 디자인 시스템에 등록되지 않은 값에만 제한적으로 사용합니다.
• 조건부 클래스는 clsx 또는 cn 유틸리티를 사용하여 가독성을 확보합니다.
• 클래스 순서는 Tailwind 공식 프리셋(prettier-plugin-tailwindcss)을 따릅니다.

외부 라이브러리 도입

• 새로운 라이브러리를 추가할 때는 PR 설명에 도입 이유, 번들 영향, 대안 검토 내용을 기록합니다.
• 동일 기능의 라이브러리를 중복 도입하지 않습니다.
• 유지보수가 중단된 패키지(6개월 이상 업데이트 없음)는 도입하지 않습니다.