После того как AGENTS.md появился в моих проектах, быстро стало понятно, что его легко превратить в ещё один README.

Я стараюсь этого избегать.

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

О проекте

Здесь достаточно короткого описания проекта. Одного-двух предложений обычно хватает.

Например:

ashikov.ru — публичная инженерная база знаний о Kubernetes, Linux и DevOps.

Стек

В этом разделе я перечисляю основные технологии.

Например:

  • Hugo
  • PaperMod
  • GitHub
  • GitHub Actions

AI не должен заново предлагать инструменты, которые уже используются в проекте.

Структура репозитория

Здесь полезно показать ключевые каталоги.

Например:

/content/posts
/content/pages
/prompts

Этого достаточно, чтобы AI быстрее ориентировался в проекте и не создавал новые сущности без необходимости.

Соглашения

В этом разделе я храню инженерные правила работы с проектом.

Например:

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

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

Документация

Здесь я описываю правила работы с текстами и документацией.

Например:

  • писать кратко
  • избегать воды
  • показывать практику вместо теории

Если в проекте есть отдельные правила для документации, AGENTS.md может ссылаться на них, но не должен дублировать полностью.

Стиль написания текстов

Для проектов с публичными материалами полезно отдельно зафиксировать стиль.

Например:

  • следовать принципам «Пиши, сокращай»
  • избегать маркетингового стиля
  • писать как инженер для инженеров

Это помогает сохранять единый голос проекта.

Минимальный пример

# О проекте

ashikov.ru — публичная инженерная база знаний о Kubernetes, Linux и DevOps.

# Стек

- Hugo
- PaperMod
- GitHub Actions

# Правила

- Не создавать новые категории без необходимости
- Не добавлять зависимости без обоснования
- Писать кратко
- Избегать маркетингового стиля

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

Что я туда не кладу

Я не дублирую README, не копирую техническую документацию и не пытаюсь описать весь проект.

Чем короче AGENTS.md, тем проще поддерживать его в актуальном состоянии.

Его задача одна: быстро объяснить AI устройство проекта и правила работы с ним.