Правила Агентов (.cursorrules / CLAUDE.md / AGENTS.md)

1. Обзор концепции и системная проблема

Современные LLM обучаются на гигабайтах открытого кода с GitHub, поэтому по умолчанию они генерируют «усредненный» код: устаревшие мажорные версии библиотек, хаотичные паттерны импортов, any в TypeScript или неэффективные подходы к обработке ошибок. Когда инженер работает в парадигме вайбкодинга без зафиксированных правил, каждый новый промпт превращается в лотерею:

• Агент устанавливает устаревший moment.js или axios вместо нативного date-fns или fetch.
• Агент смешивает архитектурные слои (например, обращается к базе данных напрямую из клиентского React-компонента).
• Агент придумывает собственные команды компиляции или тестирования вместо существующих в проекте скриптов.

Agent Rules (файлы .cursorrules, CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc) решают проблему дрейфа кодовой базы. Они превращают внутренний конвеншн команды в системный контракт, который считывается средой разработки или терминальным агентом еще до начала генерации любого кода.

2. Архитектурная таксономия и ментальная модель

Правила репозитория делятся на три уровня изоляции и активации:

┌─────────────────────────────────────────────────────────────┐
│                   УРОВНИ ПРАВИЛ АГЕНТА                     │
├─────────────────────────────────────────────────────────────┤
│ 1. Global / Machine Layer (~/.cursorrules, ~/.claude.json)   │
│    Предпочтения конкретного разработчика (язык, стиль ответов)│
├─────────────────────────────────────────────────────────────┤
│ 2. Repository Core Layer (CLAUDE.md, AGENTS.md, root rules)  │
│    Глобальный стек, запрещенные библиотеки, команды lint / test│
├─────────────────────────────────────────────────────────────┤
│ 3. Scoped / Event-Driven Rules (.cursor/rules/*.mdc)         │
│    Активация по glob-маске (например, API routes, UI, DB)    │
└─────────────────────────────────────────────────────────────┘

1. Глобальные правила репозитория (Core Repository Contract):
   • Располагаются в корне проекта (CLAUDE.md для Claude Code, AGENTS.md или .cursorrules для редакторов).
   • Описывают критический минимум: версии окружения (Node.js 22, Bun, Python 3.12), пакетный менеджер (pnpm), обязательный линтер и инструкции по структуре коммитов.
2. Контекстные модульные правила (Scoped Domain Rules):
   • Файлы с метаданными и glob-шаблонами (например, .cursor/rules/database.mdc с фильтром src/db/**/*.ts).
   • Загружаются в рабочую память модели исключительно тогда, когда агент планирует редактировать файлы миграций или ORM-модели.
3. Операционные ограничения (Operational Guardrails):
   • Четкие негативные ограничения (Negative Constraints): «НИКОГДА не выполнять git push --force», «НИКОГДА не модифицировать .env.production», «НЕ добавлять новые зависимости без явного согласия инженера».

3. Технический пайплайн и внутренняя механика

Жизненный цикл правил во время сессии вайбкодинга:

1. Инициализация сессии и сканирование репозитория: IDE или CLI-агент во время старта сканирует корневую папку и служебный каталог .cursor/rules/ или .agents/rules/.
2. Анализ намерения и сопоставление масок (Glob Matching): Пользователь отправляет запрос («Создай новый эндпоинт для оплаты подписки»). Агент прогнозирует изменение файлов в src/app/api/stripe/route.ts. Движок правил активирует правила для src/app/api/**/*.ts и stripe.mdc.
3. Сборка расширенного системного промпта: Движок конкатенирует:
   • Базовый System Prompt модели;
   • Содержимое файла глобального контракта;
   • Найденные модульные правила;
   • Текущее дерево открытых файлов и запрос пользователя.
4. Генерация кода с принудительным соблюдением инвариантов: Модель формирует вызов инструмента или код, обращаясь к правилам как к обязательному системному контексту.
5. Валидация пост-генерации: Если агент имеет доступ к терминалу, он запускает команду валидации, прописанную в правилах (например, pnpm typecheck), перед возвратом финального отчета инженеру.

4. Практические инженерные сценарии в продакшене

01. Архитектурные границы в Next.js 15+ App Router

Файл .cursor/rules/nextjs.mdc с маской src/app/**/*.tsx предотвращает классические ошибки использования серверных и клиентских компонентов:

---
description: Архитектурные стандарты Next.js App Router
globs: src/app/**/*.tsx, src/components/**/*.tsx
---
- По умолчанию все компоненты являются Server Components.
- Директиву 'use client' добавлять ТОЛЬКО при наличии useState, useEffect или обработчиков событий onClick/onChange.
- ЗАПРЕЩЕНО импортировать серверные утилиты (db, auth secret) в файлы с 'use client'.
- Все мутации данных выполнять исключительно через Server Actions в директории `src/actions/`.

02. Детерминированный запуск тестов для Claude Code

Конфигурация CLAUDE.md гарантирует, что терминальный агент использует исключительно правильные скрипты тестирования без попыток запустить несовместимый глобальный jest:

# Repository Guidelines for Claude Code

## Commands
- Build: `pnpm build`
- Typecheck: `pnpm tsc --noEmit`
- Unit Tests: `pnpm test:unit`
- E2E Tests: `pnpm test:e2e`

## Workflow Discipline
Перед тем как уведомить о успешном выполнении задания:
1. Запусти `pnpm tsc --noEmit`. Если есть ошибки типизации — исправь их.
2. Запусти `pnpm test:unit` для модифицированных модулей.
3. Не создавай новых файлов без предварительной проверки наличия существующих утилит в `src/lib/`.

03. Принудительная типобезопасность и Zod-валидация в API

Правило для бэкенда исключает использование нетипизированных JSON-пейлоадов в контроллерах:

---
description: Стандартизация бэкенд-эндпоинтов
globs: src/server/api/**/*.ts
---
- Все входные аргументы запросов должны проходить парсинг через Zod-схемы (`schema.parseAsync(req.body)`).
- Тип `any` строго запрещен; при работе с неизвестными данными использовать `unknown` с последующим type narrowing.
- В случае возникновения бизнес-ошибок выбрасывать типизированный `TRPCError` или `HttpError` с кодом статуса.

5. Подводные камни, типовые ошибки и безопасность

• Правило-свалка (Rule Bloat & Attention Saturation): Попытка записать в файл правил всю документацию проекта приводит к файлам размером более 500 строк. Это вымывает внимание модели («Lost in the Middle») и приводит к тому, что модель начинает игнорировать ключевые наставления. Разбивайте правила на модульные скоупы.
• Противоречивые или конфликтующие правила: Если глобальный CLAUDE.md требует использования pnpm, а устаревший README.md или локальное правило содержит npm install, модель может зациклиться в галлюцинациях менеджера пакетов.
• Опасность утечки чувствительных данных: Никогда не указывайте токены доступа, пароли к тестовым базам или персональные ключи API в правилах репозитория. Все переменные окружения должны описываться только как абстрактные имена (например, DATABASE_URL is required in .env.local).
• Отсутствие версионирования: Правила агентов должны развиваться вместе с кодовой базой в системе контроля версий Git. Изменение технологического стека должно сопровождаться атомарным обновлением соответствующих файлов правил в том же коммите.