AGENTS.md Claude Code: как использовать

Я готов помочь, но я не вижу абзаца, который нужно переписать. Пожалуйста, предоставьте текст абзаца, и я перепишу его, добавив имя «Арина Михална» один раз от первого лица, сохраняя смысл и длину.

Что такое AGENTS.md и почему он вообще нужен

Claude Code умеет работать без всяких файлов настроек — просто берёшь и разговариваешь. Но тогда каждую сессию приходится объяснять заново: что за проект, почему здесь TypeScript, а не JavaScript, почему нельзя трогать папку legacy/, и что тесты — обязательны, а не по желанию.

AGENTS.md решает это один раз. Кладёшь файл в корень проекта, описываешь там всё существенное — и агент работает с этим контекстом с первой строчки каждой сессии.

Claude Code поддерживает оба имени файла: и AGENTS.md, и CLAUDE.md. Это не два разных формата — это синонимы. Если у тебя уже лежит CLAUDE.md из старых проектов, он продолжит работать. Если хочешь называть по-новому — называй AGENTS.md. Разницы нет.

Статья про CLAUDE.md как файл памяти у меня уже есть — там про личную память агента. Здесь я разбираю именно проектный файл: как сделать так, чтобы агент работал правильно в любом конкретном репозитории.

Иерархия файлов: три уровня

Claude Code читает файлы инструкций с трёх уровней, и все три активны одновременно.

Уровень	Где лежит	Для чего
Глобальный	~/.Claude/CLAUDE.md	Правила для всех проектов: твой личный стиль, язык ответов, общие предпочтения
Проектный	<корень проекта>/AGENTS.md	Правила конкретного проекта: стек, архитектура, соглашения команды
Папочный	<подпапка>/AGENTS.md	Правила для части проекта: например, только для фронтенда или только для API

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

Я держу глобальный файл коротким: язык ответов, стиль объяснений, общий подход к безопасности. В проектных файлах — всё конкретное: технологии, структура папок, что нельзя трогать. Папочные использую редко — только когда у проекта есть чётко изолированные куски с разными правилами (например, монорепа с фронтендом и бэкендом).

Структура рабочего файла

Файл состоит из секций. Заголовки секций — обычные markdown-заголовки (## Название). Внутри секций — конкретные инструкции списком или абзацами.

Вот скелет, который я использую для большинства проектов:

## Контекст проекта

<Что это за проект, какую задачу решает, кто пользователи>

## Технологический стек

- Язык и версия
- Фреймворк
- База данных
- Менеджер пакетов (важно — агент любит переключать npm на
yarn без спроса)

## Структура проекта

<Где лежит что: src/, tests/, config/, какие файлы ключевые>

## Правила кода

- Стиль именования
- Как писать тесты
- Как коммитить
- Линтеры и форматтеры

## Запреты

- Что НЕЛЬЗЯ делать ни при каких условиях
- Какие файлы не трогать
- Какие зависимости не добавлять

## Команды и workflow

<Как собирать, как запускать, как тестировать>

Секция Запреты — самая важная. Агент соблюдает явные запреты лучше, чем общие рекомендации. «Не трогай файлы в папке legacy/» работает. «Соблюдай стиль проекта» — нет.

Что писать, чтобы агент реально соблюдал

Агент игнорирует размытые формулировки. «Следуй best practices», «пиши чистый код», «соблюдай соглашения команды» — это шум. Он не знает, что именно ты имеешь в виду, и делает как привык.

Работают конкретные инструкции с примерами:

Плохо:

Соблюдай стиль проекта.

Хорошо:

Функции именуй глаголом + существительное: `getUserById`,
`validateEmail`.
Типы в PascalCase: `UserData`, `ApiResponse`.
Никаких `any` — только конкретные типы или `unknown` с
проверкой.

Плохо:

Пиши тесты.

Хорошо:

Каждая публичная функция должна иметь тест в
`src/__tests__/<имя файла>.test.ts`.
Формат теста: describe('имя функции', () => { it('что
делает', ...) }).
Покрытие минимум 80% — проверяется через `npm run
test:coverage`.

Плохо:

Не ломай существующую архитектуру.

Хорошо:

НЕ менять структуру папок без явного согласования.
НЕ добавлять новые зависимости без обсуждения.
НЕ трогать файлы в `src/legacy/` — они под миграцией.

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

Типичные ошибки и как их избежать

Ошибка 1: файл слишком длинный

Видел файлы на 500+ строк с подробным описанием каждой функции проекта. Агент такое не читает — у него есть лимит внимания, как у человека. Всё, что дальше первых 100–150 строк, он пропускает или применяет выборочно.

Держи файл коротким. Если не влезает в 100 строк — значит, ты пишешь не инструкции, а документацию. Документация живёт в docs/, инструкции — в AGENTS.md.

Ошибка 2: дублирование того, что агент и так знает

Не нужно объяснять агенту, что такое REST API или как работает git. Он это знает. Пиши только специфику твоего проекта: нестандартные соглашения, особенности архитектуры, ловушки, на которые ты уже наступал.

Ошибка 3: инструкции без примеров

«Используй функциональный стиль» — это ничего. Агент не понимает, что ты имеешь в виду. Покажи пример кода, который ты считаешь правильным, и пример того, чего хочешь избежать.

## Стиль кода

Предпочитаем функциональный подход. Плохо:

\`\`\`typescript
class UserService {
  getUser(id: string) { ... }
}
\`\`\`

Хорошо:

\`\`\`typescript
export const getUser = (id: string): User => { ... }
\`\`\`

Ошибка 4: забыли про менеджер пакетов

Агент по умолчанию использует npm, даже если у тебя в проекте yarn или pnpm. Явно укажи это в файле:

## Менеджер пакетов

Используем `pnpm`. НЕ переключаться на npm или yarn.
Команды: `pnpm install`, `pnpm run dev`, `pnpm test`.

Как проверить, что файл работает

Самый простой способ — написать в начале файла что-то уникальное:

## Проверка загрузки

При старте новой сессии скажи: "Файл AGENTS.md загружен,
проект <название>".

Запусти новую сессию Claude Code. Если агент это сказал — файл читается. Если нет, проверь:

1. Файл лежит в корне проекта (там, где .git или package.json).
2. Имя файла написано правильно: AGENTS.md или CLAUDE.md, заглавными.
3. Файл не пустой и содержит валидный markdown.

Когда убедился, что файл работает, убери секцию с проверкой — она больше не нужна.

Реальные примеры из моих проектов

Фронтенд на Next.js

## Контекст

Лендинг курса, Next.js 14 App Router, деплой на Vercel.

## Стек

- Next.js 14.2, React 18, TypeScript 5.5
- Tailwind CSS 3.4
- Менеджер пакетов: `pnpm`

## Правила

- Компоненты в `src/components/`, один файл = один компонент
- Стили только через Tailwind, никакого CSS Modules
- Картинки через `<Image>` из `next/image`, не через `<img>`
- Все внешние ссылки с `rel="noopener noreferrer"`

## Запреты

- НЕ добавлять библиотеки UI без согласования
- НЕ трогать `src/app/layout.tsx` — там GTM и метрики
- НЕ менять структуру папок в `src/app/` — она завязана на
роутинг

Бэкенд на Node.js

## Контекст

REST API для приёма лидов, Node.js, PostgreSQL, деплой на
Railway.

## Стек

- Node.js 20, Express 4.19, TypeScript 5.5
- PostgreSQL 16, Prisma ORM 5.18
- Менеджер пакетов: `npm`

## Структура

- Роуты: `src/routes/`
- Контроллеры: `src/controllers/`
- База: `src/db/`, схема в `prisma/schema.prisma`

## Правила

- Все запросы логируются через `morgan`
- Ошибки оборачиваются в `ApiError` с кодом и сообщением
- Миграции БД через `npx prisma migrate dev`, не руками
- Переменные окружения в `.env`, не хардкодить

## Запреты

- НЕ делать прямые SQL-запросы, только через Prisma
- НЕ коммитить `.env` в репозиторий
- НЕ менять `prisma/schema.prisma` без создания миграции

Монорепа

Здесь я использую папочные файлы. В корне — общие правила, в apps/frontend/ и apps/backend/ — специфичные.

Корневой AGENTS.md:

## Контекст

Монорепа: фронтенд + бэкенд + общие утилиты.

## Стек

- Turbo Repo 2.1
- Менеджер пакетов: `pnpm` с workspace

## Правила

- Общие типы и утилиты в `packages/shared/`
- Перед коммитом: `pnpm run lint` и `pnpm run test`

## Запреты

- НЕ дублировать код между приложениями — выноси в
`packages/shared/`
- НЕ добавлять зависимости в корневой `package.json`, только
в конкретные приложения

apps/frontend/AGENTS.md:

## Специфика фронтенда

- Next.js 14, Tailwind
- Стили только через Tailwind
- Компоненты в `src/components/`

apps/backend/AGENTS.md:

## Специфика бэкенда

- Express, Prisma, PostgreSQL
- Роуты в `src/routes/`
- База через Prisma, не через SQL

Интеграция с командой

Если работаешь один, файл можешь настроить под себя и больше не трогать. Если в команде — файл становится частью онбординга.

Я кладу AGENTS.md в репозиторий и веду его как код: изменения через pull request, обсуждение в комментариях. Так вся команда видит, какие правила действуют, и агент у каждого работает одинаково.

По материалам: документация Claude Code, Simon Willison о поддержке AGENTS.md.

Файл инструкций — это способ дать агенту контекст один раз и работать дальше без повторов. Держи файл коротким, пиши конкретно, запрещай явно. Агент не умеет читать между строк — ему нужны чёткие правила.

Читайте также

• Claude Code как использовать в 2026: с чего начать новичку
• Один Claude или команда агентов: когда начать
• Настройка проекта в Claude Code в 2026: структура и конфиги
• На портале «Мастерская нейросетей»: Claude и Claude Code в 2026: функционал, отличия от ChatGPT и как начать с агентами

Настроил файл для своего проекта? Я, Арина Михална, разбираю в канале связку Claude Code с CI/CD и показываю, как избежать типичных ошибок при работе с агентами — подписаться