Building a Solid CLAUDE.md for Unity Projects

It's all starts with /init

Having a great CLAUDE.md file is important for Claude to be efficient and perform the best work possible.

If you haven’t yet setup an MCP in Unity, check out my previous post (https://devinreimer.substack.com/p/using-claude-with-unity-basic-setup)

One of the first things you should do when starting to use Claude is to run /init.

This will get Claude to climb through your project and build a document of information about your project setup, programming style, conventions, etc.

After it is created, I recommend giving it a read (it is located in the root of your Unity project - CLAUDE.md) as reading this file will give you some great insight into how Claude is understanding your project and any holes in knowledge that might be important.

Throughout our development at AstroBeam we’ve encountered some issues with how Claude wants to interact with our projects. Things that might work fine for a non-Unity project, but can cause issues or struggles within a Unity project.

Here are a few of the issues we have encountered and some Claude.md lines to fix them. This is a list of issues and solves, if you want all the changes scroll to the bottom for a complete list.

Dealing with Claude temporary editor scripts

Issue:
Claude often likes to generate large editor scripts to build complex gameobject/components setups. While we generally prefer it to use MCP calls, sometimes creating an editor script with all the commands is more efficient. The problem is these scripts get added to your project and if you aren’t careful will also be committed.

What can happen is in the future if you request a related change Claude may just change the editor script and re-run it. In Unity, this can be a big issue because any changes made to these items(prefabs/gameobjects) from the Unity editor will be blown away. To make matters worse, noticing the errors can be difficult as they are often within prefabs.

Solve:
Create a folder called TemporaryGeneratedScripts within the root Editor folder in Unity. Then tell Claude to place any temporary editor scripts there and to delete them as part of the last step. That way even if the delete doesn’t happen you will know not to commit them and can delete them yourself.

Our Claude.md fix:
- Any temporary editor scripts (ex: building gameobject structures) should be placed in Editor/TemporaryGeneratedScripts and then deleted as your last step

Claude sometimes loves YAML and not using MCP

Issue:
Claude sometimes decides the best approach is to edit YAML files directly. As anyone that has worked with YAML files knows this is a dicey proposition. We’ve often seen Claude making mistakes including messing up IDs.

Solve:
Instruct Claude to use MCP calls or create a temporary editor script for high volume changes (mentioned above)

Our Claude.md fix:
- Use MCP to create or modify gameobject/prefabs, never edit YAML directly. Only if there are a large volume of changes create a temporary editor script

Claude not following all our best practices

Issue:
There are some best practices for us Claude wasn’t following

Solve:
Write specific rules for each one. Note: these are subjective.

Our Claude.md fix:
- Avoid using GetComponents or GetChild use references to SerializedFields instead
- Events use `= delegate { }` initialization to avoid null checks
- If you are null checking and the result of failure is a bad outcome do a Debug.LogError so it doesn’t fail silently
- Never suppress warnings using #pragma warning disable CS0414 fix instead

Claude not finishing work

Issue:
Sometimes Claude would do almost all the work and then explain to the user the steps remaining for them to do manually within the Unity editor. As it has access to a Unity MCP, it should just do them itself. Additionally, due to visuals within Claude Desktop it is often hard to see when Claude is done or still thinking (I hope they fix this).

Solve:
Explain to Claude that it should complete all work using MCP for editor setup and add a line for Claude to explain when it is done.

Our Claude.md fix:
- Don’t ask the user to manually setup things in the editor, just do it with MCP
- Say done as the last thing when completing a long process

---

All of it together for CLAUDE.md

- Any temporary editor scripts (ex: building gameobject structures) should be placed in Editor/TemporaryGeneratedScripts and then deleted as your last step
- Avoid using GetComponents or GetChild use references to SerializedFields instead
- Use MCP to create or modify gameobject/prefabs, never edit YAML directly. Only if there are a large volume of changes create a temporary editor script
- Don’t ask the user to manually setup things in the editor, just do it with MCP
- If you are null checking and the result of failure is a bad outcome do a Debug.LogError so it doesn’t fail silently
- Events use `= delegate { }` initialization to avoid null checks
- Say done as the last thing when completing a long process
- Never suppress warnings using #pragma warning disable CS0414 fix instead

What are some of the useful CLAUDE.md additions for your unity projects? Leave comments below.