ИИ-агенты пишут код быстро, но не всегда понятно, что именно они написали. Sphinx — бесплатный open-source Git-хук, который перед каждым пушем читает диф и задаёт разработчику вопросы о поведении кода в проблемных сценариях: таймаутах, ретраях, обработке ошибок. Push проходит только после верного ответа.
Ниже — как инструмент устроен, как его установить и почему он меняет отношение к коду, сгенерированному Claude Code, Codex или Cursor.
Что такое Sphinx и зачем нужен Git-хук для кода ИИ-агентов
Проблема генерации кода агентами не в скорости, а в ответственности. Агент за минуту выдаёт диф на сотни строк, а разработчик подтверждает его в лучшем случае беглым взглядом. Стандартный Git-хук pre-push не спасает: он проверяет синтаксис и тесты, но не понимание.
Sphinx встраивается именно в этот разрыв. Это хук уровня pre-push, который:
- читает диф перед отправкой в репозиторий;
- формулирует вопросы о том, как поведёт себя код в нештатных ситуациях — таймаутах, повторных запросах, ошибках;
- требует ответить правильно, прежде чем push будет выполнен.
Формат «вопрос — ответ» превращает ревью из пассивного просмотра в активную проверку. Если вы не можете объяснить, что произойдёт при таймауте внешнего API, значит, вы не понимаете код, который собираетесь отправить в продакшен.
Как Sphinx проверяет код перед пушем
Механика проста и не требует изменения рабочего процесса.
Генерация вопросов по дифу
Хук анализирует изменения и строит вопросы о поведении кода в проблемных сценариях. Это не абстрактная викторина: вопросы привязаны к конкретным строкам дифа. Например, если агент добавил ретраи без ограничения числа попыток, Sphinx спросит, что произойдёт, когда внешний сервис ляжет на продолжительное время.
Push только после верного ответа
Ключевое отличие от обычных линтеров — блокирующее поведение. Push не проходит, пока вы не ответите на вопрос корректно. Это тот же принцип, что и в экзаменационной системе: сначала понимание, потом действие.
Схожий подход полезен и за пределами кода. При создании чат-бота ответы на вопросы о сценариях отказа — таймаут API модели, недоступность базы знаний, превышение лимита токенов — определяют, переживёт ли бот первый инцидент. Sphinx переносит эту дисциплину в Git-процесс.
Установка и настройка
Установка занимает две команды:
```
npm install -g sphinx-understand
sphinx install
```
Первая ставит пакет глобально, вторая регистрирует Git-хук в репозитории. Дальше инструмент работает в фоне — вы замечаете его только в момент пуша.
Совместимость с ИИ-агентами
Sphinx работает с основными агентными инструментами:
- Codex;
- Claude Code;
- Cursor;
- OpenCode;
- Pi;
- обычный Git без агентов.
Последний пункт важен: хук полезен и для ручной разработки, потому что вопросы о таймаутах и обработке ошибок актуальны для любого кода, а не только для сгенерированного.
Подключение модели для вопросов
Вопросы генерируются через OpenRouter или любой OpenAI-совместимый эндпоинт. Это значит, что можно подключить собственный шлюз или локальную модель — выбор провайдера остаётся за командой.
Безопасность данных и экстренный обход
Два вопроса возникают у любой команды сразу: что Sphinx отправляет наружу и что делать, когда пуш нужен срочно.
Что защищено
- Ответы агенту не передаются — Sphinx не делится с внешними сервисами тем, что вы ответили на вопросы.
- Файл .env и ключи не открываются — секреты проекта остаются вне зоны доступа хука.
Команда sphinx yolo
Для экстренных случаев предусмотрен обход: команда `sphinx yolo` пропускает проверку. Но это не тихая лазейка — каждый пропуск логируется. В команде из нескольких человек лог пропусков превращается в метрику: если кто-то обходит проверку каждую неделю, это сигнал либо о проблемах в процессе, либо о человеке, который отправляет непонятный ему код.
Подробнее о том, как формулируются вопросы, — в разделе [как Sphinx проверяет код перед пушем](#как-sphinx-проверяет-код-перед-пушем); о настройке — в разделе [установка и настройка](#установка-и-настройка).
Зачем это бизнесу: контроль над ИИ-кодом
Автоматизация бизнеса через ИИ ускоряет разработку, но создаёт новый класс рисков: код, который никто в компании не понимает. Системы автоматизации бизнес-процессов, собранные из непроверенных дифов, ломаются в самый неудобный момент — при таймауте платёжного шлюза или недоступности внешнего API.
Sphinx закрывает именно этот разрыв между скоростью и контролем.
Где хук приносит максимальную пользу
- Интеграции с внешними API. Таймауты и ретраи — главный источник инцидентов в интеграционных сервисах. Хук заставляет подтвердить, что поведение при сбое спроектировано, а не возникло случайно.
- Чат-боты для бизнеса. Код бота обрабатывает диалоги, обращения в поддержку, заказы — сценарии, где ошибка видна клиенту напрямую. Проверка понимания перед пушем снижает риск релиза бота, который теряет сообщения при сбое.
- Прототипы, идущие в продакшен. Агенты часто пишут код «на скорость», и такой код потом живёт годами. Ранняя проверка понимания дешевле, чем разбор инцидента через полгода.
- Команды с джуниорами и агентами. Хук работает как обучающий инструмент: вопросы заставляют читать код, а не просто нажимать Enter.
Культура ревью, а не только инструмент
Важный эффект Sphinx — изменение привычек. Когда каждый пуш сопровождается вопросом о поведении кода, разработчик начинает заранее думать о граничных случаях ещё на этапе промпта агенту. Это смещает контроль с конца конвейера на начало, где исправление дешевле всего.
Ограничения и на что обратить внимание
Инструмент честен в своих границах, и о них стоит знать до внедрения.
- Проверка — не тесты. Sphinx не заменяет юнит- и интеграционные тесты: он проверяет понимание разработчика, а не корректность кода.
- Качество вопросов зависит от модели. Вопросы генерирует LLM через OpenRouter или совместимый эндпоинт — качество формулировок варьируется между моделями.
- Ложное чувство безопасности. Правильный ответ на вопрос не гарантирует отсутствия багов; это фильтр невнимательности, а не серебряная пуля.
- Трение в процессе. Командам, пушащим десятки раз в день, блокирующий хук покажется раздражающим — стоит настроить порог срабатывания под свой ритм.
О компромиссе между скоростью и контролем — в разделе [зачем это бизнесу](#зачем-это-бизнесу-контроль-над-ии-кодом).
Быстрый чек-лист внедрения
1. Установите пакет: `npm install -g sphinx-understand`.
2. Зарегистрируйте хук: `sphinx install`.
3. Настройте генерацию вопросов через OpenRouter или свой OpenAI-совместимый эндпоинт.
4. Убедитесь, что .env и ключи недоступны хуку — это поведение по умолчанию.
5. Договоритесь в команде о правилах использования `sphinx yolo` и следите за логом пропусков.
Вывод
Sphinx решает узкую, но реальную проблему эпохи агентной разработки: код пишется быстрее, чем понимается. Git-хук с вопросами о таймаутах, ретраях и ошибках превращает пуш из рефлекса в осознанное действие. Инструмент бесплатный, open-source, ставится двумя командами и работает с Codex, Claude Code, Cursor, OpenCode, Pi и обычным Git.
Для команд, которые строят автоматизацию на ИИ-агентах, это дешёвый способ вернуть в процесс то, что теряется при генерации кода со скоростью мысли, — ответственность за каждую строку в репозитории.
Источник: https://sphinx-six-theta.vercel.app/