Codex и правила проекта: AI-агенту нужен рабочий бриф - без этого вы работаете не правильно

До этого я рассказывал про Attach Telegram и про плагины, skills и automations. А теперь расскажу зачем нужен бриф, потому что без него агент будет тупить по-страшному.

*Написано при поддержке Trafstat.ru.

Codex может читать файлы, открывать браузер, проверять интерфейс, работать с GitHub, собирать документы и возвращаться к задаче позже. Но сам доступ к инструментам ещё не отвечает на вопросы: что в этом проекте считается готовым, какие файлы нельзя трогать, где лежит source of truth, когда нужен тест, кто принимает решение, какой стиль текста допустим, как оформлять PR и что делать после публикации.

Для человека такие вещи часто живут в голове. Для AI-агента их надо записать.

Обычный запрос выглядит так:

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

Codex этого не знает, пока ему не дали правила.

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

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

AGENTS.md можно воспринимать как инструкцию для AI-агента внутри проекта. Это файл, который лежит рядом с кодом, контентом или workflow и отвечает на вопросы, которые обычно остаются между строк.

Что читать первым.

Какие документы являются источником правил.

Какие команды можно запускать.

Какие действия требуют подтверждения.

Как работать с чужими изменениями.

Какие папки относятся к проекту, а какие нельзя трогать.

Какие проверки нужны перед тем, как сказать “готово”.

Такой файл особенно полезен там, где один и тот же Codex работает с разными проектами. Например, один проект публикуется через WordPress, другой деплоится из git-репозитория, третий использует Google Sheets как источник данных, четвёртый собирает статьи через локальные скрипты.

Без маршрутизации агент может перенести привычку из одного проекта в другой. Для человека это выглядит странно: “Почему он решил запускать deploy здесь?” или “Почему полез в соседний checkout?” Для агента это обычная попытка найти знакомый путь.

AGENTS.md снижает такие ошибки: он говорит, где агент находится и какие правила действуют здесь.

Плохой AGENTS.md превращается в стену текста на 40 экранов. Агент читает его, но внутри слишком много инструкций одинакового веса. В итоге настоящие ограничения теряются среди пожеланий.

Хороший файл устроен иначе. Он маршрутизирует.

В начале стоит ответить на несколько вопросов:

Остальное лучше вынести в зависимые документы. Например, в docs/task-router.md, docs/publishing-workflow.md, docs/review-checklist.md. Тогда AGENTS.md остаётся входной точкой, а не энциклопедией всего проекта.

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

Допустим, в одном проекте есть несколько типов работы:

SEO-статья.

Исправление бага.

Публикация в CMS.

Обновление обложки.

Проверка индексации.

Создание отчёта.

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

Если пользователь просит написать статью, читать документ A.

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

Если просит проверить ошибку, читать документ C.

Если просит деплой, сначала проверить условия из документа D.

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

Чем сильнее инструменты, тем строже должны быть границы.

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

Например:

Не запускать git push без запроса.

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

Не менять секреты и env-файлы.

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

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

Не трогать файлы вне рабочей папки.

Не переписывать чужие незакоммиченные изменения.

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

Фраза “сделано” может означать разные вещи.

Для кода: изменения внесены, тесты прошли, UI проверен в браузере.

Для статьи: текст готов, заголовки вычитаны, ссылки проверены, обложка подобрана, draft создан.

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

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

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

Например:

Перед финальным ответом проверить live-страницу.

Перед PR указать файлы и тесты.

Перед публикацией убедиться, что title и description заполнены.

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

Если тесты не запускались, прямо написать почему.

Такие правила экономят много ручной проверки. Пользователь видит не только результат, но и маршрут, по которому агент дошёл до результата.

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

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

Пример:

В Telegram редактор пишет: “Давай поменяем структуру, как в прошлый раз, и уберём этот блок”.

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

Получается хорошая связка: Telegram даёт сырой контекст, AGENTS.md задаёт порядок работы с этим контекстом, skills описывают повторяемые процессы, plugins дают доступ к внешним системам.

Эти сущности легко спутать.

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

Skill отвечает за повторяемый навык. Например, публикация SEO-статьи, security review, работа с документами, подготовка презентации, проверка русского текста перед публикацией.

Один skill можно использовать в разных проектах. Один AGENTS.md обычно привязан к одной рабочей среде.

Пример:

Skill говорит: “Перед публикацией статьи проверь структуру, лид, заголовки, SEO-title, description, фактуру и финальный рендер”.

AGENTS.md говорит: “В этом проекте статьи лежат здесь, публикуются через этот интерфейс, временные файлы после live-публикации надо убрать, соседний проект не открывать”.

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

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

Минимальный вариант:

Название проекта.

Где находится source of truth.

Что читать для разных типов задач.

Какие команды запрещены без подтверждения.

Какие файлы нельзя менять.

Какие проверки нужны перед финальным ответом.

Как обращаться с временными файлами.

Например:

Если задача про публикацию, читать docs/publishing.md.

Если задача про frontend, читать docs/frontend.md.

Если задача про review, использовать code-review режим и писать findings по severity.

Перед правкой читать файл целиком.

Не запускать deploy без прямой просьбы.

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

Если есть незнакомое состояние проекта, сначала остановиться и объяснить риск.

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

AGENTS.md лучше растёт из практики, а не из попытки заранее предсказать все случаи.

Плохой запрос:

Подготовь статью и опубликуй.

Лучше:

Подготовь статью по текущему черновику. Работай по AGENTS.md и docs/task-router.md. Сначала вычитай текст, потом подготовь title и description, затем создай draft в CMS. Live не публикуй без моего подтверждения. В конце дай ссылку на draft и список проверок.

Для кода:

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

Для контента из Telegram:

Возьми прикреплённый Telegram-диалог как источник правок к статье. Выдели только подтверждённые требования, спорные места вынеси в вопросы. Применяй проектный workflow публикации. Если в переписке есть отсылка к старому материалу без ссылки, не угадывай, а отметь это отдельно.

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

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

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

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

Плагины дают руки.

Telegram и другие коннекторы дают входные данные.

Skills дают повторяемые навыки.

AGENTS.md даёт агенту местные правила.

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

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

#ии #ai #агенты #скилы #кодекс #codex #chatgpt #claude