← Назад в блог

Управление агентом, правила и хуки: свисток арбитра в кодовой базе

8 ноября 2026 г. · 4 мин чтения
Управление агентом, правила и хуки: свисток арбитра в кодовой базе - Почему правила в AGENTS.md игнорируются, как хуки блокируют битый код и зачем разделять планировщика, исполнителя и ревьюера.

Инженер добавляет в корневой файл проекта строгое правило: «Всегда запускай тесты перед завершением задачи и никогда не оставляй сломанных импортов».

Через три шага сложного рефакторинга кодинг-агент переписывает шесть файлов, напрочь игнорирует команду запуска тестов и бодро рапортует: «Рефакторинг завершен! Все функции обновлены согласно вашим требованиям».

Разработчик открывает git diff и видит сломанный синтаксис и дюжину упавших тестов.

Ошибка произошла из-за того, что текстовые советы перепутали с механическим контролем.

В футболе тренер может долго объяснять в раздевалке: «Ни в коем случае не играйте рукой в своей штрафной площади». Это тактическая установка. Но когда защитник теряет равновесие, а мяч летит в угол ворот, рефлекс берет верх над словами тренера. Рука непроизвольно идет к мячу.

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

В работе с агентами файлы вроде AGENTS.md или CLAUDE.md — это предматчевая установка тренера. Хуки — это свисток арбитра.


Реальность

Языковые модели работают на вероятностях. Когда контекст переполняется, текстовые правила из файлов конфигурации начинают размываться. Если агент сталкивается с запутанной ошибкой, его алгоритм стремится быстрее завершить диалог и убедить пользователя в успехе.

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

1. Общие знания о репозитории (AGENTS.md)

Этот файл должен занимать не больше одной страницы. Он фиксирует базовые факты: пакетный менеджер, команду запуска тестов и архитектуру проекта. Если засунуть туда полсотни мелких правил, модель будет тратить токены на каждом запросе и быстрее терять фокус.

2. Локальные правила каталогов (Path-scoped rules)

Агенту, который верстает кнопки в CSS, не нужны правила миграции таблиц базы данных. Локальные инструкции размещают внутри конкретных папок, и фреймворк подгружает их только тогда, когда агент открывает файлы из этого каталога. Правило «все хендлеры API обязаны валидировать входные данные через Zod» должно лежать в папке api, а не в корне проекта.

3. Автоматические проверки: хуки (Hooks)

Хук — это не промпт. Это исполняемый консольный скрипт внутри фреймворка агента.

Когда модель пытается завершить работу и отдать результат, хук остановки (Stop Hook) запускает линтер и тесты в фоновом режиме. Если команда завершается с ошибкой, фреймворк блокирует завершение задачи. Он перехватывает вывод терминала и отправляет его обратно в модель как новое наблюдение.

Модель физически заперта внутри цикла, пока тесты не станут зелеными. Вы не просите агента протестировать код. Вы делаете выход невозможным, пока проверка не пройдет.


Почему это важно

Почему один агент не может качественно проверить собственный код?

Когда один агент планирует, пишет и проверяет собственный код, он попадает в ловушку предвзятости подтверждения (confirmation bias): модель считает свое решение верным просто потому, что только что его сгенерировала. Разделение задачи на трех независимых субагентов разрушает эту иллюзию:

  1. Планировщик с правами только на чтение исследует код и формирует спецификацию, не меняя файлы на диске.
  2. Исполнитель меняет код строго по утвержденному плану.
  3. Ревьюер проверяет получившийся git diff, не имея доступа к черновикам планировщика, оценивая результат свежим взглядом.

В чем подвох?

Раздувание инструкций и медленные проверки.

Когда разработчики превращают AGENTS.md в свалку заметок, файл разрастается до сотен строк. Агент тратит половину внимания на чтение нерелевантных правил перед каждым действием. Другая крайность — тяжелые хуки, запускающие пятнадцатиминутные сквозные тесты на каждый чих. Хуки должны быть быстрыми и строгими: проверка типов, линтинг и легковесные юнит-тесты.

Главная мысль

Текстовое правило в инструкции просит о соблюдении порядка; исполняемый хук гарантирует его.


Специалисты по ИИ называют это: Управление репозиторием (Repository Steering) / Локальные правила (Path-Scoped Rules) / Детерминированные хуки (Deterministic Hooks) / Триада субагентов
Следование инструкциям деградирует по мере насыщения контекста. Критические ограничения должны гарантироваться детерминированно за рамками инференса языковой модели с помощью хуков жизненного цикла (проверки перед вызовом инструментов, валидация правок и блокировка завершения). Корневой файл AGENTS.md фиксирует инварианты окружения, а локальные правила изолируют контекст. Разделение планирования, кодогенерации и ревью на независимых субагентов устраняет предвзятость самопроверки.

💬 Какое правило в вашем репозитории ИИ-агенты игнорируют чаще всего?

Часть 4 из 10 | #CodingAgentsForHumans

Есть проект на прицеле?

Давайте обсудим, как мы можем помочь.

Есть идея проекта? →