Token-Saving Techniques for Using AI Efficiently in Unity Projects

Introduction

Using AI coding agents in a Unity project that is under development or already in production can significantly speed up investigation, implementation, and review.

At the same time, the larger the project gets, the more likely you are to run into problems like these:

• The agent reads unrelated directories.
• It tries to inspect generated files such as Library/ or Temp/.
• It reads huge Scene / Prefab / ScriptableObject YAML files in full.
• It consumes tokens by reading Addressables outputs or large logs.
• You have to repeat the same project explanation in every chat.
• You write too much in AGENTS.md / CLAUDE.md, and the agent starts following it less reliably.

The important part of using AI effectively is not just choosing a powerful model.

It is designing what the AI should read, and what it should not read.

This article focuses on Unity projects and summarizes practical ways to reduce token usage when using AI agents. At the end, I also include copy-paste friendly AGENTS.md and CLAUDE.md templates that can be adapted for both Unity and UE5 projects.

I Recommend Writing AGENTS.md / CLAUDE.md in English

The samples in this article write AGENTS.md and CLAUDE.md in English.

There are four main reasons.

First, most codebases are already centered around English. Class names, method names, file names, API names, error messages, and CLI commands are usually English. When instructions are also written in English, they naturally map to the names in the code.

Second, English rules are easier to reuse across multiple AI agents such as Codex, Claude Code, Gemini CLI, and Cursor. Japanese instructions also work, but English is usually safer for machine-facing team rules.

Third, English instructions are often easier to keep short. A rule like Do not edit generated files. is short and clear compared to a polite sentence in Japanese.

Fourth, it may slightly reduce context size in some cases. This does not mean English always produces dramatically fewer tokens than Japanese. It depends on the model, tokenizer, and how the text is written. Still, for short machine-facing rules, English tends to be compact and makes it easier to remove unnecessary explanation.

That said, switching to English alone will not magically reduce token usage. The bigger wins come from reducing duplication, clearly excluding directories, and avoiding full reads of large files.

So you do not need to write everything in English. Human-facing notes, internal terms, and background context can be written in Japanese or whatever language your team uses.

My recommendation is:

Write short rules that the AI must follow in English, and write supplemental explanation for humans in your team's preferred language.

However, if the team cannot confidently review English rules, forcing everything into English is risky. In practice, it is often best to keep AI-facing rules short and English, while adding human-facing background and exceptions in the language the team can maintain.

First Principle: Instruction Files Are Not Enforcement

AGENTS.md and CLAUDE.md are useful, but there is one misunderstanding to clear up first.

These files are context for AI agents.
They are not hard enforcement settings.

For example, even if you write:

Do not inspect Library/

there is no guarantee that the AI will never read Library/.

Of course, writing it is still much better than not writing it. It guides the agent's first moves and reduces unnecessary reads. But it is closer to a request or working policy than a hard rule.

If you need stronger guarantees, do not rely on instruction files alone. Combine them with layers such as:

• .gitignore
• .sembleignore
• Claude Code's claudeMdExcludes
• Claude Code hooks
• Codex sandbox / approval / config
• CI / lint / tests
• Keeping generated files out of Git in the first place

The first line of defense for token saving is .gitignore.
Unity's Library/ and Temp/, and Unreal's Intermediate/ and Saved/, should usually not be tracked by Git.

AI agents may still be able to read untracked files on the local disk, so .gitignore is not a complete blocker. But it is still very important because it keeps generated files out of search targets, indexes, and diffs.

Do Not Let AI Read Everything

The worst thing you can do in a large project is to ask the agent something vague like this:

Please look at this Unity project and fix the problem.

That is like asking a human, "Read every file in this company and improve something."
The AI will try to be diligent and search broadly, which often means reading unrelated files.

A better request narrows the search scope from the beginning:

Investigate only the input validation in the login screen.
First, use Semble to find related files, then report the candidate files and why they matter.
After that, read only the minimum necessary files.

The key is to specify the investigation target and search process upfront.

Clarify things like:

• Which feature is involved?
• Which directories should be inspected?
• Which directories should not be inspected?
• What search method should be used first?
• Is it allowed to modify files immediately?
• Should the agent report its findings before making changes?

Just making these explicit can greatly reduce unnecessary reading.

Files That Consume Tokens Easily in Unity Projects

Unity projects contain many things that are heavy for AI agents to inspect.

Common examples include:

Target	Problem
Library/	Contains a huge amount of generated data.
Temp/	Temporary files with low investigation value.
obj/	C# build outputs.
Logs/	Can be large and repetitive.
*.csproj / *.sln	Usually generated by Unity. Read only when needed; do not edit directly.
Scenes / Prefabs	YAML can become very large.
ScriptableObjects	Can become large depending on data size.
Addressables catalogs / bundles	Heavy as investigation targets.
Generated files under StreamingAssets	Often contains binaries or generated data.
Large CSV / JSON / YAML files	Full reads quickly consume tokens.

On the other hand, the places the agent should usually inspect first are often predictable.

Target	Reason
Assets/Scripts/	Main gameplay/runtime logic.
Assets/Editor/	Custom Unity Editor extensions.
Assets/Plugins/<CompanyName>/	Company-owned runtime/editor code.
Packages/manifest.json	Package dependencies.
ProjectSettings/	Unity project settings. Useful to read, but changes must be handled carefully.
*.asmdef	Assembly boundaries and dependencies.
Assets/AddressableAssetsData/	Addressables settings.

Depending on Unity and Addressables versions, AddressableAssetsData can also contain generated files. Avoid full reads of large .bin files or catalogs; prefer extraction.

Start with Semble Search

In a large codebase, even using grep or rg and then reading several files can consume a lot of tokens.

Local semantic code search can help. In this article, I use Semble as the example.

More information about Semble and related case studies is included in the References section at the end. If Semble is new to you, you may want to skim those links first.

Semble is a code search library for AI agents. It can search code snippets using natural language queries and return relevant snippets instead of entire files. It can be used through MCP, CLI, or instructions in AGENTS.md.

Its official documentation shows token reduction compared with grep + read. There is also a Japanese Zenn article that measures token usage reduction when using semble with Claude Code.

These numbers depend heavily on the repository, index targets, search queries, and how the AI agent reads results. In this article, I treat Semble as one practical way to implement search-first workflows, not as a guarantee of a fixed reduction rate.

Also, Semble is not magic. If .gitignore or .sembleignore is not configured and generated files are indexed, the search results themselves can become noisy.

Semble also has limitations:

• Bad queries return irrelevant results.
• Generated files and huge data files can pollute the index.
• You still need to inspect source files for final confirmation.
• For exact API names or identifiers, rg may be faster and more accurate.

A practical split is:

Search by meaning: Semble
Search exact strings: rg / grep
Inspect huge files: extraction scripts
Final confirmation: read only the necessary original files

A useful AGENTS.md rule is:

## Search policy

Use Semble first for semantic code search when available and suitable.
Use rg/grep only when exact string matching is needed or Semble results are insufficient.
Do not scan the entire repository without explaining why.

Write the Folder Structure in Advance

Letting the AI infer the project structure every time is wasteful.

Write a minimal folder map in AGENTS.md.

## Project layout

- `Assets/Scripts/`
  - Runtime gameplay code.
- `Assets/Editor/`
  - Unity Editor extensions.
- `Assets/Plugins/CompanyName/`
  - Company-owned runtime/editor packages.
- `Assets/Scripts/Generated/`
  - Generated code. Do not edit directly.
- `Assets/AddressableAssetsData/`
  - Addressables settings. Avoid generated binary files.
- `Packages/`
  - Unity package manifest and local packages.
- `ProjectSettings/`
  - Unity project settings.

This is enough in many cases.
You do not need to document every directory.

The important part is that the AI can quickly tell where to start and what to avoid.

What to Put in AGENTS.md / CLAUDE.md

AGENTS.md and CLAUDE.md are not full specifications.
They are work guides for AI agents.

The useful scope is roughly:

• Project overview
• Technologies used
• Important directories
• Directories to avoid
• Search policy
• Generated file policy
• Coding rules
• Work process
• Verification methods
• Things not to change

Be careful not to overfill them with:

• General explanations of the tech stack
• Long design philosophy
• Outdated specifications
• Rarely used procedures
• Detailed rules for one specific feature
• Large explanations duplicated from README

Files that the AI reads in every session should stay short.

Claude Code documentation also explains that long CLAUDE.md files consume context and may reduce instruction-following reliability. Codex also has a limit on the combined size of AGENTS.md instructions.

As a rough guide, keep the root AGENTS.md around 100 to 200 lines, and move detailed procedures to separate files.

## Playbooks

Read these only when relevant:

- `docs/ai/playbooks/addressables.md`
  - Addressables investigation workflow.
- `docs/ai/playbooks/prefab-audit.md`
  - Scene/Prefab extraction workflow.
- `docs/ai/playbooks/release-check.md`
  - Release verification checklist.

However, Claude Code's @path import expands the imported content into context when it is loaded.

Splitting files does not automatically reduce tokens.

The purpose of splitting is to improve maintainability and create a path for the agent to read details only when they are relevant.

Differences Between Codex and Claude Code

Codex primarily uses AGENTS.md.
You can combine global instructions in ~/.codex/AGENTS.md with repository-local AGENTS.md files.

Claude Code's standard file name is CLAUDE.md.
If you already use AGENTS.md, you can import it from CLAUDE.md.

@AGENTS.md

## Claude Code specific rules

Use plan mode before large refactors.
Do not run Unity Editor unless explicitly requested.

This lets you centralize shared rules in AGENTS.md and keep only Claude Code-specific rules in CLAUDE.md.

One important caveat: Codex does not have a standard local file equivalent to CLAUDE.local.md.
A file named .codex-local.md is not automatically read.

Codex instruction discovery basically loads at most one instruction file per directory. The search order is AGENTS.override.md, then AGENTS.md, then names registered in project_doc_fallback_filenames. If AGENTS.md exists in the same directory, adding .codex-local.md as a fallback name does not make it behave like CLAUDE.local.md.

Also, as its name implies, AGENTS.override.md is an override. If you place it at the repository root, it may replace the team-shared AGENTS.md at the same level rather than supplementing it.

If you want personal rules for Codex, consider this order:

• Write cross-repository personal rules in ~/.codex/AGENTS.md.
• Use CODEX_HOME if you want to separate working profiles.
• Use repository-local AGENTS.override.md only when the team has agreed on its meaning.
• For temporary personal notes, manually ask the agent to read them at the start of the session.

It is safer to separate team-shared rules from personal notes. In Claude Code, CLAUDE.local.md is suitable for that purpose.

# personal AI agent notes
CLAUDE.local.md

If you use a custom name with Codex, treat it as a fallback candidate for directories without AGENTS.md, not as an append-only supplement to an existing AGENTS.md.

Extract Large Data Instead of Reading It Directly

If you let the AI read full Scenes, Prefabs, ScriptableObjects, logs, CSV, JSON, or YAML files, tokens disappear fast.

In these cases, it is often more efficient to make the AI write an extraction script instead of reading the file directly.

For example, when investigating Prefabs, do not read the entire YAML. Use an Editor script to output only the needed information.

Target	Extracted information
Prefab / Scene	GameObject hierarchy, component list, missing references.
ScriptableObject	Type name, key fields, referenced GUIDs.
Addressables	Address, label, group, path.
Logs	Error lines, N surrounding lines, duplicate counts.
CSV / JSON	Row count, keys, problematic entries, a few samples.

A useful AGENTS.md rule is:

## Large file policy

Do not read large YAML, JSON, CSV, log, scene, prefab, or ScriptableObject files directly.

For large files:
1. Write a small read-only script to extract only relevant fields.
2. Show the script before running it when it may touch Unity/Unreal assets.
3. Do not call SaveAssets, ForceReserializeAssets, asset delete/move APIs, or import-triggering operations unless explicitly requested.
4. Write extraction output to a dedicated gitignored report directory such as `.ai-tmp/ai-extract/`.
5. Show the extraction summary.
6. Read the original file only if the summary is insufficient.

The point is to avoid saying "read everything" from the start.

Make the AI narrow the data first. For logs, that means error types and a few surrounding lines. For Prefabs, that means GameObject paths, component names, and missing references.

For extraction output, avoid Unity's Temp/. Use a project-controlled gitignored directory such as .ai-tmp/ai-extract/. Temp/ is managed by the Unity Editor and is not a stable workspace for AI-generated reports.

When running Unity Editor scripts, assume read-only by default. Investigation scripts should generally not call AssetDatabase.SaveAssets(), ForceReserializeAssets(), asset delete/move APIs, or anything that triggers reimport. It is also useful to confirm that the Git working tree is clean before running such scripts.

Do Not Edit Generated Code Directly

API clients, master data definitions, localization definitions, Protocol Buffers, and C# outputs from internal tools are overwritten the next time they are generated.

## Generated files

Do not edit generated files directly.

Examples:
- `Assets/Scripts/Generated/`
- `Assets/Plugins/CompanyName/Generated/`
- `*.g.cs`
- `*.generated.cs`

If a generated file has a bug, fix the generator or template instead.

Just stating "fix the source generator instead" prevents many accidents.

Ask for Findings Before Changes

If you let the AI immediately modify files, it may touch unrelated code.

For larger tasks, make the process explicit:

## Work process

For non-trivial tasks:

1. Search relevant files first.
2. Report the files you plan to inspect.
3. Summarize the current behavior.
4. Propose the smallest safe change.
5. Modify only the necessary files.
6. Run the relevant verification command if available.

This allows a human to check the search scope.

In Unity, one feature can involve Runtime code, Editor tools, Addressables, ScriptableObjects, and Prefabs at the same time.
Asking the agent to report where it will look first reduces both unnecessary reading and incorrect edits.

Keep Changes Small

AI agents sometimes try to clean up extra things while solving a task.
That can be a problem in production projects.

Unrequested refactoring increases review cost.

## Change policy

Keep changes minimal.
Do not perform broad refactors unless explicitly requested.
Do not change public APIs unless required.
Do not reformat unrelated files.

Making "minimal changes" a rule keeps reviews manageable.

Write Verification Commands

If you ask the AI to "verify it" without defining how, the result will be vague.

Write project-specific verification methods.

## Verification

Prefer the smallest relevant verification.

Examples:
- Run EditMode tests from Unity Test Runner.
- Run PlayMode tests only when the change affects runtime behavior.
- Run Unity batchmode tests when available.
- Run .NET tool tests with `dotnet test` only for standalone tool projects.

If verification cannot be run, explain what should be checked manually.

If your project runs Unity Test Runner from the command line, include the actual command.

Unity batchmode example:

`Unity.exe -runTests -batchmode -projectPath . -testPlatform EditMode -testResults TestResults.xml`

Unity Test Framework examples for -runTests do not include -quit. -quit is often used in normal batchmode build commands, but it is safer not to mix it into test execution examples.

Unity CLI execution differs by environment. Use your team's actual command rather than treating article snippets as universal. Unity.exe is a Windows example; real commands depend on Unity Hub installation paths, OS, CI image, licensing, and -logFile handling.

Keep Personal Notes Out of Git

Separate team-shared AGENTS.md / CLAUDE.md files from machine-local personal notes.

In Claude Code, you can use CLAUDE.local.md and add it to .gitignore. It is a good place for local paths, personal commands, and temporary investigation notes.

Codex does not have a standard local supplement equivalent to CLAUDE.local.md. For personal Codex rules, prefer ~/.codex/AGENTS.md. Use AGENTS.override.md only when the team agrees on its meaning, because it may replace the same-level AGENTS.md rather than supplement it.

CLAUDE.local.md

Unreal Engine Notes

The same idea applies to UE5.
Separate what the AI should inspect from what it should avoid.

Prefer reading:

Source/
Config/
Plugins/*/Source/
*.Build.cs
*.Target.cs
*.uproject
*.uplugin

Avoid by default:

Intermediate/
Saved/
DerivedDataCache/
Binaries/

.uasset and .umap files under Content/ are not useful as raw text.
For Blueprint or Map investigation, extract the necessary information through Asset Registry, Editor Utility, Python scripts, or C++ helper commands before giving it to the AI.

UE contains even more binary assets than Unity, so it is especially important to think in terms of extracting information through the editor rather than asking the AI to read files.

The Chat Prompt Still Matters

Even with a good AGENTS.md, vague chat instructions reduce the effect.

Investigate the NullReferenceException that appears during Unity startup.
First, use Semble to find likely initialization code.
Do not read the full log. Check only the error and 5 surrounding lines.
Before changing anything, report possible causes and the files you plan to modify.

Good requests include the target feature, first search method, things not to read, and a request to report before modifying.
The important part is not prompt elegance. It is scoping the investigation.

Minimum Checklist

Before publishing or introducing this workflow to a project, check at least:

• .gitignore
• directories to read and avoid
• generated file policy
• large-file extraction policy
• verification methods
• separation of personal notes

Even this alone can greatly reduce wasteful AI reads.

Summary

Reducing token usage in AI agents is not just about choosing the right model.

The important part is designing what information the AI reads.

• Keep generated files out of version control with .gitignore.
• Write search policies in AGENTS.md / CLAUDE.md.
• Understand that instruction files are context, not enforcement.
• Use search tools such as Semble first.
• Extract summaries from huge files instead of reading them directly.
• Ask for findings before changes.
• Keep changes small.
• Define verification methods.

Unity projects contain many files that are expensive for AI agents to read.
That is exactly why not letting the AI read everything is so effective.

Finally, here are general-purpose templates for Unity and UE5.

The following section intentionally repeats some of the article in a copy-paste friendly form. It is kept as an independent template so it can be pasted into real projects.

Do not use everything blindly. Delete what you do not need. Unity-specific and Unreal-specific sections are placed at the bottom of AGENTS.md; for a Unity-only project, delete the Unreal section, and for an Unreal-only project, delete the Unity section.

---

Copy-Paste AGENTS.md

# AGENTS.md

## Language
- Prefer short English for machine-facing rules.
- Use a language the team can review and maintain.
- Reply to users in the language they use.

## Project overview
- This is a game development project using Unity and/or Unreal Engine.
- Prioritize small, safe, reviewable changes.
- Do not perform broad refactors unless explicitly requested.

## Core rules
- Do not read the entire repository by default.
- Search first, inspect only relevant files, then propose the smallest safe change.
- Instruction files are guidance, not enforcement.
- Use `.gitignore`, tool settings, hooks, tests, and CI for hard guarantees.

## Search policy
- Use Semble first for semantic code search when available and suitable.
- Use `rg` / `grep` for exact symbols, APIs, errors, and paths.
- Do not scan the entire repository without explaining why.

## Workflow for non-trivial changes
1. Search for relevant files.
2. Report candidate files and why they matter.
3. Inspect only necessary files.
4. Summarize current behavior.
5. Propose the smallest safe change.

## Avoid by default
Do not inspect these unless explicitly requested:
- `.git/`, `.vs/`, `.idea/`, `.gradle/`
- `node_modules/`, `dist/`, `build/`, `Build/`, `Builds/`
- `logs/`, `MemoryCaptures/`
- `.ai-tmp/`, except report files created for the current task

## Large files
Do not read large YAML, JSON, CSV, logs, scenes, prefabs, ScriptableObjects, `.uasset`, or `.umap` files directly.
- Create a small read-only extraction script or command first.
- Show the script before running it when it may touch assets.
- Do not save, reserialize, delete, move, reimport, or modify assets unless explicitly requested.
- Write reports to `.ai-tmp/ai-extract/`.
- Read only the generated summary first.
- Read raw files only if the summary is insufficient.

## Generated files
- Do not edit generated files directly.
- Examples: `**/Generated/**`, `*.g.cs`, `*.generated.cs`, generated API clients, data loaders, localization files, protobuf/message files.
- If generated output has a bug, fix the generator, template, or source data instead.

## Coding policy
- Follow existing style.
- Keep changes minimal.
- Do not reformat unrelated files.
- Do not change public APIs unless required.
- Do not introduce new packages without approval.
- Prefer readable code over clever code.

## Verification
- Run the smallest relevant verification when possible.
- Use the project's actual commands rather than generic examples.
- If verification cannot be run, explain why and what should be checked manually.

## Reporting
When making changes, report:
- files inspected
- files changed
- reason for each change
- verification performed
- verification not performed
- remaining risks

## Platform-specific sections
Unity and Unreal Engine rules are intentionally placed at the end.
Delete the section that does not apply to your project.

## Unity policy
Prefer reading:
- `Assets/Scripts/`
- `Assets/Editor/`
- `Assets/Plugins/<CompanyName>/`
  - Treat third-party plugins and purchased assets as read-only unless explicitly requested.
- `Packages/manifest.json`, `Packages/packages-lock.json`
- `ProjectSettings/`
  - Read when relevant, but change only with explicit intent and explain the diff.
- `Assets/**/*.asmdef`

Avoid unless explicitly requested:
- `Library/`, `Temp/`, `temp/`, `obj/`, `Obj/`, `Logs/`, `UserSettings/`
- `*.csproj`, `*.sln`
  - Usually generated by Unity. Read only when needed; do not edit directly.
- `Assets/StreamingAssets/aa/`
- large generated Addressables files, bundles, catalogs, and binary outputs

For serialized assets, extract path, GUID, GameObject path, component type, serialized fields, missing references, and Addressables address/group/labels.
Verification examples: EditMode tests, PlayMode tests, Unity batchmode tests without adding `-quit` to `-runTests`, project-specific validation scripts.

## Unreal Engine policy
Prefer reading:
- `Source/`
- `Config/`
- `Plugins/*/Source/`
- `*.Build.cs`, `*.Target.cs`, `*.uproject`, `*.uplugin`

Avoid unless explicitly requested:
- `Binaries/`, `Intermediate/`, `Saved/`, `DerivedDataCache/`

Do not treat `.uasset` or `.umap` files as readable source.
For Blueprint, Map, Asset, or Content analysis, extract metadata through Unreal Editor, Asset Registry, Editor Utility, Python, or C++ helper scripts.
Verification examples: build the affected target, run relevant automation tests, run project-specific validation scripts.

Copy-Paste CLAUDE.md

@AGENTS.md

# CLAUDE.md

## Claude Code specific rules
- Use plan mode before large refactors or multi-file changes.
- Do not run Unity Editor or Unreal Editor unless explicitly requested.
- If an editor command is necessary, explain the command and expected impact first.
- Prefer Semble or narrow searches over broad Read/Grep/Glob operations.
- For large files or asset investigation, use read-only extraction and read the summary first.

## Context management
- Keep this file short.
- Put long task-specific procedures in separate files and read them only when relevant.
- `@path` imports help maintainability, but imported content is still loaded into context.
- Do not import large files unless they are needed in every session.

## Personal notes
- Use `CLAUDE.local.md` for personal, machine-specific notes.
- Do not commit `CLAUDE.local.md`.

References

• OpenAI Codex: Custom instructions with AGENTS.md https://developers.openai.com/codex/guides/agents-md
• Claude Code: Memory / CLAUDE.md https://code.claude.com/docs/en/memory
• Claude Code: Hooks reference https://code.claude.com/docs/en/hooks
• Unity Docs: Recommended ignore configuration for Unity projects https://docs.unity.com/unity-version-control/ignore-files
• Unity Docs: Running tests from the command line https://docs.unity.cn/Packages/com.unity.test-framework%401.4/manual/reference-command-line.html
• Unreal Engine Documentation: Directory Structure https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-directory-structure
• Semble official documentation https://minish.ai/packages/semble/introduction/
• Semble GitHub https://github.com/MinishLab/semble
• Zenn: Claude Code のトークン削減を実測した — semble 93%・cacheRead 1800倍の内訳 https://zenn.dev/pepabo/articles/claude-code-token-reduction-measured