Vite CLAUDE.md Template — Project Rules for Claude Code

What this template gives you

This page (vite-claude-md-template) is a copy-pasteable CLAUDE.md you can drop into the root of a Vite + React + TypeScript project so Claude Code has the context it needs without you re-typing the same project notes every conversation. The template stays under eighty lines on purpose — long instruction files cause Claude to skim past the actual rules, so concise sections win. Read the file, paste it into your project root, edit the project name and stack details if your setup differs, and commit. Claude Code reads CLAUDE.md automatically on every session opened in that directory, so the rules apply to every prompt you send afterwards — no MCP server, no tool wiring, no system-prompt customization required.

The template

# <Your project name>

Short one-line description of what this codebase does.

## Tech stack

- Vite 7
- React 19
- TypeScript 6
- Vitest 3

## Where things live

- `src/components/` — React components, one per file
- `src/lib/` — framework-agnostic helpers, fully unit-tested
- `src/pages/` — route components (if using a router)
- `vite.config.ts` — build + dev-server config

## Locked decisions (do not re-litigate)

- Path alias: `@/_` resolves to `src/_` (configured in `tsconfig.json` and `vite.config.ts`)
- State: React Context only when state genuinely crosses three or more components
- Styling: Tailwind v4 utilities; no CSS Modules

## Hard constraints

- No `any` types — use `unknown` and narrow
- All components are function components — no class components
- All side effects in `useEffect` declare every dependency

## Workflow

Run `pnpm dev` to start. Run `pnpm test --run` before opening a PR.
Run `pnpm build` to confirm the production bundle compiles.

— lastVerified: 2026-05-08

Why these specific sections

The structure mirrors the canonical Claude Code rule format: a project overview, the tech stack, file-organization conventions, decisions that should not be revisited every conversation, hard constraints expressed as positive directives, and the development workflow. Each section earns its place — drop sections that do not apply rather than padding them with filler. The “Hard constraints” block is where you encode the non-negotiable rules that Claude Code must respect on every edit, like type-system rules, component shape, and dependency-array discipline in useEffect.

The “Locked decisions” section is the pressure-relief valve. Without it the agent will suggest CSS Modules every other turn even though you have a Tailwind-only codebase. Vite-specific example: vite.config.ts is the canonical place to declare path aliases — Claude Code reads CLAUDE.md to know whether @/* is configured before suggesting an import path. If the alias is only in tsconfig.json but missing from vite.config.ts, every dev-server reload fails even though the type-checker stays green. Document the alias in both places and Claude Code stops proposing brittle alternatives.

How to customize the template

Change the project name in the H1, drop the tech-stack list to match your installed major versions, and update the “Where things live” section if your folder layout differs from the default Vite scaffold. Pin Vite to the exact major you ship — Vite 7 ships breaking changes to the dev-server preflight cache that Vite 6’s plugins do not anticipate, so a vague “Vite ^7” in the template lets Claude Code generate plugin code targeting either major. The stricter the version, the fewer hallucinated config keys you have to chase.

ViteCode itself runs Astro 6 with Vite 7 underneath, and the inheritance is non-obvious: Astro sets vite.optimizeDeps.exclude defaults that conflict with hand-rolled aliases, so we hard-code that surface in our own CLAUDE.md. If you also adopt Astro on top of Vite, copy that pattern. React Router users should name the router explicitly under “Locked decisions” so Claude Code does not propose Tanstack Router or Next-style routing. If Vitest tests live under a different folder, list that folder in “Where things live” so the agent knows where to write new test files and does not invent a __tests__/ directory next to every component.

Strictness comparison

The ai-agent-rules-generator tool emits this template at three strictness levels — Conservative, Balanced (the default and what this page shows), and Aggressive. Conservative drops the “Hard constraints” block entirely and keeps only the stack and folder layout, useful when you want the agent to suggest changes for human review rather than apply rules autonomously. Balanced is the version above. Aggressive expands the “Hard constraints” block with project-specific bans like “no inline styles”, “no useEffect for data fetching — use TanStack Query”, and “all imports go through the path alias, never relative ../../”. Pick Conservative when onboarding a new agent into a legacy codebase, Balanced for greenfield, and Aggressive when you have already paid the cost of locking in a strong opinionated stack.

Common Vite + Claude Code pitfalls

A few patterns recur often enough that this template’s “Locked decisions” block addresses them by default. First, Claude Code proposes CSS Modules in a Tailwind project — counter with “Styling: Tailwind v4 utilities; no CSS Modules”. Second, Claude Code edits vite.config.ts without realizing the same alias must be in tsconfig.json — counter with the alias mirrored in both files plus a Locked decisions line. Third, Claude Code misunderstands Vite’s HMR boundaries on circular imports and “fixes” the runtime crash by adding a barrel file, which makes HMR worse — counter with “Avoid barrel files in src/components/; HMR cannot invalidate them granularly”. Fourth, Claude Code drops import.meta.hot accept handlers when refactoring — counter with “Preserve import.meta.hot handlers in any file that defines a custom HMR boundary”.

When to update the template

Re-read your CLAUDE.md whenever you upgrade a major dependency or change a convention. Stale rules are worse than missing rules — the agent will cheerfully apply outdated guidance even after the codebase has moved on. Refresh the lastVerified footer on every meaningful edit so future readers know whether the file reflects today’s project or a six-month-old snapshot. ViteCode’s own validator (scripts/validate-templates.ts) fails the build when any template in src/tools/*/templates/ carries a lastVerified older than sixty days; copy the same gate into your CI if you ship templates for downstream consumers. Stick to the eighty-line guideline and the agent will keep reading the rules; let it balloon past two hundred lines and the rules at the bottom start to drop out of attention.

Related prompts and tools

• ai-agent-rules-generator — parameterised generator that emits this template plus AGENTS.md, .cursor/rules, and copilot-instructions.md from one set of stack choices.
• claude-code-bug-fix-prompt — per-task overlay for smallest-safe-change bug fixes. Pairs with the project-level rules on this page.
• claude-code-feature-prompt — feature-build prompt with explicit in-scope / out-of-scope sections.
• codex-agents-md-template — sister format for OpenAI Codex; the same project context expressed in AGENTS.md shape.
• cursor-rules-template — sister format for Cursor; .cursor/rules/*.mdc files with valid YAML frontmatter and globs: matchers.