AI Setup Hooks

Настройка хуков контроля правил

Перед существенной правкой правил или проверок получи ai-work-control/full; используй его результат и не выполняй контроль второй раз.

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

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

Главная граница

Хук контролирует только то, что детерминированно проверяется в артефакте на конкретном событии. Правило, требующее суждения о смысле, хуком не проверяется.

Хук-напоминание вида «примени правило X» не считается контролем: он не проверяет результат, а лишь вбрасывает текст. Если детерминированная проверка невозможна, скажи это прямо и не выдавай напоминание за контроль.

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

Режимы

• survey — обследовать события и правила, назвать кандидатов на хук без изменения файлов.
• setup — установить подтверждённые хуки в целевом проекте.
• repair — исправить существующий хук после ложных срабатываний, пропусков или расхождения проверки с источником.

Явный запрет правок означает survey. «Настрой», «добавь», «включи» означают setup, если пользователь не ограничил работу обследованием.

Обязательный порядок

1. Определи события проекта, к которым можно привязать проверку: точки Git (commit-msg, pre-commit, pre-push), запись файлов, шаги непрерывной интеграции. Определи доступные источники правил: AGENTS.md, соглашения проекта, доступные в проекте навыки.
2. Для каждого правила-кандидата проверь два условия: оно привязано к детерминированному событию и проверяет наблюдаемое свойство артефакта без суждения. Кандидатом на хук считай только правило, прошедшее оба условия.
3. Для правила, которое нельзя проверить детерминированно, не предлагай хук-напоминание. Прямо назови, что внешний контроль здесь невозможен, и оставь правило зоне применения соответствующего навыка или ревью человека.
4. Веди установку интерактивно и по одному хуку. Для каждого кандидата:
   • покажи саму проверку и пример срабатывания на плохом и хорошем входе;
   • объясни пользу для пользователя — что даёт автоматический контроль, а не какое правило этого требует;
   • дождись отдельного подтверждения именно этого хука;
   • установи хук только после подтверждения.
5. Размести логику проверки как артефакт целевого проекта, а хук сделай тонкой обёрткой, вызывающей эту логику. Активацию (например путь к каталогу хуков) опиши так, чтобы её можно было воспроизвести в другом клоне.
6. Обеспечь идемпотентность: распознай уже установленный хук и не дублируй его; предлагай обновление только при расхождении проверки с источником.
7. В отчёте назови обследованные события и источники правил, кандидатов и причину отбора, установленные по подтверждению хуки, место логики проверки и способ активации, остаточные риски.

Ограничения

• Не превращай хук в напоминание без проверки артефакта.
• Не зашивай в навык конкретные правила проекта, имена навыков или модели: правила выводятся из проекта в момент настройки.
• Не используй хук как основной переносимый путь доставки: это опциональный примитив ограниченного набора сред.
• Не устанавливай хук без отдельного подтверждения пользователя и не объединяй подтверждения нескольких хуков в один список.
• Не блокируй событие проверкой с высоким риском ложного срабатывания без явного согласия пользователя; при сомнении предложи мягкий режим или сужение правила.