# Godot Clarity

**[English version](README.md)**

Godot Clarity — open-source Skill для AI-агентов, который помогает создавать, расширять, отлаживать, проверять и рецензировать надёжные проекты на Godot 4 и GDScript.

Godot Clarity — независимый общественный проект. Он не связан с Godot Foundation и не одобрен ею.

## Статус и совместимость

- Статус: **release candidate 0.1.0-rc.4**; для выпуска финального 0.1.0 ещё требуется сравнительный fresh-agent release gate
- Эталон документации и CI: **Godot 4.7.1**
- Детерминированный runtime-набор: **14 пар broken baseline/reference solution**
- Прямая поддержка установщиком: **Codex, Claude Code и Cursor**
- Прямая поддержка: **Godot 4.7.x, GDScript, 2D и 3D**
- Best effort: **Godot 4.0–4.6** с обязательной проверкой по документации соответствующей minor-версии
- Вне текущего основного scope: **Godot 3.x, C#, GDExtension, модули движка и работа с SDK консолей**

Skill следует открытой [спецификации Agent Skills](https://agentskills.io/specification). Это не отдельная модель, не плагин редактора, не Godot addon и не генератор собственного фреймворка.

## Что он улучшает

Поведение Godot-проекта редко находится в одном скрипте: оно распределено между `.gd`, `.tscn`, `.tres`, `project.godot`, импортированными ресурсами, callback-ами движка и runtime-состоянием. Godot Clarity заставляет агента проследить и проверить всю цепочку.

Главные особенности первой версии:

- версионно-точная работа с Godot 4 и GDScript;
- безопасные решения по сценам, Nodes, Resources, owner, сигналам и lifecycle;
- создание проекта через первый играбельный vertical slice, а не через преждевременный набор менеджеров;
- явные контракты для InputMap, UI, анимации, аудио, навигации, сохранений, сети, рендера и экспорта;
- Collision Intelligence с выбором решения по требуемому поведению: направленные layers/masks, контракты CharacterBody и движущихся платформ, защита hitbox/hurtbox от двойного урона, контакты RigidBody, timing и exclusions запросов, sweep быстрых объектов, общие Shape и различия 2D/3D;
- встроенный read-only Project Doctor, который составляет инвентарь проекта и находит подтверждённые статическими данными риски в коллизиях, InputMap, ресурсах, версии и настройках проекта;
- поведенческая проверка в подходящей версии Godot вместо вывода «код выглядит правильно».

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

## Установка

### CLI-установщик

Предварительный npm-канал устанавливает проверенный архив Skill без ручного скачивания:

```bash
npx godot-clarity@next init --ai codex
npx godot-clarity@next init --ai claude
npx godot-clarity@next init --ai cursor
npx godot-clarity@next init --ai cursor --global
```

По умолчанию Skill устанавливается в текущий проект. Флаг `--global` делает его доступным во всех локальных проектах пользователя, а `--project-dir /путь/к/проекту` выбирает другую папку проекта.

CLI требует Node.js 22 или новее. Он скачивает закреплённый GitHub Release по HTTPS, проверяет встроенную контрольную сумму SHA-256, валидирует структуру архива, устанавливает файлы через временную папку и не перезаписывает существующую установку. Аккаунт GitHub, API-ключ, права администратора и собственный сервер не нужны.

Если Windows PowerShell блокирует `npx.ps1` из-за execution policy, выполните ту же команду через `npx.cmd`, например `npx.cmd godot-clarity@next init --ai cursor --global`.

### Ручная установка

Сначала клонируйте или скачайте репозиторий. Устанавливать нужно только каталог `skills/godot-clarity`: документация репозитория, CI и ответы eval-тестов намеренно не входят в пакет Skill.

### Codex

Для одного проекта:

```bash
mkdir -p .agents/skills
cp -R /path/to/godot-clarity/skills/godot-clarity .agents/skills/godot-clarity
```

Для всех проектов пользователя:

```bash
mkdir -p ~/.agents/skills
cp -R /path/to/godot-clarity/skills/godot-clarity ~/.agents/skills/godot-clarity
```

Явный вызов: `$godot-clarity`. Codex также может выбрать Skill по описанию и поддерживает symlink-каталоги для разработки. См. [документацию OpenAI](https://learn.chatgpt.com/docs/build-skills).

Эквивалент для PowerShell в scope одного проекта:

```powershell
New-Item -ItemType Directory -Force .agents\skills | Out-Null
Copy-Item C:\path\to\godot-clarity\skills\godot-clarity .agents\skills\godot-clarity -Recurse
```

### Claude Code

Для одного проекта:

```bash
mkdir -p .claude/skills
cp -R /path/to/godot-clarity/skills/godot-clarity .claude/skills/godot-clarity
```

Для всех проектов пользователя:

```bash
mkdir -p ~/.claude/skills
cp -R /path/to/godot-clarity/skills/godot-clarity ~/.claude/skills/godot-clarity
```

Явный вызов: `/godot-clarity`. См. [документацию Claude Code](https://code.claude.com/docs/en/skills).

В PowerShell используйте ту же команду копирования с адресом назначения `.claude\skills\godot-clarity`.

### Cursor

Для одного проекта:

```bash
mkdir -p .cursor/skills
cp -R /path/to/godot-clarity/skills/godot-clarity .cursor/skills/godot-clarity
```

Для всех проектов пользователя:

```bash
mkdir -p ~/.cursor/skills
cp -R /path/to/godot-clarity/skills/godot-clarity ~/.cursor/skills/godot-clarity
```

Cursor 2.4 или новее поддерживает Agent Skills в редакторе и CLI. Явный вызов Godot Clarity: `/godot-clarity`; Cursor также может выбрать Skill автоматически по описанию. Отдельная цель `--ai cursor` использует нативный каталог Cursor `.cursor/skills`; Cursor также распознаёт переносимый путь `.agents/skills`. Если Godot Clarity уже установлен там для Codex, CLI не станет создавать лишнюю копию. См. [документацию Cursor по Agent Skills](https://cursor.com/docs/skills).

В PowerShell используйте ту же команду копирования с адресом назначения `.cursor\skills\godot-clarity`. После установки откройте новый Agent chat. Если Skill отсутствует в разделе **Customize > Skills**, перезагрузите Cursor.

### Другие агенты

Подключите `skills/godot-clarity` как пакет Agent Skills. Если клиент использует собственный каталог обнаружения, скопируйте или создайте symlink на пакет, не изменяя `SKILL.md`.

## Использование

```text
$godot-clarity Создай минимальный vertical slice платформера на Godot 4.7 с клавиатурой и геймпадом. Проверь запуск главной сцены headless.

$godot-clarity Найди, почему Area2D не видит игрока. Проверь обе сцены, shapes, layers, masks и сигналы, затем докажи исправление runtime-тестом.

/godot-clarity Проведи review системы сохранений: схема, миграции, совместное использование Resources и небезопасная десериализация. Файлы не меняй.
```

В Claude Code и Cursor тот же Skill вызывается как `/godot-clarity` или выбирается агентом автоматически по описанию задачи.

Skill работает в четырёх режимах: создание, расширение, диагностика и review. Он фиксирует только существенные предположения, сохраняет сложившиеся соглашения проекта и отдельно сообщает, что было проверено, а что — нет.

### Project Doctor

В текущих исходниках находится статический preflight для Python 3.10+ без внешних зависимостей, который Skill может запускать перед сложными изменениями. Он не записывает файлы проекта, не запускает Godot и не выдаёт предупреждение за доказательство:

```bash
python /путь/к/godot-clarity/scripts/project_doctor.py /путь/к/проекту --format text
python /путь/к/godot-clarity/scripts/project_doctor.py /путь/к/проекту --format json --focus collisions
```

Текстовый формат предназначен для человека. Детерминированный JSON даёт агенту стабильные rule IDs, confidence, сериализованные доказательства, инвентарь коллизий и требуемую runtime-проверку. Код выхода `0` означает, что сканирование завершилось, даже если есть findings. Коды `2` и `3` означают ошибку самого сканирования. Project Doctor входит в устанавливаемый Skill начиная с `0.1.0-rc.4`.

## Структура репозитория

```text
skills/godot-clarity/  Переносимый устанавливаемый Skill
  SKILL.md             Основной workflow и маршрутизация справочников
  references/          Тематические правила Godot/GDScript
  scripts/             Встроенная read-only диагностика проектов
  agents/openai.yaml   Необязательные метаданные интерфейса Codex
evals/                 Запросы, сломанные fixtures, решения и runtime-oracles
scripts/               Валидатор репозитория и runner eval-тестов без зависимостей
release/               Закреплённые метаданные переносимого Skill-архива
cli/                   Кроссплатформенный Node.js-установщик и его тесты
.github/workflows/     Проверка релиза на закреплённой версии Godot
```

## Проверка

Статическая проверка:

```bash
python scripts/validate_repo.py
```

Тесты Project Doctor:

```bash
python scripts/test_project_doctor.py
```

Тесты воспроизводимости Skill-архива:

```bash
python scripts/test_package_skill.py
```

Тесты CLI и проверка состава npm-пакета:

```bash
npm ci
npm test
npm pack --dry-run
```

В Windows PowerShell используйте `npm.cmd` для этих команд разработки, если `npm.ps1` заблокирован.

Runtime fixtures с локальным Godot 4.7.1:

```bash
python scripts/run_evals.py --godot /path/to/godot --mode all
```

Режим `baseline` доказывает, что каждый fixture действительно воспроизводит нужную ошибку. Режим `solutions` накладывает эталонное исправление и проверяет тем же поведенческим oracle. Такой набор проверяет качество fixtures, но не заменяет fresh-agent сравнение со Skill и без него, описанное в [руководстве для участников](CONTRIBUTING.ru.md).

Сборка переносимого релизного архива:

```bash
python scripts/package_skill.py --version 0.1.0-rc.4
```

[Рабочий отчёт Evaluation Phase 2](evals/reports/2026-07-20-phase2.md) описывает расширение набора до 12 задач и ограниченный сравнительный пилот. Преимущество над запуском без Skill пока не доказано, поэтому полная серия повторных fresh-agent запусков остаётся gate для финального релиза.

## Границы проекта

Godot Clarity не копирует руководство Godot, не навязывает одну архитектуру и не заявляет о работоспособности без запуска движка. Справочники содержат наиболее ценные правила и failure modes, а точные API связывают с версионной официальной документацией.

Устанавливаемый Skill не содержит бинарники Godot, сторонние ассеты, сгенерированные проекты или эталонные решения eval-тестов.

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

Перед изменениями прочитайте [руководство для участников](CONTRIBUTING.ru.md). Новое правило должно закрывать наблюдаемую ошибку агента, объяснять условия применения, избегать проектной догмы, опираться на первичную документацию и иметь проверяемый результат.

## Лицензия и товарные знаки

Godot Clarity распространяется по [лицензии MIT](LICENSE). Атрибуция и информация о товарных знаках находятся в [NOTICE.md](NOTICE.md).

«Godot» и логотип Godot — товарные знаки Godot Foundation. Этот проект не использует логотип Godot как собственный знак. См. [политику Godot Foundation](https://godot.foundation/policies-and-procedures/trademark-policy).