ADSM: практика использования файлов AGENTS.md

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

В качестве наглядного примера можно посмотреть корневой файл AGENTS.md из моего текущего пет-проекта "Svyzaist". Этот файл используется в реальной работе и отражает текущее состояние подхода. Ниже, очень кратко - мои собственные, субъективные, выводы из практического опыта.

Контекст как основа работы с Codex

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

AGENTS.md как часть контекстной среды

Файлы AGENTS.md в этой практике выступают как элемент среды, в которой работает агент. Они участвуют в формировании исходного контекста и учитываются Codex при выполнении задач. Их влияние проявляется опосредованно и связано со структурой и связностью документов и исходного кода проекта, с которыми агент работает.

Два уровня контекста в работе агента

В процессе работы полезно различать два уровня:

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

Роль AGENTS.md в формировании контекста задачи

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

Иерархия AGENTS.md

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

Корневой AGENTS.md как точка ориентации

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

Компактные документы и связность смыслов

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

Практическая польза AGENTS.md

В рамках ADSM файлы AGENTS.md позволяют зафиксировать границы и правила работы с проектом в явном виде. Это снижает разброс интерпретаций при формировании контекста задачи и делает поведение Codex более предсказуемым в повторяющихся сценариях.

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

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

Спасибо за ваше внимание.

P.S.

Материалы этой публикации в процессе развития были собраны и систематизированы в моей книге "Управляемая разработка с AI-агентами".

@Bardakan

15.12.2025 09:58 UTC

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

О каком опыте вы говорите? Статья выглядит так, как будто запрос в ChatGPT был «сгенерируй 10 тезисов по теме Agents.md”

@iamkisly

15.12.2025 10:06 UTC

Я думаю личный опыт автора в BDSM был бы интереснее, чем этот нейрослоп )

@flancer

15.12.2025 10:40 UTC

-6

Вот вам нейрослоп про BDSM автора:

Скрытый текст

В воображаемом сценарии это бы выглядел так:

**Роль и позиция**
Рациональный, контролирующий **Dominant / Top**. Не про спонтанную жестокость, а про структуру, правила и ответственность. Фокус на согласии, рамках и управлении процессом.

**Стиль практики**

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

**Интенсивность**
Нерегулярно, но системно: редкие, заранее спланированные сессии, а не частая «тусовка». Качество важнее количества.

**Компания**
Небольшой, стабильный круг взрослых единомышленников. Скорее закрытое сообщество или постоянный партнёр(ы), чем открытая сцена. Ценится интеллектуальная и ценностная совместимость.

**Локации**

* Частные пространства.
* Арендованные студии с нейтральной инфраструктурой.
* Без публичности и демонстративности.

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

Что, этот нейрослоп интереснее читать? Может дело не в том, что пишут, а в том, кто читает? ;)

15.12.2025 10:32 UTC

-5

Статья выглядит так, потому что это нейро-выжимка из информации большего объёма. Я дал ссылку в статье на источник. Но вы не волнуйтесь, там тоже контент подготовлен с помощью нейронки. Только он не выдуманный, а сформулированный лично мной. Просто оформлен через нейронку.

Я проверяю, насколько люди готовы принимать знания, "созданные не человеком". Вот тут, в этой публикации, в основе лежит мой персональный опыт, но оформлен он через Модель. Я попросил её пересказать мой опыт и мои выводы. Сделать концентрат.

Я вижу, что "не лезет". Я просто пытаюсь проанализировать, почему не лезет.

Вот для вас, например, почему статья выглядит сгенерённой? Что лично вам мешает увидеть в изложении мой опыт (а он там есть, я это гарантирую).

15.12.2025 10:43 UTC

-3

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

@Apoheliy

15.12.2025 10:22 UTC

Джиллиан Андерсон на КДПВ с какими-то стеклянными глазами. Видимо версия ИванИваныча старая.

А в центре кто? Не узнаю её в гриме. И 4-го тоже.

15.12.2025 10:50 UTC

Сгенерил КДПВ только что. Через GPT 5.2 Instants.

В центре - Кларисса Старлинг. А четвёртый о-о-очень старый. Но всё равно помоложе Бонда.

@Andnet

15.12.2025 10:31 UTC

Еще один улетел в бан. Заходишь на Хабр и начинаешь чистить ленту от рекламы и статей ИИ

15.12.2025 10:55 UTC

А зачем вы пошли по ссылке? Я в ленте специально сделал очень короткий и сжатый анонс того, что будет в публикации. Я вас не старался приманить, даже наоборот. Просил чатик сделать анонс так, чтобы не заинтересованные люди на заходили. А вы зашли, да ещё и коммент оставили. За внимание - спасибо. Но интерес к своим действиям вы во мне разбудили.