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

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

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

Глоссарий

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

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

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

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

Контекстное окно — объём текста, который модель может "удерживать в памяти" в рамках одного запроса. Актуальный размер контекста 200тыс-1млн токенов. ВАЖНО: вместе с ростом контекста, качество ответов начинает падать. Внимание модели больше сконцентрировано в начале и конце с просадкой в середине. Выходное окно токенов: 32тыс-64тыс токенов.

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

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 / передача управления — переход задачи от агента к человеку или другому агенту вместе с состоянием, результатами, открытыми вопросами и причиной передачи.

Память

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, поиску и другим системам.

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

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

Code execution — режим, в котором модель не только пишет текст, но и запускает код в изолированной среде, чтобы посчитать что-то, обработать данные, построить график, преобразовать файл или проверить гипотезу.

Основы LLM

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

Как работают LLM

LLM — это вероятностная языковая модель. Она предсказывает следующее наиболее вероятное слово на основе паттернов в данных, а не "думает" или "понимает" в человеческом смысле.

Ключевые ограничения

Модели не имеют долговременной памяти

Каждый новый запрос обрабатывается изолированно, если вы не передаете историю диалога в контексте.

Знания ограничены датой обучения

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

Склонность к галлюцинациям

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

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

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

Принципы эффективной работы

Точнее промпт — точнее результат

Чем чётче обозначены требования и ограничения, тем меньше у LLM поводов импровизировать.

Каждая модель уникальна

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

LLM — это усилитель

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

Эффективность через практику

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


Актуальные LLM и инструменты

Актуальность: апрель 2026

Модели

SOTA (State of the Art)

ChatGPT 5.4, OPUS 4.6, SONNET 4.6, GEMINI 3.1 Pro

Лучшей SOTA модели не существует. Каждая имеет свои сильные стороны.

Второй эшелон

  • KIMI K2.5
  • MiniMax 2.7
  • QWEN 3.6 Plus
  • MiMo-v2-Pro
  • KAT coder V2 Pro

Остальные не актуальны.

Инструменты разработки

IDE

  • Cursor
  • Windsurf
  • Trae
  • VS Code

Топ плагины для IDE

  • Kilo
  • Continue

Терминальные агенты

  • Opencode
  • Claude code
  • Codex
  • Qwen code

Self-host

Для использования SOTA моделей нужен VPN. Можно развернуть модели локально.

Актуальные модели для self-host:

  • Kimi k2.5
  • Qwen 3.5 Plus
  • MiniMax 2.7

Стоимость

Использование по API чрезвычайно дорогое, необходимо покупать подписки. Стоимость актуальной подписки для разработки ~200$.


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

Key-Value Cache

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

Prompt Caching

Сохранение на стороне сервера больших объемов неизменяемых данных, которые часто отправляются в запросах:

  • Обычно документация, системные инструкции, описания инструментов и MCP
  • Чтобы сработало, данные нужно размещать строго в самом начале промпта
  • Позволяет снизить стоимость Prefill до 70%

Batch API

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


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

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

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

Принципы работы с AI-агентами

Эффективность зависит от постановки задач

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

Успех приходит с практикой

Успех в работе с ИИ-агентами приходит только с практикой.

Предварительный анализ

Предварительный анализ задачи является ключевым элементом.

Смещение фокуса

ИИ-агенты смещают фокус работы в сторону проектирования, управления и ревью.

Выбор моделей

Не существует одной «лучшей» модели для всего.

Рекомендация: Использовать разные модели для разных нужд:

  • Для кодинга: Модели, заточенные на код (Sonnet, Codex, Coder)
  • Для планирования: Самые мощные рассуждающие модели (GPT, Gemini, Opus)

Использование самой мощной модели для всех задач — дорого и медленно.

Плюсы использования AI

  • Быстрые и наглядные прототипы
  • Работа над несколькими задачами или проектами параллельно
  • Быстрая проверка гипотез и тестирование разных вариантов решения
  • Выполнение задач другого уровня и стека
  • Делает то, на что раньше не было времени (инструменты, парсеры, тесты)
  • Пишет бойлерплейт код, тесты, документацию
  • Помогает изучать кодовую базу, отчёты и ошибки
  • Помогает брейнштормить идеи и планировать работу
  • Проводит ревью, находит проблемы, ошибки, опечатки, несоответствия

Минусы и риски

  • Без должных ограничений тяготеет к овер-инженирингу и "энтерпрайз"-паттернам
  • Плохая связь с редактором движка и чисто визуальными инструментами
  • Мешает младшим сотрудникам расти и развиваться хардово
  • Вопросы конфиденциальности, безопасности и стоимости

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

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

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

Чёткое разделение на блоки: контекст, инструкция, формат.

Пример:

  • Контекст: готовлю презентацию о здоровом питании
  • Инструкция: перечисли группы продуктов для сбалансированного рациона
  • Формат: маркированный список

Структурирование вывода

Указание модели на нужный формат ответа.

Пример: «Создай 5 идей для квестов в формате таблицы: Название, NPC, Цель, Награда»

Role Prompting

Назначение модели роли для нужного стиля ответа.

Пример: «Представь, что ты туристический гид. Опиши три главные достопримечательности Рима»

Self-reflection / Self-critique

Модель генерирует ответ, затем сама его анализирует и улучшает.

Пример: «Опиши принципы блокчейна. Затем проанализируй объяснение и предложи более простую аналогию»


Zero-shot prompting

Постановка задачи без примеров.

Когда использовать

  • Когда задача проста и понятна
  • Когда нет времени готовить примеры
  • Для быстрых, одноразовых запросов

Пример

Переведи на английский: Искусственный интеллект меняет мир

Пример с контекстом

Контекст: пишу документацию API для финтех-стартапа
Инструкция: сгенерируй описание эндпоинта для получения баланса счета
Формат: OpenAPI 3.0 спецификация

Few-shot prompting

Несколько примеров «задача-решение» для понимания контекста.

Когда использовать

  • Когда нужен конкретный формат ответа
  • Для сложных трансформаций текста
  • Когда важен стиль или паттерн

Пример

Напиши слово в обратном порядке

Пример 1: «море» → «орем»
Пример 2: «кот» → «ток»
Задача: «кабан» → ?

Другой пример

Классифицируй отзыв как позитивный или негативный

Отзыв: "Отличный сервис, быстрая доставка" → Позитивный
Отзыв: "Товар пришел сломанным" → Негативный
Отзыв: "Качество среднее, ничего особенного" →

Chain-of-Thought (CoT)

Требование пошагово описать логику рассуждений.

Когда использовать

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

Пример

У фермера было 15 овец. 5 продал, купил ещё 8. Сколько стало? Объясни по шагам

Self-Consistency

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

Пример: «Реши задачу несколькими способами и выбери самый частый ответ»

Generated Knowledge Prompting

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

Пример: «Сначала сгенерируй факты об Эйфелевой башне. Затем ответь, почему она — символ Парижа»

Program-Aided Language Models (PAL)

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

Пример:

Поезд едет 80 км/ч. Какое расстояние за 2.5 часа? Реши с помощью Python

Tree of Thoughts (ToT)

Модель исследует несколько путей и выбирает оптимальный.

Пример:

У тебя 8 шаров, один тяжелее. Как за два взвешивания найти тяжёлый? 
Рассмотри разные варианты первого шага

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

ReAct (Reason + Act)

Итерационный фреймворк: рассуждение → действие → анализ → следующий шаг.

Пример:

Сравни капитализацию Apple и Microsoft. Какая выше и на сколько процентов?

RAG (Retrieval Augmented Generation)

Модель извлекает релевантную информацию из внешней базы знаний перед ответом.

Пример:

Используя базу знаний компании, ответь: какова политика возврата товара со скидкой?

Directional Stimulus Prompting

Включение ключевых слов для направления генерации.

Пример:

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

Multimodal CoT

Цепочка рассуждений для данных разных типов (текст + изображение).

Пример:

Опиши изображение шаг за шагом: 1) главный объект, 2) окружение, 3) настроение

Prompt Chaining

Разделение сложной задачи на последовательность промптов.

Пример:

Шаг 1: составь список 5 популярных языков программирования
Шаг 2: для каждого опиши основное применение

Automatic Prompt Engineer (APE)

Использование одной модели для генерации и оптимизации промптов для другой.

Пример:

Сгенерируй 5 промптов для креативного описания продукта «умные часы»

Active-Prompt

Модель задаёт уточняющие вопросы перед ответом.

Пример:

Хочу составить план путешествия. Задай 3 уточняющих вопроса о предпочтениях

Graph Prompting

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

Пример:

Составь учебный план: Введение → Переменные → Условия → Функции → Структуры данных

Meta-prompting

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

Пример:

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

Self-Debate

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

Пример:

Сначала аргументируй за F2P с микротранзакциями. 
Затем раскритикуй эту позицию как инди-разработчик

AI в SDLC

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

Задачи AI

  • Чтение и анализ спецификаций фич
  • Сопоставление требований с кодовой базой
  • Определение зависимостей и оценка сложности
  • Подсветка скрытых проблем и неоднозначностей
  • Проверка точности оценок ИИ
  • Назначение story points

Задачи человека

  • Управление общим направлением продукта
  • Приоритизация беклога
  • Финальное принятие решений о scope

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

Задачи AI

  • Генерация шаблонного кода
  • Перевод дизайн-макетов в готовые UI-компоненты
  • Автоматическое применение токенов дизайн-системы
  • Проверка соответствия компонентов стандартам качества

Задачи человека

  • Утверждение общих UX-паттернов
  • Архитектурные решения
  • Финальный дизайн-ревью

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

Задачи AI

  • Создание фичей по спецификации
  • Генерация моделей данных и API
  • Автоматическое исправление ошибок сборки
  • Массовый рефакторинг в десятках файлов
  • Выступление в роли ревьюера и редактора

Задачи человека

  • Фокус на сложной бизнес-логике и безопасности
  • Оценка производительности и долгосрочной поддерживаемости кода
  • Архитектурный оверсайт

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

Задачи AI

  • Предложение тест-кейсов
  • Написание автоматизированных тестов
  • Актуализация старых тестов при изменении кода

Задачи человека

  • Контроль качества сгенерированных тестов
  • Управление требованиями к тестовому покрытию
  • Планирование E2E тестирования

Review — Код-ревью

Задачи AI

  • Глубокий анализ логики между множеством файлов
  • Выявление сложных архитектурных багов, состояний гонки и хардкода
  • Проверка архитектурного соответствия

Задачи человека

  • Принятие окончательного решения о слиянии
  • Ответственность за код, уходящий в продакшен
  • Проверка бизнес-логики

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

Задачи AI

  • Генерация системных диаграмм
  • Создание саммари для измененных файлов
  • Автообновление документации на основе коммитов

Задачи человека

  • Формирование структуры, шаблонов и стандартов базы знаний
  • Написание критически важной архитектурной или юридической документации
  • Ревью технической документации

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

Задачи AI

  • Анализ логов при инцидентах
  • Связывание ошибок продакшена с конкретными Git-коммитами
  • Предложение кода для хотфиксов

Задачи человека

  • Валидация предложенных ИИ причин сбоев
  • Проверка надежности сгенерированных исправлений
  • Принятие решений в критических ситуациях
  • Управление инцидентами

Методологии

Plan and Act

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

Поэтому процесс разработки разделяется на две фазы:

Plan Mode

ИИ-агент переводится в режим «только для чтения».

  • Исследует кодовую базу
  • Анализирует контекст
  • Выявляет возможные пограничные случаи
  • Обсуждает с разработчиком архитектурную стратегию

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

Act / Build / Code Mode

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

Plan → Act → Plan

Когда использовать каждый режим

СценарийРежим
Мелкие правкиТолько Act Mode
Средние задачиЦикл Plan → Act
Крупные архитектурные измененияГлубокое планирование с детальным обсуждением

Эффективность

1 минута на планирование и написание тех спеки экономит 10 минут на отладку.

Пример: Cline и прочие современные агенты.


Test-Driven Development (TDD)

В сочетании с AI-агентами создает мощный цикл обратной связи.

TDD обеспечивает структуру и дисциплину, а агенты — скорость.

Цикл TDD

Начало → Написать провальный тест → Запуск теста: Провал? 
  → Написать минимальный код → Запуск теста: Успех?
  → Рефакторинг → Тесты проходят? → Новый тест

Достоинства с AI

Точные промпты

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

Предотвращение "подгонки" тестов

Для сломанного кода агент напишет сломанный успешный тест.

Защита от регрессий

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

Проблемы

  • ИИ-агенты по умолчанию не любят работать короткими итерациями Red-Green-Refactoring
  • Обычные текстовые промпты с просьбой "использовать TDD" часто игнорируются
  • Агенты не умеют ещё достаточно хорошо и качественно писать тесты до логики
  • Для генерации тестов требуется детализированная спецификация

Стратегии реализации

Изоляция контекста

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

Ручное ревью тестов

Человек должен проверить и скорректировать сгенерированные тесты. Написание кода только после подтверждения корректности логики.

Автоматизированный контроль

Блок написания кода без предварительно созданных тестов. Хуки или TDD guard.

Специализированные воркфлоу

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


Spec Driven Development (SDD)

Это подход, где спецификации (а не код) становятся главным источником истины.

SDD предоставляет ИИ конкретные контракты, превращая спецификацию в "высокоуровневый язык программирования", а генерацию кода в процесс его компиляции.

Уровни

Spec-first

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

Spec-anchored

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

Воркфлоу SDD

Задача → Specify → Ревью → Plan → Ревью → Tasks → Implement → Validate → Готово
         ↑__________________________________________↓
                        (при необходимости)

Этапы

Specify

Описание того, что нужно построить (поведение, пользовательский путь, бизнес-правила), без деталей реализации.

Plan

Описание того, как это реализовать (архитектура, стек, ограничения).

Tasks

ИИ разбивает план на мелкие изолированные задачи для пошаговой реализации.

Implement

Агент пишет код для каждой задачи.

Validate

Проверка тестами и человеком.

Человек выступает в роли валидатора, проверяя узконаправленные изменения.

Примеры инструментов

  • Github Spec-Kit
  • OpenSpec
  • Kiro
  • Qoder и другие современные решения

Spec as Source

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

Принципы

Спецификация (Человек) → Генерация → Код (ИИ)
                              ↓
                    Поведение соответствует?
                         Да / Нет
                        /         \
                   Продакшен   Обновление спецификации

Запрет на ручное редактирование кода

Код полностью генерируется из спецификации.

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

Устранение рассинхронизации

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

Эволюция Model-Driven Development

Разработчики больше не скованы жёсткими языками моделирования (такими как UML) и сложными генераторами кода.

Проблемы

  • Недетерминированность LLM-моделей — Нужно писать спецификации максимально однозначно
  • Необходимость автоматизированного тестирования — Для верификации контрактов

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

Context Engineering

Управление контекстом (Context Engineering) — это искусство предоставления LLM именно той информации, которая необходима для выполнения следующего шага, в рамках ограниченного окна модели.

Составляющие

Управление Памятью

Необходимо сохранять контекст между шагами для достижения целей.

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

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

Главные правила

  • Мусор на входе = Мусор на выходе
  • Всегда точно знайте, что в данный момент находится в контексте

Что такое контекст

Контекст — это краткосрочная память агента, аналогично RAM компьютера.

Контекст формируется динамически и обычно включает:

Системный промпт (System prompt)

Базовые инструкции, профиль поведения и статические правила (AI: Rules).

История диалога

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

Определения инструментов

Описания AI: Tools, AI: Skills, AI: Subagents, AI: MCP и т.д.

Внешние знания и файлы

Извлеченные фрагменты документов (AI: RAG), результаты поиска, содержимое прочитанных файлов, логи ошибок.

Т.е. это всё, кроме последнего промпта от пользователя.

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

Ограниченность окна и рост затрат

Трансформеры имеют квадратичную сложность: удвоение контекста увеличивает объем вычислений в четыре раза. Переполнение окна ведет к росту задержек (latency) и стоимости каждого запроса.

«Гниение контекста» (Context Rot) и «Lost in the middle»

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

Предотвращение галлюцинаций и путаницы

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

Долгосрочные задачи и персонализация

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

Деградация

Тесты показывают, что чем больше объем контекста и чем больше в нем "вопросов", тем ниже точность ответов модели.


Memory Bank

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

Структура файлов

Например, .memory_bank/.

Отражает иерархию знаний в виде графа. Главный файл служит маршрутизатором.

Обязательный минимум: Архитектура, стек технологий, инструкции по запуску, ключевые концепции, development conventions.

index.md
├── Product Overview
│   ├── User Stories
│   └── Features, Epics
├── Steerings
│   ├── Development Conventions
│   ├── Testing Conventions
│   └── Patterns
├── Tech Details
│   ├── Infrastructure
│   └── Tech stack
├── Workflows
└── Tasks

Описание разделов

index.md

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

Product Overview

Бизнес-контекст продукта. Содержит ответы на вопросы «для кого» и «зачем» мы это делаем:

  • User Stories: Пользовательские сценарии и их ожидания
  • Features, Epics: Крупные блоки функционала и фичи

Steerings

Руководящие принципы, конвенции и ограничения:

  • Development Conventions: Правила написания кода, архитектурные паттерны, стилистика
  • Testing Conventions: Правила написания тестов, покрытия и моков
  • Patterns: Фундаментальные архитектурные решения

Tech Details

Техническая реализация и окружение:

  • Infrastructure: Инструкции по развертыванию, CI/CD, докер-контейнеры
  • Tech stack: Базы данных, фреймворки, версии библиотек

Workflows

Пошаговые чек-листы для типовых задач.

Tasks

Живой трекинг задач. Список того, что нужно сделать (To Do), что в работе и что завершено.

Жизненный цикл

Session Starts → Read Memory Bank → Rebuild Context → Continue work
                      ↑__________________________________↓
                           Update Memory Bank

Session Starts

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

Read Memory Bank

Первое действие агента — чтение index.md и перекрестных ссылок. Агенту строго запрещено начинать писать код до этого шага.

Rebuild Context

Агент «пересобирает» контекст проекта в своей оперативной памяти. Он понимает текущий стек, ограничения и актуальную задачу из папки Tasks.

Continue work

Этап непосредственного исполнения задачи с учетом подгруженного контекста.

Update Memory Bank

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

Внедрение Memory Bank

Базовая инструкция:

"Перед началом любой задачи проверь папку memory-bank/. Если ее нет — создай базовую структуру. Если она есть — всегда читай её содержимое для понимания контекста".

Использование Mermaid в промптах

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

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

Полезно создать кастомную команду /refresh_context, которая принудительно заставит агента перечитать Memory Bank, если вы заметили, что он начал "галлюцинировать" от переполнения контекста.


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: AI-агент, получив задачу, генерирует код с проблемами.

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

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

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

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

Каждый Feedback → возможность улучшить модель.

Богаче Environment → умнее Agent.

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

Что делает 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
  • Workflows и 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-агента
  • AI пишет тесты за секунды
  • Время запуска и прогонов тестов нужно оптимизировать
  • Готовые тесты нужно защищать от саботажа со стороны AI

Playwright Agents

  • Planner
  • Generator
  • Healer

Execution & Runtime Feedback

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

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

Инструменты

  • Chrome DevTools MCP
  • BrowserMCP

Visual & Browser Feedback

Скриншоты — универсальный фидбек, который агенты отлично понимают.

Инструменты

  • BrowserMCP для подключения к вкладке
  • test-id для идентификации элементов

AI-Powered Review

AI-боты ловят проблемы раньше человека. Лучшее место для AI-ревью — CI/CD Pipeline.

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

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

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

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

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

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

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

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

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

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

Isolated Env и Sandboxing

Изоляция = безопасность. Агент может "сломать" только sandbox.

Инструменты

  • Containers: Docker
  • Cloud Sandboxes: E2B, Daytona
  • CI/CD Pipelines: GitHub Actions, Vercel
  • Preview Environments: Vercel, Netlify

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

Что такое 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 человеку.

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Не каждый 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. Чем подтверждается результат

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

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

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

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

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

Проверьте:

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

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

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

Уточните:

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

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

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

Проверьте:

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

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

Инструменты

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

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

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

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

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

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

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

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

Проверьте:

  • принцип минимальных привилегий;
  • отдельные права чтения и записи;
  • 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 баллов.

  • 0–10: прототип или демонстрация; нельзя давать значимые права.
  • 11–20: ограниченный пилот; нужны узкая область и ручной контроль.
  • 21–26: готовность к production в формализованном процессе.
  • 27–30: зрелая платформа; итог всё равно зависит от качества конкретного сценария и интеграций.

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

Вопросы перед покупкой

  1. Какие действия агент может выполнять без подтверждения?
  2. Где физически обрабатываются и хранятся данные?
  3. Можно ли ограничить агента одним проектом и временным токеном?
  4. Как выглядит полная трасса успешного и неуспешного запуска?
  5. Как система доказывает фактическое выполнение действия?
  6. Как предотвращаются дубликаты при повторе?
  7. Можно ли остановить и безопасно возобновить задачу?
  8. Как тестируются обновления модели и промптов?
  9. Какие метрики качества доступны заказчику?
  10. Как удаляются память, журналы и пользовательские данные?
  11. Что произойдёт при недоступности модели или интеграции?
  12. Кто отвечает за инцидент и как отключить агента?
  13. Как рассчитывается полная стоимость одной завершённой задачи?
  14. Какие ограничения продукта не показаны в демонстрации?
  15. Можно ли провести пилот на собственном наборе сложных и ошибочных сценариев?

Итоговый критерий

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

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

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


Model Context Protocol (MCP)

MCP — это открытый стандарт, предложенный Anthropic, который позволяет LLM взаимодействовать с внешними системами через единый интерфейс. Аналог API, адаптированный для использования агентами.

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

AI applications ←→ MCP Standardized protocol ←→ Data sources and tools

AI applications:

  • Chat interface (Claude Desktop, LibreChat)
  • IDEs and code editors (Claude Code, Goose)
  • Other AI applications (5ire, Superinterface)

Data sources and tools:

  • Data and file systems (PostgreSQL, SQLite, GDrive)
  • Development tools (Git, Sentry, etc.)
  • Productivity tools (Slack, Google Maps, etc.)

Ключевые компоненты

Host (Среда) — среда (Claude Desktop, VS Code), которая управляет клиентами и координирует взаимодействие.

Клиент (Client) — AI-приложения или агенты, которые подключаются к серверам для получения контекста или выполнения действий.

Сервер (Server) — программы, предоставляющие доступ к конкретным инструментам или данным (API GitHub, Astra DB).

Возможности сервера

  • Tool: доступ к внешним функциям и данным
  • Prompt: управление поведением AI-агента
  • Resource: предоставляет данные клиенту

Зачем нужен MCP

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

Актуальный API

Клиент самостоятельно получит от Сервера всю свежую информацию о доступном API.

Доступ к актуальным данным

LLM могут запрашивать информацию в реальном времени.

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

Автоматизация сложных задач

Агенты ИИ могут выполнять многошаговые workflows.

Пример: данные из CRM → отправить email → обновить тикет.

Достоинства MCP

  • Единый протокол для всех интеграций, снижающий затраты на разработку
  • Безопасность: Локальный-first подход, запросы подтверждаются пользователем
  • Гибкость: Поддержка любых языков программирования для серверов
  • Динамическое обнаружение инструментов: Модели автоматически находят доступные серверы и их функции

Подводные камни

  • Для подключения каждого нового сервиса всё равно требуется создать MCP-сервер
  • Зависимость от качества данных: если внешние данные неточны, ответы ИИ тоже будут ошибочными
  • Сложность отладки: Интеграции требуют мониторинга логов и проверки совместимости
  • Устаревание: Риск устаревания из-за быстрого развития AI

Проблемы и решения

Проблема: Слишком много инструментов — даже значительно.

Решения:

  • Claude Tool Search с подгрузкой mcp on-demand
  • Использовать AI: Skills вместо MCP
  • Использовать CLI-интеграции с сервисами

Проблема: Нет гарантий качества результата

Проблема: Инструменты могут быть не адаптированы под LLM

Проблема: Простой API может вернуть избыточную для AI информацию и "убить" контекст

Решение: MCP должен фильтровать данные на стороне сервера и возвращать LLM только ту информацию, которая релевантна для задачи.


Language Server Protocol (LSP)

LSP — это протокол, который позволяет редакторам кода, IDE, а теперь и AI-агентам, общаться с языковыми серверами.

Языковой сервер

Языковой сервер (LSP-сервер) — это отдельная программа, которая "понимает" конкретный язык программирования и предоставляет умные функции:

  • Автодополнение кода
  • Переход к определению (Go to Definition)
  • Поиск ссылок (Find References)
  • Анализ ошибок в реальном времени (Diagnostics)

Как работает LSP

Взаимодействие происходит в фоновом режиме по формату JSON-RPC (stdio).

Поток работы

  1. Событие: Вы открываете файл, или AI-агент вносит изменения в код
  2. Запрос: Клиент отправляет JSON-сообщение серверу
  3. Анализ: Сервер строит абстрактное синтаксическое дерево (AST), проверяет типы и ищет нужную информацию в своей памяти
  4. Ответ: Сервер возвращает клиенту ответ в формате JSON (например, точные координаты функции в соседнем файле или список синтаксических ошибок)

LSP в AI-агентах

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

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

Внедрение в разных агентах

OpenCode

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

Claude Code

Для работы встроенного инструмента часто требуется явно включить поддержку. Добавьте в конфигурационный файл ~/.claude/settings.json:

{
  "env": {
    "ENABLE_LSP_TOOL": "1"
  }
}

В корне вашего проекта создается файл .lsp.json, который описывает команду запуска установленного сервера.

В качестве более удобной альтернативы можно использовать маркетплейсы плагинов, добавив пакет claude-code-lsps, где уже настроены пресеты для десятков языков.


Agent Client Protocol (ACP)

ACP — это стандартизированный протокол взаимодействия между IDE и AI-агентами.

Зачем нужен ACP

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

Преимущества

  • Избавляет от привязки к вендору: Разработчикам не нужно менять привычный рабочий процесс ради того, чтобы воспользоваться другим AI-агентом
  • Обеспечивает универсальность: AI-агент создается один раз под стандарт ACP и после этого автоматически работает во всех редакторах кода, поддерживающих этот протокол
  • Ускоряет развитие инструментов: Создатели редакторов могут сфокусироваться на удобстве интерфейса, а создатели AI — на интеллекте моделей

Принцип работы

Разработчик не покидает свою любимую IDE.

Связь с локальными агентами

AI-агент запускается как подпроцесс прямо внутри редактора. Общение идет по стандарту JSON-RPC (stdio).

Связь с удаленными агентами

IDE общается с AI-агентом по сети через HTTP или WebSocket.

Специализация под JSON

Аналогично AI: MCP, но ACP добавляет специфичные для программирования элементы (например, передача и отрисовка diff).

Визуализация через Markdown

Ответы агента передаются в формате Markdown, не принуждая создателей IDE встраивать тяжелый HTML-рендеринг.

Поддержка ACP

Главные драйверы протокола

  • JetBrains IDEs — JetBrains является соавтором стандарта
  • GitHub Copilot
  • Emacs — через плагин agent-shell
  • AionUi — open-source Cowork-клиент с ACP
  • marimo — аналог Jupyter, которое использует ACP для интерактивного кодинга с ИИ, сфокусированного на данных
  • Unity — через плагин

RAG (Retrieval-Augmented Generation)

RAG — это подход, который объединяет поиск информации (Retrieval) во внешних базах данных и генерацию ответов (Augmented Generation) языковой моделью (LLM) на основе найденного.

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

Процесс RAG

  1. Получение запроса от пользователя
  2. Векторный поиск релевантной информации в базе данных (картотеке)
  3. Формирование контекста из найденных фрагментов
  4. Генерация ответа LLM с учетом найденных данных и "врожденных" знаний
  5. Выдача ответа пользователю со ссылками на источники

Архитектура File-first

Иногда вместо сложной RAG-системы с базами данных используется более простой подход File-first (работа напрямую с файлами).

Когда подходит File-first

✅ У вас сотни или тысячи файлов (умеренный объем)
✅ Файлы часто обновляются
✅ Нужна простота развертывания и скорость настройки
✅ Нет ресурсов или времени на построение сложных data-engineering пайплайнов
✅ Требуется сложный reasoning по тексту
✅ Нет фиксированного workflow — нужна гибкость и эксперименты

Когда File-first НЕ подходит (нужен RAG)

❌ У вас миллионы документов
❌ Необходим умный семантический поиск по смыслам
❌ Критична задержка (latency) < 100 миллисекунд
❌ Остро стоит вопрос стоимости токенов (отправлять тысячи файлов в LLM дорого)
❌ Системой пользуется очень много людей одновременно
❌ Есть понятный бизнес-процесс (DAG) и требуется стабильная структура архитектуры

Long-Context LLMs

Long-Context (LC) модели превосходят классический RAG по качеству ответов, так как видят документ целиком и не теряют связи. Однако RAG остается безоговорочным лидером по стоимости и скорости.

Когда лучше использовать Длинный Контекст (Long-Context)

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

Когда лучше использовать RAG

  • Актуальность данных: Базы RAG могут обновляться в реальном времени
  • Снижение галлюцинаций: Опора на четкие извлеченные факты
  • Приватность: Работа с закрытыми корпоративными данными
  • Оптимизация расходов: В RAG модель читает только пару релевантных абзацев, а не книгу в 1000 страниц, что радикально снижает затраты на API
  • Прозрачность: RAG позволяет точно указать, из какого абзаца какого документа взят ответ

Гибридный подход (Self-Route)

Если вопрос простой, система использует дешевый RAG. Если вопрос сложный, запрос отправляется в дорогой Long-Context.

Подводные камни RAG

  • Качество упирается в поиск: Если поисковик или эмбеддинг-модель извлекли нерелевантные фрагменты («мусор на входе»), LLM выдаст красивый, но бесполезный ответ («мусор на выходе»)
  • Задержка (Latency): Процесс преобразования запроса в вектор и поиск по базе занимает время
  • Конфликты данных: Если в базе лежат два документа с противоречащей информацией, модель может запутаться при генерации ответа

Применение RAG

RAG — это фундамент современного корпоративного ИИ:

  • Чат-боты техподдержки, знающие всю документацию компании
  • Внутренние поисковики (Intranet) по базам знаний и регламентам
  • Системы генерации образовательного контента (как в Pearson)
  • Персональные ИИ-ассистенты, ищущие релевантные рекомендации в заранее собранной базе данных

Sandbox (песочница)

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

Техническая реализация

Технически песочница чаще всего реализуется с помощью:

  • Контейнеры (например, Docker)
  • Легковесные микровиртуальные машины (например, AWS Firecracker)

Зачем нужен Sandbox

Защита от галлюцинаций и ошибок

Агент может перепутать команды и вместо сортировки файлов попытаться удалить корневой каталог (rm -rf /).

Защита от злонамеренных промптов (Prompt Injection)

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

Контроль ресурсов

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

Конфиденциальность

В изолированной среде агент не сможет получить доступ к переменным окружения хоста (например, к секретным ключам API других сервисов).

Как работает

  1. Среда выполнения: Когда агенту нужно выполнить действие, система мгновенно поднимает изолированный контейнер
  2. Ограничение прав: Контейнер не имеет доступа к основной операционной системе, сети (или сеть ограничена) и реальным базам данных
  3. Mock-сервисы: Если агенту нужно потренироваться работать с API, ему дают заглушки, которые имитируют ответы реальных сервисов, но ничего не меняют в реальном мире
  4. Уничтожение: Как только задача выполнена или истек тайм-аут, контейнер полностью уничтожается вместе со всеми временными файлами

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

Боты без агентных возможностей

Если LLM просто генерирует текст и не умеет в Tool calling или Function calling, песочница будет пустой тратой вычислительных ресурсов.

Системы реального времени (Low-latency)

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

Финальный этап выполнения реальной задачи

Если задача агента — произвести действия в "реальном" мире, песочница ему помешает. Вместо этого используется Role-Based Access Control и подход Human-in-the-loop.


Structured Output (Структурированный вывод)

Structured Output — это инструмент взаимодействия с LLM, гарантирующий, что ответ будет возвращен в строгом, заранее определенном и машиночитаемом формате (обычно это JSON).

Как это работает

Работает как API на уровне инференса. Использует технологию Constrained Decoding (Ограниченное декодирование).

Когда вы передаете в API свою JSON-схему, движок модели строит FSM или использует формальную грамматику.

Процесс генерации

На каждом шаге генерации алгоритм проверяет вероятности следующих токенов:

  1. Вычисляет все возможные следующие токены
  2. Отбрасывает те токены, которые нарушают синтаксис JSON или заданную схему
  3. Модель выбирает токен только из списка «разрешенных»

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

АспектТекстовая инструкцияJSON Schema
Способ запросаТекстовая инструкция в system prompt («выведи JSON»)Передача JSON Schema в параметр API (response_format)
НадежностьНизкая. Модель может добавить текст до или после JSONАбсолютная. Модель генерирует только валидный JSON
Соблюдение типовМожет ошибиться (вернуть строку "10" вместо числа 10)Строгое соблюдение типов из схемы
Галлюцинации ключейМожет придумать лишние ключи или забыть нужныеГенерирует строго по ключам, описанным в схеме

Best Practices

Используйте поля description

Из них модель понимает, что именно нужно положить в это поле. Пишите их максимально четко.

Keep it Simple

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

Совмещайте с SGR

Если задача сложная (требует логики), используйте AI: SGR.


Tools (Инструменты)

Исполняемые функции — «руки» агента, выходными данными и побочными эффектами. Являются "руками" агента, которые совершают действия.

Примеры инструментов

Работа с файлами

  • read — чтение содержимого файлов (включая чтение конкретных диапазонов строк для больших файлов)
  • edit — точечное изменение файлов (замена строк кода)
  • write — создание новых файлов или полная перезапись существующих
  • patch — применение файлов исправлений (патчей) к кодовой базе
  • list — просмотр содержимого директорий
  • grep — быстрый поиск по содержимому файлов с использованием регулярных выражений (под капотом работает сверхбыстрый ripgrep, который по умолчанию учитывает .gitignore)
  • glob — поиск файлов по паттернам (например, src/**/*.ts)
  • lsp — взаимодействие с настроенными LSP-серверами. Позволяет ИИ понимать архитектуру: переходить к определениям (Go to Definition), искать ссылки на функции и анализировать иерархию вызовов

Терминал и выполнение команд

  • bash — выполнение shell-команд в среде проекта

Сеть и поиск

  • webfetch — загрузка и чтение содержимого по конкретному URL-адресу (например, чтение документации)
  • websearch — поиск информации в интернете через сервис Exa AI (работает без ключа API). Отлично подходит для изучения новых тем и сбора актуальной информации, которой не было в обучающих данных модели

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

  • todowrite / todoread — создание, чтение и обновление списков задач. Помогает ИИ разбивать сложные задачи на шаги и отслеживать прогресс выполнения
  • question — инструмент, позволяющий ИИ приостановить работу и задать вам уточняющий вопрос
  • skill — загрузка файла с навыком (SKILL.md), чтобы передать агенту специфические знания или инструкции

Commands (Slash Commands)

Файлы с часто используемыми промптами и задачами для AI-агента. Вариант AI: Workflows, но с поддержкой на уровне агента. Более упрощённая реализация AI: Skills — в виде одного файла, и без динамической подгрузки в контекст — только по ручному вызову.

Как работает

Обнаружение

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

Активация

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

Развертывание шаблона

Содержимое команды превращается в текст промпта, куда подставляются переданные аргументы (через переменные $ARGUMENTS или $1, $2, ...), подгружается содержимое файлов, указанных через префикс @, и внедряется вывод bash-скриптов, указанных через префикс !.

Исполнение

Сформированный промпт отдаётся LLM, которая выполняет указанные действия, опираясь на заданные в метаданных команды настройки (модель, разрешения и т.д.).

Структура Commands

commands/
|- {command_1}.md
|- {command_2}.md

Или запись в конфигурационном файле .jsonc:

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

Расположение

  • Локально в проекте: .{agent-name}/commands/{command-name}.md
  • Глобально у пользователя: ~/.{agent-name}/commands/{command-name}.md

Файл .md

YAML-шапка (Frontmatter)

  • description: Описание для отображения в GUI
  • subtask: возможность запуска в отдельном субагенте
  • model: указание модели для использования

Тело инструкции (Markdown)

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

Пример конфигурации

---
description: "Запуск тестов и анализ ошибок"
model: "claude-3-5-sonnet-20241022"
subtask: true
---

// Основные инструкции в Markdown

Для чего команды

Задание workflow для работы агента.

Использование команд

/rnd-task Добавление статуса "Отравление"

Добавление в контекст через @, как Workflow:

Персонаж бежит не туда, исправь по инструкции @fix-bug/SKILL.md

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

Команды, применяемые к предыдущему сообщению:

  • /redo — повторить отменённое через undo сообщение
  • /fork — создание нового чата со всем текущим контекстом
  • /compact — форсированное сжатие контекста в текущем чате
  • /editor — открыть внешний редактор для промпта перед отправкой
  • /export — сохранение контекста текущего чата в файл
  • /init — автоматическое обновление AGENTS.md
  • /new — новый чат

Claude Code Routines

Routines — способ превратить разовые команды в повторяемые сценарии в Claude Code. Вместо ручного управления ты задаёшь поведение один раз, и Claude сам выполняет цепочки действий под задачу.

Это не просто промпты, а воспроизводимые workflow внутри Claude Code.

Что даёт

  • Автоматизация типовых задач — рутинные операции выполняются автоматически
  • Меньше ручного контроля — Claude сам следует заданному сценарию
  • Стабильный результат — предсказуемый выход от запуска к запуску
  • Экономия времени — один раз описал, дальше система работает сама

Триггеры запуска

Routines можно запускать разными способами:

  • По расписанию — ежедневно, еженедельно, в определённое время
  • GitHub события — PR opened, PR closed, push в ветку
  • API вызов — внешняя система инициирует запуск
  • Вручную — через CLI или веб-интерфейс

Создание Routines

Через веб-интерфейс

  1. Открыть claude.ai/code/routines
  2. Задать имя и описать задачу в промпте
  3. Выбрать репозитории
  4. Настроить окружение (cloud environment)
  5. Выбрать триггер
  6. Создать routine

Через CLI

/schedule daily PR review at 9am

Основные команды:

  • /schedule — создать новую routine
  • /schedule list — список всех routines
  • /schedule update — обновить существующую
  • /schedule run — запустить вручную

Через Desktop app

Используется локальная версия Desktop scheduled tasks.

Настройка окружения

Для cloud-запуска можно настроить:

  • Network access — уровень доступа к интернету
  • Environment variables — API ключи, токены, секреты
  • Setup script — команды установки зависимостей перед запуском

Примеры использования

  • Ежедневный review открытых PR
  • Автоматическая проверка кода при создании PR
  • Регулярное обновление документации
  • Автоматизация релизных задач
  • Реагирование на изменения в репозитории

Отличие от Skills

SkillsRoutines
Загружаются по требованию в контекстЗапускаются автоматически по триггеру
Инструкции для агентаГотовые сценарии действий
Динамическое использованиеАвтоматизированное выполнение

Best Practices

  • Начинай с простых сценариев, усложняй постепенно
  • Тестируй routine вручную перед автоматизацией
  • Используй понятные имена и чёткие промпты
  • Настраивай уведомления о результатах выполнения
  • Документируй, что делает каждая routine

Skills (Навыки)

Упакованная экспертиза для специфических задач (инструкции, скрипты, контекст), которая позволяет ИИ-агентам выполнять специфические задачи более точно и эффективно. Навыки загружаются в контекст динамически, экономя ресурсы.

Как работает

Обнаружение

Изначально агент видит только Frontmatter навыка (имя и описание) в списке доступных инструментов. Полный текст инструкции в контексте отсутствует.

Выбор

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

Активация

Если навык нужен для текущей задачи (или получена явная команда), агент делает Tool Call для загрузки содержимого.

Исполнение

Полный текст SKILL.md и связанные файлы загружаются в контекстное окно, и агент выполняет инструкции.

Структура Skills

skills/
|- {skill-name}/
   |-- SKILL.md     # Определение навыка (инструкция)
   |-- scripts/     # Вспомогательные скрипты (опционально)
      |--- *.py     # Чаще всего python или js/ts
   |-- # Любые другие файлы и директории, нужные навыку

Расположение

  • Локально в проекте: .{agent-name}/skills/{skill-name}/
  • Глобально у пользователя: ~/.{agent-name}/skills/{skill-name}/

Файл SKILL.md

YAML-шапка (Frontmatter)

  • name: Идентификатор для вызова
  • description: Описание, чтобы агент понял, когда активировать навык

Тело инструкции (Markdown)

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

---
name: skill-name           # Уникальное имя (a-z, 0-9, дефисы)
description: Use when...   # Краткое описание (1-2 предложения, до 500 знаков)
---

// Основные инструкции в Markdown

Для чего Skills

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

Специализированные знания

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

Строгие рабочие процессы

Когда нужно гарантировать выполнение чек-листа или последовательности шагов (например, выполнение задачи по плану).

Примеры Skills

  • Поиск информации в коде
  • Рефакторинг
  • Написание тех документации
  • Добавление комментариев в код

Использование Skills

Автоматический выбор

Агент автоматически выбирает подходящий навык на основе запроса:

Напиши юнит-тесты для класса Player → активирует create-unit-tests
Сделай ревью моих изменений → активирует review-code

Явный запрос

Задокументируй этот класс, используя навык → активирует add-summary

Вызов через /, как Command

/rnd-task Добавление статуса "Отравление"

Вызов через Hook

Перед обработкой промпта или после ответа агента.

Добавление в контекст через @

Персонаж не прыгает, исправь по инструкции @agents/unity-developer.md

Best Practices для Skills

  • Компактность важнее длины — Качество навыков важнее их количества в эффективности решения задач. Меньшие и более дешевые модели, снабженные хорошими навыками, способны превосходить более крупные модели без навыков
  • Создавайте для всех частых повторяющихся действий — промптов/инструкций
  • Цепочки навыков — Можно создавать цепочки навыков, когда один навык отдаёт требование на запуск другого
  • Компактные и умеренно детализированные — инструкции работают гораздо лучше, чем длинные документы. Оптимально до 150 строк или до 1000 токенов
  • Оптимальное количество — от 2 до 3 навыков для одной задачи. 4 и более навыков перегружает агента и снижает эффективность
  • Пишите навыки самостоятельно — Модели не обучены генерировать навыки сами для себя. Агент со сгенерированными навыками работает даже хуже, чем без них совсем
  • Поле description — должно отвечать на вопрос "Когда это использовать?", а не "Что это такое"
  • Используйте теги <required> или прямые приказы («CRITICAL», «MANDATORY»). Агенты лучше реагируют на императивный тон в инструкциях навыка
  • Навык должен быть самодостаточным — Если он требует внешних скриптов, положите их в папку scripts/ внутри навыка

Замена MCP

Навыки изначально разрабатывались как более эффективная и экономная в плане контекста замена AI: MCP. Вы можете заменять свои MCP на кастомные скиллы.


Subagents (Суб-агенты)

Специализированные агенты в изолированном контексте, которые работают в собственном изолированном контекстном окне с уникальным системным промптом и набором инструментов.

Как работают субагенты

Главный агент (оркестратор)

Анализирует запрос пользователя и поле description всех доступных суб-агентов.

Делегирование

Если задача соответствует специализации суб-агента, она делегируется ему. Суб-агент работает независимо.

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

Выполнение

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

Результат

Субагент возвращает оркестратору отчёт. Детали выполнения остаются внутри субагента.

Работа с контекстом

Каждый субагент имеет свое контекстное окно.

Преимущества

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

Структура

agents/
  {subagent-name}.md  # Файл определения суб-агента

Расположение

  • Локально в проекте: .{agent-name}/agents/{subagent-name}.md
  • Глобально у пользователя: ~/.{agent-name}/agents/{subagent-name}.md

Файл .md

YAML-шапка (Frontmatter)

  • name: Идентификатор для вызова
  • description: Описание, чтобы агент понял, когда активировать субагента
  • mode: subagent | primary (primary активируются строго вручную)
  • model: указание модели для использования
  • tools: настройка доступов к инструментам

Тело инструкции (Markdown)

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

---
description: Описание назначения в стиле "Use when..."
mode: subagent
model: anthropic/claude-sonnet-4
tools:
  read: true
  write: true
  edit: true
  bash: true
temperature: 0.1
---

// Системный промпт и инструкции для суб-агента в Markdown

Для чего субагенты

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

Как использовать

Автоматический выбор

Проверь выполненную задачу → активирует qa-expert

Явный запрос

Проведи рефакторинг в субагенте → активирует cs-expert

Вызов через @

@tech-writer документация на механику Призыва

Выбор в качестве режима работы

По Tab (для primary).

Вызов через Hook

Перед обработкой промпта или после ответа агента.

Best Practices для субагентов

  • Чем уже задача, тем точнее можно настроить системный промпт и тем меньше вероятность галлюцинаций
  • Предоставляйте субагенту только те инструменты, которые ему действительно нужны, чтобы не засорять контекст, фокусировать агента и обезопасить работу
  • Делайте описания детальными и используйте триггерные фразы вроде "Use when...", чтобы основной агент понимал, в каких случаях делегирование будет успешным
  • Делегируйте объемные задачи: Запуск тестов, получение объемной документации или чтение длинных логов могут переполнить контекст главного агента. Делегируйте эти задачи субагенту
  • Включайте постоянную память, чтобы они накапливали знания между сессиями
  • Распараллеливайте исследование: Если вам нужно исследовать разные, не связанные между собой части системы, поручите это нескольким субагентам одновременно
  • Последовательные вызовы: Для многошаговых процессов просите вызывать субагентов последовательно
  • Вызов из других инструментов: Можно запрашивать вызов субагентов из других инструментов: скиллы, команды и т.д.

Rules

Стандарт предоставления контекста для ИИ-агентов, по аналогии с README.md для людей, выраженный в виде инструкций, которые автоматически помещаются в контекст агента в начале каждой сессии.

Как работают Rules

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

Приоритизация

При конфликтах правил срабатывает иерархия: Локальные перекрывают Проектные, а Проектные перекрывают Глобальные.

Удержание

Агент руководствуется этим контекстом на протяжении всей сессии (пока правило не забудется из-за переполнения контекста).

Структура Rules

Расположение

  • Глобально у пользователя: действуют везде
  • Локально в проекте: в корневой директории, действуют на всём проекте
  • Локально в подпапках: действуют только там

Взаимодействие

Учитываются все файлы правил, но с разным приоритетом.

Чем файл ближе к месту работы агента, тем он приоритетнее.

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

Приоритет: Подпапки → Проект → Глобально

Варианты реализации

  • AI-IDE и плагины: множество файлов правил в директории {agent-name}/rules
  • CLI: собственный файлы правил CLAUDE.md / QWEN.md / GEMINI.md
  • Общий стандарт: AGENTS.md, поддерживается не всеми агентами

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

Файл AGENTS.md и аналоги

Содержит:

  • Инструкции
  • Ограничения
  • Общие знания о проекте
  • Стек
  • Навигация
  • Общие команды
  • Ссылки на другие инструкции и документацию

Шаблон

# Руководство для ИИ-агента на проекте X

## О проекте
...

## Структура проекта
...

## Правила работы
...

## Ограничения
...

## Ссылки и контекст
...

Для чего нужны Rules

  • Адаптация к стеку: Быстрое погружение агента в стек и специфику текущего репозитория
  • Глобальные ограничения: Предотвращение частых, критических ошибок (запрет force-push, сырого SQL и т.д.)
  • Маршрутизация: Указание агенту, где искать детали, оставляя основной промпт чистым

Best Practices для Rules

  • Оптимальный размер — 30-300 строк. При превышении 500 строк качество падает, а затраты на токены значительно возрастают
  • Вносите дополнительный контекст в другие документы, навыки и команды, проектная документация
  • Используйте компактные правила разной локальности
  • Файлы правил приносят максимум пользы на проектах, где нет документации. Если документация есть, потребность в избыточно больших правилах отпадает
  • Наличие верхнеуровневой навигации по репозиторию в правилах НЕ помогает агентам быстрее находить нужные для редактирования файлы
  • Будьте конкретны, не используйте абстрактные требования и ограничения
  • Используйте указание конкретных bash-команд для точных повторяемых действий
  • Правила нужно проектировать самостоятельно — Автогенерация через /init снижает успешность решения задач и увеличивает количество шагов агента, что приводит к росту стоимости вычислений
  • Корректируйте и обновляйте правила по мере работы над проектом. Не пытайтесь написать сразу идеальные правила. Корректируйте правилами только то, что агент делает неправильно регулярно

Hooks

Пользовательские скрипты на этапах работы агента, команды, HTTP-запросы или плагины, которые автоматически срабатывают на заранее заданных этапах работы ИИ-агента (например, перед выполнением bash-команды, после редактирования файла или при завершении сессии).

Зачем нужны Hooks

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

Польза

  • Безопасность: Перехват и блокировка опасных действий (например, защита от выполнения rm -rf или запрет на чтение .env файлов с секретами)
  • Автоматизация: Мгновенный запуск автоформатирования (Prettier/Black), линтеров или юнит-тестов сразу после того, как ИИ изменил файл
  • Удобство: Отправка уведомлений на рабочий стол или в мессенджер, когда ИИ завершил задачу или ждет разрешения на действие

Настройка Hooks

Пример конфигурации

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ./scripts/block-danger.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write ."
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "say 'Claude expects your input'"
          }
        ]
      }
    ]
  }
}

Виды событий

СобытиеMatcherОписание
PreToolUseимя инструментаПеред использованием инструмента
PostToolUseимя инструментаПосле использования инструмента
PostToolUseFailureимя инструментаПри ошибке инструмента
PermissionRequestимя инструментаПри запросе разрешения
SessionStartstartup, resume, clear, compactКак началась сессия
SessionEndclear, logout, prompt_input_exit, bypass_permissions_disabled, otherПочему сессия завершилась
Notificationpermission_prompt, idle_prompt, auth_success, elicitation_dialogТип уведомления
SubagentStartBash, Explore, Plan или пользовательские именаТип агента
SubagentStopте же значенияТип агента
PreCompactmanual, autoЧто вызвало сжатие контекста
ConfigChangeuser_settings, project_settings, local_settings, policy_settings, skillsИсточник конфигурации

События без matcher

  • UserPromptSubmit
  • Stop
  • TeammateIdle
  • TaskCompleted
  • WorktreeCreate
  • WorktreeRemove
  • InstructionsLoaded

Всегда срабатывают при каждом возникновении.

Best Practices для Hooks

  • Настройте регулярные выражения на перехват деструктивных shell-команд или попыток сделать коммит напрямую в main ветку
  • Полезно настроить хук, который автоматически делает локальный git-коммит после каждого успешного завершения задачи агентом
  • Пишите максимально быстрые скрипты, чтобы не создавать задержек в цикле работы агента
  • Настраивайте строгие Matchers и проверяйте аргументы внутри плагинов, чтобы хуки не срабатывали вхолостую

Плагины

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

Состав плагина

Обычно плагин включает в себя одну или несколько сущностей:

  • AI: Tools
  • AI: Skills
  • AI: Hooks
  • AI: Commands
  • AI: Subagents
  • AI: MCP

Установка в Claude Code

Подключение репозитория

/plugin marketplace add anthropics/claude-code

Установка плагина

/plugin install commit-commands

Устанавливается глобально или только для текущего проекта.

Управление

Плагины можно точечно включать и выключать (/plugin enable, /plugin disable), чтобы держать контекст чистым в зависимости от того, над чем вы сейчас работаете.

Установка в OpenCode

Устанавливаются в папку .opencode/plugins/, либо устанавливаются глобально в ~/.config/opencode/plugins/ через клонирование GitHub-репозиториев или npm.

Внедрение в команду

Принципы внедрения

"С завтрашнего дня все используем Copilot"

Вызывает жесткое сопротивление команды.

Только Bottom-up: «Каждый ставит, что хочет»

Приводит к хаосу инструментов и невозможности обмена опытом.

✅ Гибридный подход

  • Руководство задает общие правила, цели и выделяет ресурсы
  • Разработчики тестируют инструменты в задачах и делятся результатами

Алгоритм внедрения

Не пытайтесь внедрить ИИ сразу во все процессы

Запускайте "пилотные" фичи, которые не несут рисков и быстро показывают ценность:

  • Генерация unit-тестов
  • Помощь в code review
  • Документация

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

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

Если хотите, чтобы сотрудники использовали ИИ, дайте им ИИ.

Предоставьте возможность

Предоставьте возможность сотрудникам пробовать решать свои повседневные задачи через ИИ.

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

Опирайтесь на энтузиастов

Дайте им время на изучение. Когда они покажут рост эффективности, команда сама подтянется за ними.

Бесшовная интеграция

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

Если инструмент заберет неприятную рутину и сэкономит хотя бы 20 минут в день — это станет переломным моментом для формирования привычки.

Единая база знаний

Делитесь удачными промптами, кейсами и решениями.

Обмен best-practice и вовлечение внутри команды — ключевой фактор успеха.

Оживляйте процесс

Формат "разработчик + ИИ":

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

Этапы работы над задачей

Этап 1: Сбор требований

Назначение

Формализация входящих требований, снижение уровня шума и насыщение деталями.

Участники

Человек + reasoning-модель.

Артефакт

requirements.md

Источником требований может быть ГДД, которое необходимо превратить в полноценное ТЗ.

Этот этап можно проводить отдельно от проекта, в т.ч. в веб-чате.

Этап 2: Декомпозиция

На более мелкие, логически завершённые области работы.

Участники

Человек + reasoning-модель.

Артефакт

requirements_1.md, requirements_2.md, ...

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

Этап 3: Исследование

Назначение

Для отдельного Scope работ запросить у AI-агента полный анализ предметной области для составления "карты местности" и поиск возможных путей решения.

Участники

Reasoning-модель.

Артефакт

rnd.md

Что включить в запрос

  • Файл требований
  • Ограничения
  • Релевантные файлы и директории, которые потребуются для решения
  • Описание приложенного контекста
  • Ссылки на связанные документы

Этап 4: Спецификация

Назначение

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

Участники

Человек + reasoning-модель.

Артефакт

spec.md (+ ADRs)

Этап 5: Планирование

Назначение

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

Участники

Человек + reasoning-модель.

Артефакт

task-tracker.md, task-1.md, task-2.md, ...

Этап 6: Выполнение

Назначение

Автономная работа над задачами с настроенным Feedback Loop.

Участники

Coding-model.

Артефакт

Внесённые правки в кодовую базу.

Важно

Обеспечение полной автономности при работе над задачей:

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

Этап 7: Обновление документации

Назначение

Фиксация прогресса по работе над задачами и обновление информации о проекте.

Участники

Reasoning-model + coding-model.

Артефакт

Внесённые правки в документацию.

Что обновляется

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

Критерии оценки задач

1. Уникальность задачи

Что оценивает

Насколько задача стандартна.

Стандартная задача

Соответствует типичному паттерну, который ИИ-агент уже много раз видел.

Пример: Добавить стандартную сортировку по алфавиту в таблицу пользователей.

Уникальная задача

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

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

Решение

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

2. Глубина погружения в код

Что оценивает

Сколько контекста (файлов и зависимостей) должен изучить ИИ-агент для выполнения задачи.

Проблема

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

Решение

Разбивайте задачу на последовательные этапы:

  • Сначала компонент
  • Потом реализация логики
  • Затем интеграция

3. Знания, которых нет в кодовой базе

Что оценивает

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

Проблема

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

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

Решение

  • Отделите процесс "креатива" и описания фичи от процесса разработки
  • Добавляйте важные нюансы предметной области в промт или в глобальные правила проекта для ИИ-агента
  • Мысленно ставьте себя на место ИИ и спрашивайте: "Какую информацию мне нужно знать, чтобы выполнить эту задачу, видя только код?"

4. Количество мест для изменений

Что оценивает

Сколько файлов и участков кода нужно будет изменить для решения задачи. Это особенно актуально для рефакторинга.

Проблема

ИИ-агенты часто допускают ошибки при внесении изменений в большое количество файлов (> 20).

Пример: Простое переименование переменной, используемой по всему проекту.

Решение

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

5. Неявные состояния системы

Что оценивает

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

Проблема

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

Примеры:

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

Решение

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

Принятие решений о делегировании

Варианты:

  • Делегировать как есть (если задача простая и стандартная)
  • Декомпозировать на подзадачи
  • Добавить больше контекста (бизнес-правила, детали реализации)
  • Выполнить вручную (если задача слишком сложна или рискованна для ИИ)

Эволюция Workflow

Workflow — просто markdown-файл с часто используемыми инструкциями/промптами.

Этап 1

Передача в контекст файлом через @.

Примеры:

Проведи исправление описанного ранее бага по инструкции @fix-bug.md
Проведи код-ревью текущих изменений по инструкции @review-code.md

В AI: Rules можно было вести таблицу с перечислением всех имеющихся workflow и кратким описанием, чтобы агент мог самостоятельно искать, выбирать и применять нужные инструкции:

workflow-namedescription
review-codeРевью кода по указанной области
fix-bugШаги для исправления бага

Этап 2

Затем в агентах появилась поддержка AI: Commands. Они позволяли:

  • Создавать типовые инструкции по типу Workflows
  • Вызывать инструкции через /
  • Попадать в контекст напрямую, а не в качестве файла
  • Интегрировать в инструкции пользовательские промпты в качестве аргументов

Т.е. Commands стали официальной заменой пользовательским Workflows.

Этап 3

Затем появились AI: Skills.

Внутри каждого навыка есть Formatters, которые служат краткой мета-информацией для AI-агента о том, когда использовать навык.

Как таблица выше, которую теперь не нужно поддерживать в актуальном состоянии — агент подгружает сам все доступные Formatters.

Этап 4

Далее для Skills была добавлена поддержка ручного вызова через / и передачи аргументов внутрь описания. Теперь Skills заменяют собой и Workflows, и Commands.


Борьба с разрозненностью инструментов

Или пул поддерживаемых инструментов.

Рекомендации

Используйте открытые широко поддерживаемые стандарты, такие как AGENTS.md, Open Skills и т.д. (AI: Rules, AI: Skills).

Скрытие настроек

Скрывайте через gitignore папки с настройками конкретных агентов.

Синхронизация

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

Автоматическая настройка

Реализуйте инструмент, который автоматически проводит настройку выбранных ai-клиентов без попадания в git.

Централизованные интеграции

Используйте централизованные AI: Plugins или AI: MCP.


Главные ошибки при внедрении

Магический артефакт

Если лидер сам настроит ИИ-агентов и просто спустит их сверху, для команды это станет "магическим артефактом" без доверия и понимания.

Решение: Вовлекайте команду в процесс настройки, заставляйте их самостоятельно исправлять ошибки ИИ.

Пытаться обучить сразу всех

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

Внедрять ИИ на сложных задачах с горящими дедлайнами

Обучение работе с ИИ несовместимо со спешкой.

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


Проблематика внедрения ИИ

Текущие проблемы

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

Кто-то использует Cursor, кто-то — Copilot, кто-то — ChatGPT.

Отсутствие стандартов

У каждого свои настройки, промпты и подходы, нет общего workflow.

Расслоение

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

Скепсис

Распространено мнение, что "ИИ пишет плохой код".


Работа со скепсисом

Открыто обсуждайте слабости ИИ

Относитесь к нему как к junior-разработчику, а не как к архитектору.

Фокус на предотвращении ошибок

Позиционируйте ИИ как инструмент для поиска багов и уязвимостей, а не просто как средство для "абстрактного роста продуктивности".

Личный пример лидеров

Лиды должны сами использовать ИИ, демонстрировать свои успехи и открыто делиться ошибками.

Манифест

Открыто зафиксируйте, что можно и нужно делать с помощью ИИ, а что категорически запрещено (например, загружать ключи доступа).

Право на ошибку

Культивируйте психологическую безопасность. Ошибки сгенерированного кода — это повод для обучения, а не причина для отказа от технологии.

Загрузка комментариев...