# Как правильно настраивать ИИ-агентов: простой гайд

Клуб обучения ИИ · Автор: Ирина Накисен

Канонический URL: https://iiinfo.ru/g/155
Читать в Telegram: https://t.me/iiinfo00bot?startapp=guide_155-src_web
Читать в браузере: https://iiinfo.ru/app/?guide=155

---

Если вы пользуетесь ИИ-агентом (Codex, Cursor и похожими инструментами) для написания кода, автоматизации задач или любой другой работы — рано или поздно вы начинаете «дописывать» ему инструкции: что делать, как делать, когда спрашивать разрешения. Это нормально. Проблема в другом: с каждой новой версией ИИ-модели становятся заметно умнее и самостоятельнее, а старые инструкции, написанные «под менее сообразительную модель», начинают мешать вместо того, чтобы помогать.

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

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

## Скиллы для отдельных задач (Skills)

**Skill** — это, по сути, инструкция для конкретной ситуации: небольшой файл с шагами, который агент подключает только тогда, когда задача того требует. Например, отдельный скилл «как обновлять структуру базы данных» или «как работать с конкретным плагином».

У каждого скилла есть название и короткое описание — именно по этому описанию агент решает, нужна ли он сейчас. И вот здесь многие совершают одну и ту же ошибку: скачивают в проект десятки «про запас».

Почему это плохо:

* **Слишком много скиллов — агент путается.** Все описания загружаются в «оперативную память» модели одновременно. Если скиллов много, система начинает обрезать их описания, чтобы всё уместилось. В итоге агент видит куцые, неполные подсказки и хуже понимает, какой выбрать.
* **Описания-конкуренты.** Если несколько скиллов «кричат» о себе слишком настойчиво или противоречат друг другу, агент может подключить не ту инструкцию — и сделать работу неправильно, хотя формально «следовал скиллу».

Что делать вместо этого:

1. **Пишите описание максимально коротко**, но так, чтобы было предельно ясно, когда именно её применять. Плохо: «скилл про базу данных» — агент может решить использовать её при любом упоминании базы. Хорошо: «скилл про перенос данных при обновлении структуры базы» — он сработает только когда это реально нужно.
2. **Не заставляйте агента читать всё сразу.** Хороший скилл устроен как оглавление, а не как энциклопедия: сначала — короткий указатель «если задача такая — смотри вот этот раздел», и только потом, при необходимости, — подробности. Это экономит «внимание» модели и не грузит её лишним.
3. **Не пишите слишком подробные пошаговые рецепты.** Раньше моделям нужно было расписывать буквально каждый шаг. Сейчас они гораздо лучше понимают контекст и нюансы, поэтому избыточно детальная инструкция скорее свяжет модели руки, чем поможет.
4. **Помните: скилл может пользоваться не только ваш ИИ.** Если над проектом работают разные люди с разными инструментами, скилл, удобный для одной модели, может оказаться слишком строгим для другой. Пишите инструкции с запасом на то, что ими будут пользоваться разные «исполнители».

## Общие инструкции для проекта (AGENTS.md)

Если скилл — это инструкция «на конкретный случай», то файл с общими правилами проекта (в инструментах вроде Codex он часто называется AGENTS.md) — это должностная инструкция, которая действует всегда, при любой задаче в этом проекте.

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

Что стоит пересмотреть:

* **«Прочитай всю документацию перед любым изменением».** Такое требование имело смысл, когда модели были менее сообразительными и не понимали контекст сами. Сейчас достаточно умный агент способен сам понять, что ему нужно прочитать, а что — нет. Заставлять его каждый раз штудировать весь проект ради опечатки — то же самое, что требовать от опытного сотрудника перечитывать весь корпоративный устав перед тем, как ответить на письмо.
* **«Обязательно прогони все тесты после любого изменения».** Раньше модели нужно было прямо напоминать проверять свою работу — иначе она могла об этом «забыть». Более развитые модели делают это по умолчанию, без напоминаний. Оставленное по инерции требование в лучшем случае ничего не меняет, в худшем — заставляет агента тратить время на проверки, которые в данном случае не нужны.

Что стоит добавить:

* **Разрешение действовать самостоятельно там, где это безопасно.** Более развитые модели зачастую ведут себя даже осторожнее, чем нужно, и предпочитают лишний раз спросить разрешения, вместо того чтобы просто сделать. Если вы точно знаете, что какое-то действие безопасно (например, прогнать локальные тесты, которые ничего не ломают в реальной системе), — прямо разрешите это одной фразой:

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

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

## Где провести границу — что решает ИИ, а что человек

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

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

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

## Настойчивость: когда просить ИИ доделать до конца, а не останавливаться на полпути

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

Дело не в том, что модель стала «хуже» — она просто стала осторожнее в вопросе «где мне остановиться и спросить хозяина». И здесь важно не полагаться на то, что агент сам поймёт, где граница, а сформулировать это заранее.

Что это значит на практике:

* **Определяйте «готово» заранее, до начала работы.** Если вы хотите, чтобы агент не просто написал решение, а ещё и запустил его, проверил результат и исправил найденные ошибки — прямо включите это в задачу. Например, вместо «сделай функцию X» напишите «сделай функцию X, запусти и проверь, что она работает как надо, и исправь всё, что не работает, прежде чем показывать мне результат».
* **Не просите «остановиться после первой версии», если на самом деле хотите законченный результат.** Формулировка «покажи мне первый вариант, и я скажу, что дальше» сама по себе подталкивает модель остановиться раньше, чем нужно. Спросите себя: вам правда важно видеть промежуточный вариант, или вы просто по привычке так формулировали задачу?
* **Если хотите, чтобы агент исследовал тему шире, чем очевидный первый ответ** — прямо скажите, что именно исследовать и где остановиться. Абстрактное «сделай хорошо» модель поймёт по-своему, и не факт, что так, как хотелось вам.

## Чек-лист: что сделать прямо сейчас, если у вас уже накопились старые инструкции

1. Откройте все ваши Skills — оставьте только те, что реально используются, и сократите описания до одной ясной фразы «когда применять».
2. Проверьте, нет ли двух скиллов, которые могут «перетягивать» задачу друг у друга — уточните формулировки, чтобы они не пересекались.
3. Пройдитесь по общей инструкции проекта (AGENTS.md) и уберите требования вида «читай все документы перед любым изменением» и «всегда прогоняй все тесты», если модель и так делает это по умолчанию.
4. Добавьте явное разрешение на самостоятельные действия там, где вы точно знаете, что это безопасно (например, для локальных тестов).
5. Пересмотрите жёсткие ограничения «спрашивай разрешения на всё» — оставьте их только там, где риск реально высок.

***

Еще проще? 

> Дайте вот эту [ссылку](https://ai-club.sparkk.ru/g/155?from=/) и попросите агента проверить скиллы. Может съесть много токенов!