Claude Code works well in a Vue.js project when you give it a concise CLAUDE.md and use a plan-first workflow. Start claude in the project root, point it at the component, composable, or store you want to change, and have it run Vitest and Vue Test Utils after each step. This guide covers a practical setup for Composition API, single-file components, Pinia, and Vite.
Single-file components, Pinia, and Vite: where Claude Code fits
Vue’s single-file components mix template, script, and style in one file, and Claude Code can edit all three blocks in a single pass without losing context. Because it reads the actual project rather than relying on generic patterns, it follows your defineProps, defineEmits, defineModel, and toRefs conventions instead of pushing an options API rewrite. It is also comfortable with Pinia setup stores, Vitest specs that use Vue Test Utils, and TypeScript vue-tsc errors, so it can refactor a component and its test together. The main benefit is not code generation; it is the ability to make a small, reviewable change, run the relevant test file, and show you a diff that is easy to check.
Give the agent a Vue-aware CLAUDE.md
Create or update CLAUDE.md in the project root. Keep it short: the agent reads it on every turn, and long prose gets ignored. Include package manager commands, test and lint commands, folder conventions, and Vue-specific rules that are easy for the model to violate. A realistic file for a Vite + Pinia + Vitest project looks like this:
# CLAUDE.md
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test --run`
- Test watch: `pnpm test`
- Lint: `pnpm lint`
- Type check: `pnpm type-check`
## Structure
- `src/components`: presentational SFCs
- `src/composables`: reusable Composition API functions
- `src/stores`: Pinia stores
- `src/views`: route-level pages
- `src/__tests__`: Vitest specs colocated with the feature
## Vue-specific rules
- Use `<script setup lang='ts'>` for new components.
- Prefer `defineProps`, `defineEmits`, and `defineModel` with explicit TypeScript types.
- Never mutate props directly; use `toRefs(props)` or a computed getter/setter if a child must write back.
- Pinia stores use the setup syntax and return only refs, computed, and functions; avoid the options API.
- Tests mount components with Vue Test Utils and use `flushPromises` when waiting for reactive async updates.
- Run `pnpm lint --fix` and `pnpm test --run` before considering a task done.Put the file under version control so every agent session sees the same rules. For a larger change, ask the agent to read CLAUDE.md first; the Claude Code best practices checklist covers what else to include without turning the file into documentation.
A plan-first loop for Vue refactors
The most reliable pattern is plan first, then make a small change, run the tests, and review the diff before the next step. Start claude in the project root and describe the target file and behavior. For multi-file refactors, use plan mode so it proposes the files and changes before editing; see Claude Code plan mode. A typical loop for a Vue task looks like this:
- Find
ProductList.vueand explain how it receives and renders products. Then add aselectedIdsv-model that emits updated selection arrays, and update the parent component to bind it. - In
useCart.ts, thecartTotalcomputed uses a plain function that recalculates every render. Rewrite it with Vue reactivity and add a Vitest test that shows it updates when a cart item quantity changes. - Refactor
ProductList.vueintoProductList.vueandProductListItem.vue; keep explicit props and emits, move the item template, and update the existing Vitest test for the list. - The Pinia
authstore uses the options API. Convert it to a setup store withref,computed, and actions. Then update the two components that call it and run their tests. - Run
pnpm test --runand fix only the failing tests caused by the last change; leave unrelated tests untouched.
After each prompt, tell the agent to run the relevant test file or type check and show the diff before continuing. Avoid asking for a full feature in one turn; small steps make Vue-specific reactivity mistakes easier to spot in review.
What to hand to Claude Code and what to double-check in Vue diffs
Claude Code is good at adding typed props and emits, splitting large SFCs into child components, converting options API code to Composition API, and updating Pinia stores with their call sites. It is less reliable when the change affects reactivity, asynchronous watchers, or template tag balance. Review those diffs carefully.
| Area | What to ask it to do | What to watch in the diff |
|---|---|---|
| Props / emits | Add a new typed prop and emit an event from a child | It may destructure props directly; use toRefs when needed |
| Pinia | Convert an options store to setup or add an action | It can forget to return a state ref, so the component loses reactivity |
| Single-file components | Split a template into child components | Watch for missing closing tags, lost key attributes, or scoped CSS that stops applying |
| Composables | Extract shared logic from a component | It may capture reactive values in a plain closure; use computed or watchEffect |
| Tests | Update a test after a refactor | It may use shallowMount when the component depends on child behavior; prefer mount and real stubs |
For every task, ask the agent to run the relevant tests rather than trusting its summary. Vue-specific failures often hide in the onMounted hook, watch with immediate: true, or await inside setup; a passing type check can miss them, but Vitest with Vue Test Utils catches the runtime issue.
Vitest, Vue Test Utils, and type checks as a safety net
Tell the agent to run tests in small batches. In a Vite project, pnpm test --run runs the whole suite once, pnpm test src/components/ProductList.spec.ts --run runs a single file, and pnpm test --run --coverage adds coverage output. The agent can execute these commands itself and paste the failing lines back into the plan. For components that use Pinia, use createTestingPinia or a real createPinia with a test store so the test does not depend on local storage. For async watchers, use flushPromises from Vue Test Utils and await on trigger calls. Ask it to run pnpm type-check and pnpm lint --fix before you review the diff; those catch <script setup lang='ts'> type errors and template linter rules that the model may miss.
Parallel agents on one Vue project with AgentVera
AgentVera is a desktop app that runs Claude Code and other coding agents in real terminal panels. For a Vue.js project with several active branches, the most useful parts are parallel git worktrees so agents don’t overwrite each other’s SFCs, automatic code review that links findings to file:line after each turn, and checkpoints that let you undo a risky Pinia or template change in one click. Token budgets help keep multi-agent refactors from burning through your plan while you review the diff.
Wrap-up
Claude Code is not a replacement for your Vue judgment; it is a fast pair programmer that can edit SFCs, Pinia stores, and tests when you constrain it with a good CLAUDE.md and a plan-first loop. Keep tasks small, run the relevant Vitest file, review the diff for reactivity mistakes, and use checkpoints or branch isolation when multiple agents work at once. That is the practical way to get reliable results on a Vue.js project.