Дайте Claude Code сорок инструментов и расплывчатую задачу — он зависнет ещё на этапе планирования. Не потому что глупый, а потому что выбор слишком велик. Классическое решение — взять модель побольше и промпт подлиннее. Но есть и другой путь: вместо расширения возможностей модели сузить пространство задачи до такой степени, чтобы даже компактная локальная модель чувствовала себя уверенно. Именно эту идею воплощает Statewright — open-source фреймворк guardrails на базе конечных автоматов.

Что такое Statewright

Statewright — это система guardrails, которая описывает рабочий процесс агента как конечный автомат. Каждое состояние машины определяет, какие инструменты доступны агенту прямо сейчас, какие команды разрешены, сколько итераций можно потратить и какие переходы в другие состояния допустимы. Если агент пытается вызвать инструмент, которого нет в текущем состоянии — вызов блокируется на уровне протокола, ещё до того, как модель его увидит.

Фреймворк написан на Rust, распространяется под Apache 2.0 и поддерживает интеграцию с Claude Code, Codex, Cursor, opencode и Pi. Разработчики предлагают простую формулу: «агенты — это предложения, состояния — это законы». Предложения можно обсуждать, законы нарушать нельзя.

Почему агенты ломаются без guardrails

Современные ИИ-агенты получают доступ к десяткам инструментов: чтение файлов, редактирование кода, выполнение shell-команд, поиск по репозиторию, запуск тестов. Когда всё доступно одновременно, модель тратит токены на бесконечные размышления о том, что же выбрать. Часто выбор оказывается неверным: агент редактирует файл до того, как прочитал его целиком, запускает опасную команду вместо безопасной, или зацикливается в бесконечных попытках исправить одну и ту же ошибку.

Традиционный подход — наблюдаемость. Инструменты вроде LangSmith или OpenTelemetry показывают, что пошло не так, но уже после факта. Они не предотвращают ошибку, а лишь помогают её диагностировать. Statewright меняет логику: вместо наблюдения за хаосом он устраняет саму возможность хаоса.

Как работает конечный автомат для агента

Рассмотрим типичный workflow исправления бага. Без guardrails агент получает задачу и сразу начинает что-то менять. Со Statewright процесс разбит на чёткие фазы:

Планирование. Агенту доступны только инструменты чтения: Read, Grep, Glob. Он может изучать код, искать зависимости, анализировать структуру проекта — но не может ничего изменить. Максимум восемь итераций на этом этапе. Когда агент считает, что план готов, он переходит в следующее состояние по сигналу READY.

Реализация. Открываются инструменты редактирования: Edit, Write. Но с жёсткими ограничениями: не более двадцати строк изменений за раз, не более трёх файлов на всё состояние. Опасные операции вроде перенаправления вывода или вызова rm всё ещё заблокированы. Переход в тестирование происходит по сигналу DONE.

Тестирование. Доступны только чтение и Bash, причём из shell-команд разрешены только pytest, cargo test и npm test. Если тесты проходят — автомат переходит в финальное состояние completed. Если падают — возврат к реализации по сигналу FAIL_TEST.

Такая структура не просто ограничивает агента — она снижает когнитивную нагрузку на модель. Вместо выбора из сорока инструментов модель работает с тремя-четырьмя, релевантными текущей фазе. Это ускоряет推理 и повышает точность.

Guardrails: от мягких рекомендаций до жёсткого протокола

Statewright предлагает восемь типов guardrails, которые можно комбинировать:

Переключение инструментов по состояниям. Инструменты, не включённые в allowed_tools текущего состояния, становятся невидимыми для агента. Это самый базовый и самый мощный механизм.

Дискриминация Bash. В состояниях, где shell разрешён, блокируются перенаправления потоков, деструктивные команды вроде rm или shred, и вызов интерпретаторов скриптов. Агент может запускать тесты, но не может случайно стереть репозиторий.

Ограничение редактирования. Параметр max_edit_lines ограничивает размер diff, а max_files_per_state — количество файлов, которые агент может трогать за одно состояние. Это предотвращает массовые неконтролируемые изменения.

Белые списки команд. Префиксное сопоставление allowed_commands позволяет разрешить только конкретные утилиты. Например, в состоянии тестирования разрешены только команды, начинающиеся с pytest, cargo test или npm test.

Условные переходы. Переходы между состояниями могут зависеть от данных контекста. Guard проверяет значение поля по предикату: равенство, больше, существование и другие операции.

Точки одобрения. Флаг requires_approval останавливает выполнение перед рискованными переходами и ждёт подтверждения человека. Полезно для production-деплоев или операций с данными.

Изоляция окружения. Параметры blocked_env и env_overrides позволяют скрывать чувствительные переменные окружения или подменять их на безопасные значения для конкретного состояния.

Изоляция сессий. Каждая сессия Claude Code получает уникальный идентификатор через CLAUDE_SESSION_ID, что позволяет отслеживать состояния независимо для разных разговоров.

Результаты: локальные модели начинают справляться

Разработчики Statewright провели тесты на двух задачах: исправление бага в файле из двадцати шести строк и подмножество SWE-bench из пяти заданий. Результаты показывают, что guardrails меняют правила игры для компактных моделей.

Модель gemma3 весом 3,3 ГБ без Statewright не справилась ни с одной задачей. С guardrails она прошла тест на исправление бага. Gemma4:e2b весом 7,2 ГБ также провалила SWE-bench без ограничений, но с конечным автоматом показала результат. Это означает, что ограничение пространства задачи может быть эффективнее увеличения модели.

Для frontier-моделей эффект менее драматичен, но всё же заметен: меньше токенов до завершения, меньше ложных вызовов инструментов, более предсказуемое поведение. Главное преимущество Statewright для больших моделей — не способность решать новые задачи, а надёжность и воспроизводимость.

Интеграция с агентами: где работает жёсткий контроль

На момент публикации Statewright поддерживает пять агентных платформ, но уровень enforcement различается:

Claude Code получает жёсткий контроль на уровне протокола через hooks и MCP. Инструменты блокируются до того, как доходят до модели. Codex, opencode и Pi также работают с жёстким enforcement, хотя интеграции помечены как alpha. Cursor поддерживается только на уровне советов: правила встраиваются в контекст, но не блокируют вызовы инструментов принудительно — ограничение архитектуры Cursor.

Установка для Claude Code занимает минуту: добавление плагина из marketplace, установка и перезагрузка. После этого команды вроде /statewright start bugfix запускают соответствующий workflow. API-ключ для облачного gateway вводится один раз.

Как написать свой workflow

Workflow описывается в JSON, который следует опубликованной схеме. Каждое состояние содержит список разрешённых инструментов, ограничения, переходы и guard-условия. Машины состояний не являются DAG — они поддерживают циклы и повторные попытки, что критично для агентной работы.

Визуальный редактор на statewright.ai позволяет создавать workflow без ручного редактирования JSON. Агенты могут генерировать определения автоматически через инструмент statewright_create_workflow — достаточно описать задачу естественным языком. Готовые шаблоны покрывают типичные сценарии: исправление багов, рефакторинг, написание тестов, code review.

Self-hosting и ценообразование

Движок Statewright написан на Rust, не имеет внешних зависимостей и может быть встроен в любое приложение. Лицензия Apache 2.0 покрывает engine, а полный стек доступен для self-hosting под лицензией FSL, которая 3 мая 2029 года автоматически конвертируется в Apache 2.0.

Облачный сервис statewright.ai предлагает бесплатный тариф для индивидуальных разработчиков: три workflow, двести переходов в месяц, история выполнения хранится семьдесят два часа. Платные тарифы начинаются с двадцати девяти долларов в месяц за десять workflow и две с половиной тысячи переходов.

Ограничения и компромиссы

Statewright требует поддержки MCP в агенте или hooks для non-MCP платформ. Workflow пишутся вручную, хотя агенты могут их генерировать. Cursor не поддерживает жёсткий enforcement из-за архитектурных ограничений. Результаты SWE-bench получены на подмножестве из пяти задач, а не на полном бенчмарке из двух тысяч двухсот девяносто четырёх экземпляров. Если workflow слишком restrictive, агент застревает — для таких случаев предусмотрена команда statewright_deactivate, которая отключает guardrails.

Часто задаваемые вопросы

Чем Statewright отличается от обычного системного промпта?

Системный промпт — это рекомендация, которую модель может проигнорировать или забыть в процессе длинного разговора. Statewright работает на уровне протокола: инструменты физически скрыты из контекста модели, а вызовы блокируются до того, как доходят до неё. Это не совет — это архитектурное ограничение.

Можно ли использовать Statewright с локальными моделями?

Да, и именно здесь фреймворк раскрывается наиболее полно. Тесты показывают, что модели весом 3–7 ГБ с guardrails справляются с задачами, которые без них были недоступны. Это делает Statewright особенно ценным для команд, которые работают с локальными или собственными моделями по соображениям приватности или стоимости.

Как быстро создать workflow под свою задачу?

Три пути: использовать готовый шаблон из библиотеки, описать задачу агенту через инструмент statewright_create_workflow, или собрать машину в визуальном редакторе. Опытные пользователи могут писать JSON напрямую — схема опубликована и строго типизирована.

Итог

Statewright предлагает фундаментально иной подход к надёжности ИИ-агентов. Вместо гонки за большими моделями и длинными промптами он сужает пространство задачи до управляемых фаз, где даже компактная модель работает уверенно. Конечные автоматы, привычные из теории вычислений, оказываются удивительно эффективным инструментом для практической агентной инженерии. Если вы строите агентные системы — особенно на локальных моделях — guardrails вроде Statewright стоит рассмотреть до того, как увеличивать параметры модели вдвое.