AI агенты: 5 ошибок при настройке и как их избежать
Когда ты начинаешь работать с AI агентами, кажется просто — скинул промт в Claude Code, и готово. На практике это не работает. Я разберу, как правильно определить агента через триаду "задача — ресурсы — полномочия" и покажу реальные ошибки, которые я видел (и делал сам).
Что такое AI агент на самом деле
Агент — это не просто языковая модель, которая отвечает на вопросы. Это сущность, которая проявляет агентское поведение (или субъектность, если говорить языком педагогики). Агент действует, когда у него есть три вещи:
- Задача — что нужно сделать (обычно в промте)
- Ресурсы — доступ к данным, API, инструментам (Linear, Notion, файлы, поиск)
- Полномочия — что разрешено делать (от чтения до полного контроля над системой)
Без любого из этих трёх агент либо не сработает, либо будет работать плохо.
Ошибка 1: Путаешь контекст и ресурсы
Проблема: Ты скидываешь агенту статический контекст (текстовый файл с инструкциями) и ждёшь, что он будет работать как локальный помощник.
Почему это ошибка: Контекст — это статичный набор данных, который ты один раз загрузил. Ресурсы — это динамичный контекст, который обновляется в реальном времени. Например:
- Контекст: ты скинул PDF с описанием проекта
- Ресурс: агент может лезть в Linear и смотреть актуальные задачи прямо сейчас через MCP сервер
Как исправить: Используй MCP (Model Context Protocol) сервера для интеграции реальных сервисов. Если ты работаешь в Cursor или Claude Code, попроси агента настроить доступ к Notion, Linear или Exa (поиск). Вот так это выглядит в инструкции:
Тебе доступны следующие ресурсы:
- Linear API (читать/писать задачи)
- Notion (читать страницы)
- Gmail (читать письма)
Агент сам поймёт, как это использовать.
Ошибка 2: Даёшь слишком размытую задачу
Проблема: Ты говоришь: "Помоги мне подготовиться к встрече с клиентом" — и агент начинает гадать, что тебе нужно.
Почему это ошибка: Агент не может телепатировать. Он не знает, какого клиента, где его контакты, какие файлы открывать. Начинается бесконечный поиск по всем ресурсам сразу. [VERIFY]
Как исправить: Сформулируй задачу со ссылками на ресурсы и полномочия:
Подготовь краткий бриф по клиенту "Иван Иванов":
1. Найди его контакты в папке /Clients/IvanIvanov/
2. Посмотри историю в календаре (звёзды встречи с ним)
3. Выулиай ключевые моменты из Linear (тег #ivan-ivanov)
4. Напиши на русском, максимум 500 слов
Вот такая инструкция даёт агенту ясный путь действия. Результат будет точнее на 80%.
Ошибка 3: Не контролируешь полномочия (и потом жалеешь)
Проблема: Ты даёшь агенту полный доступ к компьютеру/облаку ("давай, делай что хочешь"), а потом он:
- Переписывает файлы в непредсказуемых местах
- Удаляет или изменяет данные без резервной копии
- Создаёт файлы с именами, которые конфликтуют с твоими системами
Это особенно актуально для Claude Code, которому ты говоришь что-то типа "выполни все полномочия".
Как исправить:
- Работай в отдельной папке — дай агенту доступ только к
/agents_workspace/или/temp/ - Требуй копии — в промте напиши: "Если нужно изменить файл, создай копию (
файл_v2.md,файл_v3.md)" - Используй Git — регулярно делай коммиты, чтобы откатиться, если что-то пошло не так
- Явно ограничивай действия — вместо "делай что угодно", напиши: "Тебе разрешено: читать файлы в /docs/, писать в /output/, НЕ разрешено удалять"
Пример для Claude Code:
ПОЛНОМОЧИЯ:
- Читать: папка /project/docs (и подпапки)
- Писать: папка /project/output только
- НЕ разрешено: удалять исходные файлы, менять конфиги
Ошибка 4: Забываешь про типы агентских сред
Проблема: Ты используешь инструмент не по его природе.
Есть два типа окружений:
1. Мы идём к агенту (облачные сервисы)
- Примеры: ChatGPT, GPTs, N8N, Make
- Как это работает: Ты приходишь в облачную платформу, загружаешь контекст и файлы, даёшь инструкцию
- Плюсы: Стабильно работает, хорошо формализуется
- Минусы: Агент "вживается" только в пределах этой платформы, не видит твои локальные файлы
2. Агент приходит к нам (локальные среды)
- Примеры: Claude Code, Cursor, Windsurf
- Как это работает: Агент запускается на твоём компьютере/сервере, видит локальные файлы, может обращаться к облачным сервисам через MCP
- Плюсы: Гибкость, доступ к локальным файлам, может решать сложные одноразовые задачи
- Минусы: Требует больше контроля, нужно следить за безопасностью
Как исправить: Если ты решаешь рутинную, повторяющуюся задачу (проверить письма, запустить поиск по шаблону) — используй N8N или Make. Если нужна гибкость и анализ файлов — Cursor или Claude Code.
Ошибка 5: Даёшь агенту слишком много задач в одном промте
Проблема: Ты пишешь мега-инструкцию на 10 пунктов, а агент её забывает на пункте 5. Особенно часто это бывает с Gemini.
Почему это ошибка: Длинный контекст — враг качества. Агент начинает путаться в приоритетах.
Как исправить: Используй режим планирования (plan mode):
- Сначала агент расшифровывает большую задачу на части
- Выполняет часть 1, делает отчёт ("Выполнена подготовка документов, найдено 15 файлов")
- Получает новый контекст с этим отчётом
- Переходит к части 2
Или выноси ключевые инструкции в отдельные файлы (claude.md, agent.md), которые агент сначала читает, потом применяет.
Пример:
Вот правила работы (файл rules.md):
- Все файлы с датами в названии (2025-01-28_report.md)
- Перед изменением — резервная копия
- Отчёты только в папке /output/
Теперь выполни основную задачу...
Практический чек-лист перед использованием агента
Прежде чем отправить промт агенту, проверь:
- Задача ясна? Можешь ли ты объяснить её за 1-2 предложения?
- Ресурсы доступны? Дал ли ты агенту доступ к Linear, Notion, файлам и т.п.?
- Полномочия ограничены? Знаешь ли ты, что именно может делать агент?
- Вывод понятен? Знаешь ли ты, где агент сохранит результаты?
- Есть план Б? Можешь ли ты откатить изменения, если что-то пойдёт не так?
Если ответов "нет" больше одного — переделай инструкцию перед запуском.
Кейс из реальной жизни
Я использовал Claude Code для поиска цитаты в сотнях файлов транскриптов. Вместо того, чтобы просто сказать "найди цитату про агентов", я:
- Дал доступ только к папке
/transcripts/ - Попросил создать временный файл с результатами в
/output/ - Указал: "Используй параллелизацию, ищи точные совпадения и синонимы"
- Попросил отчёт о проценте совпадений по файлам
Результат: агент справился за 2 итерации, вместо привычных 5-7.
FAQ
Q1: Что такое MCP сервер и нужен ли он мне?
MCP (Model Context Protocol) — это стандарт, который позволяет агентам подключаться к внешним сервисам (Linear, Notion, Telegram, Exa). Нужен ли — зависит от задачи. Если ты работаешь только с локальными файлами, можешь обойтись. Если нужен доступ к Linear или Notion в реальном времени — обязателен.
Q2: Как выбрать между Cursor, Claude Code и N8N?
Cursor — для разработки и творческих задач с файлами. Claude Code — для анализа и обработки данных на компьютере. N8N — для автоматизации рутин (отправка писем по расписанию, синхронизация между сервисами). Главный критерий — нужна ли тебе работа по расписанию или это одноразовая задача.
Q3: Агент забывает инструкции в рамках одного диалога, что делать?
Разбей большую задачу на части с промежуточными отчётами. После каждого этапа агент пишет "Этап 1 завершён: найдено 15 файлов". Ты читаешь отчёт, потом даёшь ему контекст для этапа 2. Это работает лучше, чем одна большая инструкция.
Q4: Как автоматически переименовать плохо названные файлы?
Создай скилл (переиспользуемую инструкцию) для агента: "Анализируй содержимое файла в папке /messy_files/, определи тему, переименуй в формат YYYY-MM-DD_тема.md". Запусти это на своём наборе файлов один раз — и агент переименует всё.
Q5: Насколько безопасно давать агенту полный доступ к локальной машине?
Не очень. Давай только то, что необходимо. Агент проявляет агентское поведение и может принять неожиданное решение (особенно в режиме "思考" или "plan mode"). Всегда используй Git для отката, работай в отдельных папках, делай резервные копии.