Output contract в SKILL.md: как убрать лишние комментарии AI-агента

Что такое output contract в Agent Skill?

Output contract - это явное описание конечного артефакта: какие поля и разделы обязательны, сколько подробностей допустимо, где хранить доказательства и при каких условиях результат считается готовым. Контракт не диктует ход рассуждения модели. Он ограничивает то, что получает пользователь или следующая система.

Фразы «ответь кратко» обычно мало: непонятно, можно ли пропустить риск, куда вынести логи и что делать при неполных данных. Рабочий контракт отвечает на эти вопросы до запуска и даёт ревьюеру одинаковую рамку для каждого результата.

Почему AI-агент пишет слишком много?

Многословие появляется, когда запрос смешивает задачу, отчёт о процессе и объяснение для новичка. Модель старается закрыть все три ожидания сразу. Если в skill нет приоритета и лимита, в финальный ответ попадают промежуточные действия, очевидные пояснения и повтор результата другими словами.

Какие поля нужны в контракте результата?

Минимальный контракт задаёт цель, аудиторию, формат, обязательные поля, лимит объёма, правила для неопределённости и критерий готовности. Для автоматической обработки добавьте машинно-проверяемую схему. Для текста достаточно короткого шаблона и нескольких assertions, которые редактор или программа могут проверить без субъективного толкования после каждого запуска.

• Outcome: какой артефакт должен остаться после работы.
• Audience: кто примет решение по результату.
• Shape: таблица, список, файл, JSON или короткая записка.
• Required: какие сведения нельзя опустить.
• Budget: максимальное число пунктов, строк или слов.
• Uncertainty: как обозначить неизвестное и блокеры.
• Evidence: где лежат тесты, ссылки или полный журнал.
• Done: какие проверки должны пройти.

Если результат должен проходить автоматическую проверку, добавьте подход из статьи как встроить validator и доказательства.

Как записать output contract в SKILL.md?

Поместите контракт рядом с инструкцией финального шага и сформулируйте его как наблюдаемый результат. Укажите точные заголовки, порядок, пределы и поведение при блокере. Подробные примеры вынесите в reference, чтобы основной SKILL.md оставался коротким и загружался без лишнего контекста при каждом срабатывании навыка.

1. 1. Назовите единственный основной артефакт

   Например: список замечаний к diff, решение по поставщику или готовый файл отчёта.

2. 2. Зафиксируйте форму

   Задайте обязательные разделы, порядок и максимальный размер каждого блока.

3. 3. Отделите итог от evidence

   В ответе оставьте краткое подтверждение, а полный вывод сохраните в файл или ссылку.

4. 4. Опишите честный отказ

   При нехватке данных агент перечисляет блокеры и не выдумывает завершённый результат.

5. 5. Добавьте отрицательные примеры

   Покажите, какие повторы, логи и пояснения не должны попадать в финал.

Когда хватает инструкции, а когда нужна схема?

Текстовой инструкции хватает, если результат читает человек и небольшое отклонение не ломает процесс. Когда ответ разбирает программа, используйте поддерживаемый клиентом или API режим структурированного вывода и проверяйте результат по схеме. Для файлов и команд подойдёт отдельный validator с однозначным успешным или ошибочным статусом.

Разницу между мягкой инструкцией и техническим гейтом раскрывает материал skill, hook или workflow.

Как проверить контракт на реальных задачах?

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

1. 1. Соберите пять типовых запросов

   Добавьте простой, длинный, неоднозначный, ошибочный и пограничный сценарий.

2. 2. Сохраните baseline

   Измерьте размер ответа, обязательные поля и время редактора до изменения skill.

3. 3. Запустите те же запросы

   Не меняйте модель, данные и разрешения одновременно с контрактом.

4. 4. Проверьте потери

   Убедитесь, что риски, блокеры и evidence сохранились после сокращения.

5. 5. Зафиксируйте решение

   Оставьте контракт, если он снижает ручную правку без роста критических пропусков.

Для контролируемого сравнения используйте протокол тестирования Agent Skill.

Какие ошибки делают ответ короче, но хуже?

Опасные сокращения запрещают объяснять блокер, прячут допущения, удаляют evidence или требуют фиксированное число пунктов независимо от задачи. Ещё одна ошибка - пытаться управлять каждым словом десятками запретов. Такой контракт разрастается, конфликтует сам с собой и снова создаёт лишний контекст вместо понятной формы результата.

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

С какого минимального контракта начать?

Начните с четырёх блоков: итог, выполненные действия, блокеры и проверки. Ограничьте итог двумя предложениями, действия - пятью пунктами, а доказательства вынесите в отдельный артефакт. После пяти реальных запусков поправьте только те правила, которые устраняют наблюдаемую ошибку или сокращают повторяющуюся ручную правку.

Такой контракт помещается в несколько строк и уже отделяет полезный результат от служебного шума. Если процесс стабилизировался, добавьте схему или linter для правил, которые можно проверить автоматически.

Если нужен разбор вашего SKILL.md и готовый контракт под процесс, оставьте заявку на внедрение.