AGENTS.md в ADSM: личный опыт, выводы и направления развития

Дата публикации: 2025-12-14

Введение

Эта публикация описывает использование файлов AGENTS.md в моих проектах на примере проекта Svyazist.

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

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

Публикация фиксирует текущее состояние этой практики и служит основой для её дальнейшего развития в рамках ADSM-подхода.

Типовое назначение AGENTS.md

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

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

Формат файла остаётся свободным и не накладывает жёстких требований к структуре.

Для проектов с развитой структурой применяется иерархия AGENTS.md-файлов. Агент учитывает все файлы AGENTS.md по пути от корня репозитория к текущему рабочему каталогу, при этом инструкции, расположенные ближе к месту работы, имеют приоритет.

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

Типы AGENTS.md

В ADSM-подходе файлы AGENTS.md образуют иерархическую систему инструкций, в которой разные уровни выполняют разные функции.

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

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

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

Локальные AGENTS.md

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

# <Название уровня документации или кода>

Path: `path/to/AGENTS.md`

## Назначение

<краткое описание назначения текущего уровня документов/кода>

## Карта уровня

- `dir/` — назначение каталога с текущего уровня.
- `AGENTS.md` — текущий документ.
- `file.ext` — назначение файла с текущего уровня.

## <Дальнейшие разделы зависят от уровня>

Эта структура используется для фиксации границ уровня и правил работы внутри него. Карта уровня декларативно описывает состав каталога и служит компактной моделью структуры без обращения к содержимому файлов.

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

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

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

Корневой AGENTS.md

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

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

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

Корневой AGENTS.md используется без изменений и служит стабильной базой, на которую опираются все проектные правила.

Пример типового корневого AGENTS.md, используемого в моих проектах, доступен по ссылке:
<ссылка на пример корневого AGENTS.md>

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

Влияние AGENTS.md на работу агента

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

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

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


Пределы управляемости

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

Агент самостоятельно собирает рабочий контекст из доступных ему документов. Какие именно фрагменты он возьмёт и в каком виде — заранее неизвестно. Это накладывает естественные ограничения на степень управляемости поведения агента через текстовые инструкции.

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

Корневой AGENTS.md как точка входа

Корневой AGENTS.md в моих проектах используется как точка входа агента в проект. Его задача — дать общее представление о структуре проекта, ролях и принципах работы, а не описывать детали.

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

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

Контекст задачи

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

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

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

Распределение смыслов

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

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

В этом случае агенту проще сформировать рабочий контекст задачи из согласованных блоков, а не из разрозненных фрагментов одного большого текста.

Условия эффективности AGENTS.md

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

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

Это означает, что использование AGENTS.md имеет смысл не всегда и не везде, а прежде всего там, где важна управляемость процесса в долгую.

AGENTS.md в ADSM

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

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

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

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

Эта страница соответствует второй стадии по AFKP (Acceptance-First Knowledge Principle) - "раскрытию". Четвёртую стадию ("осмысление") можно реализовать в этом телеграм-канале или непосредственно на Хабре.