AI coding tools are impressive in a clean demo and much less impressive inside a Unity project that has been shipping for years. The difference is usually not the prompt. It is the context surrounding the prompt. After 16 years in game development, I have learned that production work depends on assumptions scattered across scenes, prefabs, packages, build settings, naming conventions, and platform requirements. An AI assistant cannot respect information it cannot see. This article is not about adding a chatbot to an NPC or sending player text to a model. It is about context engineering: organizing a real Unity project so an AI assistant can make useful, reviewable changes without turning your repository into an experiment.
Key Takeaways- AI output is only as reliable as the project context supplied with the task.
- Small tasks with explicit acceptance checks outperform broad feature requests.
- Unity versions, package versions, scene ownership, and serialization rules must never be left to guesswork.
- Automated tests convert plausible AI suggestions into evidence.
- Measure accepted changes and review cost, not generated lines of code.
Why Does AI Struggle With Real Unity Projects?
Most AI coding failures I see are not failures of syntax. The generated C# compiles, the class names look sensible, and the explanation sounds confident. The failure appears one level deeper. The code assumes the wrong input system, modifies a prefab that should be treated as a template, calls an API unavailable in the installed package version, or creates a second architecture beside the one already in production. These are context failures disguised as implementation failures.
Unity makes this problem especially visible because the project is larger than its scripts. Important behavior can live in scenes, prefabs, ScriptableObjects, animation controllers, physics layers, tags, package manifests, quality settings, and platform-specific configuration. A model shown three C# files may produce a reasonable answer for those files while remaining completely unaware that a serialized event in a prefab depends on the method it wants to rename.
I learned to respect hidden dependencies long before modern coding assistants appeared. Eagle Flight Arcade, which I shipped as a Gameplay Programmer at Ubisoft Montreal in 2016, targeted PSVR, Oculus Rift, and HTC Vive. Even without discussing its internal architecture, that platform matrix illustrates the point. A change that appears local can interact with input, performance, comfort, hardware behavior, and build configuration. Production knowledge rarely fits inside one source file.
My first question for an AI task is therefore not whether the model can write the code. I ask whether it has enough evidence to understand the job. If the answer is no, I improve the evidence before refining the prompt. I provide relevant file paths, Unity and package versions, architectural boundaries, expected behavior, and known risks. A shorter request with the right project map is more valuable than a clever paragraph full of motivational instructions. Context engineering begins by making the invisible parts of the project visible.
What Should an AI-Readable Unity Project Brief Contain?
A useful project brief should explain the repository the way I would explain it to a developer joining for a focused task. It does not need to document every class. It needs to identify the decisions that must not be reinvented. I usually begin with the Unity editor version, render pipeline, supported platforms, input solution, major packages, assembly layout, testing approach, and the directory boundaries between runtime code, editor code, samples, and third-party dependencies.
The next layer describes architecture in plain language. Which system owns game state? How do scenes transition? Are services found through dependency injection, explicit references, static access, or another established pattern? Which ScriptableObjects are configuration assets, and which hold runtime state? Are asynchronous operations based on coroutines, tasks, or a project-specific abstraction? This is not an invitation for the AI to redesign those choices. It is a contract telling the assistant which choices already exist.
I also document prohibited changes. An asset package, for example, should not silently add a new dependency, modify global project settings, or require customers to restructure their scenes. That matters to products such as Touch Camera PRO and Touch Camera LITE because reusable Asset Store code lives in projects I do not control. The safest implementation is usually the one with the smallest integration footprint. The project brief should state that requirement directly instead of expecting a model to infer it.
Finally, I include a definition of done that can be observed. The code must compile without new warnings. Existing public APIs must remain compatible unless the task explicitly authorizes a breaking change. Edit Mode and Play Mode tests must pass. Any new serialized field needs a safe default and a migration plan if existing assets are affected. Files outside the approved scope should remain untouched. I keep this brief in the repository, review it like code, and update it when architecture changes. That gives humans and AI assistants the same baseline instead of allowing each conversation to invent a different version of the project.
How Should You Break Work Into AI-Sized Tasks?
Broad requests encourage broad guesses. Asking an assistant to improve the camera system gives it permission to reinterpret input, smoothing, collision, framing, serialization, and public APIs at the same time. Asking it to add an optional maximum zoom constraint to one component, preserve existing defaults, update one test file, and avoid allocation in the per-frame path creates a task that can be reviewed. The second request is smaller, but it contains more useful engineering information.
I divide work according to verification boundaries. A good task has one behavioral objective, a limited file set, known constraints, and a result I can test without finishing three other features first. Investigation is a separate task from implementation. I may first ask the assistant to trace where a value originates, list every serialized reference to a method, or compare two possible extension points. Only after validating that map do I request a patch. This prevents an uncertain analysis from being buried inside a large code change.
I also ask for a plan before code when a task crosses systems. The plan should name the files to modify, explain why each file is involved, identify compatibility risks, and propose tests. I reject plans that introduce unnecessary managers, wrappers, service locators, or generic frameworks. AI assistants often solve ambiguity by creating abstractions. Mature projects frequently need the opposite: a narrow change that respects the abstractions already present.
The final request should include stop conditions. If a required class is missing, a package API is uncertain, or a scene reference cannot be inspected, the assistant should report the uncertainty rather than fabricate an answer. This matters in 2026 because models are increasingly capable of completing a task-shaped conversation even when the repository evidence is incomplete. Fluency can hide uncertainty. Small task slices expose it. They also make commits easier to review, revert, benchmark, and assign. My preferred AI unit of work is not a feature. It is the smallest coherent change that can prove its own correctness.
Which Unity Details Must the Model Never Guess?
The Unity version is the first detail I make explicit. APIs, package compatibility, serialization behavior, and build tooling change over time. A model trained on years of Unity examples may combine an older tutorial, a newer package API, and a deprecated workflow into code that looks entirely plausible. I provide the exact editor version and relevant package versions, then require the assistant to flag any API it cannot verify against that environment.
Scene and prefab ownership must also be clear. I do not let an assistant assume that editing a prefab instance is equivalent to editing its source, or that a scene object is always present at runtime. The task should state how references are assigned, whether objects are loaded additively, what survives scene transitions, and whether a prefab belongs to the project or an imported package. If the assistant cannot inspect serialized YAML safely, I provide a human-readable summary instead of pretending the script files tell the whole story.
Execution order is another dangerous guessing area. Unity lifecycle methods, script execution settings, domain reload options, Enter Play Mode configuration, and asynchronous loading can all change when initialization occurs. An assistant may fix a null reference by adding a convenient lookup in Update, but that can replace a visible lifecycle bug with a permanent performance cost. I want the initialization contract explained and tested, not patched through repeated searching.
Platform behavior belongs on the same list. Touch, mouse, controller, VR input, safe areas, file permissions, and graphics capabilities are not interchangeable. My experience with Eagle Flight Arcade reinforced how seriously platform constraints must be treated, while maintaining camera assets reinforces the variety of customer configurations a reusable package can encounter. I tell the model which platforms matter and which ones are outside scope. I also identify code that runs per frame, in physics steps, in editor callbacks, or during builds. These details determine whether an allocation, reflection call, asset lookup, or conditional compilation symbol is acceptable. When context is unavailable, the correct AI response is a question, not a confident guess.
How Can Tests Turn AI Suggestions Into Evidence?
Generated code should enter the repository through the same evidence pipeline as human code. Compilation is only the first gate. I want tests that describe the intended behavior before I accept an implementation, especially when the assistant proposes a refactor. If a method is supposed to clamp zoom, preserve an old default, or reject invalid configuration, those expectations should be executable. Otherwise, the review becomes a debate about whether the code looks reasonable.
Tests are also a compact form of context. A well-named test tells the assistant what the system promises, which edge cases matter, and what compatibility means. For Unity work, I separate pure C# logic from engine-dependent behavior when practical. Pure calculations can often be covered quickly with Edit Mode tests. Frame timing, coroutines, scene loading, and component lifecycle behavior may require Play Mode tests. I do not force everything into an engine-free layer, but I avoid making simple rules impossible to test.
I sometimes version a small task brief as a ScriptableObject so constraints and acceptance checks remain inspectable by the team. The following is intentionally simple. It creates a consistent summary that can be copied into an approved AI tool or exported by an editor utility:
using System;
using System.Text;
using UnityEngine;[CreateAssetMenu(menuName = "AI/Task Context")]
public sealed class AiTaskContext : ScriptableObject
{
[SerializeField] private string objective;
[TextArea(3, 8)]
[SerializeField] private string constraints;
[SerializeField] private string unityVersion;
[SerializeField] private string[] packageVersions = Array.Empty<string>();
[SerializeField] private string[] acceptanceChecks = Array.Empty<string>();public string BuildBrief() { var builder = new StringBuilder(); builder.AppendLine($"Objective: {objective}"); builder.AppendLine($"Unity: {unityVersion}"); builder.AppendLine($"Packages: {string.Join(", ", packageVersions)}"); builder.AppendLine("Constraints:"); builder.AppendLine(constraints); builder.AppendLine("Acceptance checks:"); foreach (string check in acceptanceChecks) builder.AppendLine($"- {check}"); return builder.ToString(); }
}
This object is not a security boundary and it does not replace repository documentation. Its value is consistency. The objective, environment, and checks can be reviewed alongside the work rather than disappearing in a private chat history.
For every AI-assisted change, I run the tests outside the conversation. I inspect the actual diff, open affected scenes or prefabs, and test the relevant platform path. If the model writes the test and implementation together, I deliberately add or modify an edge case myself. A model can produce a test that merely confirms its own assumptions. Independent checks are what convert a plausible patch into evidence I can trust.
What Review Process Keeps AI Code Maintainable?
I review AI-generated code more skeptically than familiar human code, not because it is automatically worse, but because authorship signals are different. A human teammate can explain which assumptions came from project history. A model may provide a polished explanation assembled from incomplete evidence. I review the diff from the outside inward: scope first, behavior second, architecture third, and style last. If the patch touches files unrelated to the objective, I stop before debating naming.
My first pass checks additions that expand the maintenance surface. Did the change introduce a package, static singleton, reflection helper, editor preference, scripting define, or new public API? Did it copy logic that already exists? Did it create a generic abstraction for a single use case? These patterns can look professional while making the project harder to understand. I ask for deletion and simplification before accepting extra machinery.
The second pass follows Unity-specific failure paths. I inspect serialized field renames, default values, missing-reference behavior, event subscriptions, scene unloads, destroyed objects, domain reloads, and editor-only APIs. I check whether lifecycle methods accidentally hide a base implementation and whether repeated calls create allocations or duplicate listeners. For reusable code such as Touch Camera PRO, I also think about namespace collisions, optional integrations, sample isolation, and whether a customer can upgrade without repairing existing scenes.
The final pass treats the assistant's explanation as a claim to verify, not as proof. I compare it with the diff, run tests, and exercise the feature in the editor. I prefer one conceptual change per commit, even if the assistant could generate a larger patch in seconds. Small commits preserve accountability and make regressions easier to isolate. I also record material AI involvement according to the client's policy, especially when repository access, confidentiality, or licensing is involved. Review cannot be delegated back to the same model that produced the patch. The shipping developer remains responsible for understanding every accepted line and for removing code that the team cannot confidently maintain.
How Do You Introduce AI Into a Mature Product?
I would not begin by asking AI to refactor the heart of a mature product. I start at the edges, where outcomes are easy to compare and rollback is cheap. Good early tasks include drafting tests around existing behavior, summarizing an unfamiliar subsystem, identifying duplicate validation, improving editor diagnostics, or preparing a narrow documentation update. These jobs reveal whether the supplied context is accurate without risking a large migration.
This approach matters for long-lived Unity assets. Products such as Touch Camera PRO, Assets Manager, Tutorial Engine, Responsive UI Pro, and Level Designer have different responsibilities, but they share a publisher's constraint: existing users may depend on behavior that is not obvious from the latest code. A cleaner implementation can still be the wrong implementation if it changes defaults, serialization, namespaces, or setup steps. Before using AI on a mature package, I identify compatibility promises and capture representative project setups as tests or sample scenes.
Client work requires another layer of discipline. My freelance experience spans projects and engagements such as Meta Spirit Sling, Mindsight Journey, Loreal Viva Tech 2024, Rabbids Coding, and A Long Journey to an Uncertain End. Those names do not imply that the same AI policy, repository access rule, or tooling choice applies to each engagement. Before sending any material to an external service, I confirm the client's policy, data boundaries, contractual requirements, and approved tools. If approval is unclear, source code and project data stay out of the model.
I then run a limited trial with a reversible task and compare the full workflow against the normal approach. That includes context preparation, generation, correction, review, testing, and documentation. If the assistant saves ten minutes of typing but creates an hour of review uncertainty, it has not improved the process. If it helps expose an undocumented dependency or produces useful test cases that survive review, I keep that pattern. Adoption should expand through demonstrated value, not enthusiasm. Mature projects accumulate knowledge slowly, so AI access should expand slowly too.
What Should a Team Measure About AI Work in 2026?
Lines of generated code are a terrible success metric. More code often means more review, more surface area for defects, and more future maintenance. Prompt counts and model usage are not much better. They measure activity rather than outcomes. In 2026, when coding assistants can produce substantial patches quickly, generation speed is rarely the limiting factor. The bottleneck is deciding whether the patch belongs in the product.
I prefer to measure accepted task cycle time. Start when the developer has enough information to begin, and finish when the change is reviewed, tested, documented, and ready to merge. I compare that with similar non-AI tasks when possible. I also track correction rounds, review time, escaped defects, reverted changes, and the percentage of generated code that survives meaningful human review. These do not need to become surveillance metrics. Their purpose is to expose where the workflow creates or removes friction.
Documentation quality is another useful signal. If an assistant repeatedly asks about initialization order, supported platforms, or package versions, the repository may be missing important context. Improving that context benefits human developers too. In this sense, AI can act as a diagnostic tool for project clarity. A codebase that is difficult to explain to a model is often also difficult to hand to a freelancer, onboard to a new teammate, or revisit after several months.
My strongest metric is boring: did the change make shipping safer or easier? Useful AI work might reduce a risky manual step, add regression coverage, clarify an undocumented boundary, or help a developer compare implementation options. It does not need to generate a complete feature. I judge tools by accepted outcomes, not demonstrations. Models, context limits, integrations, and pricing will continue to change, so I avoid building a workflow around one vendor's personality. The durable investment is a repository with explicit architecture, narrow tasks, automated checks, and disciplined review. That foundation makes current AI tools more useful, and it will remain valuable when the next generation arrives.
