Unity и Claude Code: как настроить проект и проверить код

Claude Code может читать и менять C#-скрипты Unity-проекта, запускать доступные команды и помогать разбирать ошибки. Рабочая схема начинается с локальной копии проекта, узкой задачи и проверки в Unity. Для первой попытки не поручайте агенту целую игру: выберите одну механику, например счётчик очков, и заранее определите, как убедиться, что она работает.

Что нужно подготовить до работы с Unity

Для большинства на Windows, macOS и Linux проще начать с вкладки Code в десктопном приложении Claude: она открывает локальную папку, показывает изменения и предлагает подтвердить их. Это основной графический способ. Для повторяемого запуска тестов и работы на Linux удобнее Claude Code CLI. Оба варианта используют один проект и общие инструкции из CLAUDE.md, что подтверждают официальные руководства Anthropic и документация о памяти проекта.

• Создайте отдельную ветку Git или копию проекта. Перед началом проверьте git status.
• Откройте корень с папками Assets, Packages и ProjectSettings, а не только каталог скриптов.
• Устраните исходные ошибки компиляции в Unity, чтобы не принять старую проблему за новую.
• Запишите проверяемый результат: например, после подбора монеты счёт увеличивается на единицу.
• Уберите ключи и пароли из рабочей папки либо запретите их чтение правилами доступа.

Если Claude Code ещё не установлен, используйте официальную инструкцию Anthropic. Нативная установка рекомендована, а CLI удобен для повторяемого запуска тестов. Подробный порядок для Ubuntu и других дистрибутивов есть в разборе установки Claude на Linux. Не копируйте команды установки из случайных репозиториев.

Правило первого запуска: одна механика, один небольшой набор файлов, один способ проверки и заранее понятный откат. Если любой пункт нельзя назвать до правки, сначала просите план без изменения проекта.

Как объяснить Claude Code устройство Unity-проекта

Создайте в корне CLAUDE.md и запишите только устойчивые правила проекта: версию Unity, расположение игровых скриптов, команду тестов, формат кода и запрет на опасные каталоги. Anthropic рекомендует использовать проектный CLAUDE.md для команд сборки, соглашений и архитектурных решений. Более подробная схема есть в статье про память проекта Claude Code.

# Unity project rules
- Unity version: use the version recorded in ProjectSettings/ProjectVersion.txt
- Runtime scripts: Assets/Scripts
- Tests: Assets/Tests
- Before editing, explain the files and expected behavior
- Do not edit or delete Library, Temp, Logs, UserSettings or build output
- Do not move or rename an asset without its matching .meta file
- After a change, show git diff and run the documented EditMode test command

Unity создаёт .meta рядом с файлами и папками внутри Assets. В них хранятся уникальные идентификаторы и настройки импорта. Если переместить объект вне Unity без соответствующего .meta, ссылки в материалах, prefab или сценах могут сломаться. Это прямо описано в руководстве Unity по метаданным. Поэтому безопасная граница первого задания: C#-файлы в Assets/Scripts и тесты, без переименования ресурсов.

Технические запреты задавайте через .claude/settings.json, а не только текстом в инструкции. Список permissions.deny блокирует чтение .env, ключей подписи и каталога сборок встроенными файловыми инструментами Claude Code, но произвольные процессы могут обойти это правило; для чувствительных данных уберите секреты из рабочей папки и включите песочницу. Официальная документация разрешений Claude Code объясняет порядок deny, ask и allow. Для чувствительного проекта начинайте в режиме, где изменения требуют подтверждения; разбор вариантов есть в статье про настройку разрешений Claude Code.

По теме: Claude Code Remote Control: работа с телефона в 2026

Как дать первое задание без расползания правок

Хорошее задание содержит исходное поведение, новое поведение, допустимые файлы и проверку. Название функции без контекста недостаточно: агент может выбрать другой объект сцены или создать вторую систему вместо исправления существующей.

1. Попросите найти связанные скрипты и тесты без правок. В ответе должны быть конкретные файлы и поток данных.
2. Попросите предложить минимальное изменение и назвать риски для сериализованных полей, компонентов и сцен.
3. Разрешите менять только согласованные C#-файлы. Для первой задачи исключите сцены, prefab, настройки и пакеты.
4. После правки проверьте git diff --stat и diff целевых файлов. Неожиданный ресурс или зависимость являются причиной остановиться.
5. Запустите тесты, затем вручную повторите сценарий в Unity. Принимайте результат только после обеих проверок.

Сначала составь план без правок. Найди код начисления очков и связанные тесты.
Цель: после подбора монеты счёт увеличивается ровно на 1 и событие вызывается один раз.
Можно менять только Assets/Scripts/Score и Assets/Tests/EditMode.
Не меняй сцены, prefab, Packages и ProjectSettings.
После согласования сделай минимальную правку, покажи diff и запусти EditMode-тесты.
Если тестовой точки нет, сначала предложи минимальный тест и объясни, что он доказывает.

Практическое правило выбора задачи простое. Если результат можно выразить как вход, действие и наблюдаемый выход, задачу удобно отдавать агенту. Если успех зависит от ощущения управления, композиции сцены, света или анимации, Claude Code может подготовить код, но итог нужно оценивать в редакторе и во время игры.

Как проверить изменение через Unity Test Framework

Unity Editor можно запускать из командной строки и передавать ему параметры. Unity Test Framework поддерживает -runTests, -testPlatform, -testResults и фильтры тестов. Официальный справочник Unity по командной строке и справочник Test Framework показывают этот способ. Путь к исполняемому файлу Unity зависит от операционной системы и версии, поэтому подставьте путь из своей установки.

"<path-to-Unity>" -batchmode -projectPath "<path-to-project>" \
  -runTests -testPlatform EditMode \
  -testResults "<path-to-project>/TestResults.xml" \
  -logFile "<path-to-project>/unity-test.log"

Перед пакетным запуском сохраните проект и закройте Unity Editor для этой рабочей копии. После команды проверьте не только код возврата, но и TestResults.xml вместе с unity-test.log: документация Unity предупреждает, что общего определения кодов завершения для всех компонентов тестов нет, а причину лучше искать в сообщениях и трассировке стека. Затем снова откройте проект и убедитесь, что Console не содержит новых ошибок.

Минимальный чек-лист приёмки состоит из пяти пунктов: изменены только согласованные файлы; Unity компилирует проект; целевой тест проходит; соседнее поведение не сломалось; diff можно объяснить строка за строкой. Для более строгого контроля перед объединением ветки используйте проверку изменений Claude Code.

По теме: Claude и Remotion: как создать видео с помощью кода

Что делать, если результат не проходит проверку

Не исправляйте всё новым широким заданием. Сначала определите симптом и вернитесь к последнему состоянию, которое точно работало. Такой порядок сокращает число одновременно неизвестных причин.

• Unity не компилирует C#: найдите первую ошибку в Console или unity-test.log. Проверьте namespace, assembly definition и доступность API в вашей версии.
• После переименования пропала ссылка: восстановите файл вместе с исходным .meta из Git и снова откройте проект.
• Тесты не стартовали: проверьте пути, установленный Test Framework и отсутствие второй открытой копии проекта. Затем запустите один тест через -testFilter.
• Diff содержит несогласованные сцены, prefab или ресурсы: не принимайте правку. Откатите ветку и повторите задачу с явным списком путей.
• Механика работает, но ощущается неправильно: оставьте вычисления в C#, а скорость, анимацию и визуальный результат настройте в Unity.

Когда Claude Code подходит для Unity, а когда нет

Claude Code хорошо подходит для локальных задач с текстовым результатом: написать или упростить C#-компонент, добавить EditMode-тест, объяснить ошибку компиляции, подготовить Editor script или проверить повторяющийся код. Связка особенно полезна, когда в проекте уже есть Git, понятные тесты и короткие правила в CLAUDE.md.

Способ не подходит как единственная проверка для сборки сцены, баланса игры, анимации, шейдеров, производительности на целевом устройстве и поведения сторонних плагинов. Здесь нужен Unity Editor, запуск игры и иногда профилировщик или реальное устройство. Claude Code также не заменяет резервную копию и не должен получать секреты только потому, что они лежат рядом с проектом.

Частые вопросы

Нужен ли специальный плагин Claude для Unity?

Для работы с C#-файлами специальный Unity-плагин не обязателен. Откройте корень проекта в Claude Code, задайте правила и используйте штатные команды Unity для тестов. Плагин нужен только для дополнительной интеграции, которую вы осознанно выбрали и проверили.

Можно ли поручить Claude Code создать сцену целиком?

Он может подготовить Editor script или предложить структуру, но сцену нужно открыть и проверить в Unity. Для первой работы безопаснее не разрешать прямые изменения сцен и prefab, потому что там важны сериализованные ссылки и визуальный результат.

Что делать, если в проекте нет тестов?

Выберите одну чистую функцию или компонент с простым входом и выходом, затем сначала добавьте минимальный EditMode-тест. Если поведение существует только в сцене, запишите короткий ручной сценарий: начальное состояние, действие и ожидаемый результат.

Можно ли работать без Git?

Технически можно, но вы потеряете удобный просмотр diff и точный откат. Для учебной задачи хотя бы сделайте копию проекта. Для рабочего проекта настройте Git и проверьте, что важные .meta находятся под контролем версий.

Нужно ли открывать весь проект или только Assets/Scripts?

Открывайте корень проекта, чтобы агент видел зависимости и инструкции, но ограничивайте разрешённые правки конкретными каталогами. Так контекст остаётся полным, а область изменения остаётся небольшой.