Agent Rules (.cursorrules / CLAUDE.md / AGENTS.md)

1. Konzeptüberblick und systemisches Problem

Moderne LLMs werden auf Gigabytes von Open-Source-Code aus GitHub trainiert, weshalb sie standardmäßig „durchschnittlichen“ Code generieren: veraltete Major-Versionen von Bibliotheken, chaotische Import-Muster, any in TypeScript oder ineffiziente Ansätze zur Fehlerbehandlung. Wenn ein Ingenieur im Paradigma des Vibe-Codings ohne festgelegte Regeln arbeitet, wird jeder neue Prompt zu einem Glücksspiel:

• Der Agent installiert veraltetes moment.js oder axios anstelle von nativem date-fns oder fetch.
• Der Agent vermischt Architekturschichten (z. B. direkter Zugriff auf die Datenbank aus einer clientseitigen React-Komponente).
• Der Agent erfindet eigene Build- oder Testbefehle, anstatt die vorhandenen Skripte im Projekt zu nutzen.

Agent Rules (Dateien wie .cursorrules, CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc) lösen das Problem der Codebasis-Drift. Sie wandeln die internen Konventionen des Teams in einen systemischen Vertrag um, der von der Entwicklungsumgebung oder dem Terminal-Agenten bereits vor Beginn jeglicher Codegenerierung gelesen wird.

2. Architektonische Taxonomie und mentales Modell

Repository-Regeln lassen sich in drei Ebenen der Isolation und Aktivierung unterteilen:

┌─────────────────────────────────────────────────────────────┐
│                   РІВНІ ПРАВИЛ АГЕНТА                      │
├─────────────────────────────────────────────────────────────┤
│ 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. Globale Repository-Regeln (Core Repository Contract):
   • Befinden sich im Stammverzeichnis des Projekts (CLAUDE.md für Claude Code, AGENTS.md oder .cursorrules für Editoren).
   • Beschreiben das kritische Minimum: Umgebungsversionen (Node.js 22, Bun, Python 3.12), Paketmanager (pnpm), verpflichtende Linter und Anweisungen zur Commit-Struktur.
2. Kontextuelle Modulregeln (Scoped Domain Rules):
   • Dateien mit Metadaten und Glob-Patterns (z. B. .cursor/rules/database.mdc mit Filter src/db/**/*.ts).
   • Werden nur dann in den Arbeitspeicher des Modells geladen, wenn der Agent plant, Migrations- oder ORM-Modell-Dateien zu bearbeiten.
3. Operative Guardrails (Operational Constraints):
   • Klare negative Einschränkungen (Negative Constraints): „NIEMALS git push --force ausführen“, „NIEMALS .env.production modifizieren“, „KEINE neuen Abhängigkeiten ohne ausdrückliche Zustimmung des Ingenieurs hinzufügen“.

3. Technischer Pipeline und interne Mechanik

Der Lebenszyklus der Regeln während einer Vibe-Coding-Sitzung:

1. Sitzungsinitialisierung und Repository-Scan: Die IDE oder der CLI-Agent scannt beim Start das Stammverzeichnis sowie die Serviceverzeichnisse .cursor/rules/ oder .agents/rules/.
2. Intent-Analyse und Maskenabgleich (Glob Matching): Der Benutzer sendet eine Anfrage („Erstelle einen neuen Endpoint für das Abo-Zahlungssystem“). Der Agent prognostiziert Dateiänderungen in src/app/api/stripe/route.ts. Die Regel-Engine aktiviert Regeln für src/app/api/**/*.ts und stripe.mdc.
3. Zusammenstellung des erweiterten System-Prompts: Die Engine konkateniert:
   • Den Basis-System-Prompt des Modells;
   • Den Inhalt der globalen Vertragsdatei;
   • Die gefundenen Modulregeln;
   • Die aktuelle Baumstruktur der offenen Dateien und die Benutzeranfrage.
4. Codegenerierung mit erzwungener Einhaltung der Invarianten: Das Modell formuliert Tool-Aufrufe oder Code, wobei es die Regeln als obligatorischen Systemkontext heranzieht.
5. Post-Generierungs-Validierung: Wenn der Agent Terminalzugriff hat, führt er den in den Regeln definierten Validierungsbefehl aus (z. B. pnpm typecheck), bevor er den finalen Bericht an den Ingenieur zurückgibt.

4. Praktische Engineering-Szenarien im Produktionsumfeld

01. Architekturgrenzen im Next.js 15+ App Router

Die Datei .cursor/rules/nextjs.mdc mit dem Muster src/app/**/*.tsx verhindert klassische Fehler bei der Verwendung von Server- und Client-Komponenten:

---
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. Deterministische Testausführung für Claude Code

Die Konfiguration in CLAUDE.md stellt sicher, dass der Terminal-Agent ausschließlich die korrekten Testskripte verwendet, ohne Versuche, ein inkompatibles globales jest auszuführen:

# 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. Erzwungene Typsicherheit und Zod-Validierung in APIs

Eine Backend-Regel macht die Verwendung von untypisierten JSON-Payloads in Controllern unmöglich:

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

5. Fallstricke, häufige Fehler und Sicherheit

• Rule Bloat & Attention Saturation: Der Versuch, die gesamte Projektdokumentation in die Regeldatei zu schreiben, führt zu Dateien mit über 500 Zeilen. Dies verwässert die Aufmerksamkeit des Modells („Lost in the Middle“) und führt dazu, dass das Modell zentrale Anweisungen ignoriert. Teilen Sie Regeln in modulare Scopes auf.
• Widersprüchliche oder konfligierende Regeln: Wenn das globale CLAUDE.md die Nutzung von pnpm verlangt, aber eine veraltete README.md oder lokale Regel npm install enthält, kann das Modell in Halluzinationen bezüglich des Paketmanagers feststecken.
• Gefahr der Leckage sensibler Daten: Geben Sie niemals Access-Tokens, Passwörter für Testdatenbanken oder persönliche API-Keys in Repository-Regeln an. Alle Umgebungsvariablen sollten nur als abstrakte Namen beschrieben werden (z. B. DATABASE_URL is required in .env.local).
• Fehlendes Versioning: Agenten-Regeln müssen zusammen mit der Codebasis im Git-Versionskontrollsystem weiterentwickelt werden. Änderungen am Tech-Stack sollten von atomaren Updates der entsprechenden Regeldateien im selben Commit begleitet werden.