2509 Readme Ru 5a27631d

# Конфигурация ИИ-агента для Defold

Пример конфигурации `AGENTS.md` и набор скиллов (`.agents/`) для разработки игр с помощью ИИ на движке [Defold](https://defold.com). Это в первую очередь исследовательский проект, но вы можете свободно использовать конфигурацию и скиллы в своих проектах.

Папка `.deps/` используется скиллом `defold-project-setup` для загрузки исходников зависимостей проекта и встроенных модулей Defold (builtins), давая вашему ИИ-агенту простой доступ к API и типам зависимостей (только для чтения). Для обновления после изменения зависимостей в `game.project` запустите скилл `defold-project-setup`.

Переводы: [English](README.md)

## Поддерживаемые ИИ-агенты

Конфигурация использует формат директории `.agents/`, который поддерживается:

- **[Amp](https://ampcode.com)**
- **[Claude Code](https://claude.ai/code)** (требует переименования `.agents/` в `.claude/`)
- **[Codex CLI](https://github.com/openai/codex)**
- **[Cursor](https://cursor.com)**
- **[Factory Droid](https://factory.ai)**
- **[GitHub Copilot](https://github.com/features/copilot)** (требует переименования `.agents/` в `.github/`)
- **[Kilo Code](https://kilocode.ai)**
- **[OpenCode](https://opencode.ai)**
- **[Warp](https://warp.dev)**
- **[Windsurf](https://windsurf.com)** (требует переименования `.agents/` в `.windsurf/`)
- и многими другими

## Требования

- **[Defold](https://defold.com) >= 1.12.2**
- **Python >= 3.11** — необходим для скриптов скиллов.
  - **Windows:** `winget install Python.Python.3`
  - **macOS:** `brew install python3`
  - **Linux:** `sudo apt-get install python3`

## Установка

1. Скопируйте `AGENTS.md`, папку `.agents/` и файл `.defignore` в корень вашего Defold-проекта.

> **Примечание:** Некоторые ИИ-агенты используют собственные директории:
> - **Claude Code**: Переименуйте `.agents/` в `.claude/` и выполните поиск-замену во всех `.md` файлах: `.agents/` → `.claude/`
> - **GitHub Copilot**: Переименуйте `.agents/` в `.github/` и выполните поиск-замену во всех `.md` файлах: `.agents/skills/` → `.github/skills/`
> - **Windsurf**: Переименуйте `.agents/` в `.windsurf/` и выполните поиск-замену во всех `.md` файлах: `.agents/` → `.windsurf/`

2. Попросите вашего ИИ-агента: `Запусти скилл defold-project-setup, чтобы скачать зависимости в .deps/`
3. Попросите вашего ИИ-агента: `Обнови AGENTS.md на основе структуры моего проекта, зависимостей и папок`

Готово — агент автоматически подхватит инструкции и скиллы.

## Настройки gitignore для .deps — прочитайте внимательно!

Если вы добавите `.deps/` в `.gitignore` (чтобы не коммитить загруженные зависимости), **ИИ-агенты по умолчанию будут его игнорировать** — их внутренние инструменты (Glob, Grep, file picker) учитывают `.gitignore`. Иронично, что во многих агентах `node_modules` в JS-проектах обрабатывается особым образом и всё равно индексируется, а `.deps` в Defold-проектах такой привилегии не получает. Чтобы агенты видели `.deps`, но он не попадал в git, добавьте эти файлы:

**1. `.gitignore`** — используйте `.deps/**` (не `/.deps`), чтобы negation-правила работали корректно:

```
.deps/**
```

**2. `.cursorignore`** (только Cursor) — negation, чтобы индексация включала `.deps`:

```
!.deps
!.deps/**
```

**3. `.ignore`** (для ripgrep/Grep) — тот же negation, чтобы поиск находил файлы в `.deps`:

```
!.deps
!.deps/**
```

**Claude Code** не имеет `.cursorignore`. Добавьте в `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": ["Read(./.deps/**)"]
  }
}
```

Для других агентов ищите обходные пути в их документации (ignore-файлы, настройки индексации, правила доступа).

**Самопроверка:** Попросите агента: *«Найди все файлы input_binding»*. Он должен вернуть `.deps/builtins/input/all.input_binding`. Если нет — агент по-прежнему не видит `.deps`, перепроверьте настройки выше.

## Установил... а что дальше-то?

Откройте проект в Defold Editor и ИИ-агент рядом. Вот что можно делать:

- **"Создай новый экран `main_menu` с двумя кнопками: Играть и Настройки"** — агент использует `monarch-screen-setup` для создания коллекции, GUI и скрипта экрана.
- **"Добавь игровой объект игрока со спрайтом и коллизией"** — агент использует `defold-proto-file-editing` для создания файлов `.go`, `.sprite` и `.collisionobject`.
- **"Напиши скрипт, который двигает игрока влево-вправо стрелками"** — агент найдёт API ввода Defold и напишет `.script` по соглашениям проекта.
- **"Собери и запусти игру"** — агент использует `defold-project-build` для компиляции через запущенный Defold Editor и сообщит об ошибках.
- **"Как работает `go.animate`?"** — агент загрузит документацию API через `defold-api-fetch` и объяснит с примерами.
- **"Я добавил новую зависимость в game.project, обнови .deps"** — агент запустит `defold-project-setup` для повторной загрузки зависимостей.
- **"Реализуй изолированный Lua-модуль аркадной 2D-коллизии на базе quad-tree, с тестами"** — агент напишет самодостаточный модуль по соглашениям проекта и создаст юнит-тесты.
- **"Изолируй этот код в локальную Lua-функцию и создай её вариант в C++ native extension"** — агент выделит выбранный код в Lua-функцию, а затем использует `defold-native-extension-editing` для создания C++ реализации.

Просто опишите, что вам нужно, на любом языке — агент знает структуру проекта, API Defold и все соглашения из `AGENTS.md`.

### Лучшие практики

- **Сначала планируйте, потом реализуйте** — попросите агента составить план перед реализацией. В некоторых агентах есть даже специальный режим "plan". Сохраните план в файл (например, `PLAN.md`) и отдельными этапами просите агента реализовать его в отдельных беседах.
- **Одна задача — одна беседа** — небольшие, сфокусированные запросы дают лучший результат, чем длинные многошаговые сессии.
- **Держите контекст ниже ~65%** — когда беседа становится слишком длинной, агент теряет фокус. Начинайте новую сессию до того, как это случится.
- **Начинайте с готового проекта** — создать полноценную игру с нуля силами одного ИИ-агента пока вряд ли получится. Лучший подход — добавить файлы агента (`AGENTS.md`, `.agents/`) в уже работающий Defold-проект и развивать его.
- **Добавляйте как можно больше логов** — чем больше вызовов `print()` в ваших скриптах, тем проще ИИ-агенту отлаживать проблемы по выводу. Например, вызовите `monarch.debug()` для логирования переключений экранов. В этом проекте также есть полезная функция `fail_on_error()` в `main/main.script` — она немедленно закрывает игру при первой ошибке, чтобы вы сразу видели, ГДЕ произошла проблема, а не отматывали тысячи строк журнала.

## Скиллы

В `.agents/skills/` включены следующие скиллы:

| Скилл | Описание |
|---|---|
| **defold-api-fetch** | Загружает документацию API движка Defold |
| **defold-assets-search** | Поиск библиотек и расширений в Defold Asset Store |
| **defold-docs-fetch** | Загружает руководства и концептуальную документацию Defold |
| **defold-examples-fetch** | Загружает примеры кода Defold по темам |
| **defold-native-extension-editing** | Помогает с разработкой нативных расширений (C/C++, JS, манифесты) |
| **defold-project-build** | Собирает проект через запущенный Defold Editor |
| **defold-project-setup** | Загружает зависимости проекта в `.deps/` |
| **defold-proto-file-editing** | Создаёт и редактирует файлы Defold в формате Protobuf Text |
| **defold-scripts-editing** | Помогает с редактированием Lua-скриптов |
| **defold-shaders-editing** | Создаёт и редактирует шейдерные файлы Defold (.vp, .fp, .glsl) |
| **defold-skill-maintain** | Обслуживает и обновляет определения скиллов |
| **monarch-screen-setup** | Настраивает экраны и попапы с помощью Monarch |
| **xmath-usage** | Справочник API xmath и паттерны оптимизации математики без аллокаций |

## Поддерживаемые модули Defold

Конфигурация `AGENTS.md` включает встроенную поддержку этих библиотек Defold при их наличии в проекте:

- **[Monarch](https://github.com/britzl/monarch)** — Управление экранами и попапами
- **[Object Interpolation](https://github.com/indiesoftby/defold-object-interpolation)** — Плавное движение объектов с фиксированным шагом времени
- **[Sharp Sprite](https://github.com/indiesoftby/defold-sharp-sprite)** — Пиксельно-точный рендеринг спрайтов с материалами RGSS
- **[Xmath](https://github.com/thejustinwalsh/defold-xmath)** — Математические операции без аллокаций для векторов, кватернионов и матриц

## Roadmap - and can the community help with that?...

1. **Обкатка на реальных проектах** — использовать эту конфигурацию в рабочих Defold-проектах и дорабатывать в процессе. Кстати, вы всегда можете попросить вашего ИИ-агента "доработать этот скилл на основе нашего диалога" — и он сам обновит файлы скилла.
2. **Новые скиллы на основе лучших практик** — добавлять скиллы для вещей, которые сразу не пришли в голову авторам: как писать шейдеры, как создавать высокопроизводительные игры, как разделять логику и отображение, и так далее.
3. **Скиллы для популярных библиотек** — создавать скиллы для популярных библиотек Defold, которые активируются автоматически при наличии библиотеки в проекте пользователя.
4. **MCP-сервер для Defold** — попробовать сделать [MCP](https://modelcontextprotocol.io/)-сервер на базе [HTTP-сервера Defold Editor](https://gist.github.com/vlaaad/395bd021e8a4ba6561fd4f8d3562456f), чтобы ИИ-агенты могли взаимодействовать с запущенным редактором напрямую (выполнять editor-скрипты, читать структуру проекта и т.д.).
5. **Понять, чего не хватает Defold** — определить, что нужно движку и редактору Defold, чтобы достичь уровня ИИ-разработки, который уже существует для веб-сайтов и мобильных приложений.

## Участие в проекте

Мы рады любым контрибуциям! Открывайте issues и pull requests.

- 🌍 **Issues можно писать на любом языке** — ИИ всё переведёт и поймёт.
- 🐍 **Все скрипты в проекте должны быть написаны на Python или нативном шелле платформы** (bash, PowerShell), чтобы не плодить зависимости и не требовать дополнительного ПО.

## Лицензия

Проект передан в общественное достояние по лицензии [CC0 1.0 Universal](LICENSE).