Unity rules for AI coding agents
Full stack: Unity (C#)
Ready-to-commit rules for Unity (C#) 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 Unity game scripted in C#. Built for gamedev vibe coders.
Last reviewed 2026-10-21 · Customise in the generator · Raw: AGENTS.md, CLAUDE.md
The mistake agents make most on this stack
Agents hand-edit .meta, scene and prefab files, which corrupts references, and call GetComponent every frame.
Generated files
AGENTS.md
# AGENTS.md - this project
Instructions for AI coding agents working in this repository.
## Project
A Unity (C#) project.
Stack: Unity (C#).
## Commands
- Run tests (CLI): `Unity -batchmode -projectPath . -runTests -testPlatform EditMode -testResults results.xml`
## Project structure
- Scripts in `Assets/Scripts/<Feature>/`. Use Assembly Definitions per feature to keep compile times down.
## 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.
## Unity (C#)
- Only edit `.cs` files. Never hand-edit `.meta`, `.unity`, `.prefab` or `.asset` files, and never invent GUIDs. Tell the user what to change in the Editor instead.
- Never touch `Library/`, `Temp/` or `Logs/`.
- Expose inspector fields as `[SerializeField] private`, not public fields.
- Cache component references in `Awake`; never call `GetComponent`, `GameObject.Find` or `FindFirstObjectByType` (formerly `FindObjectOfType`) inside `Update`.
- Movement and physics in `FixedUpdate` with `Rigidbody`; frame-rate-dependent logic multiplies by `Time.deltaTime`.
- Avoid allocations in per-frame code (no LINQ, string concatenation or `new` in `Update`). Pool frequently spawned objects.
- Use ScriptableObjects for shared config and data.
- Use the Input System package if the project has it installed.
## Reference docs
- [Unity Manual](https://docs.unity3d.com/Manual/index.html)
CLAUDE.md
# CLAUDE.md - this project
Project instructions for Claude Code.
## Project
A Unity (C#) project.
Stack: Unity (C#).
## Commands
- Run tests (CLI): `Unity -batchmode -projectPath . -runTests -testPlatform EditMode -testResults results.xml`
## Project structure
- Scripts in `Assets/Scripts/<Feature>/`. Use Assembly Definitions per feature to keep compile times down.
## 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.
## Unity (C#)
- Only edit `.cs` files. Never hand-edit `.meta`, `.unity`, `.prefab` or `.asset` files, and never invent GUIDs. Tell the user what to change in the Editor instead.
- Never touch `Library/`, `Temp/` or `Logs/`.
- Expose inspector fields as `[SerializeField] private`, not public fields.
- Cache component references in `Awake`; never call `GetComponent`, `GameObject.Find` or `FindFirstObjectByType` (formerly `FindObjectOfType`) inside `Update`.
- Movement and physics in `FixedUpdate` with `Rigidbody`; frame-rate-dependent logic multiplies by `Time.deltaTime`.
- Avoid allocations in per-frame code (no LINQ, string concatenation or `new` in `Update`). Pool frequently spawned objects.
- Use ScriptableObjects for shared config and data.
- Use the Input System package if the project has it installed.
## Reference docs
- [Unity Manual](https://docs.unity3d.com/Manual/index.html)
.cursor/rules/project.mdc
---
description: "Core rules for this project"
alwaysApply: true
---
# this project
A Unity (C#) project.
Stack: Unity (C#).
## Commands
- Run tests (CLI): `Unity -batchmode -projectPath . -runTests -testPlatform EditMode -testResults results.xml`
## 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/unity.mdc
---
description: "Unity (C#) conventions: Unity game project scripted in C#."
globs: Assets/**/*.cs
alwaysApply: false
---
# Unity (C#)
- Only edit `.cs` files. Never hand-edit `.meta`, `.unity`, `.prefab` or `.asset` files, and never invent GUIDs. Tell the user what to change in the Editor instead.
- Never touch `Library/`, `Temp/` or `Logs/`.
- Expose inspector fields as `[SerializeField] private`, not public fields.
- Cache component references in `Awake`; never call `GetComponent`, `GameObject.Find` or `FindFirstObjectByType` (formerly `FindObjectOfType`) inside `Update`.
- Movement and physics in `FixedUpdate` with `Rigidbody`; frame-rate-dependent logic multiplies by `Time.deltaTime`.
- Avoid allocations in per-frame code (no LINQ, string concatenation or `new` in `Update`). Pool frequently spawned objects.
- Use ScriptableObjects for shared config and data.
- Use the Input System package if the project has it installed.
Docs: https://docs.unity3d.com/Manual/index.html
.cursorrules
# Cursor rules - this project
You are an expert Unity (C#) engineer working on this codebase. Follow these rules.
## Project
A Unity (C#) project.
Stack: Unity (C#).
## Commands
- Run tests (CLI): `Unity -batchmode -projectPath . -runTests -testPlatform EditMode -testResults results.xml`
## Project structure
- Scripts in `Assets/Scripts/<Feature>/`. Use Assembly Definitions per feature to keep compile times down.
## 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.
## Unity (C#)
- Only edit `.cs` files. Never hand-edit `.meta`, `.unity`, `.prefab` or `.asset` files, and never invent GUIDs. Tell the user what to change in the Editor instead.
- Never touch `Library/`, `Temp/` or `Logs/`.
- Expose inspector fields as `[SerializeField] private`, not public fields.
- Cache component references in `Awake`; never call `GetComponent`, `GameObject.Find` or `FindFirstObjectByType` (formerly `FindObjectOfType`) inside `Update`.
- Movement and physics in `FixedUpdate` with `Rigidbody`; frame-rate-dependent logic multiplies by `Time.deltaTime`.
- Avoid allocations in per-frame code (no LINQ, string concatenation or `new` in `Update`). Pool frequently spawned objects.
- Use ScriptableObjects for shared config and data.
- Use the Input System package if the project has it installed.
## Reference docs
- [Unity Manual](https://docs.unity3d.com/Manual/index.html)
.github/copilot-instructions.md
# Copilot instructions - this project
A Unity (C#) project.
Stack: Unity (C#).
## Commands
- Run tests (CLI): `Unity -batchmode -projectPath . -runTests -testPlatform EditMode -testResults results.xml`
## 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/unity.instructions.md
---
applyTo: "Assets/**/*.cs"
---
# Unity (C#)
- Only edit `.cs` files. Never hand-edit `.meta`, `.unity`, `.prefab` or `.asset` files, and never invent GUIDs. Tell the user what to change in the Editor instead.
- Never touch `Library/`, `Temp/` or `Logs/`.
- Expose inspector fields as `[SerializeField] private`, not public fields.
- Cache component references in `Awake`; never call `GetComponent`, `GameObject.Find` or `FindFirstObjectByType` (formerly `FindObjectOfType`) inside `Update`.
- Movement and physics in `FixedUpdate` with `Rigidbody`; frame-rate-dependent logic multiplies by `Time.deltaTime`.
- Avoid allocations in per-frame code (no LINQ, string concatenation or `new` in `Update`). Pool frequently spawned objects.
- Use ScriptableObjects for shared config and data.
- Use the Input System package if the project has it installed.
.windsurf/rules/project.md
---
trigger: always_on
---
# this project
A Unity (C#) project.
Stack: Unity (C#).
## Commands
- Run tests (CLI): `Unity -batchmode -projectPath . -runTests -testPlatform EditMode -testResults results.xml`
## 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/unity.md
---
trigger: glob
globs: Assets/**/*.cs
---
# Unity (C#)
- Only edit `.cs` files. Never hand-edit `.meta`, `.unity`, `.prefab` or `.asset` files, and never invent GUIDs. Tell the user what to change in the Editor instead.
- Never touch `Library/`, `Temp/` or `Logs/`.
- Expose inspector fields as `[SerializeField] private`, not public fields.
- Cache component references in `Awake`; never call `GetComponent`, `GameObject.Find` or `FindFirstObjectByType` (formerly `FindObjectOfType`) inside `Update`.
- Movement and physics in `FixedUpdate` with `Rigidbody`; frame-rate-dependent logic multiplies by `Time.deltaTime`.
- Avoid allocations in per-frame code (no LINQ, string concatenation or `new` in `Update`). Pool frequently spawned objects.
- Use ScriptableObjects for shared config and data.
- Use the Input System package if the project has it installed.
GEMINI.md
# GEMINI.md - this project
Project context for Gemini CLI.
## Project
A Unity (C#) project.
Stack: Unity (C#).
## Commands
- Run tests (CLI): `Unity -batchmode -projectPath . -runTests -testPlatform EditMode -testResults results.xml`
## Project structure
- Scripts in `Assets/Scripts/<Feature>/`. Use Assembly Definitions per feature to keep compile times down.
## 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.
## Unity (C#)
- Only edit `.cs` files. Never hand-edit `.meta`, `.unity`, `.prefab` or `.asset` files, and never invent GUIDs. Tell the user what to change in the Editor instead.
- Never touch `Library/`, `Temp/` or `Logs/`.
- Expose inspector fields as `[SerializeField] private`, not public fields.
- Cache component references in `Awake`; never call `GetComponent`, `GameObject.Find` or `FindFirstObjectByType` (formerly `FindObjectOfType`) inside `Update`.
- Movement and physics in `FixedUpdate` with `Rigidbody`; frame-rate-dependent logic multiplies by `Time.deltaTime`.
- Avoid allocations in per-frame code (no LINQ, string concatenation or `new` in `Update`). Pool frequently spawned objects.
- Use ScriptableObjects for shared config and data.
- Use the Input System package if the project has it installed.
## Reference docs
- [Unity Manual](https://docs.unity3d.com/Manual/index.html)
Commands your agent should run
| Task | Command |
|---|---|
| Run tests (CLI) | Unity -batchmode -projectPath . -runTests -testPlatform EditMode -testResults results.xml |
What the rules cover
Unity (C#)
Unity game project scripted in C#. Scoped to Assets/**/*.cs in Cursor, Copilot and Windsurf.
- Only edit
.csfiles. Never hand-edit.meta,.unity,.prefabor.assetfiles, and never invent GUIDs. Tell the user what to change in the Editor instead. - Never touch
Library/,Temp/orLogs/. - Expose inspector fields as
[SerializeField] private, not public fields. - Cache component references in
Awake; never callGetComponent,GameObject.FindorFindFirstObjectByType(formerlyFindObjectOfType) insideUpdate. - Movement and physics in
FixedUpdatewithRigidbody; frame-rate-dependent logic multiplies byTime.deltaTime. - Avoid allocations in per-frame code (no LINQ, string concatenation or
newinUpdate). Pool frequently spawned objects. - Use ScriptableObjects for shared config and data.
- Use the Input System package if the project has it installed.
Source docs: Unity Manual
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 Unity (C#)?
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 Unity (C#)?
Agents hand-edit .meta, scene and prefab files, which corrupts references, and call GetComponent every frame.
Which commands should the agent run to check its work?
For this stack: Unity -batchmode -projectPath . -runTests -testPlatform EditMode -testResults results.xml. They are listed in the generated files so the agent runs them before finishing a task.
Do these Unity (C#) 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 + shadcn/ui + Supabase + Zod validation
The default vibe-coding SaaS stack: Next.js App Router, Supabase for auth and Postgres, Tailwind and shadcn/ui for the interface.
Next.js (App Router) + Tailwind CSS v4
A plain Next.js + TypeScript + Tailwind v4 starter, the most common front-end setup in 2026.
Next.js (App Router) + Tailwind CSS v4 + Prisma + Stripe payments + Zod validation
A paid SaaS on Next.js with Prisma and Stripe subscriptions.
Next.js (App Router) + Tailwind CSS v4 + Drizzle ORM + Clerk auth + Zod validation
Next.js with Clerk for auth and Drizzle ORM on Postgres: fast to build, type-safe end to end.
Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Vercel AI SDK + Zod validation
Build an AI chat app or agent UI with Next.js and the Vercel AI SDK.
Next.js (App Router) + Tailwind CSS v4 + Supabase + Stripe payments + Zod validation + Vitest
The full indie-hacker SaaS kit: auth, database, payments and tests.