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

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

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

Обычно я храню несколько разделов.

О проекте

Короткое описание проекта.

Одного-двух предложений достаточно.

Например:

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

Стек

Используемые технологии.

Например:

  • Hugo
  • PaperMod
  • GitHub
  • GitHub Actions

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

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

Например:

/content/posts
/content/pages
/prompts

Это помогает AI быстрее ориентироваться в проекте.

Соглашения

Инженерные правила работы с проектом.

Например:

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

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

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

Например:

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

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

Например:

  • избегать маркетингового стиля
  • писать как инженер для инженеров

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

# Project

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

# Stack

- Hugo
- PaperMod
- GitHub Actions

# Rules

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

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

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

Я не дублирую README.

Не копирую техническую документацию.

Не пытаюсь описать весь проект.

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

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