Phaser + Vitest rules for AI coding agents
Full stack: Phaser (TypeScript web games) + Vitest
Ready-to-commit rules for Phaser (TypeScript web games) + Vitest in every major format: AGENTS.md (Codex, Cursor, Copilot), CLAUDE.md (Claude Code), Cursor .mdc project rules, legacy .cursorrules, Copilot instructions, Windsurf rules and GEMINI.md. A 2D browser game with Phaser, TypeScript and Vite.
Last reviewed 2026-10-21 · Customise in the generator · Raw: AGENTS.md, CLAUDE.md
The mistake agents make most on this stack
Movement ignores delta time, so the game runs faster on 120 Hz screens.
Generated files
AGENTS.md
# AGENTS.md - this project
Instructions for AI coding agents working in this repository.
## Project
A Phaser (TypeScript web games) + Vitest project.
Stack: Phaser (TypeScript web games), Vitest.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Unit tests: `npx vitest run`
## Project structure
- One class per scene in `src/scenes/`, game objects in `src/objects/`, static assets in `public/assets/`.
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Phaser (TypeScript web games)
- Check the Phaser major version in `package.json` and use APIs from that version only.
- Each scene is a class extending `Phaser.Scene` with `preload`, `create` and `update`.
- Load assets in `preload` (or a dedicated Boot/Preload scene), never in `update`.
- Movement uses the `delta` argument of `update(time, delta)` so speed is frame-rate independent.
- Pool bullets, particles and enemies with `Phaser.GameObjects.Group` instead of creating and destroying each frame.
- Keep game state in scene or registry data, not in DOM elements.
- Remove event listeners and timers on scene `shutdown` to avoid leaks.
## Vitest
- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.
## Reference docs
- [Phaser docs](https://docs.phaser.io)
- [Vitest docs](https://vitest.dev)
CLAUDE.md
# CLAUDE.md - this project
Project instructions for Claude Code.
## Project
A Phaser (TypeScript web games) + Vitest project.
Stack: Phaser (TypeScript web games), Vitest.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Unit tests: `npx vitest run`
## Project structure
- One class per scene in `src/scenes/`, game objects in `src/objects/`, static assets in `public/assets/`.
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Phaser (TypeScript web games)
- Check the Phaser major version in `package.json` and use APIs from that version only.
- Each scene is a class extending `Phaser.Scene` with `preload`, `create` and `update`.
- Load assets in `preload` (or a dedicated Boot/Preload scene), never in `update`.
- Movement uses the `delta` argument of `update(time, delta)` so speed is frame-rate independent.
- Pool bullets, particles and enemies with `Phaser.GameObjects.Group` instead of creating and destroying each frame.
- Keep game state in scene or registry data, not in DOM elements.
- Remove event listeners and timers on scene `shutdown` to avoid leaks.
## Vitest
- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.
## Reference docs
- [Phaser docs](https://docs.phaser.io)
- [Vitest docs](https://vitest.dev)
.cursor/rules/project.mdc
---
description: "Core rules for this project"
alwaysApply: true
---
# this project
A Phaser (TypeScript web games) + Vitest project.
Stack: Phaser (TypeScript web games), Vitest.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Unit tests: `npx vitest run`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.cursor/rules/phaser.mdc
---
description: "Phaser (TypeScript web games) conventions: 2D browser game with Phaser, TypeScript and Vite."
globs: src/**/*.ts
alwaysApply: false
---
# Phaser (TypeScript web games)
- Check the Phaser major version in `package.json` and use APIs from that version only.
- Each scene is a class extending `Phaser.Scene` with `preload`, `create` and `update`.
- Load assets in `preload` (or a dedicated Boot/Preload scene), never in `update`.
- Movement uses the `delta` argument of `update(time, delta)` so speed is frame-rate independent.
- Pool bullets, particles and enemies with `Phaser.GameObjects.Group` instead of creating and destroying each frame.
- Keep game state in scene or registry data, not in DOM elements.
- Remove event listeners and timers on scene `shutdown` to avoid leaks.
Docs: https://docs.phaser.io
.cursor/rules/vitest.mdc
---
description: "Vitest conventions: Unit and component tests with Vitest."
globs: **/*.test.ts, **/*.test.tsx, **/*.spec.ts
alwaysApply: false
---
# Vitest
- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.
Docs: https://vitest.dev
.cursorrules
# Cursor rules - this project
You are an expert Phaser (TypeScript web games), Vitest engineer working on this codebase. Follow these rules.
## Project
A Phaser (TypeScript web games) + Vitest project.
Stack: Phaser (TypeScript web games), Vitest.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Unit tests: `npx vitest run`
## Project structure
- One class per scene in `src/scenes/`, game objects in `src/objects/`, static assets in `public/assets/`.
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Phaser (TypeScript web games)
- Check the Phaser major version in `package.json` and use APIs from that version only.
- Each scene is a class extending `Phaser.Scene` with `preload`, `create` and `update`.
- Load assets in `preload` (or a dedicated Boot/Preload scene), never in `update`.
- Movement uses the `delta` argument of `update(time, delta)` so speed is frame-rate independent.
- Pool bullets, particles and enemies with `Phaser.GameObjects.Group` instead of creating and destroying each frame.
- Keep game state in scene or registry data, not in DOM elements.
- Remove event listeners and timers on scene `shutdown` to avoid leaks.
## Vitest
- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.
## Reference docs
- [Phaser docs](https://docs.phaser.io)
- [Vitest docs](https://vitest.dev)
.github/copilot-instructions.md
# Copilot instructions - this project
A Phaser (TypeScript web games) + Vitest project.
Stack: Phaser (TypeScript web games), Vitest.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Unit tests: `npx vitest run`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.github/instructions/phaser.instructions.md
---
applyTo: "src/**/*.ts"
---
# Phaser (TypeScript web games)
- Check the Phaser major version in `package.json` and use APIs from that version only.
- Each scene is a class extending `Phaser.Scene` with `preload`, `create` and `update`.
- Load assets in `preload` (or a dedicated Boot/Preload scene), never in `update`.
- Movement uses the `delta` argument of `update(time, delta)` so speed is frame-rate independent.
- Pool bullets, particles and enemies with `Phaser.GameObjects.Group` instead of creating and destroying each frame.
- Keep game state in scene or registry data, not in DOM elements.
- Remove event listeners and timers on scene `shutdown` to avoid leaks.
.github/instructions/vitest.instructions.md
---
applyTo: "**/*.test.ts,**/*.test.tsx,**/*.spec.ts"
---
# Vitest
- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.
.windsurf/rules/project.md
---
trigger: always_on
---
# this project
A Phaser (TypeScript web games) + Vitest project.
Stack: Phaser (TypeScript web games), Vitest.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Unit tests: `npx vitest run`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.windsurf/rules/phaser.md
---
trigger: glob
globs: src/**/*.ts
---
# Phaser (TypeScript web games)
- Check the Phaser major version in `package.json` and use APIs from that version only.
- Each scene is a class extending `Phaser.Scene` with `preload`, `create` and `update`.
- Load assets in `preload` (or a dedicated Boot/Preload scene), never in `update`.
- Movement uses the `delta` argument of `update(time, delta)` so speed is frame-rate independent.
- Pool bullets, particles and enemies with `Phaser.GameObjects.Group` instead of creating and destroying each frame.
- Keep game state in scene or registry data, not in DOM elements.
- Remove event listeners and timers on scene `shutdown` to avoid leaks.
.windsurf/rules/vitest.md
---
trigger: glob
globs: **/*.test.ts, **/*.test.tsx, **/*.spec.ts
---
# Vitest
- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.
GEMINI.md
# GEMINI.md - this project
Project context for Gemini CLI.
## Project
A Phaser (TypeScript web games) + Vitest project.
Stack: Phaser (TypeScript web games), Vitest.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Unit tests: `npx vitest run`
## Project structure
- One class per scene in `src/scenes/`, game objects in `src/objects/`, static assets in `public/assets/`.
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Phaser (TypeScript web games)
- Check the Phaser major version in `package.json` and use APIs from that version only.
- Each scene is a class extending `Phaser.Scene` with `preload`, `create` and `update`.
- Load assets in `preload` (or a dedicated Boot/Preload scene), never in `update`.
- Movement uses the `delta` argument of `update(time, delta)` so speed is frame-rate independent.
- Pool bullets, particles and enemies with `Phaser.GameObjects.Group` instead of creating and destroying each frame.
- Keep game state in scene or registry data, not in DOM elements.
- Remove event listeners and timers on scene `shutdown` to avoid leaks.
## Vitest
- Co-locate tests next to the code as `*.test.ts(x)`.
- Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.
## Reference docs
- [Phaser docs](https://docs.phaser.io)
- [Vitest docs](https://vitest.dev)
Commands your agent should run
| Task | Command |
|---|---|
| Dev server | npm run dev |
| Build | npm run build |
| Unit tests | npx vitest run |
What the rules cover
Phaser (TypeScript web games)
2D browser game with Phaser, TypeScript and Vite. Scoped to src/**/*.ts in Cursor, Copilot and Windsurf.
- Check the Phaser major version in
package.jsonand use APIs from that version only. - Each scene is a class extending
Phaser.Scenewithpreload,createandupdate. - Load assets in
preload(or a dedicated Boot/Preload scene), never inupdate. - Movement uses the
deltaargument ofupdate(time, delta)so speed is frame-rate independent. - Pool bullets, particles and enemies with
Phaser.GameObjects.Groupinstead of creating and destroying each frame. - Keep game state in scene or registry data, not in DOM elements.
- Remove event listeners and timers on scene
shutdownto avoid leaks.
Source docs: Phaser docs
Vitest
Unit and component tests with Vitest. Scoped to **/*.test.ts, **/*.test.tsx, **/*.spec.ts in Cursor, Copilot and Windsurf.
- Co-locate tests next to the code as
*.test.ts(x). - Test behaviour through public APIs; for components use Testing Library queries by role/label.
- Mock network calls at the boundary (e.g. MSW) rather than mocking internal modules.
- Every bug fix adds a test that fails without the fix.
Source docs: Vitest docs
How to install
- Copy
AGENTS.mdto your repo root. That covers Codex, Cursor, GitHub Copilot and most other agents. - Using Claude Code? Add a
CLAUDE.mdwith the single line@AGENTS.md, or use the standalone CLAUDE.md tab above. - Want rules that only load for certain files in Cursor? Add the
.cursor/rules/*.mdcfiles. - Commit the files so your whole team (and every agent) shares them.
FAQ
Where do I put the AGENTS.md for Phaser (TypeScript web games) + Vitest?
Save it as AGENTS.md in the root of your repository, next to your main config file. Codex, Cursor and GitHub Copilot pick it up automatically. For Claude Code, add a CLAUDE.md containing @AGENTS.md (or use the standalone CLAUDE.md on this page).
What is the most common mistake AI agents make with Phaser (TypeScript web games)?
Movement ignores delta time, so the game runs faster on 120 Hz screens.
Which commands should the agent run to check its work?
For this stack: npm run dev, npm run build, npx vitest run. They are listed in the generated files so the agent runs them before finishing a task.
Do these Phaser (TypeScript web games) + Vitest rules work with Cursor and Claude Code?
Yes. This page includes the same rules as AGENTS.md, CLAUDE.md, Cursor .mdc project rules, a legacy .cursorrules file, GitHub Copilot instructions, Windsurf rules and GEMINI.md.
Can I customise these rules?
Yes. Open this stack in the generator to add or remove libraries, set your project name and package manager, switch beginner explanations on, and download everything as a zip.
Related stacks
Next.js (App Router) + Tailwind CSS v4 + Supabase + Stripe payments + Zod validation + Vitest
The full indie-hacker SaaS kit: auth, database, payments and tests.
Next.js (App Router) + Tailwind CSS v4 + Vitest + Playwright E2E
A Next.js app with a proper test setup: Vitest for units, Playwright for end-to-end.
React + Vite + Tailwind CSS v4 + TanStack Query + Vitest + Zod validation
A classic single-page app: React + Vite with TanStack Query for server data.
React + Vite + Tailwind CSS v4 + Firebase + Vitest
A React SPA on Firebase Auth and Firestore.
SvelteKit (Svelte 5) + Tailwind CSS v4 + Drizzle ORM + Vitest
SvelteKit full-stack with Drizzle ORM.
Node.js + Express + Prisma + Zod validation + Vitest + Docker
A TypeScript REST API with Express 5, Prisma and Zod.