AGENTS.md for Unity

# AGENTS.md

Instructions for coding agents working in this Unity repository. Cursor, Claude Code, Codex, Copilot, and other agents should follow this file before they guess.

## Stack

This repository is a Unity project in C#. Compose behavior with components, expose inspector values with SerializeField, and keep the Unity API on the main thread.

## Layout

- Runtime scripts live under `Assets/` in the folder the feature already uses.
- Editor-only code lives in an `Editor` folder or an editor assembly definition.
- Prefabs and ScriptableObjects are the data. Do not hard-code tuning numbers that designers already edit in the inspector.

## Commands

- Open: `Open the project in the Unity Editor for this version`
- Tests: `Window > General > Test Runner`
- Play: `Enter Play Mode from the scene you changed`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Expose inspector fields with `[SerializeField]` and a private field. Do not make fields public just to show them.
- Cache component references in `Awake` or via `[SerializeField]`. Do not call `GetComponent` or `Find` methods inside `Update`.
- Use events, UnityEvents, or a message the project already has. Do not poll a flag every frame when a callback exists.
- Scene and prefab changes are part of the change. Do not leave a missing script behind.
- Keep gameplay code out of `Editor` assemblies, and editor windows out of runtime assemblies.
- Match the naming already in the assembly: PascalCase for types and methods, the project's field prefix if it has one.

## Testing

Add or update tests when behavior changes.

Use the Unity Test Framework. Prefer an Edit Mode test for pure C# and a Play Mode test only when you need the engine.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Log with context (`Debug.LogError(message, this)`) for unexpected states. Disable the component or skip the frame for a missing optional reference, and say which reference.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not touch `UnityEngine` objects from a worker thread.
- Do not use `GameObject.Find` or `FindObjectOfType` in `Update`.
- Do not compare tags with `==` on a typo-prone string when `CompareTag` will do.
- Do not commit `Library/` or other generated folders. Respect the project's `.gitignore`.

## Done when

- The requested behavior works.
- The script compiles in the Editor, and you ran the Test Runner or Play Mode for the scene you touched.
- The diff stays inside the task.
- You list anything you could not run.