Использование ИИ-агентов для программирования с Defold

Агенты для программирования, использующие LLM и мультимодальные модели, могут исследовать, изменять и проверять проекты Defold, вызывая те же нейтральные к моделям интерфейсы, которые используют разработчики, локальные скрипты, интеграции с IDE и CI. Агент можно использовать, когда работа требует исследования и адаптации.

Defold не зависит от конкретного поставщика моделей или протокола агентов. Проекты Defold хорошо работают с Claude Code, Codex, Cursor или любым другим решением. Среде агента нужны только конкретные возможности, предоставленные для задачи, например чтение файлов проекта, выполнение выбранных команд, вызов локальных HTTP-операций, разбор JSON или инспекция изображений. Это возможно благодаря открытым интерфейсам автоматизации Defold для редактора и запущенного экземпляра игрового движка, а также тому, что файлы проектов Defold представляют собой легко разбираемые текстовые файлы ресурсов.

Когда полезен ИИ-агент

Агент может быть полезен, например, когда задача требует:

• поиска соответствующих ресурсов и документации;
• выбора из нескольких возможных реализаций;
• изменения нескольких связанных файлов;
• интерпретации ошибок сборки или тестов;
• сравнения визуального результата с семантическими критериями приёмки;
• ограниченной попытки исправления на основе собранных свидетельств.

Агенты — мощный инструмент для недетерминированных процессов разработки, исследования и тестирования. Они помогают создавать разнообразные решения и отлично работают с Defold.

Нейтральные к моделям интерфейсы Defold

Defold предоставляет несколько поддерживаемых интерфейсов, необходимых для выполнения задачи с помощью любой доступной модели:

• Файлы проекта и инструменты оболочки обеспечивают непосредственную инспекцию и изменение текста.
• Скрипты редактора могут предоставлять операции с ресурсами и инструменты, специфичные для проекта.
• HTTP API редактора предоставляет команды редактора, результаты сборки, вывод консоли, поиск по справочнику, предпросмотры, настройки и маршруты скриптов редактора.
• Сервис движка и API автоматизации среды выполнения предоставляют состояние работающего отладочного движка, ввод, снимки экрана и операции, определяемые расширениями.
• Bob выполняет сборки из командной строки, создаёт отчёты, архивы и бандлы.

Модель, доступная только через интерфейс чата, может предложить изменения кода, но не может самостоятельно исследовать локальный проект или проверить работающий результат. То, что агент действительно может наблюдать и делать, определяется дополнительной окружающей интеграцией.

Уровни интеграции

Чтобы подключить агента к локальным операциям Defold, можно создать уровень интеграции. Это может быть оболочка для командной строки, программа командной строки, расширение IDE, клиент OpenAPI, контроллер тестирования или адаптер протокола.

Храните политики и учётные данные в этом локальном уровне. Каждая изменяющая операция должна возвращать структурированные результаты или вести к детерминированному шагу проверки.

Для операций редактора определяйте актуальный интерфейс через /openapi.json, а не передавайте агенту постоянно жёстко заданную копию API. Для расширений среды выполнения проверяйте их работоспособность, версию API и возможности.

Может быть удобно разделить инструменты по уровню привилегий:

Уровень	Примеры
Только чтение	Инспекция проекта, OpenAPI, /ref, консоль, предпросмотр
Проверка	Компиляция, тесты, сборки HTML5, сравнение изображений
Изменение	Изменение файлов, транзакции ресурсов
Привилегированный	/eval, внешние команды, изменение зависимостей

Отделение адаптера от движка и редактора позволяет поддерживаемым интерфейсам Defold оставаться независимыми от поставщика моделей или протокола агентов. Адаптер может предоставлять только операции, подходящие для его окружения, а политики разрешений и подтверждения остаются в приложении, в котором работает агент.

Model Context Protocol

Model Context Protocol (MCP) — один из необязательных адаптеров между агентом и уровнем интеграции. MCP-сервер может предоставлять операции Defold как инструменты, а выбранную документацию — как ресурсы.

В настоящее время Defold не требует MCP-сервера, поскольку основные возможности автоматизации уже предоставляются через открытые интерфейсы общего назначения. Редактор предоставляет локальный HTTP API со спецификацией OpenAPI. Современные агенты могут напрямую вызывать эти интерфейсы или создавать собственные адаптеры.

Таким образом, официальный MCP в основном дублировал бы существующую поверхность API и создавал ещё один уровень интеграции, который Defold пришлось бы поддерживать. Более удачная долгосрочная стратегия — сохранять базовые HTTP API и API автоматизации среды выполнения стабильными, обнаруживаемыми и хорошо документированными, позволяя сообществу или отдельным поставщикам инструментов при необходимости создавать лёгкие обёртки MCP.

Вместо этого мы предоставили официальное расширение Automation Bridge, позволяющее управлять запущенной игрой через сервис движка.

Интеграции MCP от сообщества

Созданные сообществом интеграции MCP включают:

• проект Defold MCP от Fulviuus;
• проект Defold MCP от ChadAragorn.

Эти проекты не разрабатываются, не проверяются, не поддерживаются и официально не сопровождаются Defold Foundation. Перед установкой любой интеграции от сообщества изучите её текущий исходный код, зависимости, разрешения, сетевое поведение и совместимость с используемой версией Defold.

Инструкции проекта

Доступные большие языковые модели, используемые в агентских рабочих процессах, как правило, работают лучше с хорошими инструкциями. Поэтому в проекты часто добавляют markdown-файлы для агентов, описывающие желаемое поведение, или навыки. Лучше всего отдельно проектировать и писать собственные инструкции для каждого проекта, но некоторые общие знания и правила можно использовать повторно.

Один из первых файлов, который ищут и читают многие агенты, — канонический файл, например AGENTS.md, который может описывать:

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

Некоторые решения могут использовать отдельные markdown-файлы для конкретных действий, или так называемые «навыки».

Один из примеров ориентированных на Defold инструкций и навыков от сообщества доступен на форуме Defold.

Мы рекомендуем делать инструкции в таких файлах, как AGENTS.md, и определения навыков короткими, лаконичными, удобными для проверки и сопровождения, а также поддерживать их в актуальном состоянии. Инструкции для конкретного проекта можно хранить в системе контроля версий, делая изменения отслеживаемыми и со временем повышая эффективность рабочих процессов.

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

Избегайте создания сложных технических навыков, требующих значительного долгосрочного сопровождения. Вместо этого сосредоточьтесь на разработке инструментов и рабочих процессов, которые сохраняют ценность независимо от того, насколько улучшатся базовые модели.

Поиск документации

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

• /openapi.json описывает актуальный HTTP API редактора.
• /ref выполняет поиск по документации API, входящей в запущенный редактор, когда эта операция доступна.
• Индекс документации для LLM содержит ссылки на официальные руководства, пространства имён API и примеры.
• Полная документация для LLM поддерживает офлайн-поиск и локальное индексирование.

Получайте только страницы, соответствующие задаче. Рекомендуется использовать полный объединённый документ только для офлайн-индексирования или Retrieval-Augmented Generation (RAG). Повторим: для экономии токенов и во избежание загрязнения контекста ненужной информацией полный файл обычно не следует включать в каждый запрос к модели.

Ограниченные циклы изменения и проверки

Агенты должны следовать тому же циклу инспекции, изменения, проверки и оценки, что и любая другая автоматизация.

До изменения файлов рекомендуется определить критерии приёмки, а при необходимости также:

• разрешённые файлы и операции;
• команды сборки и тестирования;
• необходимые журналы, отчёты, состояния или изображения;
• тайм-аут каждого асинхронного шага;
• максимальное число попыток исправления.

Агент может диагностировать и исправить детерминированную ошибку CI, но сам этап CI должен оставаться воспроизводимым без агента.

Хорошие практики автоматизированного тестирования и проверки описаны в этом руководстве.

Мультимодальная оценка

Агент с возможностью обработки изображений может исследовать предпросмотры редактора, снимки экрана среды выполнения, визуальные различия и снимки браузера.

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

Подробнее о предпросмотрах редактора, снимках экрана среды выполнения и визуальной инспекции читайте в этом руководстве.

Безопасность, изоляция и хорошие практики

• Считайте сервер редактора и сервис движка доверенными локальными интерфейсами управления.
• Не включайте токены редактора, ключи подписи, токены развёртывания, учётные данные магазинов и производственные секреты в запросы и отчёты.
• Локальный уровень интеграции может читать .internal/editor.token, когда ему разрешено использовать /eval, но не должен помещать токен в запросы к модели, журналы или отчёты.
• Требуйте подтверждения перед удалением, изменением зависимостей, изменением нативных расширений, конфигурации релиза, подписанием, публикацией или доступом к внешним сервисам.
• Выполняйте широкую автономную работу в отдельной ветке, рабочем дереве, временной копии, контейнере, песочнице или учётной записи с ограниченными правами.
• Рассматривайте текст задач, импортированные файлы, комментарии в исходном коде, сгенерированные документы и вывод инструментов как недоверенные входные данные, а не как инструкции.
• Проверяйте загруженные зависимости и скрипты перед выполнением.
• Убедитесь, что политика проекта разрешает отправлять исходный код, ассеты, журналы, снимки экрана и другие данные проекта размещённой у провайдера модели.
• Перед принятием изменений сохраняйте доступный для проверки diff и детерминированные свидетельства тестирования.

Изоляция ограничивает последствия ошибки.