Home › Rules › Browser game (Phaser)

Browser game (Phaser) rules: AGENTS.md, CLAUDE.md & Cursor rules

Free to copy. File formats checked against the official docs on Oct 19, 2026 (sources).

• Games
• Claude Code
• OpenAI Codex
• Cursor
• GitHub Copilot

Phaser games fall apart when the AI rewrites the game loop every time you ask for a new enemy. These rules keep it to one mechanic at a time, with a playable build after every step.

Stack these rules assume: Phaser 3 + Vite, JavaScript or TypeScript, runs in the browser. Different stack? Customize it in the generator.

Quick start

1. Copy the AGENTS.md below into your project's root folder.
2. Fill in the three [bracketed] lines under "Project". Delete any rule that doesn't fit.
3. Start your first chat with: "Read AGENTS.md and follow it for this whole session."

AGENTS.md (works across tools)

Read by OpenAI Codex, Cursor, GitHub Copilot, Claude Code (when there's no CLAUDE.md) and many other agents.

# AGENTS.md: Browser game (Phaser)

Instructions for AI coding agents working on this project. Replace anything in [brackets].

## Project
- What it is: [one sentence: what you are building and who it is for]
- Stack: Phaser 3 + Vite, JavaScript or TypeScript, runs in the browser
- Version 1 only needs to: [the ONE thing it must do]

## Commands
- Create the project (official Phaser starter): `npm create @phaserjs/game@latest`
- Install: `npm install`
- Run locally: `npm run dev`
- Production build: `npm run build`

## Project rules
- Keep each scene in its own file under src/scenes/ (or wherever the starter put them). Don't merge scenes.
- Add one mechanic per task (movement, then jumping, then enemies). After each one, the game must still start and be playable.
- Put tunable numbers (speed, gravity, spawn rate, lives) in one config object at the top of the scene or in a config file.
- Load assets in preload() with clear keys. If an asset file is missing, use a colored rectangle placeholder and tell me.
- Use the Phaser version that's in package.json. Don't use Phaser 2/CE examples or APIs.
- Don't add a physics engine, state library, or framework unless I ask. Use Phaser's built-in Arcade Physics.

## How to work
- Do one task per request. If my request is really several tasks, list them and do only the first.
- Before writing code, give a 3-line plan: what you'll change, which files, and how I'll test it.
- Make the smallest change that works. Don't refactor, rename, or reformat code I didn't ask about.
- Ask before adding a dependency, deleting or moving files, changing the data/database structure, or touching more than 3 files.
- If you're not sure a library, API, or setting exists in the version we use, say so and check the installed package or the docs instead of guessing.
- Never say something works unless you ran it or I confirmed it. Report errors exactly.
- Secrets (API keys, tokens, passwords) live only in environment variables or a .env file listed in .gitignore. Never print, hardcode, or commit them.
- Never run destructive commands (rm -rf, git reset --hard, force-push, dropping tables) without asking first.

## Finish every task with
1. What changed (list the files).
2. How to run or test it in under a minute, and what I should see.
3. A suggested git commit message.

Why each rule exists

• Browser game (Phaser) ruleKeep each scene in its own file under src/scenes/ (or wherever the starter put them). Don't merge scenes.Why: One scene per file means a change to the menu can't break the level.
• Browser game (Phaser) ruleAdd one mechanic per task (movement, then jumping, then enemies). After each one, the game must still start and be playable.Why: Games are tested by playing. If every step ends playable, you always know which step broke it.
• Browser game (Phaser) rulePut tunable numbers (speed, gravity, spawn rate, lives) in one config object at the top of the scene or in a config file.Why: You'll tweak these 50 times. One place to change them beats hunting through code.
• Browser game (Phaser) ruleLoad assets in preload() with clear keys. If an asset file is missing, use a colored rectangle placeholder and tell me.Why: The AI can't draw your sprites, but it shouldn't stall on them either. Placeholders keep you moving.
• Browser game (Phaser) ruleUse the Phaser version that's in package.json. Don't use Phaser 2/CE examples or APIs.Why: Old Phaser 2 tutorials are all over the internet and the AI has read them. Their APIs don't work in Phaser 3.
• Browser game (Phaser) ruleDon't add a physics engine, state library, or framework unless I ask. Use Phaser's built-in Arcade Physics.Why: Arcade Physics handles platformers and shooters fine. Extra engines add weight and new ways to break.
• How to workDo one task per request. If my request is really several tasks, list them and do only the first.Why: Big multi-part requests are where AI tools change 12 files and you can't tell which change broke things.
• How to workBefore writing code, give a 3-line plan: what you'll change, which files, and how I'll test it.Why: A plan you can read in 10 seconds catches the wrong approach before it costs you an hour or a pile of credits.
• How to workMake the smallest change that works. Don't refactor, rename, or reformat code I didn't ask about.Why: Drive-by "cleanups" are the #1 cause of "it was working yesterday".
• How to workAsk before adding a dependency, deleting or moving files, changing the data/database structure, or touching more than 3 files.Why: These are the changes that are hard to undo. One quick question is cheaper than a rollback.
• How to workIf you're not sure a library, API, or setting exists in the version we use, say so and check the installed package or the docs instead of guessing.Why: AI tools confidently invent functions and config options. Making it check is the cure.
• How to workNever say something works unless you ran it or I confirmed it. Report errors exactly.Why: "Should work now" isn't a test result. You want facts, not optimism.
• How to workSecrets (API keys, tokens, passwords) live only in environment variables or a .env file listed in .gitignore. Never print, hardcode, or commit them.Why: Leaked keys get found by bots within minutes of a public push. This rule is the cheapest insurance you'll ever buy.
• How to workNever run destructive commands (rm -rf, git reset --hard, force-push, dropping tables) without asking first.Why: One bad command can delete the only copy of your work.
• Finish every task withWhat changed, how to test it, and a commit message.Why: This turns every task into a checkpoint: you test it, you commit it, and you always have a last good version to go back to.

Use it as CLAUDE.md (Claude Code)

Pick one:

1. Do nothing. Current Claude Code versions read AGENTS.md when the project has no CLAUDE.md. Run /memory in a session to check it loaded.
2. Import it (best if you want Claude-only extras, or you're on an older Claude Code). Create CLAUDE.md next to AGENTS.md:

@AGENTS.md

## Claude Code
- Use plan mode before any change that touches more than 3 files.

3. Claude only? Save the same AGENTS.md text as CLAUDE.md instead. Don't keep two separate copies; they drift apart.

Heads-up: if a project has both files and CLAUDE.md doesn't import AGENTS.md, Claude Code reads only CLAUDE.md by default. More in AGENTS.md vs CLAUDE.md.

Use it as Cursor rules (.cursor/rules/*.mdc)

Cursor reads AGENTS.md too, so the file above already works. If you prefer Cursor's own Project Rules, split it into two .mdc files. The .mdc extension and frontmatter are required; Cursor ignores plain .md files in .cursor/rules.

---
description: Project overview and working rules for Browser game (Phaser)
alwaysApply: true
---

# Browser game (Phaser)

Instructions for AI coding agents working on this project. Replace anything in [brackets].

## Project
- What it is: [one sentence: what you are building and who it is for]
- Stack: Phaser 3 + Vite, JavaScript or TypeScript, runs in the browser
- Version 1 only needs to: [the ONE thing it must do]

## Commands
- Create the project (official Phaser starter): `npm create @phaserjs/game@latest`
- Install: `npm install`
- Run locally: `npm run dev`
- Production build: `npm run build`

## How to work
- Do one task per request. If my request is really several tasks, list them and do only the first.
- Before writing code, give a 3-line plan: what you'll change, which files, and how I'll test it.
- Make the smallest change that works. Don't refactor, rename, or reformat code I didn't ask about.
- Ask before adding a dependency, deleting or moving files, changing the data/database structure, or touching more than 3 files.
- If you're not sure a library, API, or setting exists in the version we use, say so and check the installed package or the docs instead of guessing.
- Never say something works unless you ran it or I confirmed it. Report errors exactly.
- Secrets (API keys, tokens, passwords) live only in environment variables or a .env file listed in .gitignore. Never print, hardcode, or commit them.
- Never run destructive commands (rm -rf, git reset --hard, force-push, dropping tables) without asking first.

## Finish every task with
1. What changed (list the files).
2. How to run or test it in under a minute, and what I should see.
3. A suggested git commit message.

The project rules only attach when a matching file is in the chat (globs with alwaysApply: false). Want them on all the time? Change it to alwaysApply: true.

---
globs: src/**/*.js, src/**/*.ts
alwaysApply: false
---

# Project rules: Browser game (Phaser)

- Keep each scene in its own file under src/scenes/ (or wherever the starter put them). Don't merge scenes.
- Add one mechanic per task (movement, then jumping, then enemies). After each one, the game must still start and be playable.
- Put tunable numbers (speed, gravity, spawn rate, lives) in one config object at the top of the scene or in a config file.
- Load assets in preload() with clear keys. If an asset file is missing, use a colored rectangle placeholder and tell me.
- Use the Phaser version that's in package.json. Don't use Phaser 2/CE examples or APIs.
- Don't add a physics engine, state library, or framework unless I ask. Use Phaser's built-in Arcade Physics.

Use either AGENTS.md or these .mdc files, not both, so you don't send the same rules twice. See Cursor rules vs AGENTS.md.

Related

• Best AI tool to build a small game (which tool to use, real prices)
• AGENTS.md, CLAUDE.md and Cursor rules formats explained