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 80 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 conversation, so the rules apply to every prompt you send afterwards — no extra wiring 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-07

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 (“do X”), and the development workflow. Each section earns its place — if a project has no special workflow, drop the workflow section. 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: it captures decisions you have already made and do not want re-litigated every time the agent suggests an alternative. Without it, the agent will suggest CSS Modules every other turn even though you have a Tailwind-only codebase. With it, the agent reads “Styling: Tailwind v4 utilities; no CSS Modules” and moves on.

Sections you do not list, the agent will infer from the files. Sections you do list, the agent will treat as ground truth. So list only the rules that actually matter for the codebase — not generic programming advice. The agent already knows the generic stuff.

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. If you adopt React Router, name it explicitly under “Locked decisions” so Claude Code does not propose Tanstack Router or Next-style routing. If you ship Vitest tests under a different folder, list that folder in “Where things live” so the agent knows where to write new test files.

The “Hard constraints” list is where opinionated codebases differentiate themselves. A team that treats any as a bug should keep the no-any rule. A team that is mid-migration from JavaScript may want to soften that rule and instead require new files to be TypeScript-only. Either way, the rule should be specific enough that Claude Code can apply it mechanically, not subjective enough that two readers would interpret it differently.

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. 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.

Phase 1 placeholder note

This is the Phase 1 proof-of-concept page. Phase 5 expands the body to over 500 words with annotated explanations, a strictness comparison, and links to the related ai-agent-rules-generator tool that produces this output parameterized by your stack choices.