ИИ агенты и их документация

UX-дизайнер Егор Камелев больше года разрабатывает CRM для фрилансеров, используя большие языковые модели (LLM, модели вроде ChatGPT, которые генерируют текст и код) в роли основного инструмента. В его проекте уже больше 150 тысяч строк кода. Когда агент Codex от OpenAI начал своевольничать, Камелев завёл файл AGENTS.md и стал записывать туда каждое правило поведения для нейросети. Ниже практический гайд по настройке такого файла на основе его опыта.

Что понадобится?

• Проект с кодом и установленный ИИ-агент (Codex, Claude Code, Cursor или аналог)
• Текстовый редактор, поддерживающий Markdown (разметка для структурированного текста; расширение .md)
• 30 минут на создание первой версии файла, затем 5 минут после каждого инцидента

Пошаговая инструкция

1. Создайте файл AGENTS.md в корне проекта. Большинство LLM-агентов автоматически читают этот файл перед каждым подходом к работе. Если агент игнорирует его, укажите путь к файлу в системном промпте (системный промпт, базовая инструкция, которую агент получает до вашего запроса).

2. Опишите локальное окружение одной строкой. Камелев заметил, что Codex несколько раз пытался запустить сервер на случайных портах, терпел неудачу и упрямо пробовал снова. Одна строка решила проблему:

Локальный сервер всегда считается уже поднятым на http://127.0.0.1:8080

1. Добавьте правило тайм-аута для внешних зависимостей. В проекте Камелева использовался инструмент code-review-graph, который строит карту зависимостей кода и отдаёт агенту только нужные фрагменты вместо всего проекта. Он зависел от внешнего MCP-сервера (MCP, Model Context Protocol, протокол подключения агента к внешним инструментам и данным). Сервер регулярно не отвечал, и агент зависал на 120 секунд. Первая строка, которую Камелев добавил вручную:

Если code-review-graph не отвечает в течение 10 секунд — дальше двигайся без него.

Агент перестал ждать и начал разбираться с проектом локально.

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

Codex не должен запускать, перезапускать или останавливать dev-сервер
без прямого запроса пользователя. Если сервер не отвечает в течение
5 секунд — сообщить об этом и продолжить без попытки запуска.
Не запускать долгоживущие команды вроде manage.py runserver в foreground.

1. Ограничьте использование браузера. Автоматический запуск Playwright или встроенного браузера для мелких правок в HTML и CSS, это лишние токены (токен, единица текста, за которую платит пользователь) и время. Камелев прописал:

Browser-use / Playwright использовать только по прямой просьбе:
«открой в браузере», «проверь визуально», «сделай скриншот».
Для мелких HTML/CSS/JS-правок ограничиваться кодовой проверкой.

1. Укажите агенту на папку с документацией и потребуйте её обновлять. Это правило Камелев называет самым ценным:

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

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

1. Замените внешние зависимости локальными, если агент справится. Камелев попросил Codex написать локальный аналог code-review-graph. Агент справился за 30 минут. Инструмент не стал полноценным продуктом, но закрыл конкретную задачу и избавил от 120-секундных тайм-аутов навсегда. Теперь в начале AGENTS.md стоит указание работать с локальным инструментом «Norm Codex Memory».

Что делать с этим прямо сейчас?

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

Маркетологу. Файл инструкций фиксирует поведение агента и делает результат воспроизводимым. Это снижает расход токенов (то есть деньги) и убирает ситуации, когда нейросеть каждый раз ведёт себя по-разному.

Предпринимателю в РФ. Подход работает с любым агентом, включая доступные в России инструменты. Если вы используете локальные открытые модели (опенсорс, модели с открытым кодом), файл AGENTS.md читается так же, главное указать на него в конфигурации.

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