Skip to content
Avache

Claude Code in Unity projects

A practical setup for Unity developers who already use Claude Code: CLAUDE.md, path-scoped rules, sub-agents, MCP and skills that make it follow your project.

  • claude code
  • unity
  • workflow
Portrait of Vũ Thanh Nam

Vũ Thanh Nam

8 min read

Cover with the title "Claude Code in Unity projects" next to a portrait of the author, Vũ Thanh Nam
On this page

If you have used Claude Code on a Unity project, you have probably seen both sides of it. It writes a working MonoBehaviour in seconds, then calls an API your Unity version marked obsolete, edits a prefab file by hand, or puts editor code where the player build will choke on it.

Most of those mistakes are not about model quality. Claude starts every session knowing nothing about your project: which Unity version you are on, how your assemblies are split, which folders are generated, how you run tests. Claude Code gives you several places to write that knowledge down once. This post walks through them in the order I would set them up: CLAUDE.md, path-scoped rules, permissions, sub-agents, MCP and skills.

Why Unity projects need configuration

A Unity repository looks like a normal C# codebase, but it has traps that a general-purpose assistant will not guess:

  • Every asset has a .meta file holding its GUID. Move or rename a script without its .meta file and every scene or prefab that references it breaks.
  • Scenes and prefabs are YAML, often thousands of lines long. They are readable, but editing them by hand is fragile, and they burn through the context window.
  • Library/, Temp/ and Logs/ are generated. They are huge and useless to read, and they change constantly.
  • Editor and runtime code must stay apart. Anything that uses UnityEditor has to live in an Editor folder or an editor-only assembly definition, or the player build fails.
  • APIs change between versions. Object.FindObjectOfType became obsolete in Unity 2023.1 in favor of FindFirstObjectByType and FindAnyObjectByType. Without your version, Claude has to guess which API applies.

Each section below closes one of these gaps.

CLAUDE.md: the project brief

CLAUDE.md at the repository root is loaded into every session. Treat it as the brief you would give a new teammate on day one: facts Claude cannot reliably infer from the code.

For a Unity project, that usually means:

  • the exact Unity version and render pipeline (Built-in, URP or HDRP)
  • the folder layout and which assembly definitions exist
  • naming and coding conventions for C#
  • how to run tests and what "done" means for a change
  • the things Claude must never do
# Project brief

- Unity 6000.0 LTS, URP. Target platforms: Android and iOS.
- Gameplay code lives in Assets/_Project/Scripts, split into the Game.Runtime,
  Game.Editor and Game.Tests assemblies (.asmdef).
- C#: PascalCase for public members, _camelCase for private fields,
  [SerializeField] private instead of public fields.
- Prefer FindFirstObjectByType over the obsolete FindObjectOfType.
- Never edit .unity, .prefab or .asset files by hand; describe the change
  and let me apply it in the Editor.
- Done = compiles without warnings and EditMode tests pass.

Keep the file short; the official guidance is to stay under about 200 lines, because longer files cost context and are followed less consistently. Run /init to have Claude draft a first version from your codebase, then trim it down to what actually matters. Personal preferences that should not be committed go into CLAUDE.local.md, which loads alongside it; add that file to .gitignore.

Path-scoped rules in .claude/rules/

As the brief grows, move topic-specific instructions into Markdown files under .claude/rules/. A rule with a paths field in its frontmatter only loads when Claude reads or edits a matching file, so editor conventions do not cost context while Claude works on gameplay code.

---
paths:
  - "Assets/**/Editor/**/*.cs"
---

# Editor scripts

- Editor code only. Never reference these types from runtime assemblies.
- Wrap destructive operations in Undo.RecordObject so they can be undone.
- Use EditorUtility.SetDirty after changing serialized data on assets.

Good candidates for separate rules in a Unity project:

  • Editor tooling (Assets/**/Editor/**): the example above.
  • Tests (Assets/**/Tests/**/*.cs): Unity Test Framework conventions, EditMode versus PlayMode, naming.
  • Shaders (**/*.shader, **/*.hlsl): pipeline-specific includes and keyword rules.
  • UI: whether the project uses UI Toolkit or uGUI, so Claude does not mix them.

Rules without paths load in every session, just like CLAUDE.md. Keep each file to one topic so it is easy to find and update.

Keep Claude out of generated files

Instructions are context, not enforcement. For folders Claude should never read, use permissions in .claude/settings.json, which Claude Code applies regardless of what the model decides:

{
  "permissions": {
    "deny": [
      "Read(./Library/**)",
      "Read(./Temp/**)",
      "Read(./Logs/**)",
      "Read(./UserSettings/**)"
    ]
  }
}

This keeps searches fast and stops Claude from pulling megabytes of generated data into the conversation. Pair it with a line in CLAUDE.md about .meta files: assets should be moved or renamed in the Editor, which keeps GUIDs intact, not with file operations.

Sub-agents for focused work

A sub-agent is a specialist Claude can hand a task to. It runs in its own context window with its own system prompt and tool access, and only its final summary comes back to the main conversation. That makes sub-agents a good fit for work that produces a lot of output, such as reviewing a large diff or digging through documentation.

Project sub-agents live in .claude/agents/ as Markdown files. Only name and description are required; the description is what Claude uses to decide when to delegate.

---
name: unity-code-reviewer
description: Reviews C# changes in this Unity project. Use proactively after gameplay or editor code changes.
tools: Read, Grep, Glob
model: sonnet
---

You review C# code in a Unity project. Check for: allocations in Update loops,
missing null checks on serialized references, UnityEditor usage outside editor
assemblies, obsolete APIs for the project's Unity version, and missing .meta
handling when files are moved. Report findings by severity with file and line.

Useful agents for a Unity team include a code reviewer like the one above, a test writer that knows your Unity Test Framework conventions, and a researcher that reads Unity documentation and release notes so that work stays out of your main session. Restricting tools to read-only access is a simple way to make reviewers safe to run often.

MCP: connect Claude to the Unity Editor

Out of the box, Claude Code sees your files but not the running Editor. It cannot read the Console, see compile errors as Unity reports them, or inspect the scene hierarchy. The Model Context Protocol (MCP) closes that gap: an MCP server exposes tools that Claude can call.

Several community servers bridge Claude Code and the Unity Editor. Two established ones are MCP for Unity by CoplayDev and mcp-unity by CoderGamester. Both install a Unity package that talks to a local server, and they offer tools such as reading Console logs, managing scenes and GameObjects, and running tests. Requirements differ (Unity version, Python or Node.js), so follow the README of the one you choose.

Claude Code registers servers with claude mcp add. Everything after -- is the command that starts a local server:

claude mcp add --scope project unity -- <command from the server's README>

The scope decides who gets the server. local (the default) is just you in this project, user is you in every project, and project writes it to .mcp.json at the repository root so the whole team shares it through version control. Inside Claude Code, /mcp shows each server's status.

Treat Editor tools with the same care as any automation that can change scenes. Read the tool list before enabling a server, commit your work before letting Claude modify scenes, and keep "never edit scenes by hand" in CLAUDE.md so changes go through the Editor's own APIs.

Skills for repeatable workflows

Some tasks follow the same steps every time: running the test suite, scaffolding a new feature folder with its assembly definition, preparing a build. A skill packages those steps so you can trigger them with one command.

A project skill is a folder in .claude/skills/ with a SKILL.md file. Its frontmatter description tells Claude what it does, and you run it as /<name>. Setting disable-model-invocation: true means it only runs when you type it, which is what you want for anything with side effects.

---
name: unity-tests
description: Run the EditMode test suite in batch mode and summarize failures.
disable-model-invocation: true
---

1. Make sure the project is not open in the Unity Editor; batch mode cannot
   open a project that is already open.
2. Run the Unity editor binary for this project's version:
   "<path to Unity>" -batchmode -projectPath . -runTests -testPlatform EditMode
   -testResults ./TestResults/editmode.xml -logFile -
3. Read TestResults/editmode.xml and list each failing test with its message
   and the most likely cause in our code.

Start with the one workflow you repeat most. If you find yourself typing the same multi-step instructions into the chat, that is a skill waiting to be written.

A setup checklist

  1. Run /init, then cut CLAUDE.md down to your Unity version, render pipeline, layout, conventions and test command.
  2. Add permissions.deny for Library/, Temp/, Logs/ and UserSettings/ in .claude/settings.json.
  3. Move editor, test and shader conventions into path-scoped rules in .claude/rules/.
  4. Add a read-only code reviewer in .claude/agents/.
  5. Connect the Editor through an MCP server, shared with the team in .mcp.json.
  6. Turn your most repeated task into a skill, starting with running tests.

None of these files need to be perfect on day one. Commit them with the project, and update them whenever Claude makes the same mistake twice. Over time, that repository of instructions becomes the most valuable part of the setup.

Back to blog