Przejdź do głównej zawartości

Przepisy Vue.js dla agentów AI to gotowe prompty, dzięki którym Claude Code, Codex lub Cursor piszą produkcyjny kod w Vue 3.5. Każdy przepis łączy prompt z kontrolą, która dowodzi wyniku: vue-tsc, reguły utraty reaktywności z eslint-plugin-vue, Vitest z Vue Test Utils i skan dostępności w Playwright. Najważniejsze jest przypięcie wersji, bo popularne pakiety Vue różnią się co do wspieranych wersji.

Ta strona jest dla programistów Vue i tech leadów, którzy ustalają konwencje pracy z agentami w zespole. Prosisz agenta o store, a on pisze Vuex w Options API. Prosisz o formularz, a on instaluje @vee-validate/zod, który jako peer deklaruje Zod 3, choć projekt działa na Zod 4. Komponent się renderuje, zdestrukturyzowane pole store’a po cichu przestaje się aktualizować, a nic nie pada, dopóki użytkownik nie zmieni ilości w koszyku.

  • Blok przypinający wersje do CLAUDE.md, AGENTS.md lub reguły Cursora, który trzyma agenta przy <script setup>, Pinia 4 i pakietach, które naprawdę są w twoim lockfile’u
  • Jedno polecenie verify, które agent uruchamia, zanim zgłosi sukces, więc przeglądasz zieloną bramkę zamiast każdej linii
  • Osiem promptów do zadań, o które agentów prosi się najczęściej: typowane komponenty, store’y Pinia, composables, formularze wieloetapowe, długie listy, leniwe trasy, i18n i migracje z Options API, a do tego konfiguracja Storybooka
  • Tabelę, która pokazuje, jaka bramka łapie jaką klasę błędów i kto zatwierdza zmianę
  • Typowe awarie kodu Vue pisanego przez agenta i sposób wyjścia z każdej z nich

Agenci uczyli się Vue na latach tutoriali do Vue 2, Vuex i Options API oraz na README pakietów sprzed tegorocznych dużych wydań. Wpisz wersje, zakazane wzorce i polecenie „gotowe” do instrukcji, które czyta twoje narzędzie: CLAUDE.md dla Claude Code, AGENTS.md dla Codex i reguła projektu dla Cursora. Claude Code od v2.1.277 czyta też AGENTS.md, gdy projekt nie ma CLAUDE.md.

## Frontend stack (Vue)
- Vue 3.5 with <script setup lang="ts"> only. TypeScript strict. Vite 8, Vitest 5,
Vue Test Utils 2, Playwright for e2e.
- State: Pinia 4 setup stores. Routing: Vue Router 5. i18n: vue-i18n 11 with legacy: false.
Utilities: check @vueuse/core before writing a composable (useFetch, useWebSocket,
useColorMode, useRefHistory already exist).
- Validation: Zod 4 schemas. Do not install @vee-validate/zod (its peer range is Zod 3).
- Never write: Options API in new files, Vuex, `this.$store`, destructuring a store or a
reactive() object without storeToRefs/toRefs, `as any`, `<Suspense>` for route loading.
- Before you say a task is done, run `npm run verify` and paste the last 20 lines of output.
- Tests find elements by role and label text, never by CSS class.

Poniższe pułapki sprawdziliśmy w opublikowanych pakietach 2026-09-26. W każdej z nich domyślny wybór agenta albo pierwsze znalezione README daje coś, co się instaluje, a potem działa źle:

Agent piszeCo mówi rejestr 2026-09-26Napisz zamiast tego
createI18n({ locale: 'en' })W vue-i18n 11.4.12 legacy domyślnie ma wartość true i jest oznaczone jako „will be removed at vue-i18n v12”createI18n({ legacy: false, ... }) i useI18n()
npm i @vee-validate/zod przy Zod 4@vee-validate/zod 4.15.1 deklaruje peerDependencies: { zod: "^3.24.0" }Walidacja przez safeParse schematu Zod 4 w małym composable, jak w przepisie na formularz poniżej
import { expect } from '@storybook/test'Pakiet zatrzymał się na 8.6.15; Storybook 10.6.0 dostarcza go jako storybook/testimport { expect } from 'storybook/test'
@storybook/addon-vitest obok Vitest 5Zakres peer w 10.6.0 to vitest ^3.0.0 || ^4.0.0Najpierw sprawdź zakres peer, jak w przepisie na Storybooka poniżej
vite-plugin-vue-mcp w aplikacji na Vite 8Zakres peer w 0.3.2 kończy się na Vite 6Chrome DevTools MCP lub Playwright MCP podłączone do serwera deweloperskiego
const { items } = useCartStore()Reaktywność ginie: items to migawkaconst { items } = storeToRefs(useCartStore())

Dodaj jeden skrypt łączący wszystkie bramki i każ agentowi uruchomić go, zanim zgłosi ukończenie:

{
"scripts": {
"verify": "vue-tsc --noEmit && eslint . --max-warnings 0 && vitest run && playwright test --grep @a11y"
}
}

Ostatni krok uruchamia tylko testy z @a11y w tytule, więc w świeżym projekcie nie trafia w nic, dopóki nie dodasz takiego testu. Zacznij od jednego skanu axe dla strony i dopisuj test dla każdego widoku, który budujesz:

e2e/a11y.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test('home page has no axe violations @a11y', async ({ page }) => {
await page.goto('/');
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toEqual([]);
});

eslint-plugin-vue 10 ma preset flat/recommended, ale dwie reguły, które łapią najczęstszy błąd agenta w Vue, czyli utratę reaktywności, nie należą do tego presetu. Włącz je sam:

eslint.config.js
import pluginVue from 'eslint-plugin-vue';
export default [
...pluginVue.configs['flat/recommended'],
{
rules: {
'vue/no-ref-object-reactivity-loss': 'error',
'vue/no-setup-props-reactivity-loss': 'error',
'vue/require-explicit-emits': 'error',
'vue/no-v-html': 'error',
},
},
];

Dodaj w tym samym pliku konfigurację parsera TypeScript (na przykład typescript-eslint). Sposób, w jaki zmuszasz agenta do uruchomienia verify, zależy od narzędzia:

Wpisz regułę do CLAUDE.md jak w bloku powyżej. Żeby ją egzekwować, a nie tylko o nią prosić, dodaj hook Stop, który uruchamia npm run verify i blokuje zakończenie, gdy się nie powiedzie; zobacz automatyzację hookami. W trybie bezobsługowym w CI ten sam prompt przyjmuje claude -p.

Repozytorium vuejs-ai/skills pakuje wiedzę o Vue jako skille agenta: vue-best-practices, vue-pinia-best-practices, vue-router-best-practices, vue-testing-best-practices, vue-debug-guides i create-adaptable-composable. README nazywa je „early experiment” i projektem społeczności, a skill do routera celuje w Vue Router 4, więc traktuj je jak listę kontrolną recenzenta, a nie bramkę.

Okno terminala
claude plugin marketplace add vuejs-ai/skills
claude plugin install vue-best-practices@vue-skills

README radzi zaczynać prompt od „Use vue skill”, bo skill nie zawsze uruchamia się sam. Jeśli chcesz zestawu dla całego Vite i Nuxta, antfu/skills generuje skille vue, pinia, vite i vitest z oficjalnej dokumentacji. Wczytaj jeden zestaw frameworkowy, nie oba: nakładające się skille konkurują o ten sam kontekst. Więcej opcji znajdziesz w najlepszych skillach do frontendu.

Scenariusz: potrzebujesz komponentu nowej funkcjonalności zgodnego z konwencjami zespołu: typowane propsy, typowane emity i testy, które sprawdzają jedno i drugie.

Skąd wiesz, że zadziałało: verify jest zielone, a nazwy testów czyta się jak listę propsów i emitów. Czytaj nazwy testów, nie szablon. Jeśli test szuka elementu po klasie CSS, odeślij go do poprawki.

Scenariusz: store koszyka ma przetrwać odświeżenie strony, pozwalać cofnąć ostatnią zmianę i utrzymywać wszystkie komponenty w synchronizacji.

Skąd wiesz, że zadziałało: test przeładowania i oba testy cofania przechodzą, a grep -rn "useCartStore()" src/components pokazuje, że każda destrukturyzacja jest owinięta w storeToRefs. stubActions: false ma znaczenie: createTestingPinia domyślnie podmienia wszystkie akcje na atrapy, więc test akcji bez tej opcji przechodzi, choć akcja nigdy się nie wykonuje.

Scenariusz: dwanaście komponentów powtarza ten sam wzorzec pobierania danych ze stanem ładowania, wyszukiwanie z debounce i sprawdzanie uprawnień.

Pułapką jest to, że agent pisze własne useFetch albo useWebSocket, choć @vueuse/core 15 eksportuje oba, z opcjami przerwania, automatycznego ponownego łączenia i heartbeatu. Każ mu najpierw sprawdzić.

Skąd wiesz, że zadziałało: raport wymienia każdy wzorzec raz, diff komponentów usuwa więcej linii, niż dodają composables, a vue/no-ref-object-reactivity-loss milczy. Composable zwracający reactive() oblewa tę regułę w chwili, gdy wywołujący go zdestrukturyzuje.

Scenariusz: czteroetapowy formularz zamówienia ma blokować „Dalej” przy błędnych polach, zachowywać dane przy powrocie i przetrwać przypadkowe odświeżenie.

Skąd wiesz, że zadziałało: cztery testy przechodzą, grep -rn "vee-validate\|string().email" src package.json nic nie zwraca, a skan axe jest czysty. Wykluczenie pól karty to jedyna linia warta ludzkiego spojrzenia, bo błąd w niej zapisuje dane karty w przeglądarce.

Scenariusz: widok logów w panelu administracyjnym ma pokazać 50 000 wierszy z sortowaniem i filtrowaniem.

Wirtualizacja rozwiązuje renderowanie, ale nie sortowanie uruchamiane przy każdym naciśnięciu klawisza. Proś o zmierzony wynik, nie o listę komponentów. Chrome DevTools MCP daje agentowi ślad wydajności działającej strony; konfigurację dla wszystkich trzech narzędzi znajdziesz w automatyzacji przeglądarki przez MCP.

Skąd wiesz, że zadziałało: liczby ze śladu są w raporcie, a liczba wierszy w DOM podczas przewijania pozostaje bliska rozmiarowi widoku, a nie 50 000. Zachowaj ślad jako punkt odniesienia; testy wydajności pokazują, jak zamienić go w budżet w CI.

Scenariusz: każdy widok trafia do pierwszego bundla, a po każdym wdrożeniu część użytkowników widzi pustą stronę, bo ich karta prosi o chunk, którego już nie ma.

Skąd wiesz, że zadziałało: wynik builda pokazuje jeden chunk na każdą leniwą trasę, a test przeładowania dowodzi działania zabezpieczenia. Dokumentacja Vue wciąż oznacza <Suspense> jako eksperymentalny, dlatego prompt zakazuje go przy routingu.

Scenariusz: aplikacja ma tylko angielski, a hiszpański i japoński mają się doładowywać na żądanie bez powiększania pierwszego bundla.

Skąd wiesz, że zadziałało: test zgodności kluczy przechodzi, grep -rn "legacy: true\|this\.\$t" src nic nie zwraca, a build pokazuje es i ja jako osobne chunki. Test zgodności kluczy powstrzymuje następnego agenta przed dodaniem angielskiego klucza bez dwóch pozostałych.

Przenieś komponent z Options API bez zmiany zachowania

Dział zatytułowany „Przenieś komponent z Options API bez zmiany zachowania”

Scenariusz: 500-liniowy komponent w Options API z watcherami i modułem Vuex, bez testów, do przeniesienia na <script setup> i Pinia.

Zanim zaczniesz refaktoryzację, przypnij zachowanie testami. Metodę opisują testy charakteryzujące.

Skąd wiesz, że zadziałało: ciała testów są identyczne w obu commitach (git diff HEAD~1 -- '*.test.ts' dotyka tylko helpera montującego store) i przechodzą w obu. Ten diff to jedyna rzecz do sprawdzenia ręcznie.

Scenariusz: nowe osoby w zespole nie potrafią znaleźć istniejących komponentów, a problemy z dostępnością wychodzą dopiero w review.

Instalator zadaje pytania, więc sposób jego uruchomienia zależy od narzędzia:

Najpierw uruchom npm create storybook@latest we własnym terminalu, odpowiedz na pytania (Vue 3 z Vite), a potem przekaż claude poniższy prompt, żeby napisał historie.

Skąd wiesz, że zadziałało: build-storybook kończy się sukcesem, panel a11y nie pokazuje naruszeń w pięciu komponentach, a funkcja play dla Modal przechodzi. Jeśli agent zgłasza niezgodność zakresu Vitesta, to znaczy, że przepis działa: wymuszona instalacja z --legacy-peer-deps jest złą poprawką.

Jak zweryfikować kod Vue od agenta bez czytania każdej linii

Dział zatytułowany „Jak zweryfikować kod Vue od agenta bez czytania każdej linii”
BramkaCo łapieGdzie działaKto zatwierdza
vue-tsc --noEmit ze strictBłędne propsy i emity, zgubione typy generyczne, API, których zainstalowana wersja nie mapętla agenta, CIautomatycznie
eslint-plugin-vue z regułami utraty reaktywności na errorZdestrukturyzowane propsy, refy i store’y, które przestają się aktualizować; niejawne emity; v-htmlpętla agenta, CIautomatycznie
Vitest + Vue Test Utils + MSWZachowanie po każdej akcji użytkownika, łącznie ze ścieżkami błędów i przeładowaniempętla agenta, CIautomatycznie; autor przegląda nazwy testów, nie ich ciała
Testy charakteryzujące, niezmienione w trakcie migracjiDryf zachowania przy refaktoryzacjipętla agenta, CIautor sprawdza diff testów
Test zgodności kluczy tłumaczeńBrakujące tłumaczeniapętla agenta, CIautomatycznie
Playwright + @axe-core/playwright, dodatek a11y w StorybookuBrakujące etykiety, pułapki fokusu, kontrast, roleCIautomatycznie; osoba odpowiedzialna za dostępność przegląda nowe wyjątki
Ślad wydajności przed i poRegresje w zmienionej interakcjipętla agenta z Chrome DevTools MCPautor; budżet w CI, gdy to ważne

Człowiek przegląda to, czego bramki nie sprawdzą: kryteria akceptacji, nazwy testów i każdy diff w pliku testowym. Kryteria akceptacji napisz przed promptem; zobacz kryteria akceptacji. Nie pozwól agentowi edytować własnych testów, żeby przeszły; zobacz ochronę wyroczni. O samym pull requeście, czyli kto go zatwierdza i na jakiej podstawie, mówi przegląd pull requestów od agentów.

  • Reaktywność ginie po cichu. Agent destrukturyzuje store, obiekt reactive() albo wynik composable, a UI przestaje się aktualizować po pierwszym renderze. Wyjście: storeToRefs dla store’ów, toRefs lub zwracanie refów z composables oraz obie reguły utraty reaktywności na error.
  • Kod z Vue 2 albo Options API w projekcie na Vue 3.5. W nowych plikach pojawiają się this.$store, data(), Vuex i filtry. Wyjście: blok przypinający wersje, skill Vue oraz reguła lintera albo review, które odrzuca Options API w nowych plikach.
  • Niezgodności zakresów peer przepchnięte na siłę. Agent dostaje błąd ERESOLVE z @vee-validate/zod albo @storybook/addon-vitest i ponawia instalację z --legacy-peer-deps. Wyjście: zakaż tej flagi w pliku instrukcji i każ agentowi zgłaszać niezgodność, tak jak robi to prompt do Storybooka.
  • Testy store’a, które nigdy nie uruchamiają store’a. createTestingPinia domyślnie podmienia akcje, więc test sprawdza, że wywołano atrapę, a ciało akcji nigdy się nie wykonuje. Wyjście: stubActions: false w testach store’a; podmieniaj akcje tylko w testach komponentów.
  • Composable, który powiela VueUse. Agent pisze 200 linii logiki ponownego łączenia, którą useWebSocket już ma. Wyjście: linia „najpierw sprawdź @vueuse/core” w instrukcjach i raport „zastąpione czy napisane”, o który prosi prompt do composables.
  • Błędy hydratacji albo window po przejściu aplikacji na SSR. Kod, który czyta window lub localStorage na poziomie modułu, pada na serwerze. Wyjście: kod tylko dla przeglądarki trafia do onMounted; bramki SSR dla renderowanej na serwerze aplikacji Vue opisują przepisy Nuxt.
  • Testy, które testują atrapę. Agent mockuje composable, który sam napisał, i sprawdza, co zwróciła atrapa. Wyjście: mockuj na granicy HTTP przez MSW i odrzucaj testy, które robią vi.mock na testowanym module.

Czy ten artykuł Ci pomógł?

Jedno kliknięcie, bez logowania.

wcale bardzo