Agent Rules (.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. Зміна технологічного стеку повинна супроводжуватися атомарним оновленням відповідних файлів правил у тому самому коміті.