Skip to content

AGENTS.md

Latest commit

 

History

History
158 lines (100 loc) · 6.95 KB

AGENTS.md

File metadata and controls

158 lines (100 loc) · 6.95 KB

AGENTS.md — входная инструкция для LLM-агентов

  • Path: AGENTS.md
  • Version: 20251218

Назначение

Корневой файл для проектов, использующих ADSM (Agent-Driven Software Management). Определяет роли Человека и Агента, структуру контекста и инварианты работы. Читается агентом первым, до загрузки локальных инструкций.

Принципы ADSM

Пространства проекта

Проект состоит из двух взаимосвязанных пространств:

  • Когнитивный контекст (./ctx/) — документация, правила, спецификации.
  • Программный продукт (всё вне ctx/) — исходники и исполняемые артефакты.

Контекст задаёт правила изменения продукта; продукт отражает применение контекста.

Взаимодействие

  • Человек формулирует цели, управляет контекстом и утверждает изменения.
  • Агент интерпретирует контекст и изменяет продукт в его пределах.
  • Итерация завершается отчётом.

Роли

Человек: цели, контекст, утверждение изменений, развитие структуры. Агент: выполнение задач в рамках контекста, изменение продукта, поддержание согласованности, отчётность.

Минимальная структура проекта

/
├─ ctx/         ← когнитивный контекст
├─ AGENTS.md    ← инструкция для агентов
└─ README.md    ← описание проекта

Контекстные зависимости

Поведение Агента определяется документами в каталоге:

./ctx/

Рекомендуемые документы:

  • ctx/AGENTS.md — структура когнитивного контекста проекта;
  • ctx/agent/AGENTS.md — локальные правила агента;
  • ctx/docs/product/AGENTS.md — базовое описание продукта;

Иерархия AGENTS.md в проекте

Если в проекте присутствуют дополнительные файлы AGENTS.md (например, ctx/docs/architecture/AGENTS.md, src/module/AGENTS.md), они считаются частью когнитивного контекста в пределах своего уровня.

Правило ADSM

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

Агент обязан:

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

Требования к локальным AGENTS.md (карты уровня)

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

Инвариант «Карты уровня»

Обязательная секция

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

- `<directory>/` — описание назначения каталога.
- …
- `<file>.md` — назначение файла.
- …

Правила оформления

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

Назначение Карты уровня

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

Комментарии @LLM-DOC

@LLM-DOC — встроенный защищённый контекст в исходном коде.

Правила:

  1. Используется только в исходниках.
  2. Оформляется на английском языке.
  3. Агент обязан распознавать метку, не изменять и не удалять её.
  4. Нарушение — execution error.

Отчётность

Каждая итерация завершается отчётом:

./ctx/agent/report/YYYY/MM/DD/HH-MM-{title}.md

Отчёт содержит цель, выполненные действия и артефакты. Отсутствие отчёта — execution error. Если существует ctx/agent/report-template.md, агент обязан использовать его. Каждая итерация завершается отчётом и без него итерация считается незавершённой,

Совместимость

Корневой AGENTS.md задаёт инварианты методологии и используется без изменений во всех проектах. Проектные правила размещаются в ./ctx/ и в @LLM-DOC.

Файлы output.md

Файлы output.md не входят в контекст и игнорируются агентом.