Смотреть урок

Если каждый раз приходится заново объяснять ИИ-агенту, как устроен проект, что можно менять и какие правила соблюдать — это можно вынести в AGENTS.md.

Что внутри:
🔷 что такое AGENTS.md и чем он отличается от обычного промпта;
🔷 как устроены root-файлы, вложенные инструкции и AGENTS.override.md;
🔷 что реально стоит писать внутри, а что лучше оставить в документации;
🔷 примеры из реальных репозиториев и ошибки, из-за которых большой файл начинает мешать агенту.

💡 Главная идея: хороший AGENTS.md — не энциклопедия проекта, а короткий набор постоянных правил, которые агент не должен угадывать сам.

Формат AGENTS.md: как задавать постоянные инструкции ИИ-агентам

1. Что такое AGENTS.md

AGENTS.md — это файл с постоянными инструкциями для ИИ-агента внутри проекта.
По смыслу он похож на README, только предназначен не для человека, а для агента.

В нём можно один раз зафиксировать правила работы с проектом:

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

Файл пишется в обычном Markdown. Обязательной схемы или строгого набора разделов у него нет.

Минимальный вариант может выглядеть так:

# Project instructions ## Setup npm install ## Run npm run dev ## Tests npm test ## Rules - Use TypeScript. - Do not modify generated files. - Run tests before finishing the task.

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

Вместо того чтобы каждый раз объяснять:

«Используй ТypeScript, не трогай эту папку, после изменений запусти тесты»

мы записываем эти правила один раз в AGENTS.md.

2. Зачем AGENTS.md, если уже есть промпт

Промпт и AGENTS.md решают разные задачи.

Промпт описывает, что нужно сделать сейчас:

Добавь фильтрацию товаров по цене.

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

• Все фильтры находятся в src/features/filters.
• Не добавляй новые зависимости без необходимости.
• Для состояния используй Zustand.
• После изменений запусти npm run test.

В результате запрос может оставаться коротким:

Добавь фильтрацию товаров по цене.

А агент уже знает правила проекта.
Особенно полезно хранить в AGENTS.md то, что агент не сможет надёжно определить только по коду:

• внутренние соглашения по…