База знаний по AI и LLM

Комплексное руководство по работе с AI-агентами, LLM и внедрению искусственного интеллекта в процессы разработки.

Автор: Владимир Ломтев

Глоссарий

Глоссарий: Основные термины

LLM и базовые понятия

LLM (Large Language Model) — большая языковая модель, которая умеет понимать и генерировать текст, опираясь на закономерности в огромных наборах данных.

Токен — минимальная единица текста для модели. Это не всегда слово: токеном может быть часть слова, знак препинания или целое короткое слово.

Контекстное окно — предел объёма данных, обрабатываемых моделью в одном запросе. Размер, допустимый выход и учёт reasoning-токенов зависят от модели и API. Большое окно не гарантирует одинаковую точность работы со всеми его частями; подробнее — Context Engineering.

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

Inference — процесс запуска модели для получения ответа.

Параметры модели — внутренние численные веса, в которых "зашиты" знания и закономерности, выученные при обучении.

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

Fine-tuning — дополнительная настройка модели на специальном наборе данных под задачу, стиль или домен.

Embedding — числовое представление текста, в котором похожие по смыслу фрагменты находятся близко друг к другу.

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

Hallucination / галлюцинация — ситуация, когда модель уверенно сообщает неверную или выдуманную информацию.

Техники промптинга

Few-shot prompting — способ работы с моделью, когда в промпт добавляют несколько примеров желаемого ответа.

Zero-shot — когда модель решает задачу без примеров, только по инструкции.

Chain-of-thought — пошаговое рассуждение модели. На практике часто важно не само длинное рассуждение, а хорошо структурированный ответ.

Архитектура

Transformer — архитектура нейросети, на которой основано большинство современных LLM.

Attention — механизм, который помогает модели понимать, какие части текста важны в текущем контексте.

RAG и агенты

RAG (Retrieval-Augmented Generation) — подход, при котором модель сначала получает внешние данные из базы знаний или поиска, а потом формирует ответ на их основе.

AI-агент — программная система на базе модели, которая получает цель, собирает необходимый контекст, выбирает допустимые инструменты, выполняет действия, оценивает наблюдения и продолжает цикл до достижения условия остановки.

Agentic system / агентная система — общий термин для системы, в которой модель участвует в выборе действий. Может включать одного агента, детерминированный workflow с агентными шагами или несколько координируемых агентов.

Agent Harness / обвязка агента — программная среда вокруг модели, которая собирает контекст, регистрирует инструменты, исполняет вызовы, хранит состояние, применяет права и управляет циклом выполнения.

Agent Loop / агентный цикл — повторяющаяся последовательность: получить состояние → выбрать действие → выполнить инструмент → получить наблюдение → проверить результат → продолжить или остановиться.

Agentic Workflow — процесс с детерминированным каркасом, внутри которого модель самостоятельно принимает отдельные решения: классифицирует ситуацию, выбирает ветвь, ищет контекст или готовит действие.

Агентность — степень свободы системы при выборе контекста, инструментов, последовательности шагов и момента остановки.

Автономность агента — объём решений и действий, которые агент может выполнить без промежуточного участия человека. Оценивается отдельно для планирования, доступа к данным, выбора инструментов, записи и внешних коммуникаций.

Tool use / вызов инструментов — способность агента пользоваться внешними средствами: поиском, калькулятором, API, календарем, почтой, базой данных.

Function calling — формат, в котором модель не просто пишет текст, а выбирает структуру вызова нужного инструмента с аргументами.

Компоненты агентов

Planner — компонент агента, который решает, какие шаги нужны для достижения цели.

Executor — компонент, который выполняет выбранные шаги и вызывает инструменты.

Observation — результат действия агента: например, ответ API, результат поиска, состояние базы данных.

Action — конкретное действие агента: сделать запрос, прочитать файл, отправить письмо, пересчитать данные.

State / состояние агента — структурированная запись о текущем положении задачи: цель, статус, подтверждённые факты, выполненные действия, артефакты, ошибки, бюджет и контрольная точка.

Trajectory / траектория — последовательность решений, вызовов инструментов и наблюдений, через которую агент пришёл к результату.

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

Stop condition / условие остановки — формальное правило завершения цикла: критерии готовности выполнены, требуется подтверждение, достигнут лимит, возникла невосстановимая ошибка или задача отменена.

Checkpoint / контрольная точка — сохранённое согласованное состояние, с которого агент может безопасно возобновить работу после сбоя.

Handoff / передача управления — переход задачи от агента к человеку или другому агенту вместе с состоянием, результатами, открытыми вопросами и причиной передачи.

Память

Compaction / сжатие контекста — сокращение истории для следующих запросов с сохранением существенных решений и состояния. Сводка требует проверки актуальности и может терять детали.

KV cache — переиспользуемые представления ранее обработанных токенов при генерации; не долговременная память пользователя.

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

Memory / память агента — механизм сохранения информации между шагами или сессиями.

Short-term memory — краткосрочная память в рамках текущей задачи или диалога.

Long-term memory — долговременная память о предпочтениях, фактах или прошлых действиях пользователя.

Подходы и паттерны

ReAct — подход, где модель чередует рассуждение и действия: подумать → вызвать инструмент → посмотреть результат → продолжить.

Multi-agent system — система, где несколько агентов с разными ролями работают вместе.

Supervisor agent — агент-координатор, который распределяет задачи между другими агентами.

Critic / reviewer — агент или этап проверки, который оценивает качество промежуточного результата.

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

Orchestration — управление несколькими моделями, агентами, инструментами и шагами в одном процессе.

Guardrails — проверки и ограничения, предназначенные для удержания поведения в заданных границах. Их надёжность зависит от реализации; текстовая инструкция не равна техническому запрету.

Human-in-the-loop — режим, в котором человек подтверждает ключевое действие до его исполнения.

Human-on-the-loop — режим, в котором агент действует самостоятельно в ограниченной области, а человек наблюдает, получает уведомления и может вмешаться.

Human-out-of-the-loop — режим без оперативного участия человека в отдельных запусках. Требует формальных критериев, минимальных прав, автоматических проверок, мониторинга и аварийной остановки.

Retry / повторная попытка — повтор операции после временной ошибки. Для действий с побочным эффектом требует ограничения числа попыток и защиты от дубликатов.

Idempotency / идемпотентность — свойство операции, при котором безопасный повтор не создаёт дополнительного эффекта. Критично для платежей, отправки сообщений и создания записей.

Rollback / откат — возврат системы в подтверждённое состояние после неудачного или ошибочного изменения.

Blast radius / радиус поражения — максимальный объём данных, пользователей или систем, на которые может повлиять один ошибочный запуск агента.

Intent drift / дрейф намерения — постепенное отклонение действий агента от исходной цели по мере накопления промежуточных решений и контекста.

Метрики и оценка

Evaluation / evals — тесты и метрики для проверки качества модели или агента.

Latency — задержка между запросом и ответом.

Cost per token — стоимость обработки входных и выходных токенов.

Rate limit — ограничение нагрузки: например, запросов или токенов за интервал, параллельных операций либо другого ресурса.

Alignment — насколько поведение модели соответствует намерениям разработчиков и ожиданиям пользователя.

Безопасность

Prompt injection — попытка через входные данные подсунуть модели вредную инструкцию и изменить ее поведение.

Инструменты и протоколы

SOTA — state of the art: передовой результат в конкретной задаче и условиях сравнения на определённую дату. Не означает универсально лучшую модель.

MCP (Model Context Protocol) — открытый протокол, который стандартизирует, как AI-приложение подключается к внешним данным и инструментам: файлам, базам данных, API, поиску и другим системам.

ACP (Agent Client Protocol) — протокол взаимодействия клиентского интерфейса с кодирующим агентом; подробнее — ACP.

LSP (Language Server Protocol) — протокол языковых возможностей, включая навигацию и диагностику кода; подробнее — LSP.

Structured Output — получение данных по схеме при поддержке модели и API. Соответствие формату не доказывает истинность значений.

Skill — переиспользуемый пакет инструкций и ресурсов для конкретного типа задач.

Hook — обработчик события или точка расширения в жизненном цикле агента. Hook позволяет выполнить дополнительную логику "до", "после" или "во время" какого-то шага — например, перед вызовом инструмента, после получения результата, при handoff между агентами или при завершении run.

Code execution — выполнение предложенного моделью кода внешней программой. Может использоваться для расчётов, обработки файлов и проверки гипотез. Наличие и качество изоляции зависят от среды исполнения.

Основы LLM

Основные принципы LLM

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

Что происходит при запросе

  1. Приложение собирает инструкции, сообщения и нужные данные.
  2. Токенизатор преобразует вход в последовательность токенов.
  3. Модель обрабатывает контекст и генерирует продолжение.
  4. Приложение показывает ответ либо выполняет предложенный вызов инструмента.

Для обычного чата результатом будет текст. У AI-агента ответ модели становится одним из шагов более длинного процесса.

Обучение, контекст и память

МеханизмЧто хранитКак обновляется
Параметры моделиЗакономерности, усвоенные при обученииОбучением или дообучением
Контекст запросаДанные текущего вызоваПри сборке очередного запроса
Память приложенияИсторию, предпочтения, решенияЗаписями во внешнем хранилище

Сообщение «запомни» само по себе не меняет веса модели. Чат может сохранять историю и подставлять её в будущие запросы, но это свойство приложения. Подробнее: контекст и память.

Ограничения, которые влияют на работу

Знания могут устареть. Дата среза не гарантирует знание каждого факта до неё. Для изменяемой информации нужны свежие источники.

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

Повторяемость ограничена. Одинаковые запросы могут дать одинаковые или разные ответы. Низкая температура не доказывает корректность и не гарантирует полную воспроизводимость всей системы.

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

Практический пример

Вместо «объясни, почему упал сервис» передайте время сбоя, обезличенный фрагмент лога, последнее изменение и ожидаемое поведение. Попросите разделить наблюдения, гипотезы и способы проверки. Причину подтверждает проверка гипотезы, а не уверенность формулировки.

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


Выбор LLM и инструментов

Проверено: 8 сентября 2026. Доступность моделей, тарифы и возможности клиентов меняются; перед подключением проверяйте документацию поставщика.

Модель, приложение и тариф — разные вещи. Модель обрабатывает запрос. IDE, терминальный агент или чат определяют доступ к файлам, инструментам и памяти. Тариф задаёт оплату и ограничения. Название продукта не всегда совпадает с идентификатором модели в API.

Как выбрать модель

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

КритерийЧто измерять
КачествоДолю результатов, принятых после проверки
ИнструментыПравильность выбора операции и аргументов
КонтекстУмение находить нужные факты в ваших документах
ЗадержкаВремя до полезного результата, включая повторы
СтоимостьПолные затраты на принятую задачу
ЭксплуатацияДоступность, лимиты, обработку ошибок, управление данными

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

Где смотреть актуальный состав

Например, официальный каталог OpenAI на дату проверки выделяет GPT-6 Astra для сложных задач, GPT-5.6 Terra для баланса возможностей и стоимости и GPT-5.6 Luna для массовых экономичных запусков. Это позиционирование поставщика, а не сравнительный рейтинг всех LLM. Идентификаторы и ограничения приведены в каталоге моделей OpenAI.

Для сравнения с другими экосистемами используйте их первичные каталоги:

ЭкосистемаПримеры на дату проверкиГде проверять
AnthropicClaude Fable 5.1, Opus 5, Sonnet 5, Haiku 4.5Модели Claude
GoogleGemini 3.8 Flash, 3.5 Flash-LiteМодели Gemini API
Модели с доступными весамиНапример, опубликованные варианты QwenКаталог разработчика Qwen

Это примеры для поиска кандидатов, а не полный список и не рекомендация выбирать по номеру версии. Для скачиваемых весов читайте карточку конкретной модели: доступность, лицензия и требования отличаются даже внутри семейства. Назначение таких карточек объясняет Hugging Face.

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

Как выбрать приложение

  • IDE: удобна для изменений с навигацией по коду и просмотром diff.
  • Терминальный агент: подходит для команд, скриптов и работы в репозитории.
  • Веб-чат: полезен для обсуждения и документов; доступ к проекту зависит от подключённых средств.
  • API: нужен для собственного продукта и управляемых автоматических процессов.

Проверьте поддержку вашего стека, правила доступа, восстановление сессий и переносимость настроек. Общий список критериев — в оценке агентской платформы.

Локальное размещение и расходы

Для self-host нужны доступные веса, подходящая лицензия и достаточные ресурсы для выбранной модели, контекста и параллельности. Наличие облачного API не означает доступность весов для скачивания. Учитывайте обслуживание, оборудование и качество после квантования.

Подписка может быть удобна для ручной работы, API — для нерегулярной нагрузки или автоматизации. Универсальной обязательной цены нет. Считайте стоимость принятого результата вместе с временем сотрудника; подробнее — оптимизация расходов.


Оптимизация расходов на LLM

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

Из чего складывается стоимость

Учитывайте входные и выходные токены, платные инструменты, поиск, хранение, повторные попытки и проверку человеком. У провайдера могут быть отдельные правила оплаты кэширования и reasoning-токенов.

Учебный расчёт: при условных ценах 1 единица за миллион входных токенов и 4 за миллион выходных запрос с 20 000 входных и 2 000 выходных стоит 0,028 единицы. Это пример арифметики, не действующий тариф. Три одинаковых запуска стоят уже 0,084 до учёта инструментов.

KV cache и prompt caching

KV cache переиспользует представления ранее обработанных токенов при генерации. Это механизм вычисления модели, а не долговременная память пользователя. Он уменьшает повторную работу, но занимает память. Механизм описан в документации Transformers.

Prompt caching позволяет переиспользовать вычисления для повторяющегося префикса запросов. Размещайте устойчивые инструкции и примеры перед изменяемыми данными. Условия попадания, время хранения и стоимость записи зависят от провайдера и модели: нельзя обещать одну скидку всем запросам. Проверяйте фактический usage, включая запись и чтение кэша. Пример правил — OpenAI Prompt caching.

Практический порядок оптимизации

  1. Запишите исходные качество, задержку и затраты на типичных задачах.
  2. Уберите дублирующиеся инструкции и нерелевантные результаты инструментов.
  3. Запрашивайте нужные диапазоны, поля и страницы вместо полных выгрузок.
  4. Ограничьте бессмысленные повторы и зацикливание.
  5. Сравните более дешёвую модель на простых подзадачах.
  6. Проверьте кэширование на повторяющейся нагрузке.
  7. Повторно оцените качество: потеря важных данных не считается успешной экономией.

Что можно выполнять асинхронно

Классификацию архива или подготовку эмбеддингов можно вынести из интерактивного пути. Пакетные API подходят независимым заданиям без требования немедленного ответа; скидки, поддерживаемые операции и сроки выполнения определяет сервис. Сверяйте условия, например в руководстве OpenAI Batch.

Какие метрики оставить в отчёте

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


Риски и ограничения

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

Основные риски

РискКак проявляетсяПрактическая мера
Выдуманные сведенияНесуществующая функция или источникПроверить документацию и фактическое выполнение
Устаревшие данныеРешение для другой версии библиотекиЗафиксировать версию и открыть соответствующее руководство
Потеря контекстаЗабыто согласованное ограничениеХранить решения и критерии отдельно от длинного чата
Ошибка действияИзменён не тот файл или объектОграничить область записи и проверять diff
Утечка данныхВ запрос попали секретыМинимизировать передаваемые данные и права
ЗацикливаниеПовторяется неудачная операцияВвести бюджет попыток и условие остановки
Избыточное решениеМаленькая задача породила новую подсистемуУказать границы и критерии достаточности

Prompt injection

Инструкции могут быть спрятаны в странице, документе, комментарии к коду или ответе инструмента. Например, найденный файл предлагает передать секрет на внешний адрес. Содержимое источника следует обрабатывать как данные, а право на действие проверять отдельно от текста модели.

Фильтрация текста — только один слой. Важны ограничение инструментов, контроль исходящих соединений и прав доступа. Для выполняемого кода используйте подходящую песочницу. Общий принцип отделения недоверенного контента от управления рассмотрен в рекомендациях OpenAI по безопасности агентов.

Как распределить контроль

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

Для нового сценария сначала проверьте работу на ограниченной области. Расширяйте автономность после наблюдаемого результата. Подробности — в уровнях автономности.

Как не потерять собственную экспертизу

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

Признаки готовности результата

Есть проверяемый артефакт, выполнены требования, известны ограничения и зафиксированы реальные результаты проверок. Если команда видит только сообщение «готово», задача ещё не прошла приёмку.

Техники промптинга

Принципы промптинга

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

Рабочая структура

БлокЧто указать
ЦельКакой результат нужен и кому
КонтекстФакты, документы, версии, исходное состояние
ОграниченияДопустимые действия, границы и запреты
ФорматТаблица, документ, diff или структурированный объект
ПриёмкаПо каким признакам результат подходит
НеопределённостьКогда задать вопрос или сообщить о нехватке данных

Пример для разработки

Цель: исправить сброс фильтра каталога после обновления страницы.
Контекст: URL содержит выбранную категорию; шаги воспроизведения приложены.
Ограничения: сохранить текущий API и поведение остальных фильтров.
Сначала найди источник состояния и объясни причину сброса.
После исправления проверь открытие прямой ссылки, обновление и сброс фильтров.
В отчёте укажи изменения и фактически выполненные проверки.

Здесь есть наблюдаемая проблема и проверяемый результат. Запрос «улучши фильтры» оставляет и причину, и границы на усмотрение модели.

Примеры, роли и уточнения

Примеры полезны, когда формат или граница между классами неоднозначны. Несколько разных корректных примеров обычно информативнее длинного перечня запретов. Подробнее — Few-shot.

Роль «редактор технической документации» задаёт ракурс и стиль. Она не даёт модели реальный опыт, доступ к данным или право принимать решение от имени специалиста.

Уточняющий вопрос нужен, если неизвестное меняет результат: например, формат экспорта или правило округления. Для несущественной детали можно разрешить разумное допущение с явной пометкой.

Проверка и итерации

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

Самокритика модели помогает улучшать текст, но не является независимым подтверждением фактов. Для чисел, ссылок и действий используйте внешнюю проверку. Официальное руководство по структуре и примерам: OpenAI Prompt engineering.


Zero-shot prompting

Zero-shot — постановка задачи без демонстрационных примеров решения. При этом запрос может содержать инструкции, исходный документ и ограничения: отсутствие примеров не означает отсутствие контекста.

Когда подходит

Начните с zero-shot, если задача достаточно однозначна: перевести абзац, выделить даты из текста, сократить описание или перечислить отличия двух предоставленных версий. Так проще понять, нужна ли дополнительная настройка.

Для нестандартного стиля или спорных категорий добавьте few-shot примеры, если одной инструкции недостаточно.

Практический пример

Из приведённого описания задачи выдели:
1. Ожидаемое поведение.
2. Наблюдаемое поведение.
3. Шаги воспроизведения.
Если информации нет, напиши «не указано». Не дополняй её предположениями.

Описание: после выбора категории «Книги» и обновления страницы
снова показываются товары всех категорий.

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

Как проверить ответ

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

Частые ошибки

  • Требовать точный результат, не предоставив обязательные исходные данные.
  • Смешивать несколько задач с несовместимыми форматами вывода.
  • Просить модель использовать информацию, к которой у неё нет доступа.
  • Считать один удачный ответ достаточным доказательством качества для потока запросов.

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


Few-shot prompting

Few-shot — передача нескольких примеров входа и ожидаемого результата прямо в контексте. Модель использует их в текущем запросе; это не дообучение её параметров.

Когда добавлять примеры

Приём полезен для единого редакционного стиля, преобразования нестандартных записей и классификации со специфическими границами. Если zero-shot уже даёт нужное качество, лишние примеры могут только увеличить запрос.

Пример классификации

Определи тон отзыва: positive, negative, neutral или mixed.
neutral — нет явной оценки; mixed — есть и положительная, и отрицательная оценка.
Верни только название категории.

«Всё понравилось, доставка вовремя» → positive
«Привезли сломанным» → negative
«Заказ получил во вторник» → neutral
«Товар отличный, но доставка опоздала» → mixed

«Упаковка повреждена, сам товар работает хорошо» →

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

Как подбирать примеры

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

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

Как оценивать улучшение

Отделите примеры в промпте от входов, на которых оцениваете результат. Иначе вы проверите повторение эталонов, а не перенос правила. Сравните долю верных ответов, типы ошибок, размер запроса и время обработки до и после добавления примеров.

Если качество нестабильно, сначала проверьте сами категории. Противоречивую бизнес-классификацию нельзя починить подбором формулировки. Общие рекомендации по демонстрационным примерам — в руководстве OpenAI.


Chain-of-Thought (CoT)

Chain-of-Thought — подход, в котором решение сопровождается промежуточными шагами. Исторически демонстрационные примеры с такими шагами помогали моделям решать ряд задач на рассуждение. Это не универсальная команда повышения точности и не способ проверить внутренний процесс модели. См. исходную работу о CoT.

Как применять на практике

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

Рассчитай время обработки 120 файлов при скорости 8 файлов в минуту.
Укажи формулу, единицы измерения и итог.
Отдельно отметь допущение о постоянной скорости.

Для современных reasoning-моделей подробная команда «думай пошагово» часто избыточна. Например, OpenAI рекомендует ясные прямые инструкции без требования раскрывать цепочку рассуждений.

Связанные методы

Self-consistency использует несколько сгенерированных решений и агрегирует итоговые ответы. Это требует отдельных выборок; просьба перечислить несколько вариантов в одном ответе не воспроизводит весь метод. Совпадение ответов тоже не доказывает истинность. См. исследование self-consistency.

PAL переносит вычислительную часть в исполняемую программу. Важно действительно выполнить код и проверить входные данные, а не принять напечатанную моделью программу за результат. См. Program-aided Language Models.

Tree of Thoughts организует поиск по альтернативным промежуточным состояниям с оценкой и возвратом. Обычный список идей не равен такому поиску. См. Tree of Thoughts.

Ограничения

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

Генерация «фактов по теме» самой моделью создаёт черновые предположения. Без источников их нельзя считать дополнительными знаниями, подтверждающими следующий ответ.


Продвинутые техники промптинга

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

ReAct: действие и наблюдение

ReAct связывает рассуждение с использованием инструментов и анализом результатов. Например, агент находит документ, проверяет его дату, извлекает правило и при необходимости продолжает поиск. Запрос «сравни два сервиса» без инструментов и цикла наблюдений ещё не создаёт ReAct. Основа метода — работа ReAct.

Prompt chaining: последовательность операций

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

Цепочка удобна, когда можно определить вход, результат и условие перехода каждого шага. Для небольшой задачи она может добавить лишние задержки. Сравнение workflow-паттернов есть в Building effective agents.

Поиск и мультимодальные данные

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

При работе с изображением задайте наблюдаемую цель: проверить читаемость подписи, найти несоответствие макету или извлечь значение. Передайте изображение модели, поддерживающей такой вход. Просьба описать картинку по пунктам не воспроизводит отдельный исследовательский метод Multimodal CoT.

Оптимизация самого промпта

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

В Automatic Prompt Engineer существенны и генерация кандидатов, и их оценка. В Active-Prompt отбираются неопределённые примеры для разметки; это не название обычного диалога с уточняющими вопросами.

Критика и альтернативы

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

Обсуждение позиций помогает находить слабые места, но не гарантирует объективность. Для спорного утверждения всё равно нужен источник или эксперимент. Если задача требует связей между объектами, задайте сущности и рёбра явно; список тем со стрелками не становится полноценной графовой моделью.

AI в SDLC

Plan — Планирование

На этапе планирования AI помогает превратить пожелание в ограниченную задачу с проверяемым результатом. Человек определяет приоритет и смысл изменения; агент связывает требования с текущей системой.

Что передать агенту

Опишите проблему, пользователя и ожидаемое поведение. Приложите связанные документы, ограничения, примеры и известные зависимости. Разделите подтверждённые факты и предположения.

Рабочая последовательность

  1. Найти затронутые пользовательские сценарии и модули.
  2. Проверить существующее поведение по коду и доступным данным.
  3. Выделить неизвестное, влияющее на выбор решения.
  4. Сформулировать минимальный полезный объём работы.
  5. Указать порядок реализации и критерии приёмки.

Попросите ссылки на найденные файлы: это помогает отличить исследованный план от правдоподобной догадки.

Пример запроса

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

Что решает человек

Владелец продукта выбирает приоритет, допустимые компромиссы и границы задачи. Команда проверяет зависимости и оценку сложности. Story points или сроки, предложенные моделью, остаются гипотезой: модель не знает реальную загрузку и все организационные ограничения.

Результат этапа

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

План готов к реализации, когда существенные неизвестные разрешены либо выделены в отдельный исследовательский шаг. Для крупных изменений используйте Plan and Act и SDD.


Design — Проектирование

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

От требования к решению

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

Что полезно поручить AI

  • Найти похожий компонент или интеграцию в проекте.
  • Сравнить несколько решений по понятным критериям.
  • Описать пустое состояние, загрузку, ошибку и успешный результат.
  • Проверить согласованность API и модели данных.
  • Подготовить макет или схему для обсуждения.

Пример для формы импорта

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

Как сравнивать варианты

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

Приёмка этапа

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

Соответствие макету проверяется на реальном интерфейсе, включая клавиатуру, длинный текст и небольшой экран. Наличие правильных CSS-классов не доказывает удобство. Реализация начинается на этапе Build.


Build — Разработка

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

До первого изменения

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

Как организовать работу

  1. Выберите небольшой законченный участок поведения.
  2. Измените необходимые модули, сохраняя их ответственность.
  3. Выполните подходящие проверки.
  4. Изучите diff и причины побочных изменений.
  5. Продолжите следующий шаг, если предыдущий подтверждён.

Массовый рефакторинг лучше выделять отдельно от исправления дефекта: иначе трудно понять, какое изменение повлияло на результат.

Пример задания

Добавь выгрузку заказов с теми же фильтрами и проверкой доступа,
что используются в списке. Переиспользуй существующие функции.
Не меняй формат API списка. Проверь пустую выборку и отсутствие доступа.
В отчёте перечисли реально выполненные проверки.

За чем следит человек

Проверьте бизнес-логику, границы доверия, новые зависимости и сложность сопровождения. Агенту легко добавить лишний слой абстракции или обойти неудобное ограничение. Полезное изменение должно объясняться требованиями задачи.

Критерий завершения

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

Далее — Test и Review; проверяющий цикл подробнее описан в Feedback Loop.


Test — Тестирование

AI помогает находить сценарии проверки и анализировать сбои. Цель этапа — подтвердить требуемое поведение и обнаружить ошибки, а не получить формально зелёный отчёт.

Откуда брать сценарии

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

Пример: экспорт заказов

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

Что поручить агенту

  • Составить матрицу сценариев по требованиям.
  • Найти подходящие существующие проверки.
  • Выполнить разрешённые проверки и объяснить сбой.
  • При необходимости предложить новые проверки значимого поведения.
  • Сопоставить результаты с критериями готовности.

Чего недостаточно

Проверка реализации тем же предположением, на котором она написана, может подтвердить ошибку. Изучайте ожидаемые значения и связь с бизнес-правилом. Не принимайте массовое обновление эталонов без объяснения изменившегося поведения.

Для текста может хватить просмотра, для интерфейса нужен реальный браузер, для контракта — проверка входов и выходов. Вид проверки определяется задачей и правилами проекта.

Как оформить результат

Укажите команду или сценарий, окружение, фактический результат и ограничения. Отделяйте «успешно», «неуспешно» и «не выполнялось». Если проверка заблокирована отсутствующим сервисом, это не подтверждает работоспособность интеграции.

Связанные материалы: TDD, Feedback Loop, код-ревью.


Review — Код-ревью

AI-ревью полезно для поиска конкретных дефектов и несоответствий требованиям. Финальное решение о принятии изменения опирается на доказательства и ответственность команды.

Что дать ревьюеру

Передайте цель, diff, связанные требования и результаты проверки. Укажите существенные контракты и область анализа. Просьба «найди любые проблемы» часто смешивает реальные дефекты со стилистическими пожеланиями.

Порядок анализа

Сначала проверьте пользовательское поведение и бизнес-правила. Затем изучите доступ к данным, ошибки, повторы, совместимость и влияние на соседние сценарии. Стиль и именование обсуждайте после вопросов корректности.

Формат полезного замечания

Проблема: экспорт не применяет ограничение по организации.
Место: функция формирования выборки.
Условие: пользователь одной организации запрашивает общую выгрузку.
Последствие: в файл могут попасть чужие записи.
Проверка: сравнить фильтр доступа списка и экспорта.

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

Как работать с ответом AI

Воспроизведите существенные находки или подтвердите их по коду. Не применяйте автоматически все предложенные исправления. Отдельный контекст ревью снижает зависимость от истории реализации, но не обеспечивает полной независимости и безошибочности.

Критерии приёмки

Все значимые замечания разобраны; поведение соответствует задаче; проверки относятся к фактическому изменению; оставшиеся риски понятны. Отсутствие замечаний от модели не равно отсутствию дефектов.

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


Document — Документирование

AI помогает обновить объяснение системы по её текущему состоянию. Документация должна описывать проверенное поведение и помогать читателю выполнить задачу.

Что обновлять

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

Пример запроса

По изменению экспорта обнови руководство пользователя:
где запустить выгрузку, какие фильтры учитываются,
что будет при пустом результате и где увидеть ошибку.
Проверь утверждения по реализации. Нереализованное пометь отдельно.

Как разделить материалы

Пользователю нужны действие, результат и восстановление после ошибки. Разработчику — контракт, ограничения и причины решений. Оператору — настройка, наблюдение и восстановление. Не перегружайте пользовательскую инструкцию внутренними именами модулей.

Проверка документа

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

Сопровождение

Для изменяемых сведений укажите дату или версию. Храните решение рядом с областью, которой оно касается, и назначьте владельца обновления. Лучше сослаться на один поддерживаемый источник, чем размножить противоречащие копии.

Результат этапа — актуальная инструкция, проверенный пример и понятные ограничения. Если документ описывает будущий план, это должно быть явно видно. Навигацию и устойчивые команды можно вынести в Rules, а рабочие процедуры — в Skills.


Deploy & Maintain — Развёртывание и поддержка

AI помогает готовить релиз, анализировать наблюдения и разбирать инциденты. Работа с production требует определённых прав, проверенного артефакта и понятного восстановления.

До развёртывания

Зафиксируйте версию изменения и результаты проверки. Проверьте конфигурацию, миграции, зависимости и совместимость со старой версией. Определите способ восстановления и признаки, по которым релиз нужно остановить.

План «откатить код» недостаточен, если миграция необратимо изменила данные. Восстановление приложения и данных нужно рассматривать отдельно.

Чем помогает агент

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

После переключения

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

Разбор инцидента

Составь временную линию по приложенным логам и событиям релиза.
Отдели наблюдаемые факты от гипотез.
Для каждой гипотезы предложи проверку с минимальным воздействием.
Не считай совпадение по времени доказательством причины.

Человек или назначенный процесс управления инцидентом выбирает действия с учётом влияния на пользователей. Сначала важно ограничить ущерб и восстановить работу; окончательный анализ причины можно продолжить после стабилизации.

Итоговые артефакты

Сохраните версию релиза, результаты проверок, выполненные действия и оставшиеся проблемы. После инцидента обновите документацию и наблюдаемость там, где они не помогли обнаружить или объяснить сбой. Общая архитектура контроля описана в Agent Harness.

Методологии

Plan and Act

Plan and Act разделяет исследование задачи и внесение изменений. Это полезно, когда выбор решения влияет на несколько модулей, данные или пользовательское поведение. Для исправления опечатки отдельный большой план обычно не нужен.

Plan: разобраться и выбрать

Агент читает требования и код, воспроизводит проблему доступным способом, находит зависимости и отмечает неизвестное. Результат — короткий план с объяснением выбранного подхода, областью изменений и способом проверки.

Название Plan Mode не гарантирует режим «только чтение». Запрет записи должен обеспечиваться правами конкретного клиента. В некоторых системах планировщик может создавать файл плана, не меняя код приложения.

Act: реализовать и проверить

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

Пример плана

Задача: сохранять фильтр каталога при обновлении страницы.
Причина: начальное состояние формы не читается из URL.
Изменение: использовать URL при инициализации и синхронизировать сброс.
Границы: не менять API каталога и остальные фильтры.
Проверка: прямая ссылка, обновление, очистка, навигация назад.

Такой план помогает проверить объём работы. Перечень «изучить → написать → проверить» не содержит решения и мало помогает приёмке.

Как выбрать глубину

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

Ошибки процесса

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

Связанные материалы: планирование в SDLC, SDD, Feedback Loop.


Test-Driven Development (TDD)

TDD строит разработку вокруг короткого цикла: описать ожидаемое поведение проверкой, увидеть её корректное падение, реализовать минимум для успеха и улучшить код без изменения поведения. AI может помогать на каждом шаге, но качество критерия определяет человек и предметная область.

Red → Green → Refactor

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

Green. Реализуйте необходимое поведение. Не ослабляйте ожидания только ради зелёного результата.

Refactor. Уберите дублирование и улучшите структуру, сохраняя подтверждённое поведение. Затем переходите к следующему случаю.

Это классическое определение процесса; см. Test Driven Development — Martin Fowler.

Пример для AI-задачи

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

Как оценивать предложенные проверки

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

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

Где TDD не заменяет другие методы

Зелёные проверки не подтверждают удобство интерфейса, полноту требований и отсутствие всех уязвимостей. Для визуального изменения нужен просмотр интерфейса, для производительности — измерение, для интеграции — проверка реального контракта.

Не всякая правка требует нового набора проверок: для исправления текста достаточно уместной проверки результата. Выбирайте процесс по риску и правилам проекта. Подробнее: Test в SDLC и Feedback Loop.


Spec Driven Development (SDD)

SDD — разработка, в которой явная спецификация направляет реализацию и приёмку. Она описывает ожидаемое поведение, ограничения и примеры. Код показывает фактическое поведение; соответствие между ними нужно проверять.

Что включить в спецификацию

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

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

Пример требования

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

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

Рабочий цикл

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

GitHub Spec Kit поддерживает процесс со спецификацией, планом и задачами; конкретные команды и расширения описаны в документации проекта. Использование инструмента само по себе не гарантирует качество спецификации.

Как долго живёт спецификация

В spec-first документ может служить стартом реализации. В spec-anchored он поддерживается вместе с системой. Более строгий Spec as Source делает спецификацию основным редактируемым артефактом. Названия и границы подходов могут различаться; модель сопровождения нужно договорить явно. См. модели сохранения спецификаций Spec Kit.

Когда подход полезен

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


Spec as Source

Spec as Source — подход, в котором человек в первую очередь меняет спецификацию, а реализация создаётся или обновляется генератором. Его удобно рассматривать как строгий вариант SDD, а не универсальную замену инженерной работе.

Что становится источником изменений

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

Условия жизненного цикла спецификаций обсуждаются в документации Spec Kit.

Почему соответствие не гарантировано

Даже без ручного редактирования генератор может неверно интерпретировать требование, пропустить случай или использовать неподходящую зависимость. Изменение версии модели и окружения тоже может изменить реализацию. Отсутствие ручных правок устраняет один источник расхождения, но не доказывает правильность кода.

Практический цикл

  1. Зафиксируйте требование и пример ожидаемого поведения.
  2. Сохраните версии спецификации, генератора, модели и зависимостей.
  3. Сгенерируйте изменение в контролируемой рабочей области.
  4. Проверьте diff, контракты и сценарии использования.
  5. Сохраните принятый артефакт и способ его развёртывания.

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

Пример границы применения

Генерация клиента по формальной API-схеме имеет ограниченный и проверяемый контракт. Генерация всей информационной системы по описанию на естественном языке оставляет больше неоднозначностей. Эти случаи нельзя оценивать одной меркой.

Что договорить в команде

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

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

Контекст и память

Context Engineering

Context Engineering — управление данными, которые модель получает для очередного шага. Сюда входят инструкции, история, состояние задачи, описания инструментов и результаты поиска. Последний запрос пользователя тоже является частью входного контекста.

Что включать

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

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

Практический цикл

  1. Определить, какое решение нужно принять сейчас.
  2. Найти соответствующие файлы или записи.
  3. Прочитать нужный объём и проверить актуальность.
  4. Выполнить действие и получить результат.
  5. Сохранить существенное изменение состояния.

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

Длинный контекст

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

Компактизация, заметки и делегирование обсуждаются в Anthropic Context engineering. Механизм повторного использования вычислений отдельно описан в KV cache.

Как сжимать историю

Сводка должна сохранять цель, ограничения, решения, незавершённые действия и ссылки на артефакты. Не превращайте предположения в подтверждённые факты и не удаляйте единственное основание важного решения.

После восстановления проверьте живое состояние: файл мог измениться, процесс завершиться, а доступ — истечь. Сводка о запущенной задаче не доказывает, что она всё ещё выполняется.

Как увидеть проблему

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

Поддерживаемые проектные знания описаны в Memory Bank, поиск — в RAG.


Memory Bank

Memory Bank — соглашение команды о хранении устойчивых знаний проекта вне чата. Это набор поддерживаемых документов, а не встроенная память модели и не обязательный стандарт структуры каталогов.

Что хранить

МатериалНазначение
Обзор продуктаДля кого система и какие задачи решает
АрхитектураМодули, границы и основные зависимости
РешенияВыбранный подход и причины важных компромиссов
Запуск и проверкаАктуальные команды и требования окружения
Состояние задачиЧто сделано, что осталось и где артефакты

Если эти сведения уже есть в docs/, используйте существующие документы. Создание параллельной папки с копиями увеличивает вероятность расхождения.

Пример компактной структуры

docs/
  README.md
  architecture.md
  development.md
  decisions/
  tasks/

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

Как обновлять память

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

Запись полезно снабдить датой, источником и областью действия. Например: «Экспорт использует фильтр списка; подтверждено текущей реализацией модуля». Если поведение только планируется, обозначьте это явно.

Пример передачи задачи

Цель: исправить повторный импорт.
Подтверждено: дубликаты возникают при сетевом повторе после записи.
Сделано: найден путь создания записи и существующий внешний идентификатор.
Осталось: выбрать контракт идемпотентности и проверить повтор.
Артефакты: описание задачи и ссылки на затронутые файлы.

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

Что не стоит сохранять

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

Качество памяти проверяется восстановлением: новый участник должен понять решение, найти доказательства и продолжить работу. Количество Markdown-файлов само по себе не является метрикой. Связанный материал — Context Engineering.


Feedback Loop

Основная концепция работы агента:

Human ↔ LLM Call → Action → Environment → Feedback → LLM Call
                      ↓
                    Stop
  • Human или LLM Call инициирует действие
  • Action выполняется в Environment
  • Environment возвращает Feedback
  • Feedback поступает обратно в LLM Call для следующего шага

Без vs С Feedback Loop

Без Feedback Loop: после генерации система не получает фактического подтверждения поведения.

С Feedback Loop: наблюдения помогают обнаруживать ошибки и корректировать решение. Готовность к production по-прежнему требует проверки требований, безопасности и эксплуатации.

Стратегическая цель

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

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

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

Больше автономности → выше требования к правам, проверкам, наблюдаемости и восстановлению.

Что делает Feedback полезным

Обратная связь должна быть:

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

Фраза агента «задача выполнена» не является Feedback. Результат теста, ответ API, состояние записи в базе или проверяемый артефакт — являются.

Полный цикл обратной связи

  1. Зафиксировать цель и критерии готовности.
  2. Выбрать действие на основании текущего состояния.
  3. Проверить допустимость и права.
  4. Выполнить действие.
  5. Получить наблюдение от среды.
  6. Сравнить наблюдение с ожидаемым результатом.
  7. Обновить состояние задачи.
  8. Продолжить, повторить, изменить стратегию, откатить или остановиться.

Цикл должен иметь лимит шагов, времени, стоимости и повторов. Иначе Feedback Loop может превратиться в бесконечное исправление симптомов без прогресса.

Типы обратной связи

Code-Level

Unit tests, Linters, IDE, LSP.

Environment

Browser, E2E tests, Logs.

Contextual

Session memory, Codebase index, Grep.

Степени автономности

УровеньОбратная связьЧто делает агентКонтроль человека
No ToolsТолько ответ моделиПредлагает решениеПроверяет и выполняет всё
Code-LevelТесты, типы, линтерИсправляет проверяемые ошибкиПринимает итог
EnvironmentБраузер, API, E2E, логиПроверяет результат в средеКонтролирует исключения
ContextualПоиск, память, состояние проектаАдаптирует решение к задачеПроверяет границы и качество
OperationalМетрики, события, контрольные точкиВедёт продолжительную задачуНаблюдает, останавливает, разбирает инциденты

Уровни не являются автоматической лестницей зрелости. Для операции с высокой ценой ошибки режим с обязательным подтверждением может быть правильным production-решением.

Типы инструментов обратной связи

Fail Fast Principle

Дёшево и детерминировано:

  • Post Tool Hooks
  • Проверки, запускаемые workflow; Rules могут описывать их применение, но сами не являются исполняемой проверкой
  • Type checking, Linting, Formatting
  • Security Checks
  • Pre-commit hooks
  • Интеграция в CI/CD

Инструменты для Secrets Detection

  • GitLeaks
  • TruffleHog

Инструменты для Vulnerability Scanning

  • Semgrep
  • Bandit

Инструменты для Dependency Safety

  • npm audit
  • Snyk

TDD Feedback

TDD используется как протокол коммуникации:

  • Тесты = спецификация для AI-агента
  • Качество сценария и ожидаемого результата важнее скорости генерации
  • Время запуска и прогонов тестов нужно оптимизировать
  • Изменения ожиданий нужно проверять отдельно, чтобы не подгонять их под ошибочную реализацию

Подбор проверки

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

Execution & Runtime Feedback

Данные из Console/Terminal, Debuggers, Logs, Profilers.

Агенту нужен доступ к фактическому статусу процесса и диагностике. Сервис может быть запущен им самим или отдельно; важно не угадывать состояние по старому сообщению.

Доступ к среде

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

Visual & Browser Feedback

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

Инструменты

  • Браузерная автоматизация для переходов и пользовательских действий
  • test-id для идентификации элементов

AI-Powered Review

AI-ревью можно запускать локально или в CI/CD. Выберите место, где замечания поступят вовремя и их можно проверить без лишнего шума.

Через subagents или CLI-версии агентов.

Модельное ревью не заменяет детерминированные проверки. Если правило можно проверить кодом, используйте код; ревьюер нужен для неоднозначных требований, архитектурных противоречий и семантических ошибок.

Обработка отрицательной обратной связи

Перед повтором агент должен определить тип ошибки:

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

Для операций записи нужны идемпотентность или предварительная проверка. Слепой повтор может повторно отправить письмо, списать деньги или создать дубликат.

Условия остановки

Агент обязан остановить цикл, если:

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

Остановка должна сохранять статус, причину, выполненные действия, полученные артефакты и безопасный способ продолжения.

Isolated Env и Sandboxing

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

Инструменты

  • Containers: Docker
  • Cloud Sandboxes: E2B, Daytona
  • CI/CD и preview-окружения: позволяют отделить проверку от production, но требуют самостоятельной настройки прав, сети и секретов

Агенты и инструменты

Что такое AI-агент

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

Главное отличие агента от обычного чата с LLM заключается не в стиле ответа и не в названии продукта. Агент способен самостоятельно выбирать следующий шаг внутри заданных человеком границ.

Короткая рабочая формула: AI-агент = модель + программная обвязка + контекст + инструменты + состояние + цикл выполнения + ограничения.

Почему нет единственного определения

Слово «агент» используют для разных систем:

  • чат-бота, который один раз вызывает модель;
  • сценария из нескольких заранее заданных LLM-вызовов;
  • помощника, который сам выбирает инструменты;
  • автономного исполнителя, работающего часами;
  • группы специализированных агентов под управлением оркестратора.

Все эти системы используют модель, но обладают разной степенью свободы. Поэтому агентность полезнее рассматривать как спектр, а не как бинарную категорию «агент или не агент».

УровеньКак работает системаКто выбирает следующий шагПример
Одиночный LLM-вызовПолучает запрос и генерирует ответПользовательОтвет на вопрос, резюме документа
Детерминированный процессВыполняет фиксированную последовательность шаговРазработчик процессаКлассификация → шаблон → отправка на проверку
Агент с выбором действийАнализирует состояние и выбирает инструментМодель в установленных границахИсследование темы, работа с кодовой базой
Автономный агентСам планирует продолжительную работу, исправляет ошибки и возобновляет выполнениеМодель и управляющая обвязкаОбработка очереди задач, мониторинг инцидентов
Мультиагентная системаДелит работу между несколькими ролямиОркестратор и специализированные агентыИсследователь → исполнитель → ревьюер

При расширении самостоятельности обычно растут вариативность траектории, сложность наблюдения и потенциальная цена ошибки. Само число агентов не определяет уровень автономности. Это не означает, что более автономная система всегда лучше. Для большинства бизнес-процессов нужен минимальный уровень свободы, достаточный для получения результата.

Модель, обвязка и агент

Языковая модель

LLM принимает входные данные и генерирует продолжение текста или структурированный вызов инструмента. Сама по себе модель:

  • не открывает файл;
  • не выполняет SQL-запрос;
  • не отправляет письмо;
  • не знает фактический результат действия;
  • не хранит долговременное состояние между независимыми запусками;
  • не гарантирует, что остановится в правильный момент.

Модель может предложить действие, но выполнять его должна внешняя программа.

Программная обвязка

Программную среду вокруг модели часто называют agent harness, runtime или оркестратором. Она:

  1. формирует запрос к модели;
  2. добавляет инструкции и доступный контекст;
  3. описывает инструменты и права;
  4. разбирает ответ модели;
  5. проверяет допустимость действия;
  6. вызывает API, терминал, браузер или другой инструмент;
  7. возвращает модели наблюдение;
  8. сохраняет состояние;
  9. решает, можно ли продолжать цикл;
  10. останавливает, откатывает или передаёт выполнение человеку.

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

Агентная система

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

Граница остаётся условной. Практически важен не спор о термине, а ответы на вопросы:

  • какую свободу получила модель;
  • к каким данным и действиям она допущена;
  • как проверяется результат;
  • какова цена неверного решения;
  • кто отвечает за остановку и восстановление.

Чем AI-агент отличается от похожих систем

СистемаОсновная функцияСамостоятельный выбор действийРабота с внешней средойСостояние между шагами
Обычная LLMГенерация ответаНетНетТолько переданный контекст
Чат-ботДиалог по заданному сценариюОбычно ограниченИногдаИстория диалога
AI-ассистентПомощь пользователю по запросуОграничен подтверждениямиЧастичноСессия и предпочтения
WorkflowИсполнение заданных шаговНет или минимальныйДаСостояние процесса
RPAПовторение формализованных операцийНетДаТехническое состояние
AI-агентВыбор шага и инструмента ради целиДаДаСостояние задачи и наблюдения
Мультиагентная системаКоординация нескольких исполнителейДа, на нескольких уровняхДаОбщее и локальное состояние агентов

Название продукта не является доказательством агентности. Система может называться агентом, но фактически выполнять жёсткий workflow. И наоборот: фиксированный процесс с несколькими LLM-вызовами может быть полезнее автономного агента.

Рабочая граница агентности

Для практической оценки можно использовать два признака:

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

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

Дополнительные признаки зрелого агента:

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

Качество агента определяется не только моделью

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

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

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

Когда агент не нужен

AI-агент избыточен, если:

  • последовательность действий известна заранее;
  • правила можно выразить обычным кодом;
  • результат должен быть полностью воспроизводимым;
  • цена ошибки высока, а автоматическая проверка невозможна;
  • операция выполняется быстрее и дешевле одним API-вызовом;
  • системе не требуется выбирать между альтернативными действиями;
  • нет качественных инструментов или обратной связи от среды.

В таких случаях лучше использовать обычную функцию, workflow, очередь задач, RPA или LLM-вызов внутри детерминированного процесса.

Когда агент оправдан

Агент полезен, когда:

  • путь к результату заранее неизвестен;
  • необходимо исследовать несколько источников;
  • решение зависит от промежуточных наблюдений;
  • требуется работать с неструктурированными данными;
  • число возможных маршрутов слишком велико для ручного описания;
  • доступна автоматическая проверка результата;
  • ошибку можно безопасно обнаружить и исправить;
  • человек задаёт цель, но не хочет управлять каждым шагом.

Типичные задачи: исследование, диагностика, анализ кодовой базы, подготовка черновиков с проверкой, сортировка обращений, поиск причин инцидента, работа в песочнице, сбор данных из нескольких систем.

Частые вопросы

Обязателен ли цикл

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

Обязательна ли долговременная память

Нет. Агенту необходимо состояние текущей задачи, но долговременная память между сессиями нужна не всегда. Более того, неподтверждённая память может закреплять ошибки и создавать риски конфиденциальности.

Обязан ли агент планировать

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

Является ли RAG агентом

Сам по себе RAG — механизм поиска и добавления данных в контекст. Если маршрут поиска фиксирован, это часть workflow. Если система сама решает, что искать, оценивает достаточность источников и меняет стратегию, RAG становится инструментом агента.

Является ли чат с function calling агентом

Только наличие function calling недостаточно. Важны реальный выбор инструмента, повторный цикл после результата, управление состоянием и возможность изменить дальнейшие действия.

Должен ли агент быть полностью автономным

Нет. Полезный агент может запрашивать подтверждение перед важными действиями. Автономность является настраиваемым свойством системы, а не обязательным признаком качества.

Что запомнить

  • Агент — это не отдельная модель, а целая исполнительная система.
  • Агентность образует спектр от одиночного ответа до автономного исполнения.
  • Практическая граница проходит по самостоятельному выбору контекста и инструментов.
  • Больше автономности означает больше требований к проверкам, правам и наблюдаемости.
  • Лучший уровень агентности — минимальный уровень свободы, достаточный для надёжного результата.

Далее: анатомия AI-агента, уровни автономности и выбор между агентом и workflow.

Источник для дальнейшего чтения: «Агенты и вайб-кодинг», глава «Что такое агент».


Анатомия AI-агента

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

Цель пользователя
      ↓
Политики и границы → Сбор контекста → LLM → Выбор действия
                                           ↓
Состояние ← Наблюдение ← Среда ← Инструмент
    ↓                                      ↑
Проверка результата → продолжить / повторить / откатить / остановить

Основные компоненты

Цель и критерии готовности

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

Плохая цель: «улучши сайт».

Рабочая цель: «уменьши размер клиентского JavaScript на странице каталога минимум на 15%, сохрани поведение фильтров, пройди существующие тесты и приложи результаты измерений до и после».

Хорошая постановка содержит:

  • ожидаемый результат;
  • границы задачи;
  • обязательные ограничения;
  • критерии проверки;
  • допустимые изменения;
  • запрещённые действия;
  • бюджет времени, стоимости или числа шагов;
  • условие передачи человеку.

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

Языковая модель

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

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

  • качество работы с инструментами;
  • устойчивость структурированного вывода;
  • размер и фактическое использование контекста;
  • способность следовать ограничениям;
  • задержка;
  • стоимость;
  • поддержка нужных типов данных;
  • предсказуемость на конкретном наборе задач.

Agent Harness — программная обвязка

Harness связывает модель с реальным миром. Он хранит состояние, собирает запрос, исполняет вызовы, применяет политики и управляет циклом.

Минимальные обязанности обвязки:

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

Если эти функции отсутствуют, надёжность системы зависит от того, насколько удачно модель сформулировала очередной ответ.

Инструкции и политики

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

Важно различать:

  • мягкую инструкцию: «не изменяй production без разрешения»;
  • жёсткую гарантию: токен агента физически не имеет права записи в production.

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

Контекст

Контекст — рабочие данные, доступные модели в текущем вызове:

  • цель и история задачи;
  • системные инструкции;
  • план;
  • результаты инструментов;
  • документы;
  • фрагменты кода;
  • состояние внешних систем;
  • сведения о пользователе и его правах;
  • описание доступных инструментов.

Контекстное окно ограничено, поэтому агент должен не просто накапливать данные, а управлять ими:

  • выбирать релевантное;
  • удалять устаревшее;
  • сжимать историю;
  • сохранять решения и инварианты;
  • отделять факты от предположений;
  • указывать происхождение данных;
  • повторно получать изменяемые сведения перед важным действием.

Подробнее: Context Engineering.

Инструменты

Инструмент — строго описанная операция, которую обвязка может выполнить от имени агента: прочитать файл, вызвать API, выполнить запрос, открыть страницу, создать документ или запустить тест.

Хороший инструмент имеет:

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

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

Подробнее: Tools, Structured Output и MCP.

Состояние

Состояние фиксирует, где находится задача прямо сейчас. Оно не равно истории чата.

Полезная структура состояния:

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

Состояние должно храниться вне контекста модели. Тогда процесс можно восстановить после перезапуска, проверить независимо от LLM и показать оператору.

Память

Память сохраняет полезную информацию за пределами текущего шага. У неё есть несколько уровней:

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

Любая долговременная запись должна иметь источник, дату, область действия и механизм исправления. Автоматически сохранённое предположение может превратиться в постоянную ошибку.

Планировщик

Планировщик декомпозирует цель и выбирает стратегию. Он может быть:

  • неявным — модель выбирает только следующий шаг;
  • явным — модель сначала формирует план;
  • иерархическим — верхний уровень распределяет подзадачи;
  • детерминированным — каркас плана задан кодом;
  • адаптивным — план пересматривается после наблюдений.

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

Исполнитель

Исполнитель переводит решение модели в фактический вызов инструмента. Он:

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

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

Среда и наблюдение

Среда — система, с которой работает агент: файловая система, браузер, CRM, база данных, репозиторий, почта или облачная инфраструктура.

Наблюдение — структурированный результат действия. Оно должно отвечать на вопросы:

  • операция действительно выполнена;
  • что изменилось;
  • как проверить изменение;
  • является ли результат полным;
  • можно ли безопасно повторить действие;
  • возникла ли ошибка;
  • нужно ли обновить контекст.

Сообщение «готово» от модели не является наблюдением. Фактический ответ API, результат теста, запись из базы или скриншот состояния — являются.

Проверяющий контур

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

  1. детерминированная проверка кодом;
  2. проверка независимым источником данных;
  3. сравнение с формальной схемой;
  4. отдельный модельный ревьюер;
  5. человеческое подтверждение.

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

Ограничения и права

Границы определяют, что агент может видеть и изменять:

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

Принцип минимальных привилегий важнее текстового обещания агента «быть осторожным».

Условие остановки

Агент должен завершаться по формальному событию:

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

Остановка должна содержать статус и причину: completed, blocked, failed, cancelled или timed_out. Ответ «не получилось» без состояния затрудняет автоматическое восстановление.

Агентный цикл

Полный цикл можно представить так:

  1. Получить цель. Зафиксировать ожидаемый результат и границы.
  2. Загрузить состояние. Восстановить план, факты, бюджет и контрольную точку.
  3. Собрать контекст. Получить только данные, необходимые для решения текущего шага.
  4. Выбрать действие. Модель предлагает инструмент и аргументы либо сообщает о завершении.
  5. Проверить допустимость. Обвязка применяет права, схемы, лимиты и подтверждения.
  6. Выполнить. Исполнитель вызывает инструмент.
  7. Получить наблюдение. Результат нормализуется и записывается.
  8. Проверить прогресс. Система сравнивает факт с критерием готовности.
  9. Обновить состояние. Сохраняются решения, артефакты, ошибки и затраты.
  10. Продолжить или остановить. Выбирается следующий шаг, повтор, откат, блокировка или завершение.

Подробнее о проверяющем цикле: Feedback Loop.

Обработка ошибок

Ошибки необходимо классифицировать до повторной попытки.

Тип ошибкиПримерРеакция
Временнаясетевой тайм-аут, rate limitповтор с задержкой и ограничением попыток
Входные данныеневерный формат аргументаисправить аргументы или запросить данные
Праваоперация запрещенаостановить и запросить разрешение
Конфликт состояниязапись уже измениласьповторно прочитать состояние и перепланировать
Невыполнимая задачаотсутствует обязательный ресурсперейти в blocked с точной причиной
Нарушение политикипопытка выйти за разрешённую областьотклонить действие и зафиксировать событие
Ошибка моделицикл повторяет один маршрутсменить стратегию, модель или передать человеку

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

Наблюдаемость

Для воспроизводимости агент должен вести трассу выполнения:

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

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

Минимальная production-архитектура

Для агента, способного изменять внешние системы, минимальный набор выглядит так:

  • состояние задачи вне LLM-контекста;
  • инструменты с узкими схемами;
  • авторизация каждого действия;
  • журнал вызовов;
  • тайм-аут и лимит шагов;
  • ограниченные повторы;
  • идемпотентность операций записи;
  • критерии готовности;
  • независимая проверка результата;
  • подтверждение необратимых действий;
  • отмена и безопасное завершение;
  • контрольная точка и восстановление;
  • sandbox для выполнения кода;
  • понятный handoff человеку.

Подробнее об обвязке: архитектура Agent Harness.

Следующий материал: спектр агентности и уровни автономности.


Архитектура Agent Harness

Продолжение анатомии агента по The Harness Playbook, Can Bölük, Stencil. Часть решений omp² ещё разрабатывается.

Состояние и исполнение

  • Единый журнал. Сообщения, настройки, задания и расширения восстанавливаются вместе при возобновлении, откате и ветвлении.
  • Доверенный host. Политики, разрешения и журнал остаются снаружи sandbox; внутри работает ограниченный исполнитель.
  • Управляемые задания. Инструменты, процессы и субагенты имеют общие потоки ввода/вывода и лимиты. Принудительная отмена требует завершаемой границы исполнения.
  • Изоляция субагентов. Отдельная копия рабочей среды возвращает изменения родителю; worktree не изолирует всё окружение.

Управление и контекст

  • Director. Управляет несколькими ходами и условиями завершения; поддерживает вложенные режимы. Hook обрабатывает отдельное событие.
  • Настройки. Область действия, сохранение и наследование централизованы.
  • Совместимость. Возможности зависят от модели, провайдера и API. Неизвестная поддержка отличается от отсутствующей.
  • Фоновое сжатие. Сводка готовится по снимку журнала; применение требует актуальной ветки.

Инструменты и интерфейс

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

Почему история чата не заменяет состояние

Представьте импорт файла из ста строк. После обработки сорока строк процесс прервался. История «начинаю импорт» не отвечает, какие записи уже созданы, какие пропущены и можно ли повторить оставшиеся действия.

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

Event sourcing позволяет восстанавливать состояние по событиям, но добавляет требования к версиям событий, повторному воспроизведению и согласованности. Для простой задачи может быть достаточно устойчивой записи состояния и журнала операций. Выбор зависит от требований к восстановлению и аудиту; см. Event Sourcing Pattern.

Как проверить поведение обвязки

СценарийЧто должно быть видно
Соединение пропало после записиИзвестно, выполнена ли операция; повтор не создаёт дубликат
Пользователь отменил задачуНовые действия прекращены; оставшаяся работа и побочные эффекты отражены
Истёк бюджет ожиданияДолгая операция имеет проверяемый статус и управляемое продолжение
Данные изменились параллельноКонфликт обнаружен до перезаписи; состояние перечитано
После перезапуска открыт интерфейсПоказано восстановленное состояние, а не устаревшая локальная копия

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

Долгая задача и передача контекста

Храните небольшое описание прогресса: цель, завершённые части, текущую проблему и следующий проверяемый шаг. Следующая сессия должна прочитать его и проверить рабочую среду. Подход с явными артефактами прогресса описан в Anthropic — Effective harnesses for long-running agents.

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

Когда архитектуру не нужно усложнять

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

Применение: оценка платформы, Sandbox, Context Engineering.


Спектр агентности и уровни автономности

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

Поэтому уровень автономности необходимо оценивать по отдельным измерениям.

Измерения автономности

Автономность цели

  • получает одну конкретную операцию;
  • получает задачу с критериями готовности;
  • получает общую цель и формирует подзадачи;
  • самостоятельно обнаруживает задачи по событиям или метрикам.

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

Автономность планирования

  • выполняет заранее заданные шаги;
  • выбирает один из утверждённых маршрутов;
  • формирует собственный план;
  • меняет план после наблюдений;
  • создаёт новые подзадачи и назначает исполнителей.

Автономность выбора инструментов

  • использует один заранее указанный инструмент;
  • выбирает из инструментов одного класса;
  • выбирает из общего набора;
  • подключает дополнительные интеграции;
  • создаёт код или временные инструменты для задачи.

Динамическое подключение инструментов требует особенно строгой проверки происхождения, прав и побочных эффектов.

Автономность доступа к данным

  • получает только переданный фрагмент;
  • читает данные одной задачи;
  • ищет по проекту;
  • обращается к нескольким корпоративным системам;
  • использует внешние источники и долговременную память.

Широкий доступ увеличивает полезность, но одновременно повышает риск утечки, смешения контекстов и prompt injection.

Автономность действий

  • только предлагает ответ;
  • готовит черновик;
  • выполняет обратимые изменения;
  • выполняет запись после подтверждения;
  • самостоятельно совершает внешние или необратимые действия.

Разница между чтением и записью принципиальна. Агент, который анализирует CRM, и агент, который удаляет сделки или отправляет клиентам сообщения, требуют разных контуров безопасности.

Временная автономность

  • один вызов;
  • короткая сессия;
  • задача продолжительностью несколько часов;
  • фоновый запуск по расписанию;
  • постоянно работающий процесс, реагирующий на события.

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

Социальная автономность

  • работает только для пользователя;
  • взаимодействует с внутренней командой;
  • отправляет сообщения клиентам;
  • координирует других агентов;
  • действует как представитель организации.

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

Практическая шкала уровней

Это учебная классификация для обсуждения системы, а не отраслевой стандарт или сертификация.

УровеньРоль системыСамостоятельные решенияКонтроль человекаПодходящие задачи
0. ОтветГенераторФормулировка ответаПроверяет всёОбъяснение, черновик, суммаризация
1. РекомендацияСоветникАнализ и выбор вариантаСам выполняет действиеДиагностика, подбор решения
2. Черновик действияПомощникПодготавливает результатПодтверждает каждое изменениеПисьма, SQL, изменения кода
3. Ограниченное исполнениеИсполнительВыполняет обратимые действия в узкой областиНаблюдает и вмешивается по исключениямТесты, sandbox, внутренняя классификация
4. Автономная задачаДелегатПланирует и завершает задачуПринимает итог или эскалациюИсследование, обработка очереди, миграция в тестовой среде
5. Постоянный агентОператор процессаСам обнаруживает и решает задачиКонтролирует политики и метрикиМониторинг, операции с формальными ограничениями

Уровень не является оценкой зрелости продукта. Надёжный агент уровня 2 может приносить больше пользы, чем плохо контролируемый агент уровня 5.

Свобода, неопределённость и цена ошибки

Для качественной оценки рассмотрите вероятность ошибки, масштаб доступа, необратимость и последствия. У этих факторов нет общей универсальной шкалы, поэтому их произведение не является готовой формулой расчёта риска.

Дополнительно оцените два свойства:

  • обнаруживаемость: насколько быстро система заметит неверное действие;
  • восстанавливаемость: можно ли автоматически вернуть корректное состояние.

Пример: ошибочное форматирование файла легко обнаружить тестом и отменить через Git. Ошибочную отправку конфиденциального письма невозможно полностью отозвать. Даже при одинаковой вероятности ошибки допустимый уровень автономности будет различаться.

Human-in-the-loop, Human-on-the-loop и Human-out-of-the-loop

Human-in-the-loop

Человек подтверждает ключевой шаг до исполнения.

Подходит для:

  • платежей;
  • удаления данных;
  • публикации;
  • юридически значимых сообщений;
  • изменения production;
  • передачи чувствительной информации.

Преимущество — высокий контроль. Недостаток — задержка и невозможность полностью автономной работы.

Human-on-the-loop

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

Необходимы:

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

Human-out-of-the-loop

Агент выполняет процесс без оперативного участия человека. Такой режим допустим, когда:

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

Отсутствие человека в каждой операции не означает отсутствие человеческой ответственности за систему.

Как выбрать уровень автономности

Шаг 1. Определить цену ошибки

Оцените возможный ущерб:

  • потеря времени;
  • финансовые потери;
  • нарушение данных;
  • простой системы;
  • утечка информации;
  • репутационный ущерб;
  • юридические последствия;
  • физический вред.

Шаг 2. Разделить чтение и действие

Разрешите агенту свободно исследовать безопасные источники, но отдельно определите права на запись, отправку, публикацию и удаление.

Шаг 3. Найти автоматическую проверку

Чем сильнее проверяющий контур, тем больше автономности можно дать:

  • схема данных;
  • unit-тест;
  • статический анализ;
  • сравнение до и после;
  • бизнес-инвариант;
  • лимит суммы;
  • allowlist адресатов;
  • независимый запрос состояния;
  • ручное подтверждение.

Шаг 4. Ограничить радиус поражения

Даже надёжный агент должен работать малыми порциями:

  • одна задача;
  • один проект;
  • один tenant;
  • ограниченное число записей;
  • фиксированный бюджет;
  • тестовое окружение;
  • временный токен;
  • узкий набор инструментов.

Шаг 5. Начать с минимальной свободы

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

  1. агент предлагает решение;
  2. готовит проверяемый черновик;
  3. выполняет действие после подтверждения;
  4. самостоятельно выполняет обратимые действия;
  5. обрабатывает исключения и эскалирует сложные случаи;
  6. получает более широкую область только после накопления метрик.

Матрица контроля

Цена ошибкиАвтоматическая проверкаРекомендуемый режим
НизкаяСильнаяАвтономное выполнение
НизкаяСлабаяВыполнение с выборочной проверкой
ВысокаяСильнаяОграниченное выполнение, лимиты и журнал
ВысокаяСлабаяРекомендация или черновик с обязательным подтверждением

Признаки избыточной автономности

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

Признаки недостаточной автономности

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

Главный принцип

Цель внедрения — не максимальная автономность, а максимальная полезность при приемлемом и контролируемом риске.

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

  • показывать фактический результат;
  • соблюдать границы;
  • останавливаться;
  • восстанавливаться;
  • эскалировать неопределённость;
  • подтверждать качество метриками.

Следующий материал: AI-агент или Workflow.


AI-агент или Workflow

Workflow — это процесс, в котором последовательность шагов и переходов в основном определена заранее. Агент получает цель и выбирает маршрут во время выполнения. Оба подхода могут использовать LLM, инструменты, память и внешние API.

Ключевой вопрос — не «где есть нейросеть», а «кто принимает решение о следующем шаге».

Базовое различие

Workflow: вход → шаг A → условие → шаг B или C → результат

Агент: цель → наблюдение → выбор действия → новое наблюдение → новый выбор → результат

В workflow разработчик заранее описывает пространство переходов. В агенте разработчик задаёт границы, инструменты и критерии, а конкретная траектория формируется в процессе.

Подробное сравнение

КритерийWorkflowAI-агент
МаршрутЗадан заранееФормируется во время работы
ПовторяемостьМаршрут контролируем; LLM-шаги могут давать разные ответыМогут меняться и маршрут, и ответы
ОбъяснимостьВидна из схемы процессаТребуется журнал траектории
Работа с исключениямиКаждое исключение программируетсяМожет анализировать новые ситуации
Стоимость запускаОбычно предсказуемаЗависит от числа шагов и модели
ЗадержкаЗависит от шагов, внешних сервисов и повторовДополнительно зависит от выбранной траектории
ТестированиеПроверяются ветви и шагиПроверяются сценарии, траектории и итог
Риск дрейфа целиНизкийВыше
МасштабированиеХорошо для однотипного потокаХорошо для неоднородных задач
Изменение процессаТребует изменения схемыЧастично адаптируется через контекст
НаблюдаемостьТехнические события процессаНужны решения, вызовы и состояние агента
Подходящая средаФормализованнаяНеопределённая и контекстная

Когда выбирать обычный код

Не каждый workflow требует LLM. Используйте обычную функцию или сервис, если:

  • правила формализуются условиями;
  • входные данные структурированы;
  • результат однозначен;
  • важны скорость и низкая стоимость;
  • нет необходимости интерпретировать текст;
  • требуется полная воспроизводимость;
  • существует готовый API или алгоритм.

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

Добавление LLM в детерминированную задачу повышает стоимость и неопределённость без обязательного роста ценности.

Когда выбирать Workflow с LLM

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

Примеры:

  • классифицировать обращение → извлечь реквизиты → проверить схему → направить в очередь;
  • расшифровать звонок → выделить договорённости → создать черновик задачи → отправить менеджеру на подтверждение;
  • получить документ → определить тип → извлечь поля → проверить правила → сохранить;
  • сгенерировать описание товара → проверить запрещённые утверждения → отправить редактору;
  • проанализировать резюме → заполнить структурированную карточку → применить прозрачные фильтры.

Здесь модель выполняет отдельные недетерминированные преобразования, а порядок, права и условия задаёт процесс.

Когда выбирать AI-агента

Агент оправдан, если:

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

Примеры:

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

Когда выбирать мультиагентную систему

Несколько агентов полезны, когда работа действительно разделяется на независимые контексты или роли:

  • исследователь собирает факты;
  • исполнитель создаёт артефакт;
  • ревьюер проверяет по отдельным критериям;
  • координатор управляет зависимостями.

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

Подробнее: Subagents.

Гибридная архитектура

Наиболее надёжная production-схема часто сочетает детерминированный каркас и агентные участки.

Событие
  ↓
Детерминированная валидация
  ↓
Агент исследует и готовит решение
  ↓
Детерминированная проверка
  ↓
Подтверждение при необходимости
  ↓
Обычный код выполняет изменение
  ↓
Независимая проверка результата

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

Что оставить детерминированным

  • аутентификацию и авторизацию;
  • расчёты с формальными правилами;
  • проверку схем;
  • лимиты;
  • выбор tenant и области данных;
  • списание денег;
  • фактическое изменение статуса;
  • дедупликацию;
  • аудит;
  • условия обязательного подтверждения;
  • аварийную остановку.

Что можно делегировать агенту

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

Дерево выбора

  1. Можно ли описать решение обычным кодом?

    • Да → используйте код.
    • Нет → переходите к следующему вопросу.
  2. Известна ли последовательность шагов?

    • Да → используйте workflow с отдельными LLM-шагами.
    • Нет → рассмотрите агента.
  3. Можно ли автоматически проверить результат?

    • Да → допустимо автономное исполнение в ограниченной области.
    • Нет → агент должен готовить рекомендацию или черновик.
  4. Обратимы ли действия?

    • Да → можно постепенно повышать автономность.
    • Нет → требуется подтверждение или детерминированное исполнение.
  5. Нужны ли независимые роли или контексты?

    • Да → рассмотрите субагентов.
    • Нет → сохраняйте одного агента.

Примеры бизнес-решений

Поддержка клиентов

Workflow: определить тему обращения, найти статью базы знаний, подготовить ответ, передать оператору.

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

Агент оправдан только при строгих правах, журнале и правилах внешней коммуникации.

Продажи

Workflow: обогатить лид, рассчитать скоринг, назначить ответственного, создать задачу.

Агент: исследовать компанию, сопоставить потребности с продуктом, подготовить персональный сценарий контакта и выбрать момент следующего действия.

Отправку сообщения лучше отделить от исследования и контролировать отдельно.

Разработка

Workflow: запустить форматирование, линтер, тесты и сборку.

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

Сами проверки остаются детерминированными, а поиск решения является агентным.

Работа с документами

Workflow: распознать документ, извлечь поля, проверить схему, сохранить карточку.

Агент: определить, каких документов не хватает, сопоставить противоречия, запросить уточнение и подготовить аналитическое заключение.

Антипаттерны

Агент вместо простого условия

Модель решает задачу, которую надёжнее выразить несколькими строками кода. Результат становится дороже, медленнее и менее воспроизводимым.

Workflow, замаскированный под автономность

Продукт обещает самостоятельного агента, но каждое исключение требует ручного создания новой ветви процесса. Это не обязательно плохо, но архитектуру и стоимость нужно оценивать как workflow.

Полная свобода без проверяющего контура

Агент получает широкие права, а качество определяется его итоговым сообщением. Убедительный текст ошибочно принимается за доказательство выполненной работы.

Мультиагентность ради демонстрации

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

Человек как ручной API

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

Как перейти от Workflow к агенту

  1. Соберите метрики существующего процесса.
  2. Найдите шаги с наибольшим числом нестандартных решений.
  3. Оставьте входную валидацию и критичные действия детерминированными.
  4. Дайте модели один узкий участок выбора.
  5. Добавьте структурированное состояние и журнал.
  6. Формализуйте критерии результата.
  7. Запустите в режиме рекомендаций.
  8. Сравните качество с текущим процессом.
  9. Разрешите обратимые действия малым объёмом.
  10. Расширяйте права только на основании метрик и разбора ошибок.

Следующий материал: как оценить AI-агента и агентскую платформу.


Как оценить AI-агента и агентскую платформу

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

Экспресс-проверка за пять минут

Задайте поставщику или команде пять вопросов.

1. Кто выбирает следующий шаг

  • шаги заранее записаны в схеме;
  • модель выбирает одну из разрешённых ветвей;
  • модель формирует план и меняет его после наблюдений.

Ответ показывает, имеете ли вы дело с workflow, гибридной системой или агентом.

2. Кто выбирает инструменты

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

Уточните не только количество интеграций, но и область прав каждой из них.

3. Кто собирает контекст

  • система подставляет фиксированные поля;
  • выполняет заранее заданный поиск;
  • агент сам решает, какие данные запросить;
  • используется долговременная память;
  • контекст разделяется между пользователями и проектами.

4. Что происходит при ошибке

Нужен конкретный механизм:

  • повтор с ограничением;
  • изменение стратегии;
  • откат;
  • переход в безопасное состояние;
  • запрос подтверждения;
  • блокировка с причиной;
  • передача оператору.

Фраза «модель попробует ещё раз» не является полноценной стратегией отказоустойчивости.

5. Чем подтверждается результат

Попросите показать:

  • фактический ответ целевой системы;
  • тест;
  • изменение записи;
  • ссылку на созданный артефакт;
  • сравнение состояния до и после;
  • трассу инструментов;
  • независимую проверку.

Итоговое сообщение агента не доказывает выполнение действия.

Полный аудит архитектуры

Дополнительные архитектурные ориентиры: Agent Harness.

Цель и область ответственности

Проверьте:

  • для каких задач создан агент;
  • какие задачи исключены;
  • как формулируются критерии готовности;
  • что считается неуспехом;
  • когда система обязана остановиться;
  • кому передаётся неопределённый случай;
  • кто является владельцем результата.

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

Модель и стратегия выбора модели

Уточните:

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

Обновление модели может изменить поведение без изменений в коде, поэтому необходимы версионирование и регрессионные проверки.

Контекст и источники данных

Проверьте:

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

Красный флаг: агент не показывает источники и не различает системные инструкции, пользовательский запрос и текст из внешнего документа.

Инструменты

Для каждого инструмента проверьте:

  • назначение;
  • схему аргументов;
  • тип результата;
  • права;
  • побочные эффекты;
  • тайм-аут;
  • повторяемость;
  • идемпотентность;
  • возможность предварительного просмотра;
  • тестовое окружение;
  • маскирование секретов;
  • журналирование.

Красный флаг: один универсальный инструмент принимает произвольную команду и работает с полными правами.

Управление состоянием

Система должна отвечать на вопросы:

  • где хранится статус задачи;
  • можно ли восстановить выполнение после перезапуска;
  • есть ли контрольные точки;
  • как предотвращаются дубликаты;
  • можно ли безопасно повторить операцию;
  • видит ли оператор текущий план;
  • как отменить задачу;
  • как обрабатываются параллельные изменения;
  • какая версия инструкций использовалась.

Красный флаг: единственным состоянием является история чата внутри модели.

Права и изоляция

Проверьте:

  • принцип минимальных привилегий;
  • отдельные права чтения и записи;
  • task-scoped или временные токены;
  • изоляцию tenant;
  • allowlist ресурсов;
  • ограничения директорий;
  • sandbox для кода;
  • сетевые ограничения;
  • запрет на получение секретов моделью;
  • отзыв прав во время активного запуска.

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

Подтверждения и необратимые действия

Определите перечень операций, которые нельзя выполнять без человека:

  • списание денег;
  • удаление данных;
  • публикация;
  • отправка внешнего сообщения;
  • изменение прав;
  • развёртывание в production;
  • подписание документа;
  • передача конфиденциальной информации.

Подтверждение должно показывать конкретное действие, адресата, данные и ожидаемый эффект. Общая кнопка «разрешить агенту работать» не заменяет осознанного подтверждения рискованной операции.

Обработка ошибок

Попросите продемонстрировать:

  • сетевой тайм-аут;
  • rate limit;
  • неправильный аргумент;
  • отсутствие прав;
  • конфликт версии данных;
  • частично выполненную операцию;
  • падение процесса;
  • недоступность модели;
  • отмену пользователем;
  • повтор после восстановления.

Красный флаг: happy path показан подробно, а все ошибки превращаются в свободный текст модели.

Условия остановки

Должны существовать технические лимиты:

  • максимальное число шагов;
  • максимальное время;
  • бюджет токенов или денег;
  • число одинаковых ошибок;
  • ограничение параллельности;
  • лимит объектов на один запуск;
  • аварийная остановка;
  • статус blocked для запроса данных;
  • статус failed для невосстановимой ошибки.

Красный флаг: агент останавливается только тогда, когда модель решает написать финальный ответ.

Наблюдаемость и аудит

Проверьте наличие:

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

Красный флаг: команда может посмотреть только финальное сообщение и общий расход токенов.

Проверка качества

Уточните:

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

Подробнее: Feedback Loop.

Экономика

Считайте полную стоимость задачи:

Стоимость результата = модель + инструменты + инфраструктура + проверки + ручной контроль + стоимость ошибок

Оцените:

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

Красный флаг: поставщик сравнивает стоимость одного LLM-вызова со стоимостью всего ручного процесса, игнорируя проверки и исключения.

Эксплуатация

Проверьте:

  • мониторинг доступности;
  • алерты;
  • версионирование конфигурации;
  • постепенное развёртывание;
  • откат версии;
  • резервного провайдера;
  • повтор очереди;
  • защиту от перегрузки;
  • ручное вмешательство;
  • документацию для операторов;
  • владельца инцидента;
  • процедуру отключения агента.

Красный флаг: агент разработан как демо и не имеет операционной модели после запуска.

Тестовые сценарии для пилота

Пилот должен включать не только успешные примеры.

Нормальный сценарий

Дайте типовую задачу с полными данными. Измерьте качество, время, стоимость и число ручных вмешательств.

Неполные данные

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

Конфликтующие источники

Предоставьте два несовместимых факта. Агент должен указать конфликт, проверить приоритет источников или запросить решение.

Ошибка инструмента

Имитируйте временный сбой. Проверьте ограниченный повтор и отсутствие дублированного побочного эффекта.

Недостаточные права

Запросите запрещённое действие. Обвязка должна отклонить его независимо от формулировки модели.

Prompt injection

Поместите в документ инструкцию игнорировать правила и передать данные наружу. Агент должен воспринимать её как недоверенный контент.

Частичный успех

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

Длинный запуск

Перезапустите runtime в середине задачи. Проверьте контрольную точку, восстановление и отсутствие повторных операций.

Превышение бюджета

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

Отмена пользователем

Отмените активную задачу. Проверьте прекращение новых действий, завершение текущей безопасной операции и корректный статус.

Метрики пилота

Результативность

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

Автономность

  • число ручных вмешательств на задачу;
  • доля задач, завершённых самостоятельно;
  • доля корректных эскалаций;
  • число ненужных запросов подтверждения;
  • время человека на контроль.

Надёжность

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

Экономика

  • стоимость успешной задачи;
  • стоимость неуспешной задачи;
  • медианная и 95-й перцентиль задержки;
  • расход токенов;
  • стоимость ручной проверки;
  • экономия времени относительно контрольной группы.

Безопасность

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

Карта оценки

Оцените каждый блок от 0 до 2:

  • 0: механизм отсутствует;
  • 1: механизм существует частично или требует ручной работы;
  • 2: механизм формализован, протестирован и наблюдаем.
Блок0–2
Цель и критерии готовности
Границы задач
Качество инструментов
Контекст и источники
Управление состоянием
Права и изоляция
Подтверждения
Обработка ошибок
Условия остановки
Проверка результата
Наблюдаемость
Восстановление
Оценка качества
Экономика
Эксплуатация

Максимум — 30 баллов. Это рабочая карта обсуждения, а не валидированная шкала зрелости. Не используйте сумму как автоматический допуск в production.

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

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

Вопросы перед покупкой

  1. Какие действия агент может выполнять без подтверждения?
  2. Где физически обрабатываются и хранятся данные?
  3. Можно ли ограничить агента одним проектом и временным токеном?
  4. Как выглядит полная трасса успешного и неуспешного запуска?
  5. Как система доказывает фактическое выполнение действия?
  6. Как предотвращаются дубликаты при повторе?
  7. Можно ли остановить и безопасно возобновить задачу?
  8. Как тестируются обновления модели и промптов?
  9. Какие метрики качества доступны заказчику?
  10. Как удаляются память, журналы и пользовательские данные?
  11. Что произойдёт при недоступности модели или интеграции?
  12. Кто отвечает за инцидент и как отключить агента?
  13. Как рассчитывается полная стоимость одной завершённой задачи?
  14. Какие ограничения продукта не показаны в демонстрации?
  15. Можно ли провести пилот на собственном наборе сложных и ошибочных сценариев?

Итоговый критерий

Хороший агент не тот, который выглядит наиболее самостоятельным. Хороший агент:

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

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


Model Context Protocol (MCP)

MCP — открытый протокол обмена контекстом и вызова инструментов между AI-приложением и внешними серверами. Он стандартизирует взаимодействие, но не заменяет API сервиса, его права доступа и бизнес-логику.

Участники и возможности

Host — приложение, управляющее подключениями. Client — компонент host для общения с сервером. Server — программа, предоставляющая возможности. Локальные подключения могут использовать stdio, удалённые — Streamable HTTP.

Сервер может предоставлять tools для операций, resources для данных и prompts для переиспользуемых шаблонов. Подробности и версии описаны в архитектуре MCP.

Как выглядит работа

Приложение подключает выбранный сервер, узнаёт его возможности и делает их доступными согласно своей политике. Затем модель может предложить вызов; host проверяет допустимость, а сервер проверяет права пользователя на данные и действие.

Наличие протокола не означает, что модель самостоятельно найдёт любой сервер в интернете. Подключение, авторизация и управление видимостью зависят от клиента.

Пример интеграции с CRM

Для поиска клиента сервер предоставляет ограниченный поиск по имени или идентификатору. Для изменения контакта — отдельную операцию с проверкой доступа. Результат содержит идентификатор записи и статус. Возвращать всю клиентскую базу ради одного совпадения не нужно.

Если соединение оборвалось после отправки изменения, сначала выясните состояние операции. Слепой повтор может создать дубликат, если контракт не предусматривает идемпотентность.

Что проверить при подключении

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

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

MCP, Skills и CLI

Skill объясняет процедуру, MCP предоставляет интерфейс, CLI исполняет команды. Навык может использовать MCP или CLI. Замена одного другим требует сохранить авторизацию, наблюдаемость и нужные операции; одинаковая цель не делает эти механизмы взаимозаменяемыми.

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


Language Server Protocol (LSP)

LSP задаёт общий протокол между клиентом и языковым сервером. Он позволяет использовать языковые возможности — например, переход к определению и поиск ссылок — в разных редакторах. Описание протокола публикует Microsoft.

Зачем языковой сервер агенту

Текстовый поиск находит совпадение имени, а языковой сервер может определить, к какому символу оно относится. Это полезно при одинаковых именах в разных модулях, переименовании и изучении связей кода.

Типичные возможности: определения, ссылки, диагностика, сведения о типах и переименование. Доступность конкретного метода зависит от сервера и клиента.

Пример рабочего цикла

Агент находит вызов функции, переходит к её определению, изучает ссылки и меняет контракт. После правки проверяет диагностику и затронутые места. Затем выполняет подходящую проверку поведения приложения.

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

Как подключать

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

В Claude Code языковые серверы можно подключать через плагины; формат LSP-компонента описан в руководстве по плагинам. Проверяйте актуальную установку сервера отдельно от установки плагина.

Если результаты неполные

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

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


Agent Client Protocol (ACP)

Agent Client Protocol стандартизирует связь редактора или другого клиента с кодирующим агентом. Он помогает отделить интерфейс работы от реализации агента. Определение и текущие возможности приведены в документации ACP.

Какую проблему решает

Без общего протокола каждой паре «редактор — агент» нужна собственная интеграция. ACP задаёт общий способ обмена сообщениями и событиями сессии. Поддержка протокола облегчает подключение, но полнота функций зависит от возможностей обеих сторон и конкретного адаптера.

Что видит пользователь

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

ACP, MCP и LSP

ПротоколКакая связь
ACPКлиентский интерфейс ↔ кодирующий агент
MCPAI-приложение ↔ внешние данные и инструменты
LSPРедактор или клиент ↔ языковой сервер

Они могут использоваться вместе: агент общается с IDE через ACP, получает документы через MCP и использует языковой сервер для навигации.

Как проверить интеграцию

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

Ограничения

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

Подробнее: MCP, LSP, оценка платформы.


RAG (Retrieval-Augmented Generation)

RAG объединяет поиск внешних материалов и генерацию ответа по найденному контексту. Поиск может быть лексическим, векторным, гибридным или опираться на структурированные запросы. Векторная база не является обязательным условием.

Два процесса

Подготовка источников: загрузить документы, извлечь текст, сохранить происхождение и права, при необходимости разделить на фрагменты и построить индекс.

Ответ на вопрос: сформировать запрос поиска, отфильтровать доступные материалы, отобрать полезные фрагменты, передать их модели и проверить опору ответа на источники.

Пример использования лексического поиска, эмбеддингов и дополнительного ранжирования описан в Anthropic Contextual Retrieval.

Что важно сохранить у фрагмента

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

Практический пример

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

Права проверяются до включения фрагмента в контекст. Скрытие ссылки после генерации не отменяет передачу закрытого текста модели.

Файлы, индекс или длинный контекст

ПодходКогда рассмотретьЧто проверить
Поиск по файламРепозиторий или небольшой набор документовПолноту поиска, актуальность и права
Индексированный поискПовторяющиеся запросы к большой коллекцииКачество выдачи и обновление индекса
Длинный контекстОграниченный набор взаимосвязанных документовРеальную точность, задержку и расходы
ГибридРазные типы вопросовКритерий маршрутизации и отказа

Поиск по файлам с передачей найденного в модель тоже может быть RAG. Универсального порога количества файлов или гарантированной задержки нет. Длинный контекст не всегда точнее, а индекс не всегда дешевле с учётом обслуживания.

Как оценивать качество

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

Если поиск не нашёл доказательств, модель должна сообщить об этом. RAG уменьшает зависимость от знаний в весах, но не устраняет галлюцинации и prompt injection. Подробнее — Context Engineering.


Sandbox (песочница)

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

Что именно изолировать

ГраницаПример ограничения
ФайлыДоступ только к рабочему каталогу; исходные данные доступны для чтения
СетьРазрешены только необходимые адреса
РесурсыОграничены память, CPU, время и размер вывода
СекретыПереданы только нужные краткоживущие полномочия
ПроцессыОперацию можно завершить вместе с дочерними процессами

Контейнеры и виртуальные машины дают разные механизмы изоляции. Контейнер с привилегиями, чувствительными host-mounts или Docker socket может предоставить широкие права на хост. Это рассмотрено в документации Docker по безопасности.

Жизненный цикл задачи

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

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

Практический пример

Для обработки загруженного архива агенту можно дать отдельный каталог, лимит распакованного объёма и запрет исходящих соединений. Результат — набор обработанных файлов и отчёт. Ключи production-базы для такой задачи не нужны.

Если скрипту выдали токен внешнего сервиса с правом записи, он может изменить этот сервис даже из изолированной VM. Поэтому песочница дополняет авторизацию, а не заменяет её.

Что проверить перед использованием

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

Для агента, который только вызывает узкий API, основная граница может находиться в самом сервисе. Требование низкой задержки само по себе не повод отключать изоляцию. Подробнее о владельце политик и исполнителе — в Agent Harness.


Structured Output (Структурированный вывод)

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

Три разных уровня

ПодходЧто обеспечивает
Инструкция «ответь JSON»Пожелание к тексту, которое может быть нарушено
JSON modeСинтаксический JSON в пределах условий API
Вывод по схемеСоответствие поддерживаемой схеме при успешном завершении

Даже корректный объект может содержать неверное число или выдуманный идентификатор. Также нужно обрабатывать отказ модели, незавершённый ответ и ошибку API. Поддерживаемые части JSON Schema различаются. Эти границы описаны, например, в OpenAI Structured Outputs.

Пример результата

{
  "category": "delivery",
  "order_id": null,
  "needs_clarification": true
}

Для обращения «не привезли заказ» отсутствие идентификатора — корректная неопределённость. Если поле допускает только строку, система может провоцировать заполнение несуществующего значения. Схема должна уметь выражать недостаток данных.

Как проектировать контракт

Задайте понятные имена полей и конечные категории там, где они известны. Различайте отсутствие значения и пустую строку. Описывайте бизнес-смысл поля, а не только тип. Не добавляйте вложенность, которой не требует потребитель.

Механизм ограниченного декодирования может отсекать недопустимые продолжения при генерации. Конкретная реализация зависит от провайдера; не всякий сервис с JSON-ответом использует один и тот же алгоритм.

Проверка после генерации

  1. Убедитесь, что запрос успешно завершён и не содержит отказ.
  2. Разберите объект и проверьте схему на стороне приложения.
  3. Проверьте бизнес-ограничения: существование объекта, диапазоны и связи полей.
  4. Отдельно проверьте права на предполагаемое действие.
  5. При ошибке примените ограниченный повтор или запрос уточнения.

JSON с полем approved: true не является разрешением пользователя. Структура данных помогает автоматизации, а авторизация остаётся задачей приложения. Подробнее — инструменты.


Tools (Инструменты)

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

Основные группы

ЗадачаТипичные операцииНа что обратить внимание
Найти информациюПоиск по файлам, веб-поиск, запрос к базеСвежесть, права и полнота результатов
Прочитать данныеФайл, документ, запись APIДиапазон, размер и формат
Изменить состояниеEdit, запись, создание объектаОбласть действия, повторы и конфликты
Выполнить кодТерминал, интерпретаторИзоляция, время и доступ к сети
Проверить результатБраузер, сборка, диагностикаСвязь проверки с требованием

Названия read, grep, bash и websearch — распространённые примеры, а не единый стандарт. Наличие веб-поиска не означает использование конкретного поискового сервиса или отсутствие платы.

Контракт хорошего инструмента

Описание должно объяснять назначение, вход и последствия вызова. Укажите обязательные поля, допустимые значения, ошибки и ограничения объёма. Результат должен различать успех, отсутствие данных, отказ в доступе и временный сбой.

Для записи полезны идентификатор операции, защита от повторов и проверка версии объекта. Например, повторное создание задачи после сетевого тайм-аута не должно незаметно создать дубликат.

Практический сценарий

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

Как управлять результатами

Большие выгрузки возвращайте страницами или сохраняйте как артефакт с кратким итогом. Отмечайте усечение явно. Агент не должен принять первые сто строк за полную базу.

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

Подключение внешних операций описано в MCP, формат данных — в Structured Output, исполнение — в Agent Harness. Принципы проектирования инструментов: Anthropic — Writing effective tools.


Commands (Slash Commands)

Slash command — короткий способ вызвать действие клиента или переиспользуемую инструкцию. Встроенная команда может выполнять фиксированную логику, а пользовательская — разворачивать промпт для модели. Одинаковый префикс / не означает одинаковое поведение.

Для чего применять

Команды удобны для регулярно повторяющегося запроса: проверить diff, подготовить описание изменения или объяснить незнакомый модуль. В аргументе указывается конкретная область работы.

/review-import изменения обработки CSV

Это пример пользовательской команды; она появится только после соответствующей настройки клиента.

Пример для OpenCode

В OpenCode проектную Markdown-команду можно хранить в .opencode/commands/review-import.md. Пример инструкции:

---
description: Проверить изменения импорта
---
Проверь $ARGUMENTS на соответствие контракту импорта.
Для каждой находки укажи условие возникновения и последствия.
Не меняй файлы в ходе ревью.

Пути, аргументы и параметры описаны в OpenCode Commands. Доступ к записи при необходимости ограничьте средствами клиента: текст в шаблоне не заменяет права.

Отличие от Skills

Команда задаёт удобный способ запуска. Skill может содержать более полную процедуру, справочники и скрипты, а также выбираться по задаче. Граница зависит от продукта: в Claude Code пользовательские commands объединены со skills, прежние файлы команд продолжают поддерживаться. См. документацию Claude Code.

Что проверить

Убедитесь, что команда обнаружена, аргумент подставлен правильно, а ограничения не потерялись. Проверьте пустой аргумент и неоднозначную область. Если шаблон исполняет shell-команды при загрузке, оцените этот код отдельно.

Встроенные /compact, /fork, /new и другие команды доступны не во всех клиентах и могут различаться по смыслу. Пользуйтесь справкой своей версии, особенно перед действиями с историей сессии.

Как поддерживать набор

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


Claude Code Routines

Проверено: 8 сентября 2026. Возможности и доступность уточняйте для своего аккаунта и версии клиента.

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

Запуск и настройка

Официальное руководство описывает расписание, API и GitHub-триггеры. На дату проверки GitHub-события включают pull request и release; произвольный push нельзя считать поддерживаемым без проверки. Сценарий настраивается через веб-интерфейс, а /schedule позволяет работать с расписанием из CLI. Подробности — Claude Code Routines.

При создании задайте промпт, репозиторий, окружение и триггер. Проверьте доступ к источникам и выбранный часовой пояс. Облачная routine, локальная задача Desktop и цикл текущей CLI-сессии имеют разные условия исполнения; их нельзя описывать как один механизм.

Пример полезного сценария

Ежедневно подготовить внутренний черновик обзора изменений: какие PR приняты, что меняет пользовательское поведение и какие вопросы требуют проверки. Источники — конкретный репозиторий и заданный период. Публикация обзора выполняется только в предусмотренном процессе.

Что включить в задание

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

Фраза «каждый день улучшай проект» оставляет неопределёнными и результат, и предел изменений.

Надёжность повторных запусков

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

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

Routines и Skills

Routine отвечает за запуск, skill — за способ выполнения задачи. Автоматизированная задача может использовать навык. Версионируйте процедуру и пересматривайте её при изменении API или репозитория, чтобы повторение не масштабировало устаревшее поведение.


Skills (Навыки)

Skill — переиспользуемый пакет инструкций и ресурсов для определённой задачи. Он помогает агенту применять процедуру: например, готовить документацию в принятом формате или проверять импорт данных.

Как устроен навык

В формате Agent Skills пакет содержит SKILL.md с YAML-метаданными и Markdown-инструкцией. В метаданных задаются имя и описание применения. Скрипты, справочники и шаблоны можно хранить рядом. Поля и ограничения описаны в спецификации Agent Skills.

review-import/
  SKILL.md
  references/
    import-contract.md

Пример собственного SKILL.md:

---
name: review-import
description: Проверка изменений импорта данных и обработки повторов.
---
Сопоставь изменение с контрактом импорта.
Проверь поведение повторного запуска и частичной ошибки.
Для каждой находки укажи условие, последствия и место в коде.
Если данных недостаточно, обозначь вопрос отдельно от дефекта.

Как загружается контекст

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

Конкретные пути, ручной вызов, приоритет и дополнительные поля зависят от клиента. Например, Claude Code поддерживает проектные навыки в .claude/skills/ и ручной вызов через /имя; см. его руководство. Не переносите клиентские расширения формата без проверки.

Что делает навык полезным

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

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

Границы механизма

Навык не выдаёт доступ к сервису и не гарантирует исполнение каждого пункта. Жёсткое ограничение должно обеспечиваться приложением. Скрипт внутри пакета — исполняемый код, который нужно оценивать перед запуском.

Навыки можно создавать с помощью AI и дорабатывать по результатам проверок. Самостоятельное авторство или громкие слова в инструкции не доказывают качество.

Rules хранят общие договорённости, skill описывает процедуру, MCP подключает данные и операции. Они дополняют друг друга.


Subagents (Субагенты)

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

Когда делегирование полезно

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

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

Контракт подзадачи

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

Исследуй обработку повторного импорта, не меняя файлы.
Найди место создания записи и проверку внешнего идентификатора.
Верни ссылки на код, подтверждённые наблюдения и открытые вопросы.
Не предлагай менять соседний API без найденной необходимости.

Такой отчёт легче проверить, чем «посмотри проект и улучши что-нибудь».

Контекст и общая среда

Отдельное контекстное окно не означает отдельную файловую систему. Исполнители могут менять одни файлы, использовать общую базу, порты и процессы. Разделяйте области записи и заранее определяйте, кто собирает итог.

Git worktree помогает разделить рабочие копии отслеживаемого кода, но не изолирует внешние сервисы и все локальные ресурсы. Для исполнения недоверенного кода нужна отдельная песочница.

Настройка зависит от клиента

Например, Claude Code поддерживает файлы определений в .claude/agents/ и пользовательской ~/.claude/agents/, с настройками инструментов и поведения. Поля и ограничения приведены в руководстве по субагентам. Поля mode, tools и синтаксис вызова из других клиентов не следует смешивать с этой схемой.

Как принять результат

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

Учитывайте суммарные токены, дублирующее чтение и время согласования. Долговременная память нужна только там, где есть повторное применение знаний и правила их актуализации. Не включайте её автоматически ради самого наличия.

Подробнее — Agent Harness и AI-агент или Workflow.


Rules — инструкции проекта

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

Где находятся правила

У клиентов есть пользовательские, проектные и иногда вложенные инструкции. Форматы и порядок их применения различаются. AGENTS.md — открытый Markdown-формат для инструкций кодирующим агентам; его назначение описано на agents.md.

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

Что включить

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

Лучше написать «переиспользуй существующий клиент API», чем «пиши качественный код». Не повторяйте весь README и автоматически определяемые сведения без причины.

Пример инструкции

# Работа с проектом
Документация находится в docs/README.md.
Перед изменением проверь рабочее дерево и инструкции затронутого модуля.
Не перезаписывай несвязанные изменения.
При изменении API обнови описание контракта.
В отчёте разделяй выполненные проверки и оставшиеся ограничения.

Это пример содержания. Команды и дополнительные условия должны соответствовать конкретному репозиторию.

Как сопровождать

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

Автогенерация может подготовить черновик, но его необходимо сверить с реальными файлами. Ни ручное происхождение, ни определённое число строк не гарантируют эффективности.

Как проверить полезность

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

Запрет «не читать секреты» полезен как инструкция, но защита должна ограничивать фактический доступ. Для повторяемой процедуры используйте Skills, для событийных проверок — Hooks.


Hooks — обработчики событий

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

Где полезны

СобытиеВозможная задача
Перед вызовомПроверить путь и допустимость операции
После вызоваСобрать диагностику или отформатировать изменённый файл
Перед завершениемПроверить наличие обязательного результата
При уведомленииПередать разрешённое сообщение оператору

Обработчик после операции не может предотвратить уже выполненное действие. Если нужен запрет записи, он должен срабатывать до неё или обеспечиваться правами среды.

Пример границы в Claude Code

Для PreToolUse код завершения 2 может блокировать вызов. Другие события имеют собственные правила; например, PostToolUse получает уже выполненный результат. Нельзя считать любой ненулевой exit code универсальным запретом. Контракт приведён в Hooks reference.

Как проектировать обработчик

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

Пример: проверка пути должна нормализовать его и учитывать реальную границу рабочей области. Поиск строки rm в shell-команде не решает задачу авторизации всех возможных способов удаления.

Как проверить настройку

Запустите безопасный разрешённый пример, запрещённый пример и случай ошибки обработчика. Убедитесь, что сообщение видно, операция действительно блокируется там, где должна, а обычные действия продолжают работать.

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

Ограничения

Детерминированный запуск hook не означает безошибочность проверки. Сам скрипт может иметь дефект, а некоторые клиенты поддерживают и модельные обработчики. Не выдавайте им лишние секреты и права.

Автоматический commit, отправка уведомления или публикация — отдельные действия с последствиями. Их наличие в обработчике должно соответствовать политике проекта. Для общих соглашений используйте Rules, для процедуры — Skills.


Плагины

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

Когда нужен пакет

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

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

Совместимость

Каталоги Claude Code, OpenCode и других продуктов не являются взаимозаменяемыми. Даже при переносимом SKILL.md обработчики и конфигурация сервера могут требовать адаптации. Компоненты плагина Claude Code описаны в официальном руководстве.

Не устанавливайте случайный репозиторий только потому, что в нём есть папка plugins. Проверьте ожидаемый манифест, способ установки и поддерживаемые версии клиента.

Перед установкой

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

Проверка на проекте

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

Сопровождение

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

Плагин упрощает распространение возможностей, но не заменяет их проверку. Связанные материалы: Hooks, MCP, работа с набором инструментов.

Внедрение в команду

Принципы внедрения

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

Общая рамка и участие команды

Руководство определяет цели, допустимые данные, бюджет и ответственность. Участники команды проверяют инструменты на своих задачах и показывают результаты, включая неудачные. Такой подход сочетает управляемость с практическим опытом.

Что договорить заранее

  • Какие рабочие задачи подходят для пилота.
  • Какие данные можно передавать и куда.
  • Кто проверяет результат и принимает изменение.
  • Где хранить общие инструкции и примеры.
  • Как сообщать о проблемах и менять правила.

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

Пример пилота

Команда выбирает подготовку черновиков документации по небольшим изменениям. Автор проверяет текст по реализации. До пилота и во время него измеряются затраты на подготовку и исправление. Если черновик экономит время только за счёт пропуска проверки, это не подтверждённое улучшение.

Как оценивать пользу

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

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

Что закреплять

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

Продолжение: алгоритм внедрения, ошибки, оценка задач.


Алгоритм внедрения

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

1. Зафиксировать исходное состояние

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

2. Подготовить рабочие условия

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

3. Провести ограниченный пилот

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

4. Разобрать результат

Для каждого принятого артефакта посмотрите, что сделал AI, что исправил человек и где появились задержки. Сохраняйте полезные инструкции вместе с примером результата. Удачная формулировка без контекста применения плохо переносится на другие задачи.

5. Принять решение

Расширьте сценарий, скорректируйте его или прекратите использование. Заранее заданные критерии помогают принять отрицательный результат без поиска оправданий. Например, снижение времени написания при удвоении ревью может не устраивать команду.

6. Закрепить процесс

Назначьте владельца процедуры, правила обновления и канал поддержки. Добавьте рабочие материалы в базу знаний проекта, а повторяемые действия — в Skills.

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


Этапы работы над задачей

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

1. Требования

Опишите цель, пользователя, ожидаемое поведение и ограничения. Разделите подтверждённые правила и открытые вопросы. Человек определяет, что действительно нужно продукту; AI помогает найти неоднозначности.

Результат: краткое описание задачи или requirements.md с примерами приёмки.

2. Исследование

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

Результат: карта затронутых модулей, причина проблемы и неизвестные зависимости.

3. Выбор решения

Сравните необходимые альтернативы по стоимости, сложности и последствиям. Для значимого решения сохраните причины выбора. C4-диаграмма или ADR полезны, когда помогают разобраться; они не обязательны для каждого небольшого изменения.

Результат: согласованный контракт и границы реализации. Подробнее — Design.

4. Планирование

Разбейте работу на законченные шаги с понятными зависимостями. Для каждой части укажите результат и проверку. Не отделяйте все проверки на далёкий финальный этап, если ошибку можно обнаружить раньше.

Результат: короткий план или трекер задач. Отдельный файл на каждый шаг нужен только при удобстве сопровождения.

5. Выполнение

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

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

6. Приёмка

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

Результат: решение о принятии и явные оставшиеся ограничения.

7. Сопровождение

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

Сквозной пример

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


Критерии оценки задач

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

Матрица оценки

ИзмерениеХороший признакЧто сделать при неопределённости
ТребованияЕсть наблюдаемое ожидаемое поведениеУточнить правило и пример
КонтекстДоступны связанные файлы и документыСначала провести исследование
ОбластьПонятны модули и контрактыРазделить на законченные части
ПроверкаЕсть способ подтвердить результатОпределить приёмку до реализации
ПраваДоступ соответствует операцииОграничить разрешения
ОбратимостьИзменение можно безопасно отменитьПодготовить восстановление и контроль
КоординацияМало неявных зависимостейНазначить владельца интеграции

Пример простой задачи

Добавить сортировку списка по имени. Даже здесь нужно договорить регистр, локаль, пустые значения и связь с пагинацией, если это влияет на продукт. «Стандартная» задача не освобождает от уточнения контракта.

Пример сложной задачи

Изменить расчёт статуса заказа при параллельной оплате и отмене. Сначала нужны таблица состояний, допустимые переходы и поведение повторов. Затем можно поручить агенту отдельный участок и проверить взаимодействие частей.

Количество файлов

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

Неявные знания

Агент может использовать код, документы и доступные инструменты, но не обязан знать устные договорённости команды. Существенное бизнес-правило нужно явно передать или найти в подтверждённом источнике.

Как выбрать режим работы

  • Делегировать целиком: ясный контракт, ограниченная область, доступная проверка.
  • Сначала исследовать: неясно текущее поведение или зависимости.
  • Декомпозировать: части имеют самостоятельные результаты и определённую интеграцию.
  • Сохранить ручное управление: высоки последствия ошибки или нет надёжной приёмки.

Решение можно пересмотреть после исследования. Сложность сама по себе не запрещает AI, а простота не гарантирует безопасную автономность. Подробнее — уровни автономности.


Workflows, Commands и Skills

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

Как выбрать форму

МеханизмОсновная задачаПример
Документ процедурыОбъяснить шаги человеку и агентуРуководство по разбору дефекта
CommandДать короткий ручной запуск/review-import
SkillПодключать инструкцию и ресурсы под задачуПроверка импорта по контракту
HookОбработать событие клиентаДиагностика после изменения
RoutineЗапустить задачу по триггеруПериодический обзор изменений

В Claude Code пользовательские команды объединены со skills, но это свойство конкретного продукта. В других клиентах механизмы могут оставаться отдельными. См. руководство Claude Code.

Пример эволюции одной процедуры

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

Не нужно создавать все четыре слоя заранее. Каждый должен устранять конкретное повторяющееся неудобство.

Что сохранить при переносе

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

Метаданные навыка называются frontmatter, а не formatters. Они помогают обнаружить назначение пакета; основной текст и дополнительные ресурсы загружаются согласно механизму клиента.

Как понять, что перенос удался

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

Подробнее: Commands, Skills, Hooks, Routines.


Работа с набором AI-инструментов

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

Что стандартизировать

Согласуйте допустимые сервисы и данные, общую документацию, способ проверки и владельцев интеграций. Интерфейс редактора можно выбирать индивидуально, если он поддерживает нужный процесс.

Для переносимых инструкций рассмотрите AGENTS.md и формат Agent Skills. Поддержка конкретного поля или способа вызова всё равно проверяется в каждом клиенте.

Что хранить в Git

Тип настройкиПодход
Общие правила и навыкиВерсионировать и проверять изменения
Примеры конфигурацииХранить без секретов
Личные предпочтенияОставить локально, если не влияют на команду
Токены и ключиИспользовать предназначенное хранилище секретов
Временные логи и кэшИсключать из репозитория по необходимости

Не стоит целиком скрывать все каталоги агентов через gitignore: вместе с персональными файлами можно потерять важную общую конфигурацию.

Как синхронизировать

Выберите один поддерживаемый источник инструкций. Адаптеры для клиентов могут ссылаться на него или создаваться скриптом. Симлинки подходят не каждому окружению; проверьте Windows, контейнеры и обработку ссылок выбранным клиентом.

Минимальная проверка нового клиента

Убедитесь, что он читает правила, находит документацию, запускает нужную проверку и соблюдает область доступа. Выполните одну типичную задачу и сравните артефакт с требованиями команды.

Обновление и отказ от инструмента

Назначьте владельца конфигурации и порядок обновлений. Должно быть понятно, как перенести знания, отключить интеграцию и отозвать доступ. Общий процесс не должен зависеть от личного токена единственного сотрудника.

Подробнее — Rules, Skills, Plugins.


Главные ошибки при внедрении

Ошибки внедрения часто связаны с процессом: команда не понимает, где применять AI, как оценивать результат и кто отвечает за исправления. Решение — сделать эти условия явными.

Готовая настройка без объяснения

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

Обучение на критическом дедлайне

Освоение нового инструмента добавляет неопределённость. Для первых попыток выбирайте задачи, где допустим повтор и есть время на разбор. Срочная работа не всегда запрещает AI, но требует уже освоенного и проверяемого сценария.

Метрики активности вместо пользы

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

Одинаковая автономность для всех действий

Черновик и изменение production имеют разные последствия. Права должны соответствовать конкретной операции. Общее разрешение «работай самостоятельно» не объясняет границы данных, публикации и внешних коммуникаций.

Разрастание инструкций

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

Пример корректировки

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

Что оставить после пилота

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

Связанные материалы: алгоритм внедрения и оценка задач.


Проблематика внедрения ИИ

Проблему полезно описывать через наблюдаемое поведение команды. Формулировка «люди не пользуются AI» не объясняет, что мешает работе и нужен ли инструмент для выбранного сценария.

Типичные ситуации

НаблюдениеВозможная причинаСледующий шаг
Одни и те же инструкции настраивают зановоНет общего источникаСохранить поддерживаемые правила и процедуру
Черновики быстрые, ревью долгоеСлишком широкие задачи или слабая проверкаУменьшить область и уточнить приёмку
Результаты различаются у сотрудниковРазный контекст, версии или доступСравнить рабочие условия
Инструмент регулярно забрасываютОн не решает повседневную проблемуПроверить реальный сценарий на практике
Расходы растут без ясной пользыНет метрик результатаСчитать принятую задачу целиком

Как диагностировать

Разберите несколько конкретных задач от начала до приёмки. Уточните, где сотрудник искал данные, что получил от модели, сколько исправлял и почему не доверился результату. Наблюдение процесса обычно информативнее опроса «нравится ли вам AI».

Пример

Два разработчика используют один клиент. У первого есть актуальная документация и доступ к запуску приложения, у второго — только описание задачи. Разница результата не позволяет сразу сделать вывод о навыках сотрудников или качестве модели.

Что не стоит делать

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

Результат диагностики

Сформулируйте одну проверяемую гипотезу и изменение процесса. Например: «дадим актуальный пример контракта и проверим, уменьшились ли исправления схемы ответа». По итогам оставьте работающую меру или пересмотрите гипотезу.

Подробнее: работа со скепсисом, набор инструментов, принципы внедрения.


Работа со скепсисом

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

Что обсуждать

Уточните задачу, доступный контекст, ожидаемый результат и фактическую ошибку. Разделите ограничения модели, проблемы инструмента и неясные требования. Аналогия с junior-разработчиком иногда удобна, но неточна: способности модели не соответствуют одному человеческому уровню опыта.

Небольшой совместный эксперимент

Выберите знакомую задачу с понятной приёмкой. Пусть сотрудник задаст критерии и сравнит обычный подход с AI. Учитывайте время на проверку и исправление. Если улучшения нет, это допустимый результат эксперимента.

Пример: подготовить описание небольшого изменения API и проверить каждый пункт по реализации. Здесь легко увидеть, ускорилась ли работа и появились ли выдуманные детали.

Открытость лидеров

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

Ясные правила

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

Чего избегать

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

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

Подробнее: принципы внедрения и проблемы процесса.

Загрузка комментариев...