In the previous Beginner’s guide to Unity CLI and the Pipeline package article, I introduced the Unity CLI and Pipeline package, explained how they replace the click-driven layer of the Editor with a local HTTP server, and how to get a basic Claude Code session talking to a running Editor instance. We also covered 20 useful CLI commands in another article, to help speed up your daily workflows, in case you missed it.
Unity CLI supports a wide variety of LLMs, including Codex, Gemini, and GitHub Copilot, as well as many other tools. In this article, I’ll primarily focus on two of the most popular options at the time of writing: Claude Code and Codex. That said, many of these tips apply across the other tools as well, just as most of these techniques are broadly useful for software development workflows outside of Unity.
As a quick disclaimer, things are moving fast, and best practices change all the time. There is no one right way or one-size-fits-all approach to solving this, so these tips are based on workflows that work for me; use what you like and leave the rest behind.
All right, let’s dig in.
Provide context to your agents
If you don’t provide context, chances are you’ll get generic answers. Obviously, the best context you can give is a rich, mature codebase; but if you’re in the early phases, that won’t say much about your preferences, and starting with a solid foundation shapes what the codebase eventually becomes. AI coding agents start each session with an almost blank slate (depending on how much persistent “memory” they’ve accumulated based on your other work), but they don’t have to. You can give them a set of instructions that are “injected” into the context window of every session. In the case of both Claude and Codex, you can use the initialize command to create an agent file:
# Use this in Claude Code or Codex to initialize your project and create a CLAUDE.md (Claude) or AGENTS.md (Codex) file
/init
This creates a CLAUDE.md file for Claude Code or an AGENTS.md file for Codex.
Think of these files as persistent project instructions and onboarding documents. They help agents understand your architecture, coding conventions, and preferred workflows without requiring you to repeat that information at the beginning of every session. If you’re using both Codex and Claude Code, AGENTS.md can also serve the same purpose for Claude, if you just instruct it to reference the AGENTS.md. Then you can simply use CLAUDE.md for any specific Claude instructions.
The initialization process will generate a good starting point out of the box, but you should expand on that and fill in the gaps. A good set of instructions ensures that the agent understands aspects of your project’s architecture, tech stack, and coding conventions that aren’t self-explanatory from the code. Your instructions should also contain any “non-negotiable” behavioral rules you want to enforce. You don’t need to tell the agent to write clean code or follow best practices; instead, focus on specific preferences. For example, you might prefer uGUI with an MVP pattern over UI Toolkit. Or you might want to avoid singletons and expose data in the Unity Inspector window using [SerializeField].
Think of these instructions as sitting a new developer down on their first day and giving them a handbook that explains how your specific project works and that clarifies your decisions, thus removing any guesswork on their part.
Both Gemini CLI and GitHub Copilot also support project-level context files that function almost identically to CLAUDE.md and AGENTS.md. Gemini CLI uses GEMINI.md, and GitHub Copilot uses copilot-instructions.md. From now on, I’ll just refer to the AGENTS.md file for simplicity.
Get the official plugins
If you haven’t already, make sure to install the official Unity Plugin for Claude Code and Codex. The plugin provides first-party skills maintained by Unity, covering workflows such as UI Toolkit, URP, asset management, and the Unity CLI. These skills help agents follow Unity’s recommended practices and use supported APIs. For workflows that require direct interaction with a running Unity Editor, ensure the Unity CLI and its MCP integration are configured as well.
Provide more context
I wrote a post on custom LLM instructions earlier, and the idea is similar to the agent instructions file: providing specific context on what you like and what you don’t. Consider including the following files outside of your AGENTS.md file:
CodeStyleGuide.md
In most of my projects, I like to include a code style guide as well. That might feel like overkill to some, but I find that it makes my code reviews as efficient as possible. As your codebase grows, you might also find that consistency helpful.
UnityProjectSettings.md
I also like to create a tech stack overview document combined with my default project settings, which I call UnityProjectSettings.md. You could put that inside the AGENTS.md file as mentioned above, but I prefer creating a separate document that specifies more details about my project settings.
For example, it will usually specify whether I want to use uGUI or UI Toolkit, that my render pipeline is URP, and that I prefer the new Input System over the old Input Manager to avoid writing code I’d need to refactor later. This file can also include specific instructions like using the Awaitable class rather than coroutines, or using the built-in object pooling API rather than creating a bespoke solution. I also include notes on API changes, such as instructing the agent not to use FindObjectOfType but to use `FindAnyObjectByType` instead, since I’m using the latest Unity 6 syntax at the time of writing.
GameDesignDocument.md
In some of my experiments, I’ve also included a high-level game design document detailing specific game mechanics. There are many formats for a game design document, ranging from a high-level brief to detailed requirement specifications, so pick whatever format works for you. You can also use various skills like “grill me” to flesh out specific sections depending on how much upfront detail you want. In general, it’s a good idea to specify core game mechanics upfront. For instance, having turn-based map control combined with real-time gameplay without early clarification could cause confusion when designing the architecture. If you don’t want to write full documentation, including a few sentences about that in your AGENTS.md can also solve that problem.
Skills and custom instructions
You might also have your own set of skills or additional documents that help provide context, such as a UI style guide or a spreadsheet with game balancing data. However, be careful to avoid overlapping information: strive for a single source of truth. As an example, your spreadsheet with game balancing data should only exist in one place and not be duplicated in your game design document, particularly because initial balancing data is prone to drift during development.
In my earlier projects, I created several of my own bespoke Unity skills for things like UI Toolkit. I now only use the official skills, which can easily be installed as described earlier.
The main idea here is to avoid confusing the LLM with conflicting or competing information, which wastes tokens on clarifying which document provides the correct guidance.
How to lazy-load the information
A good rule of thumb is that AGENTS.md, because it’s loaded into every session, should only hold what’s true in every session, such as the non-negotiable rules, universal code style, and pointers.
That said, it’s a balance of how much information you want to dump into the agent’s file. Including everything would make it bloated. A useful technique is to split up your documentation into multiple separate files and reference them from AGENTS.md. Anything that’s true only when working on one subsystem, running one workflow, or investigating one specific use case belongs in complementary files rather than AGENTS.md.
This creates a form of on-demand context loading. Instead of placing detailed instructions directly in AGENTS.md, you instruct the agent to read specific reference documents when particular tasks require them. Unlike native skills, which may be discovered and activated automatically, this approach relies on the agent following your instructions to load the relevant files.
Each reference costs only one line in the always-loaded file. Just make sure to be explicit about when to use it. For example: “For any game design-related decisions, please review the game design document” or “When doing code reviews, please refer to and ensure all rules in CodeStyleGuide.md are followed.” That way, the target information costs near zero tokens until there is an actual use case for the agent to read it.
Trim your AGENTS.md and docs
Up until now, the advice has been about adding more context. As your project expands, so should your reference docs, which should live and evolve alongside your project. You might already have a workflow that automatically updates agent files, but it’s a good idea to continuously trim them to ensure your documentation reflects the current state of your project, as well as to update your game design document so it reflects your active intent. If your agent files start drifting, so will your codebase and token consumption. Make sure to bake this review process into your workflow.
I regularly do a “mini project review”, asking Codex or Claude to review the codebase and project documentation to ensure my code follows the style guide, tighten up documentation files, and add new rules or gotchas as needed. Because I do this often, I developed my own custom skill that checks all these rules.
Similarly, when an agent makes a mistake twice, simply ask what went wrong and add a rule to AGENTS.md to prevent it from happening again.
Agent instructions are useful for establishing conventions, but they aren’t a substitute for automated enforcement. Where possible, back up rules with tooling such as .editorconfig, analyzers, and automated code checks. That way, the agent receives objective feedback when its output deviates from your standards.
Disable what you don’t need
The same applies to the MCP connectors, plugins, and skills you have installed. Providing the right context is a balancing act where you don’t want to flood the context window with irrelevant information.
While it might be convenient to have everything installed, trimming down to focus on just what you need saves tokens over time and removes ambiguity if you have overlapping skills. In Claude, you can run the command /context in a fresh new session to get an overview of your token consumption.
Be selective with the external tools you connect (like GitHub, Google Drive, Slack, or Notion) via MCP or plugins. Depending on the agent and integration, connected tools and plugins may consume context through their definitions, descriptions, and instructions. Skills are often designed to load their detailed instructions only when relevant. While this reduces the initial context overhead, maintaining a focused set of tools and skills can still improve tool selection, reduce ambiguity, and avoid unnecessary complexity.
External connectors can also introduce irrelevant information when agents retrieve more data than a task requires. Limit retrieval to relevant sources and avoid granting access to tools that aren’t needed. The goal is to help your agent pick the right tools and avoid off-topic actions, so disable plugins you don’t need to keep the context clean.
Similarly, if you have defined “dos and don’ts” in your agent file, modern reasoning models respond more effectively to positive intent (“do X because of Y”) rather than rigid negative constraints (“never do X”). When you explain the intent, the LLM is better equipped to make sound micro-decisions aligned with your context.
Check the doctor
Running diagnostic checks periodically is a useful habit, particularly after major updates. Unity CLI provides unity doctor to check its environment and configuration, while Claude Code offers /doctor for diagnosing installation issues. Codex also provides troubleshooting options, although the available commands depend on the interface and version you’re using.
Another simple trick is to ask the LLM what it has observed over past sessions and whether there are insights that should be added to relevant files or acted upon. That said, I keep a close eye on any changes to AGENTS.md (never approve changes blindly) to keep it under control. When to do this depends on the scope of your changes, but if you’re refactoring or making architectural decisions like adopting dependency injection, this is a great way to identify impact.
Be careful of overlapping skills
If you were experimenting with custom skills before the official skills became available, make sure to check for potential overlaps. As an example, I had been working on custom UI Toolkit skills for a while, but the official skills also cover UI Toolkit and uGUI, rendering my custom set redundant. To avoid bloating the context window or introducing conflicting instructions that compete to be the source of truth, I now stick exclusively to the official plugins. If there are niche instructions not covered by the official skill, or something specific needed for your workflows, simply add them to your project configuration document instead.
Strengthen your prompts
There are a lot of opinions on effective prompting techniques and advice varies widely.
However, there is general consensus that effective prompts rely on a solid foundation of relevant files, technical documentation, error logs, and project constraints (such as architecture or style guides). With custom instructions in place and a clean context window, your prompts will already have a strong baseline.
There are a few easy wins to improve most prompts. Directly referencing relevant assets or scripts using precise file paths or @ file references where supported reduces guesswork and can prevent agents from unnecessarily scanning large project directories or misinterpreting your instructions. That makes your workflow far more efficient. You can also attach screenshots, logs or performance data as an appendix to your prompts to pinpoint specific issues.
Stay at the wheel, but don’t micromanage
While older LLMs performed best with step-by-step instructions, newer models require much less micromanagement and navigate ambiguous requirements far more effectively when provided with the core rationale. Providing the intent behind an instruction empowers the model to make sound micro-decisions. For example, rather than prompting “Add a stamina cost to player sprinting”, try “Add a stamina cost to player sprinting to force the player to make tactical choices about when to run or conserve stamina during combat.” Explaining your intent allows the LLM to choose underlying architectural decisions that support your overall goal and provide better recommendations.
Even though recent models perform well with minimal direction, agents can still stumble, and course-correcting after a mistake can get expensive. A lack of proper context may lead an agent to misread your intent, omit unstated requirements, or rely on unintended assumptions. Writing initial code is cheap, but fixing and maintaining it grows costly as the project scales. Spending a moment to refine and pressure-test your prompt upfront pays off significantly compared to reactively fixing issues later.
If you’re working on open-ended or long-running tasks, ensure you set a concrete goal with a clear “Done When” verification criterion. For example: “A sound effect plays on item pickup, and a floating text indicator displays ‘+25 HP’”. Establishing explicit exit criteria prevents the agent from running into endless loops.
Don’t be shy to talk to your LLM
If you prefer speaking to typing, try voice dictation. Depending on your platform and coding agent, you may have access to built-in dictation or can use operating-system features such as macOS Dictation. Third-party dictation tools (like Wispr) are another option.
Speaking can be 2–3x faster than typing, and LLMs excel at filtering out conversational fluff from dictation during brainstorming sessions, so don’t worry about making a perfect prompt. Some also find that speaking rather than writing can help bypass the self-censorship that often gets in the way of including context that is actually relevant.
“Claude, make no mistakes”
You might have seen the “make no mistakes” memes. Modern reasoning models already perform substantial internal reasoning and self-correction, so generic instructions such as “think step by step” or “double-check everything” don’t necessarily improve results. Instead, define concrete verification steps: compile the project, run relevant tests, inspect errors, or confirm that the implementation satisfies your acceptance criteria. Evidence-based verification is generally more useful than asking the model to reconsider its answer without additional information.
Use Plan Mode
Both Codex and Claude Code offer a dedicated Plan Mode. Using Plan Mode before executing code on major tasks is a great way to break down complex problems into manageable steps. Most importantly, Plan Mode establishes a useful checkpoint where you can review the proposed implementation before authorizing changes. This reduces the risk of an agent making architectural decisions or modifying unrelated systems before you’ve agreed on the intended approach.
Plan Mode also helps define clear exit criteria and stopping points. If a model tends to over-deliver or refactor unrelated code, use Plan Mode to set explicit boundaries such as restricting edits to specific files or breaking tasks into phases that pause for review after each core milestone.
In my workflow, I create a plan subfolder named `Implemented` and enforce a rule that completed plans are moved there to keep project directories organized.
Ask the agent to interview you
A popular technique I also often use is asking the model to “interview me regarding any open questions” before executing prompt instructions. It’s a great way to pressure-test assumptions that might not be immediately obvious. You can also leverage community skills like the popular grill me skill. The goal is to prompt the model to query you for missing requirements so you can make informed decisions upfront rather than leaving the LLM to guess. Matt Pocock, author of the skill, describes it well: “Grilling helps us through the invisible step of closing the communication gap between you and your agents. It helps you avoid subtle misalignments and misunderstandings that good engineering practices are designed to prevent.”
The interview process works particularly well for complex tasks. After enabling plan mode and describing your project goals, ask the agent to interview you to build a clear blueprint before generating any code.
For complex, multi-step tasks, you can also define measurable completion criteria that allow the agent to iterate until tests pass or a target is reached. Where supported, goal-oriented workflows let an agent continue working toward a persistent objective across multiple iterations. You can achieve a similar approach in other agents by providing explicit success criteria, maintaining a persistent plan, and instructing the agent to iterate until the objective is met or it encounters a blocker.
Picking the right model
While it’s easy to default to top-tier models, not every task requires the most capable model. Faster, lower-cost models are often sufficient for straightforward edits, small refactors, documentation, and routine questions. More capable reasoning models can be worthwhile for architectural decisions, complex debugging, and multi-file changes. Experiment with the models available in your preferred agent and choose based on the complexity and risk of the task.
You can also adjust the reasoning effort setting. Effort settings control thinking volume (the depth of reasoning performed), not output length. Lower reasoning effort settings can reduce latency and token consumption on simpler tasks, while higher settings may improve performance on problems requiring more extensive reasoning. So consider reserving High or Extra High effort settings for complex multi-file tasks. Monitoring token consumption across sessions will reveal significant cost savings over time.
The Architect-Builder Pattern
Related to model selection, another effective technique is the “Architect-Builder Pattern,” which decouples planning from implementation. You can use a high-intelligence reasoning model (such as Opus 5 or Astra) to draft high-level architectural plans, and then hand off execution to faster, lower-cost models (like Sonnet 5, Terra, or Luna) or lower reasoning levels for minor edits and bug fixes.
This pattern can reduce inference costs. The savings depend on the models, task complexity, and number of iterations required, so it’s worth monitoring actual usage rather than assuming cheaper models always produce lower total costs.
Testing
Manual testing can quickly become repetitive and error-prone. Fortunately, LLMs are great at writing and executing automated tests. Automated testing provides objective feedback that agents can use to verify their changes. This can reduce costly debugging iterations because failures are identified earlier and reported in a structured format.
After Claude Code or Codex modifies a script, running the relevant tests helps identify regressions before you continue. You can instruct your agent to run tests after making changes or automate the process through scripts, hooks, or continuous integration depending on how much complexity you need. Without automated tests, you often rely heavily on manual playtesting and runtime diagnostics to identify regressions. With tests, you get an instant pass/fail report that you can feed back to the agent to fix failing cases.
There are many approaches to testing, ranging from running no tests to enforcing Test-Driven Development (TDD) and the needs are obviously different from a solo developer hobby project to full scale game productions. Finding the right balance on testing tactics and test coverage is obviously a matter of personal opinion, but in general, you should consider covering some of the basics even for small hobby projects.
Unity includes a testing solution called the Unity Test Framework (also known as the “Test Runner”), available as a package. If you’re not already familiar or just need a refresher, it allows you to test your project code in both Edit mode and Play mode across target platforms.
EditMode tests run without entering Play mode. EditMode tests are faster and ideal for testing isolated logic (math, data structures, non-MonoBehaviour classes) and Editor functionality.
PlayMode tests execute in a runtime environment, either in the Editor or a supported player, and are useful for validating interactions between GameObjects, MonoBehaviours, scenes, and runtime systems. Ideally you should consider a good mix of both but start with EditMode tests as they execute faster, are simpler to write, and cover most early validation needs. Once the test framework and Unity CLI are set up, you can also invoke tests directly from the command line:
# Run the project’s EditMode tests using Unity CLI.
unity test . --mode EditMode
This runs every EditMode test and writes the results to results.xml, which is just a structured report of what passed and failed.
Instead of opening results.xml manually, ask your agent to execute the suite and summarize failures: “Run the EditMode tests and report any failing tests in plain English.” The agent executes the CLI command, parses the XML output, and reports key results back.
If you found a process that works for you, consider updating the AGENTS.md file with those instructions too.
Use git checkpoints
Before starting a long-running agent task, establish a clean Git checkpoint. Commit your current work or use an isolated Git worktree so you can review changes and recover from unwanted modifications without losing existing work. You can create a branch using git checkout -b feature/agent-task and commit your current state before starting a session.
Thorough planning, clear verification criteria, and incremental steps go a long way. Being able to easily revert or fork your state avoids correction loops that compound token costs.
Communication style
In addition to code style preferences, instruct agents to follow your preferred communication style. If responses feel too verbose, ask for succinct summaries or structured formats. Structuring progress into task tables or milestone checklists makes tracking status straightforward.
If agents run in parallel or handle multiple tasks, ask them to always include a brief TL;DR recap so you can pick up context quickly across sessions.
Consider placing communication preferences in a global AGENTS.md file to maintain reusable defaults across all repositories.
Using subagents
If you haven’t already, consider creating custom subagents to handle targeted tasks without cluttering your main conversation context. You can think of a subagent as a colleague you hand a task to. Subagents operate with their own conversation context, allowing them to investigate a task independently and return a concise summary to the main agent. Depending on the configuration, they may share the same project files or work in isolated environments such as Git worktrees.
You don’t need to set anything up to start. Both Claude Code and Codex support subagents, although their configuration and delegation behavior differ. Depending on the tool and settings (including AGENTS.md), agents may delegate tasks automatically, or you can explicitly request that a subagent handle a particular task.
Split by task, not by code layer. It’s tempting to create a “UI Toolkit designer” and a “gameplay programmer,” but in Unity almost every feature touches both. Each subagent starts with a blank memory, so splitting a feature across two leads to mismatched events and fields. For expertise, use skills instead. A skill adds knowledge to the agent doing the work, while a subagent takes work elsewhere and reports back. The official Unity skills already cover UI Toolkit as an example and you can supplement with your own style guide preferences or specific guidelines as discussed earlier.
One area where subagents pay off in Unity development workflows is when running EditMode tests and returning only the failures, going through Editor logs for recurring errors, reviewing code against your CodeStyleGuide.md with fresh eyes, and handing routine chores to cheaper models like Sonnet or Haiku.
So as you notice you repeat a task often, turn it into a custom agent. It’s a small file in .claude/agents/ or .codex/agents/ with a name, a clear description, and only the tools it needs. Learn more: Claude Code subagents · Codex subagents
Starting fresh vs. compacting
As conversations grow, accumulated context can become less relevant and harder for agents to manage. Both Claude Code and Codex offer mechanisms for compacting conversation history, but summarization can lose important details. Starting a fresh session for a new task is often a simple way to maintain focus.You can also compact the conversation by summarizing or dropping older history to make room. You also have manual control over freeing up the context window by clearing history, compacting/summarizing history, or simply starting a new session.
Generally speaking, it’s often better to maintain “One Chat per Task.” Avoiding multitasking in long chat threads or continuing unrelated work in an old session prevents forcing the model into the “dumb zone” caused by constantly re-reading irrelevant historical context.
Reuse what works across projects
Rather than starting every project from scratch, establish a structured knowledge workspace (using tools like Obsidian, Notion, or a dedicated Git repo) to store reusable guidelines and project notes. A root CLAUDE.md or AGENTS.md file then acts as a central routing hub, linking to specialized context files across your repository so agents only load detailed documentation when specific subsystems are touched.
Convert repeatable workflows into reusable agent skills. These typically use a folder containing a SKILL.md file and supporting files. The SKILL.md describes the skill’s purpose, instructions, and when it should be invoked. Additional reference documents or scripts can be included when necessary. Instead of re-typing massive, complex prompts every time you run a recurring task, package your coding standards, PR review checklists, bug triage routines, and design patterns into reusable .md skill files. Keep each skill narrowly focused on a single workflow with clear input expectations and triggers. This prevents context clutter while giving your AI agents exact step-by-step blueprints to execute predictably every time.
Not every Unity task should be handled through direct file manipulation. Coding agents can safely edit many project files, such as C# scripts, documentation, and configuration files. However, operations involving scenes, prefabs, or other serialized Unity assets are often better handled through Unity’s Editor APIs or the Unity CLI. This reduces the risk of introducing invalid references or corrupting serialized project data.
Don’t be shy to ask your agent
Speaking of identifying things that overlap, what’s suitable to be a skill, or what could be optimized for performance, don’t be shy to ask the agents to check the logs or provide recommendations based on what they find. Maybe something like: “Which Unity logs or diagnostics could we review to identify errors, performance bottlenecks, or recurring warnings, and turn those findings into prioritized actions for the next project phase?”
Learn more
I hope some of these tips were useful and something you can leverage in your workflows. If you’re interested in learning more about creating your own custom instructions, make sure to check out our article here. If you’d like to learn more about customizing your own style guide, check out this GitHub repo here.
If you’re not already familiar with and using the Unity CLI and Pipeline package, check out our getting started guide here. Also, make sure to install the plugins for your favorite LLM. Let me know if you have any other tips I missed here or if you have found different workflows that work better for your needs in the comments.