CLAUDE.md for Unity: A Project Instructions Template

A Unity CLAUDE.md should tell Claude Code which editor the project uses, which assets it may change, how to verify its work, and what needs a person’s review. Start with the template below, replace its example paths with your own, and remove any instruction you cannot verify.

Keep gameplay decisions and unfinished bugs outside the instruction file. fenbs can hold those changing details so the next connected assistant sees the approved design and the remaining work. The file can then stay focused on how to work safely in this particular Unity repository.

What should you check before filling in the template?

Inspect the repository before asking Claude to draft instructions. Find the recorded editor version, package manifests, existing test assemblies, and any team build scripts. Confirm those details with someone who can open and run the project. A plausible command is not a verified command.

Write down the supported target platforms and the scope of the current task. A change to shared gameplay logic has different review needs from an editor-only utility. Also identify where your team keeps source art, generated files, and assets maintained by outside packages. Do not assume every folder under Assets is open for editing.

• Editor: the exact installed version that opens the project without an upgrade.
• Packages: the project’s chosen rendering, input, networking, and test packages, when relevant.
• Allowed paths: the code and test folders the assistant may edit for normal tasks.
• Restricted paths: scenes, prefabs, source art, package files, or settings that need explicit approval.
• Verification: commands or editor steps someone has actually run successfully.

Anthropic describes CLAUDE.md as project instructions in its Claude Code memory documentation↗ (opens in a new tab). For the general file format, use our CLAUDE.md guide; this page focuses on the Unity details worth putting inside it.

What can you copy into a Unity instruction file?

This is an example for a small game whose team wants code changes reviewed separately from scene and prefab changes. The paths are illustrative. Replace the entire verification section with your real workflow rather than leaving instructions that merely sound complete.

# Unity project instructions

## Start here
- Read ProjectSettings/ProjectVersion.txt and Packages/manifest.json.
- Use the project editor version; do not upgrade it or packages.
- Inspect existing code and test patterns before changing them.

## Normal change boundaries
- Gameplay code: Assets/Game/Scripts/.
- Tests: Assets/Game/Tests/.
- Ask before editing scenes, prefabs, render settings, or source art.
- Do not edit generated caches or third-party package contents.
- Keep unrelated asset and settings changes out of the change.

## Asset handling
- Preserve existing asset IDs and matching .meta files.
- Do not recreate metadata to silence a missing-reference problem.
- Explain any required asset move before making it.

## Code conventions
- Follow the nearest existing component and assembly patterns.
- Keep runtime code separate from editor-only code.
- Do not change serialized field names without a migration plan.
- Keep public behavior unchanged outside the requested task.

## Verification
- Use the verified test procedure documented by this repository.
- Report Edit Mode and Play Mode results separately.
- List the scene, platform, and manual steps actually checked.
- If the editor or a required test is unavailable, report that gap.

## Review and handoff
- Summarize changed code, assets, and settings separately.
- Include reproduction steps for the original bug and the result.
- Save current task progress in the shared project record.
- A person approves gameplay or art direction changes.

Read it as a reviewer would. Could a new teammate find each named path? Does “ask before” match the access you have actually granted? Is there an obvious way to tell whether a task passed its checks? If an instruction depends on private knowledge, supply the missing reference or rewrite it.

Do not turn the file into a tutorial on C#. Keep the conventions that differ from the surrounding code or prevent a known project mistake. Our CLAUDE.md examples offer other instruction patterns when you need a different starting shape.

Which asset boundaries deserve explicit instructions?

Unity assets carry relationships that a text change may not reveal at a glance. Unity’s asset metadata documentation↗ (opens in a new tab) explains that .meta files hold asset identifiers and import settings. Losing or regenerating those identifiers can break references. Make preservation of the asset and its metadata an explicit review concern.

Your rule should identify the permitted action and the review needed. For example: an assistant may edit a movement calculation in a script, but a person must approve changes to the player prefab. That boundary makes the task easier to assess than a broad instruction to improve the player system.

Serialized data means information Unity saves with components and assets. If the requested code change could affect existing saved values, require a migration explanation and a representative scene check. This is a proposed review policy for your template, not a claim that every field rename behaves identically.

Keep the human reason for those restrictions in fenbs Decisions and rules. “The level designer must review player-prefab changes because three levels override its values” gives a later assistant more useful context than an unexplained prohibition.

How should the template describe tests and editor checks?

Separate code checks from game checks. Unity’s Test Framework documentation↗ (opens in a new tab) distinguishes Edit Mode tests, which run in the editor, from Play Mode tests, which can exercise game behavior in the editor or a player. Use the documentation for the package version your project actually installs.

Write down which existing tests matter to the change and how to run them. Then describe the small manual check needed for behavior that tests do not cover. For a jump bug, that could be the scene to open, the input sequence, and the expected landing behavior. A successful compilation alone does not demonstrate that result.

If your team uses command-line verification, copy its working script rather than generating a universal Unity command. Unity publishes editor command-line arguments↗ (opens in a new tab), but your executable path, project path, installed modules, and build method still belong to your environment. Record a failed launch separately from a failing game test.

• Evidence: the command or editor action, the result, and the relevant log or test output.
• Coverage: which scene, input path, and platform were checked.
• Limitations: any missing editor, package, device, or manual review.
• Remaining work: the exact next check another person or assistant should perform.

Where should gameplay changes and handoffs live?

The instruction file should explain how the team evaluates a gameplay change. It should not contain every proposed jump height, balancing experiment, or unresolved collision bug. Those details change as the game changes and need a current task, evidence, and a decision owner.

Say a designer approves keeping the dash distance while changing its recovery time. Save the approved choice with the task and say which result is still untested. The next session can work from that record instead of finding an old experiment written as a permanent instruction.

How to do this with fenbs

1. Create a free account, then add your game as a project on your kanban board.
2. Record the human-approved asset boundaries and gameplay choices in Decisions and rules. Keep suggestions open until a person chooses.
3. Add a task for the actual Unity change, with its plan and the scene or test that will demonstrate success.
4. Connect Claude Code using the integration guide, then ask it to read the project context before using the repository template.
5. Save what changed, what was tested, and what the next session must check in Where we left off.

fenbs does not run the Unity editor or inspect your game automatically. If all you need is a static instruction file for one repository, that file may be enough; the shared record helps when decisions, bugs, and handoffs need to survive across sessions or assistants.

Start with one bounded change and review the resulting file changes. If the assistant opens the wrong asset or reports an unrun check as complete, correct that specific instruction. Our CLAUDE.md troubleshooting guide covers instruction failures, and the AI prompts hub collects related guides.