TL;DR
Одна и та же задача, одни и те же инструменты — но качество документации изменило результат с 10% до 80% успешных выполнений. Исследователи из Sidia взяли 10 идентичных API-endpoints и подключили к ним ИИ-агент дважды: сначала с оригинальными описаниями, потом с обогащёнными. Функциональность не менялась — только текстовые описания. Разрыв оказался радикальным.
ИИ срывается не там, где "не хватает мощности" — а там, где контекст слабый. В оригинальной документации агент провалился на этапе планирования в ~70% задач: не мог понять что делает инструмент, что ему передать, что получить в ответ. Описания были технически корректны, но семантически пусты — написаны для людей, которые "и так всё знают". Агент такого неявного знания не имеет.
Исследователи выделили 9 категорий "смеллов" (smell — дословно "запах", термин из практики кода) — признаков, по которым контекст разваливается. Эти категории универсальны: они одинаково работают и для API-документации, и для инструкций, которые вы даёте ИИ в чате.
Схема метода
Метод работает в одном промпте — это аудит-запрос.
ШАГ 1: Берёшь инструкцию/промпт/бриф → передаёшь в аудит-запрос
ШАГ 2: ИИ проверяет по 9 категориям смеллов → находит проблемы
ШАГ 3: ИИ объясняет каждую проблему + даёт конкретное улучшение
ШАГ 4: Ты видишь диагностический отчёт → переписываешь слабые места
Все шаги — в одном диалоге с ИИ.
Пример применения
⚠️ Сильная зона метода: Структурированные инструкции с несколькими требованиями — системные промпты, ТЗ для ИИ, брифы, шаблоны задач. Не работает для коротких импульсивных вопросов.
Задача: Ты настраиваешь GPT-ассистента для отдела маркетинга «Сбера» — пишешь системный промпт, который ИИ будет получать перед каждой задачей. Промпт написан, но результаты нестабильные: иногда отлично, иногда мимо.
Промпт:
Ты — опытный аудитор инструкций для ИИ.
Проверь мои инструкции по 9 категориям "смеллов" — признаков,
из-за которых ИИ теряет понимание задачи:
ДОКУМЕНТАЦИОННЫЕ СМЕЛЛЫ (качество описания):
- LAZY (ленивый): Описание слишком короткое, расплывчатое или
использует дефолтные фразы — "обрабатывает данные", "возвращает
результат", "выполняет операцию". ИИ не понимает сути.
- BLOATED (раздутый): Много слов — мало смысла. Объём текста не
равен информационной ценности.
- TANGLED (запутанный): В одном абзаце смешаны разные темы —
бизнес-логика, ограничения, формат ответа, краевые случаи.
- FRAGMENTED (фрагментированный): Связанные инструкции разбросаны
по разным местам без явной связи между собой.
СТРУКТУРНЫЕ СМЕЛЛЫ (полнота контекста):
- INPUT (вход): Не описано что именно ИИ получает на вход —
формат, обязательные поля, допустимые значения, примеры.
- RESPONSE (выход): Не описан ожидаемый формат ответа — структура,
длина, стиль, что делать при разных условиях.
- SECURITY (ограничения): Не прописаны запреты, ограничения,
что делать в неожиданных ситуациях.
- PATH (именование): Названия ролей/задач/функций не отражают суть.
"Помощник" вместо "редактор SMM-постов для Telegram".
- METHOD (действие): Глагол действия неточный или отсутствует.
"Работай с текстом" вместо "сокращай текст до 280 символов".
Мои инструкции для аудита:
---
{вставь свои инструкции}
---
Для каждого найденного смелла:
1. Укажи категорию
2. Процитируй проблемный фрагмент
3. Объясни в чём проблема
4. Дай конкретное улучшение
Результат:
Модель пройдёт по каждой из 9 категорий и выдаст структурированный диагностический отчёт. Для каждого найденного смелла — цитата из твоего текста, объяснение почему это проблема, и конкретное переписанное предложение. Промпты с LAZY-смеллами ("отвечай полезно") получат конкретизированные версии. Промпты без описания выхода (RESPONSE) получат шаблон формата ответа. В финале — рейтинг уязвимости по категориям.
Почему это работает
ИИ не "понимает" контекст так, как понимаем его мы. Когда вы пишете "отвечай профессионально" — вы слышите в этом годы опыта, понимание аудитории, эстетику тона. Модель видит два слова без якорей. Она генерирует ответ по наиболее частотному паттерну для слова "профессионально" — и это может быть что угодно.
У ИИ нет неявного знания, зато есть острая чувствительность к структуре. Именно поэтому одна и та же бизнес-логика в эксперименте дала 10% успеха с тонкими описаниями — и 80% с подробными. Модель не стала умнее. Ей просто убрали туман.
Смеллы — это диагностические категории, а не оценочные суждения. LAZY — не значит "плохо написал". Это значит: у модели нет материала для различения. TANGLED — это не "сложно". Это сигнал: модель не знает какую из смешанных инструкций применять первой. Зная категорию — знаешь лечение.
Рычаги управления: - Глубина аудита → попроси проверить только 2-3 категории (например, INPUT + RESPONSE) — быстрее, фокуснее - Формат вывода → добавь "дай итоговую оценку по каждой категории от 1 до 5" — получишь скоринговую карту - Приоритизация → добавь "сначала найди самую критичную проблему" — если времени мало - Сравнение версий → передай два варианта промпта и попроси сравнить по смеллам — выберешь лучший
Шаблон промпта
Ты — аудитор инструкций для ИИ.
Проверь текст по 9 категориям смеллов — признаков слабого контекста:
ДОКУМЕНТАЦИОННЫЕ:
- LAZY: расплывчато, слишком коротко, дефолтные слова
- BLOATED: много слов, мало смысла
- TANGLED: разные темы смешаны в одном блоке
- FRAGMENTED: связанные инструкции разбросаны без связи
СТРУКТУРНЫЕ:
- INPUT: не описан формат и содержание входных данных
- RESPONSE: не описан формат и структура ожидаемого ответа
- SECURITY: не прописаны ограничения и запреты
- PATH: название роли или задачи не отражает суть
- METHOD: действие сформулировано нечётко или отсутствует
Текст для аудита:
---
{инструкция / промпт / бриф / ТЗ}
---
Для каждого найденного смелла:
1. Категория
2. Цитата из текста
3. Объяснение проблемы
4. Конкретное улучшение
Плейсхолдер: {инструкция} — вставь системный промпт, инструкцию ассистенту, бриф для ИИ, шаблон задачи или любой текст, по которому ИИ должен работать.
🚀 Быстрый старт — вставь в чат:
Вот шаблон smell-аудита инструкций. Адаптируй под мою задачу: {твоя задача}.
Задавай вопросы, чтобы понять что именно аудировать.
[вставить шаблон выше]
LLM спросит какие инструкции/промпты/брифы ты хочешь проверить — потому что без этого материала аудит невозможен. Она возьмёт структуру 9 категорий из шаблона и применит к твоему конкретному тексту.
Ограничения
⚠️ Не для коротких сообщений: Аудит работает на структурированных инструкциях — системных промптах, брифах, шаблонах, ТЗ. На вопросах типа "объясни мне про квантовую физику" смеллы неприменимы — там другая логика.
⚠️ Субъективность некоторых категорий: BLOATED и TANGLED — размытые границы. Что одному кажется "лишним", другому — необходимым контекстом. Используй как направление, не как жёсткий приговор.
⚠️ Не заменяет итерацию: Аудит покажет где слабо — но проверить улучшение всё равно нужно в деле. Смелл-чистый промпт ≠ гарантированно рабочий промпт.
⚠️ RESPONSE-смелл — системный: В оригинальном исследовании он встречался в 100% случаев. Это значит: описание ожидаемого выхода пропускают почти всегда. Проверяй в первую очередь.
Ресурсы
Making OpenAPI Documentation Agent-Ready: Detecting Documentation and REST Smells with a Multi-Agent LLM System — EASE 2026, Glasgow
Авторы: Rayfran Rocha Lima, Davi G. Assuncao Pinheiro, Thiago Medeiros de Menezes — Sidia Institute of Technology, Manaus, Бразилия
Смелл-таксономия документации базируется на: Khan et al. [11] — документационные смеллы в программном обеспечении