Sphinx — проверка понимания кода перед push

Sphinx — это Node.js-инструмент, который превращает push в защищённую ветку в короткий экзамен. Когда вы отправляете изменения в main или master, git останавливается и ждёт. Вам показывают вопросы о том, что именно делает ваш код. Вы отвечаете, и только после правильного ответа push продолжается.

Главная идея проекта записана в его слогане: отдавайте агенту мышление, но не понимание. Если код пишет ИИ-агент, у вас нет обычного ревью, на которое можно опереться. Ревьюер смотрит на диффы и ловит стиль, но не проверяет, понимаете ли вы логику. Sphinx закрывает именно эту дыру.

Как это работает

Вопросы задаёт отдельная модель-рецензент. Она читает сделанный коммит через инструменты Git только для чтения. Переписку, в которой код писался, она не видит вообще. Это принципиально: агент не может подсказать вам ответ, потому что он не участвует в проверке.

Вот как выглядит типичный обмен для изменения, которое добавляет очередь фоновых задач:

Вопрос. Воркер фиксирует операцию, но падает до того, как подтвердит задачу. После повторной доставки может ли операция выполниться дважды? Ответьте коротко.

Ваш ответ. Нет, задача помечается выполненной в момент фиксации операции.

Sphinx. Не совсем. Задача помечается выполненной только при подтверждении, а оно происходит после фиксации. Падение между этими двумя шагами оставляет задачу неподтверждённой, поэтому очередь доставит её снова, и операция выполнится второй раз.

Новый сценарий. Воркер завис дольше таймаута видимости, и ту же задачу получил второй воркер. Оба зафиксировали операцию до того, как кто-то подтвердил. Что мешает дубликату, если вообще что-то мешает?

Вопросы касаются поведения, отказов и инвариантов, а не имён файлов и функций. Проверка открытая: во время ответа можно читать код или попросить агента показать нужное место.

Что нужно до установки

Автор честно перечисляет ограничения, и их стоит прочитать до установки.

• Требования. Node.js 22.19 или новее, git и macOS, Linux или WSL. Нативный Windows пока не поддерживается.
• Настройка действует на всю машину. sphinx install прописывает глобальную настройку git core.hooksPath. Ваши собственные хуки продолжают выполняться первыми. Сразу после установки проверяются пуши в main или master в любом репозитории. Дальше sphinx init позволяет настроить каждый репозиторий отдельно.
• Git блокируется. Подходящий push ждёт, пока вы пройдёте проверку, поставите её на паузу или пропустите. Максимум — 25 минут. Оболочка вашего кодинг-агента может завершиться раньше.
• Нужен доступ к модели-рецензенту. Это может быть авторизованный Codex или Claude Code CLI, который тратит лимит вашего тарифа. Также подходит ключ OpenRouter (он оплачивается отдельно и нужен даже для бесплатных моделей) или любой OpenAI-совместимый адрес. У самого Sphinx нет ни аккаунта, ни своего сервиса.
• Код покидает вашу машину. Провайдер рецензента получает изменённый код, ваши ответы и файл .sphinxcontext.md. Файлы из списка игнора не читаются, .env, приватные ключи и распространённые файлы с секретами исключены по умолчанию. Свои чувствительные пути нужно добавить в .sphinxignore до первой проверки. Правила игнора смотрят только на путь файла. Поэтому секрет, вставленный в обычный исходник, они не поймают.
• Потолка на число вызовов модели нет. Типичная проверка делает примерно 5–8 запросов плюс около одного на каждый ответ. Потолок можно задать, а для платных провайдеров лимиты расходов лучше выставить у самого провайдера.
• Это практика, а не защита. Любой, у кого есть локальный доступ, включая кодинг-агента, может обойти хуки. Успешная проверка не доказывает, кто написал код. Экзаменатор — это тоже LLM, и он может ошибиться.

Быстрый старт

Установка глобальная:

npm install -g sphinx-understand
sphinx install

Мастер спрашивает, какими агентами вы пользуетесь и какую модель взять рецензентом. Дальше он предлагает готовые наборы проверок (пуши в main или master на стандартной глубине) или пункт Customize, где выбираются события, ветки, удалённые репозитории и глубина. Без вопросов:

sphinx install --yes --preset claude-economy --agents claude

Затем Sphinx нужно подключить в вашем агенте, если вы им пользуетесь. Для Codex нужно открыть /hooks и доверять хукам — сделать это за вас Sphinx не может. Для Claude Code достаточно начать новую сессию: в /mcp должен появиться подключённый sphinx. Для Pi, Cursor и OpenCode есть отдельные заметки в документации по интеграциям.

Дальше настройка репозитория:

cd your-repo
sphinx init

Команда создаёт три файла и не перезаписывает существующие:

• .sphinxconfig — политика репозитория.
• .sphinxignore — пути, которые никогда не читаются. Отредактируйте его сразу, если в проекте есть приватные или генерируемые файлы.
• .sphinxcontext.md — короткое описание того, что делает проект. Его получают все запросы рецензенту. Секретов там быть не должно.

Проверка установки:

sphinx doctor

В конце должно быть ✓ Configured integrations are in place.

И первый push:

git push origin main

Git печатает адрес локальной страницы и ждёт:

Sphinx: understanding check needed for refs/heads/main (medium change).
Sphinx: Git is waiting for your answers in the local Sphinx questionnaire.
Sphinx questionnaire: http://127.0.0.1:56114/fSdZM7yg…

На macOS страница открывается фоновой вкладкой, ваше рабочее окно остаётся на месте. На Linux, WSL и по SSH git вместо этого печатает open the local URL above to answer, и адрес нужно открыть вручную. На странице видно, как идёт работа рецензента, какие файлы изменились, сколько строк добавлено и удалено, сам дифф и места в коде, которые рецензент прочитал для конкретного вопроса. После правильного ответа:

Sphinx: understanding check complete. Continuing this Git operation.
To github.com:you/your-repo.git
 * [new branch]      main -> main

Повторный push того же изменения вопросов не задаёт. Результат держится 24 часа, если не поменялись код, адрес назначения или политика.

Во время проверки

• Неверный ответ. Вы получаете объяснение и новый сценарий по той же теме. Спорные и ошибочные ответы зачтёнными не считаются.
• Объяснить. Показывает суть и задаёт новый вопрос.
• Оспорить вопрос. Нужно, если в вопросе неверная или неоднозначная посылка. Плохой вопрос исправляется до того, как тема будет засчитана.
• Пауза. Сохраняет прогресс и останавливает push. Позже тот же git push продолжит с того места.
• Закрытие вкладки ничего не отменяет. Git продолжает ждать, адрес работает до истечения 25 минут.
• Пропустить. Пуск происходит сразу, даже пока рецензирование ещё идёт. Пропуски зачтёнными не считаются.
• sphinx yolo. Отключает проверки в текущем репозитории, а если запустить вне репозитория — глобально. Повторный запуск включает обратно. Настройка репозитория сильнее глобальной. Флаг --reason "prod hotfix" необязателен.
• sphinx check. Прогоняет ту же проверку в терминале, без браузера.

Ваши ответы идут со страницы прямо в Sphinx. Ваш кодинг-агент видит только статус проверки, прогресс и расход, но никогда — сами ответы. Каждый пропуск и каждое переключение yolo пишутся в журнал вместе с причиной, sphinx status показывает последние.

Стоимость

Число вопросов зависит от размера изменения и выбранной глубины. На стандартной глубине маленькое изменение получит один вопрос, а большое — до трёх. После коммитов Sphinx готовит вопросы в фоне, так что к моменту push они часто уже готовы. Сколько вызовов модели, токенов и денег потрачено, видно прямо на странице.

sphinx config --max-model-calls 30        # необязательный потолок на проверку (1–100)
sphinx config --preset openrouter-value --allow-paid

Размер изменения определяется детерминированно, без запросов к модели: считаются добавленные и удалённые строки, число файлов и подозрительные пути. Путь считается подозрительным, если содержит auth, permission, migration, billing, payment, crypto, security или terraform. Даже крошечный патч с таким путём будет отнесён к большому изменению.

Глубина задаётся в .sphinxconfig и отвечает за характер вопросов. На relaxed рецензент спрашивает про наблюдаемое поведение и самый важный крайний случай. На standard — про поведение, отказы и взаимодействие с другими частями системы. На thorough добавляются допущения о выкатке, откате и совместимости.

Это верхние границы, а не квота. Если код не даёт материала на пять разных вопросов, рецензент не будет их выдумывать.

Команды

У каждой команды есть своя справка: sphinx <command> --help. Флаг --json даёт машинный вывод, NO_COLOR=1 отключает цвет.

Чего Sphinx не делает

Версия 0.1 проверяет только локальные коммиты и пуши. Веб-слияния, обязательные CI-проверки и деплои не охвачены. Содержимое бинарных файлов не читается. Инструмент проверяет понимание, а не качество кода. Результаты оценки качества собраны на синтетических изменениях и не являются сертификатом для произвольных репозиториев.

Проект распространяется под лицензией MIT. Требования, архитектура и приёмы работы описаны подробнее в документации по архитектуре, а цена и лимиты моделей — в разделе про конфигурацию.