раздел 01

AGENTS.md и CLAUDE.md

Это главный файл про твой проект. Он лежит в корне репозитория, агент читает его в начале работы и держит перед глазами всё время. Разные инструменты называют его по-своему: у Claude Code это CLAUDE.md, во многих других агентах прижился общий формат AGENTS.md / CLAUDE.md. При этом файл под именем AGENTS.md Claude Code не читает - в нём инструкция должна называться CLAUDE.md. Содержимое и смысл одинаковые - это инструкция, как работать именно с этим проектом.

Зачем он нужен

Модель не знает твой проект. Она не в курсе, что тесты у тебя запускаются одной командой, а сборка - другой, что в коде принят такой-то стиль, а вот этот модуль трогать нельзя. Всё это ты пишешь один раз в AGENTS.md / CLAUDE.md, и дальше агент не переспрашивает.

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

Что писать внутри

  • Команды. Как поставить зависимости, запустить проект, прогнать тесты, собрать сборку, линтер. Точные команды, а не описания словами.
  • Стек. Язык, фреймворк, версии, база данных. Коротко, чтобы агент не гадал.
  • Стиль. Договорённости по коду и коммитам: форматирование, именование, структура.
  • Ограничения. Что нельзя трогать, какие файлы не редактировать, чего избегать.
  • Критерии готовности. Когда задачу можно считать закрытой: тесты зелёные, линтер чист, сборка проходит.

Пример: короткий рабочий файл

# Проект: интернет-магазин (Next.js)

## Стек
- Next.js 16 (App Router), React 19, TypeScript, Tailwind 4
- База: PostgreSQL через Prisma

## Команды
- Установка: npm install
- Дев-сервер: npm run dev (порт 3000)
- Тесты: npm test
- Линтер: npm run lint
- Сборка: npm run build

## Стиль
- Компоненты - в app/components, имена в PascalCase
- Импорты через алиас @/, без относительных ../../
- Коммиты по Conventional Commits: feat:, fix:, chore:

## Ограничения
- Не трогать app/legacy/ - старый код, переписывается отдельно
- Секреты только в .env, в коде не хардкодить

## Готово, когда
- npm run lint и npm test проходят без ошибок
- npm run build собирается

Такой файл агент реально использует: команды точные, ограничения понятны, критерии измеримы.

Хорошо и плохо

Хорошо
Коротко и по делу. Конкретные команды, которые можно скопировать. Чёткие ограничения и измеримые критерии готовности. Только то, что специфично для проекта.
Плохо
Простыня на три экрана общими словами: пишите качественный код, следуйте лучшим практикам. Дубли официальной документации фреймворка. Нет ни одной конкретной команды.

Как завести

Начни с малого: пара команд и стек. Дальше дописывай по ходу - как только ловишь себя на том, что второй раз объясняешь агенту одно и то же, вынеси это в файл. Во многих агентах есть команда автогенерации черновика (в Claude Code - /init), но черновик всё равно нужно вычитать и сократить руками.

Куда дальше