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

Файл AGENTS.md в корне проекта решает эту проблему. Это онбординг и операционная система для LLM, которая задает стек, границы ответственности и правила сдачи кода.

1. Если кратко
2. В чем разница с README.md
3. Анатомия идеального AGENTS.md
4. Базовый шаблон
5. Как внедрить

Если кратко

Главный принцип работы с AI: вы — архитектор, агент — исполнитель.

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

<!-- ❌ Плохой запрос: слишком размыто -->

Сделай страницу поиска с AI-фильтрацией и красивым UI.

<!-- ✅ Системный запрос: четкие границы -->

Реализуй страницу поиска по документам:

- Серверный роут /api/search с валидацией через Zod.
- UI на компонентах из components/SearchCard.astro.
- Перед написанием кода покажи план реализации.

В чем разница с README.md

README.md и AGENTS.md решают разные задачи:

Анатомия идеального AGENTS.md

Рабочий AGENTS.md состоит из 6 коротких разделов:

1. Протокол работы

Порядок действий агента до первой строчки кода:

• Изучить связанные файлы и типы данных.
• Задать один уточняющий вопрос при неоднозначности.
• Составить краткий план изменений.
• Написать код строго по плану.
• Запустить линтер, тайпчек и тесты.
• Сдать краткий отчет о результатах.

2. Стек и черный список

Явно укажите стек и запрещенные решения:

### Стек

- Next.js 15 (App Router), TypeScript, Tailwind CSS v3, Zod.

### Запрещено

- ❌ Не ставить сторонние UI-библиотеки (MUI, Chakra).
- ❌ Не использовать any в TypeScript.
- ❌ Не писать inline-стили и CSS Modules.
- ❌ Не создавать микросервисы — все API строго в App Router.

3. Границы ответственности и секреты

Защитите проект от утечки токенов на клиент:

### Архитектура

- **Клиент**: только отображение UI и безопасные вызовы API.
- **Сервер**: работа с БД, вызовы LLM и сторонних API.

### Переменные окружения

- 🟢 Публичные (клиент): NEXT_PUBLIC_APP_URL
- 🔴 Приватные (только сервер): OPENAI_API_KEY, DATABASE_URL

4. Дизайн и UI

• Источник истины: эталонные скриншоты или макеты Figma воспроизводятся 1-в-1.
• Переиспользование: проверять src/components/ перед созданием новых элементов.
• Адаптивность: корректное отображение на мобильных без поломки десктопа.

5. Критерии готовности

Команды, которые агент обязан выполнить перед отчетом:

npm run type-check    # Проверка типов TypeScript (tsc --noEmit)
npm run lint          # Линтер без ошибок
npm run build         # Успешная сборка проекта
npm run test          # Запуск unit-тестов

6. Формат отчета

Короткое резюме без лишнего текста:

• Что сделано: 3–5 пунктов.
• Тесты: статус сборки и проверок.
• Внимание: неявные допущения или вопросы к ревьюеру.

Базовый шаблон

Пишите правила в AGENTS.md на английском языке.

• Экономия токенов: английский текст в 2–3 раза компактнее кириллицы в контекстном окне LLM.
• Точность: современные модели (Claude, GPT-4o, Gemini) обучены на англоязычном коде и лучше следуют системным инструкциям на английском.

Starter kit для корня репозитория:

# AGENTS.md

## 1. Role & Principles

You are a senior software engineer. Write clean, maintainable code adhering to project architecture. Inspect existing patterns and types before coding.

## 2. Workflow

1. Outline a brief implementation plan.
2. Implement changes with minimal required code footprint.
3. Run verification: `npm run type-check` and `npm run lint`.
4. Provide a concise completion report.

## 3. Tech Stack & Boundaries

- **Stack**: TypeScript, Tailwind CSS, Astro / Next.js.
- **Security**: Strict client/server separation. Never expose private API keys to the browser.
- **UI**: Reuse existing design system components. Do not introduce arbitrary styles.

## 4. Definition of Done

- [ ] TypeScript compiles with zero errors (`tsc --noEmit`).
- [ ] Linter passes (`eslint .`).
- [ ] Production build succeeds (`npm run build`).
- [ ] Existing logic and comments are preserved.

## 5. Report Format

- **What was done**: 3–5 bullet points.
- **Verification**: Build and test statuses.
- **Needs attention**: Edge cases, assumptions, or questions.

Файл с примером корректного AGENTS.md

Правила в файле описывают большой проект (Next.js + Sanity + AI-поиск + авторизация):

Скачать AGENTS.md

Как внедрить

1. Создайте AGENTS.md в корне репозитория на английском языке.
2. Зафиксируйте стек и главные запреты (антипаттерны).
3. Добавьте команды проверки (type-check, lint, build).
4. Опишите правила для приватных токенов и ключей API.
5. Дополняйте файл каждый раз, когда агент ошибается в типичном сценарии.

AGENTS.md — живой документ. Через 2–3 итерации AI-ассистент начнет выдавать предсказуемый и чистый код с первого промпта.