vue-pinia-best-practices

vue-pinia-best-practices 스킬 개요

vue-pinia-best-practices 스킬은 Pinia를 사용하는 Vue 3 팀이 상태 관리 버그를 줄이고, 기본 아키텍처 결정을 더 안정적으로 가져가도록 돕는 집중형 가이드 스킬입니다. 광범위한 Vue 입문서가 아니라, 실제 프로젝트에서 시간을 가장 많이 잡아먹는 Pinia 실수에 초점을 맞춥니다. 예를 들면 잘못된 설치 시점, 구조 분해로 인해 깨지는 반응성, setup store의 SSR/DevTools 문제, 그리고 어떤 상태를 store에 둘지 URL에 둘지에 대한 혼선 같은 문제들입니다.

이 스킬이 가장 잘 맞는 대상

vue-pinia-best-practices 스킬은 다음과 같은 경우에 특히 잘 맞습니다.

• 이미 Pinia를 쓰고 있거나 도입 중인 Vue 3 개발자
• Vuex 또는 직접 만든 reactive() store에서 옮겨오는 팀
• getActivePinia() 같은 구체적인 런타임 오류를 겪는 개발자
• 토이 앱을 넘어서는 규모에서도 통하는 규칙을 원하는 프론트엔드 엔지니어

특히 앱에 공유 상태, 라우팅, SSR 이슈, DevTools 워크플로, 또는 여러 명의 기여자가 있는 경우 유용합니다.

이 스킬이 해결해 주는 일

vue-pinia-best-practices 스킬은 AI 어시스턴트에게 Pinia 코드를 리뷰하거나 생성하게 할 때, 숨어 있는 함정을 덜 밟도록 만들고 싶을 때 쓰면 좋습니다. 여기서 진짜 해결하려는 일은 “Pinia를 설명해 줘”가 아니라, “배포 전에 알려진 실수를 피하면서 store 구조를 올바르게 잡도록 도와줘”에 가깝습니다.

일반적인 Vue 프롬프트와 다른 점

일반 프롬프트도 그럴듯한 Pinia 코드를 만들어 줄 수는 있지만, 실제로는 깨지는 경우가 많습니다. vue-pinia-best-practices 스킬이 더 강한 이유는 영향도가 큰, 검증된 패턴 몇 가지에 집중하기 때문입니다.

• store를 소비하는 코드보다 먼저 Pinia를 설치한다
• 앱 초기화 전 최상위 레벨에서 store에 접근하지 않는다
• setup store에서는 모든 반응형 상태를 반환한다
• 상태와 getter를 구조 분해할 때는 storeToRefs()를 사용한다
• 공유 가능한 필터 상태는 Pinia에만 두지 말고 URL에도 반영한다
• 규모가 있는 앱에서는 임시방편식 ad hoc store보다 Pinia를 우선한다

이 스킬이 다루지 않는 범위

이 스킬은 의도적으로 범위를 좁게 잡았습니다. 따라서 다음을 대체하지는 않습니다.

• 고급 plugin 작성
• end-to-end SSR 프레임워크 통합의 세부 구현
• 가능한 모든 store 구성 스타일
• Pinia와 무관한 Vue 컴포넌트 패턴

프레임워크별 설정을 빠짐없이 다뤄야 한다면, 이 스킬은 전체 구현 계획이 아니라 실수를 막아 주는 가드레일 계층으로 보는 것이 맞습니다.

vue-pinia-best-practices 스킬 사용 방법

vue-pinia-best-practices 설치 맥락

사용 중인 skill runner가 repository 기반 스킬 설치를 지원한다면, vuejs-ai/skills에서 다른 스킬을 추가하듯 vue-pinia-best-practices를 설치하면 됩니다. 설치 후 핵심 작업 디렉터리는 다음입니다.

• skills/vue-pinia-best-practices/

시작할 때는 먼저 아래 파일을 보세요.

• SKILL.md

그다음에는 현재 겪는 문제에 맞는 reference 파일을 읽으면 됩니다.

문제 유형별로 먼저 읽어야 할 파일

가장 빠른 방법은 현재 증상과 맞는 reference를 바로 여는 것입니다.

• 시작 시점/설치 순서 충돌은 reference/pinia-no-active-pinia-error.md
• setup store의 SSR 또는 DevTools 문제는 reference/pinia-setup-store-return-all-state.md
• 구조 분해 후 UI가 갱신되지 않는 문제는 reference/pinia-store-destructuring-breaks-reactivity.md
• 필터, 검색, 정렬, 페이지네이션 상태는 reference/state-url-for-ephemeral-filters.md
• 아키텍처 판단은 reference/state-use-pinia-for-large-apps.md
• Pinia가 아닌 reactive store의 메서드 바인딩 문제는 reference/store-method-binding-parentheses.md

이 repo는 작고 압축되어 있어서, 처음부터 순서대로 다 읽는 것보다 초기에 맞는 파일을 고르는 편이 훨씬 중요합니다.

이 스킬이 잘 작동하려면 어떤 입력이 필요한가

vue-pinia-best-practices 스킬은 단순히 “Pinia 도와줘”라고 하는 것보다, 구체적인 구현 맥락을 줄 때 훨씬 잘 작동합니다. 가능하면 아래 정보를 함께 주세요.

• 사용 중인 Vue 버전과 Vue 3 + Composition API 사용 여부
• 해당 store가 Pinia store인지, 직접 만든 reactive store인지
• 문제가 시작 시점에 나는지, 라우팅 중에 나는지, 템플릿에서 나는지, 새로고침 후에 나는지
• main.ts, router 설정, store 파일 1개, store를 사용하는 컴포넌트 1개 같은 관련 파일
• SSR, DevTools 표시, URL 영속성이 중요한지 여부

이런 맥락이 없으면, 어시스턴트가 맞는 말이지만 현재 상황과는 어긋난 답을 줄 수 있습니다.

두루뭉술한 목표를 강한 프롬프트로 바꾸는 법

약한 프롬프트:

• “Help me fix my Pinia store.”

더 좋은 프롬프트:

• “Use the vue-pinia-best-practices skill. I have a Vue 3 app with Pinia and Vue Router. I get getActivePinia() during startup when a router guard reads useAuthStore(). Review my main.ts and router file, explain the root cause, and rewrite the setup in the safest order.”

또 다른 좋은 예시:

• “Use vue-pinia-best-practices to review this setup store for SSR and DevTools compatibility. Tell me if any reactive state is not returned, what that breaks, and provide a corrected store.”

실전적인 vue-pinia-best-practices 사용 워크플로

이 스킬을 안정적으로 쓰려면 다음 흐름이 좋습니다.

1. 증상 범주를 먼저 정합니다: startup, reactivity, setup store shape, URL state, architecture 중 무엇인지 식별합니다.
2. 문제를 재현하는 데 필요한 최소 파일만 첨부합니다.
3. 해당 증상에 맞는 reference/*.md 파일 기준으로 진단해 달라고 요청합니다.
4. 수정된 코드와 함께, 다른 곳에도 재사용할 수 있는 짧은 규칙 한 줄을 요청합니다.
5. 첫 수정이 끝나면, 같은 패턴을 repo 전체에 적용할 체크리스트를 요청합니다.

코드 없이 한 번에 “best practices 리뷰”를 해 달라고 하는 것보다 이 방식이 결과가 훨씬 좋습니다.

startup 및 plugin 순서 버그에 활용하기

vue-pinia-best-practices의 가장 가치 높은 활용처 중 하나는 “no active Pinia” 계열 오류를 해결하는 것입니다. router guard나 모듈이 store를 너무 일찍 호출한다면, 아래 파일을 어시스턴트가 보게 하세요.

• main.js 또는 main.ts
• router 생성 코드와 guard 등록 코드
• 최상위 import에서 useXxxStore()를 호출하는 부분

핵심 문제는 대개 store 구현 자체가 아니라 초기화 타이밍입니다.

반응성을 깨지 않는 구조 분해 점검에 활용하기

store에서 값을 꺼낸 뒤 UI가 더 이상 갱신되지 않는다면, 이 스킬로 store를 직접 구조 분해했는지 확인하게 하세요. 보통의 수정 방향은 다음과 같습니다.

• 필요하다면 action은 직접 구조 분해해도 된다
• state와 getter는 storeToRefs()를 통해 꺼낸다

store 값을 많이 읽는 컴포넌트를 리뷰할 때 특히 좋은 점검 포인트입니다.

setup store의 SSR 및 DevTools 점검에 활용하기

defineStore('x', () => {}) 형태를 쓰고 있다면, 어시스턴트에게 모든 반응형 상태가 반환되고 있는지 확인하게 하세요. 이 부분이 중요한 이유는, 빠진 상태가 조용히 아래 기능을 망가뜨릴 수 있기 때문입니다.

• SSR 직렬화와 hydration
• Vue DevTools에서의 inspection
• Pinia plugin 호환성

그래서 vue-pinia-best-practices 스킬은 디버깅뿐 아니라 코드 리뷰 단계에서 쓰는 가치가 큽니다.

상태를 어디에 둘지 결정할 때 활용하기

vue-pinia-best-practices guide의 은근히 큰 장점 중 하나는, 어떤 데이터가 애초에 Pinia에 들어가야 하는지 판단하는 데 도움을 준다는 점입니다. 어시스턴트에게 상태를 아래처럼 분류해 달라고 요청해 보세요.

• 앱 전역에서 공유되는 상태
• 로컬 컴포넌트 상태
• 필터, 검색, 페이지네이션, 정렬처럼 URL과 연동되는 view state

이 지점에서 이 스킬은 단순한 Pinia 코드 조각보다 더 큰 가치를 냅니다. 코드가 커진 뒤에 잘못된 아키텍처를 고치는 대신, 애초에 잘못된 방향으로 가는 것을 막아 주기 때문입니다.

repo 리뷰에 가장 좋은 프롬프트 패턴

vue-pinia-best-practices for Frontend Development를 repo 수준에서 점검할 때는 이런 감사 프롬프트가 효과적입니다.

• “Use the vue-pinia-best-practices skill to audit these files for Pinia gotchas. For each issue, label it as install timing, reactivity, setup-store return shape, or state-placement mistake. Show exact fixes and explain production impact.”

이렇게 프레이밍하면 모델이 추상적인 조언보다 실제로 손댈 수 있는 문제를 더 잘 찾아냅니다.

vue-pinia-best-practices 스킬 FAQ

vue-pinia-best-practices는 초보자에게도 괜찮은가요?

네, 이미 Vue 3로 개발을 시작했고 Pinia도 쓰기 시작했다면 괜찮습니다. 이 스킬은 짧고 문제 중심이라서, 넓은 범위의 문서보다 실제 적용이 쉽습니다. 다만 완전 입문자라면 store, getter, action 같은 개념을 익히기 위해 공식 Pinia 기초 문서가 여전히 필요할 수 있습니다.

vue-pinia-best-practices 스킬이 특히 잘 다루는 문제는 무엇인가요?

이 스킬은 흔하면서도 영향이 큰 몇 가지 문제에 특히 강합니다.

• getActivePinia() 설치/초기화 타이밍 오류
• 직접 구조 분해로 인해 깨지는 반응성
• 모든 상태를 반환하지 않는 setup store
• URL query 상태가 store 상태보다 더 적합한 시점 판단
• 직접 만든 상태 관리보다 Pinia를 쓰는 편이 나은 시점 판단

일반적인 Pinia 도움 요청보다 이게 더 나은가요?

이 주제들에 한해서는 대체로 그렇습니다. 일반 프롬프트는 겉보기엔 멀쩡한 코드를 만들지만, plugin 순서, SSR 직렬화, storeToRefs() 같은 런타임 디테일을 놓치는 경우가 많습니다. vue-pinia-best-practices skill은 검증된 함정과 수정 패턴으로 모델의 범위를 좁혀 주기 때문에 더 실전적인 답을 기대할 수 있습니다.

언제는 vue-pinia-best-practices를 쓰지 않는 편이 좋나요?

다음과 같은 작업이 중심이라면 굳이 이 스킬을 쓸 필요는 없습니다.

• Vue를 처음부터 배우는 경우
• Pinia와 무관한 프레임워크별 배포 설정
• repo 범위를 넘어서는 고급 상태 머신 설계
• Vue가 아닌 프론트엔드 스택

이 스킬은 Pinia에 특화된 가드레일이지, 범용 프론트엔드 아키텍처 스킬은 아닙니다.

Vuex 마이그레이션 판단에도 도움이 되나요?

간접적으로는 그렇습니다. 이 repo는 규모가 있는 Vue 앱에서는 Pinia가 기본 선택지로 적합하고, Vuex는 maintenance mode에 가깝다는 관점을 분명히 지지합니다. 특히 예전 Vuex 습관을 현재의 Pinia 패턴으로 바꿔 생각할 때, 더 단순한 store ergonomics와 tooling 관점에서 도움이 됩니다.

직접 만든 store에도 vue-pinia-best-practices가 도움이 되나요?

어느 정도는 그렇습니다. reference 중 하나는 reactive store의 method-binding 함정을 다루고 있고, 직접 만든 상태 관리가 아직 허용 가능한지 판단하는 데도 도움을 줍니다. 다만 이 스킬의 중심은 어디까지나 Pinia이지, 커스텀 store 라이브러리 전반은 아닙니다.

vue-pinia-best-practices 스킬을 더 잘 활용하는 방법

정확한 실패 증상을 전달하세요

vue-pinia-best-practices의 출력 품질을 높이려면, 정확한 에러 문구와 발생 위치, 언제부터 시작됐는지를 함께 알려 주세요. 예를 들면 다음과 같습니다.

• “Error occurs only during router navigation”
• “DevTools does not show a ref from my setup store”
• “UI stops updating after destructuring the store in <script setup>”

이런 단서는 repo가 가장 강하게 다루는 가이드와 바로 연결됩니다.

라이프사이클과 파일 경계를 함께 알려 주세요

많은 Pinia 버그는 사실상 타이밍 버그입니다. 해당 코드가 언제 실행되는지 어시스턴트에게 알려 주세요.

• module import 시점
• setup() 내부
• router guard 내부
• 앱 bootstrap 중
• SSR hydration 중

이 정보가 있어야 설치 순서 문제인지, 일반적인 컴포넌트 버그인지를 정확히 가를 수 있습니다.

최소한이지만 완전한 코드 조각을 제공하세요

보통 더 좋은 입력은 아래 정도를 포함합니다.

• main.ts
• guard에서 store를 쓰는 경우 router 파일 1개
• store 파일 1개
• 해당 store를 소비하는 컴포넌트 1개

처음부터 repo 전체를 붙여 넣지 마세요. 재현 범위를 좁히면 진단 속도가 빨라지고, 뜬구름 잡는 일반론도 줄어듭니다.

수정만 요청하지 말고 분류도 요청하세요

효율이 높은 프롬프트 예시는 다음과 같습니다.

• “Classify each issue by category, explain why it happens, then patch the code.”

이 스킬에서는 다음 같은 분류가 특히 유용합니다.

• install timing
• reactivity
• setup-store return shape
• URL vs store state
• scale/architecture fit

이렇게 하면 이후 다른 파일에도 재사용할 수 있는 결과가 나옵니다.

전후 비교 코드도 요청하세요

vue-pinia-best-practices install 자체는 간단하지만, 실제 도입에서 더 중요한 질문은 “생성되는 코드 품질이 실제로 좋아지느냐”입니다. 이를 판단하는 가장 좋은 방법은 아래를 함께 요청하는 것입니다.

• 수정된 코드 예시
• 원래 코드가 왜 실패했는지에 대한 짧은 설명
• 다른 곳에도 적용할 수 있는 체크리스트

이렇게 해야 일회성 답변이 아니라 반복 가능한 리뷰 도구로 쓸 수 있습니다.

자주 나오는 실패 패턴을 주의하세요

입력이 불충분할 때 가장 약한 출력이 나옵니다. 예를 들면 이런 경우입니다.

• 코드나 증상 없이 “best practices”만 요청하는 경우
• store가 option-style인지 setup-style인지 말하지 않는 경우
• startup 관련 문제인데 router 설정을 생략한 경우
• 필터 영속성을 말하면서 공유 가능한 URL 필요성을 언급하지 않은 경우

이런 상황에서는 어시스턴트가 맞는 말을 하더라도, 정작 문제를 해결하지 못할 수 있습니다.

첫 답변 뒤에 한 번 더 반복하세요

첫 답변을 받은 뒤에는 다음 같은 2차 질문을 던져 보세요.

• “Now scan for the same pattern in the rest of my stores.”
• “Convert this fix into a team convention.”
• “Show how this changes if the state should be shareable by URL.”
• “Add SSR and DevTools checks to the review.”

이렇게 해야 vue-pinia-best-practices usage에서 단일 수정 이상의 가치를 뽑아낼 수 있습니다.

reference를 코드 리뷰 규칙으로 바꾸세요

reference 파일은 팀 코드 리뷰 체크 항목으로 옮기기 좋을 만큼 짧고 명확합니다. 예를 들면 다음과 같은 규칙입니다.

• module 최상위에서 useXxxStore()를 호출하지 않는다
• guard가 store를 읽는다면 router보다 먼저 Pinia를 설치한다
• setup store에서는 모든 반응형 상태를 반환한다
• state/getter를 구조 분해할 때는 storeToRefs()를 사용한다
• 새로고침/공유가 중요하다면 view filter는 URL에 둔다

장기적으로 vue-pinia-best-practices for Frontend Development의 효과를 가장 크게 높이는 방법은 이것입니다. 버그가 생긴 뒤에만 고치는 것이 아니라, 더 나은 기본값을 팀 차원에서 먼저 강제하는 데 활용하세요.