Warum AGENTS.md?

Ohne AGENTS.md startet jede KI-Interaktion bei Null:

Sie:  "Fuege einen neuen API-Endpunkt hinzu"
KI:   *Verwendet CommonJS, erstellt eine Callback-basierte Express-Route,
       packt Geschaeftslogik in den Route-Handler*
Sie:  "Nein, wir verwenden ESM, async/await und Services..."

Mit AGENTS.md kennt die KI bereits Ihre Konventionen:

Sie:  "Fuege einen neuen API-Endpunkt hinzu"
KI:   *Erstellt ESM-Modul, verwendet async/await, packt Logik in
       einen Service, folgt Ihren Namenskonventionen*

AGENTS.md ist eine einmalige Investition, die bei jeder zukuenftigen Interaktion Zeit spart.

Die Struktur

Eine umfassende AGENTS.md hat fuenf Abschnitte:

# AGENTS.md

## 1. Projektuebersicht
Was dieses Projekt ist, was es tut, Tech-Stack.

## 2. Architektur
Wie der Code organisiert ist, wichtige Muster.

## 3. Code-Stil
Formatierung, Benennung, Konventionen, Sprachfeatures.

## 4. Haeufige Aufgaben
Schritt-fuer-Schritt-Anleitungen fuer wiederkehrende Operationen.

## 5. Fallstricke
Dinge, die die KI (und neue Entwickler) haeufig falsch machen.

Platzieren Sie sie im Wurzelverzeichnis Ihres Projekts. KI-Tools wie Claude Code, OpenCode und Cursor erkennen und lesen sie automatisch.

Die Projektuebersicht schreiben

Beginnen Sie mit Kontext, den die KI nicht aus dem Code ableiten kann:

## Projektuebersicht
Mandantenfaehige SaaS-Analyseplattform.
- **Backend:** Node.js 20, Express, ESM-Module, MongoDB
- **Frontend:** React 18, Mantine UI, Vite
- **Auth:** JWT-Tokens, bcrypt-Passwort-Hashing
- **Deployment:** Docker-Container, einzelnes Image bedient API + statisches Frontend
- **Testing:** Jest fuer Backend, Vitest fuer Frontend
- **API-Stil:** RESTful, OpenAI-kompatible Gateway-Endpunkte

Wichtige Details zum Einfuegen:

• Geschaeftsdomaene (SaaS, E-Commerce, Gesundheitswesen etc.)
• Warum bestimmte Technologien gewaehlt wurden
• Wichtige Integrationen (Stripe, AWS etc.)
• Zielgruppe (internes Tool, oeffentliche API, Verbraucher-App)

Code-Konventionen definieren

Hier zahlt sich AGENTS.md selbst zurueck:

## Code-Stil

### JavaScript/Node.js
- Nur ESM-Module (`import/export`, niemals `require`)
- Ueberall `async/await` -- keine Callbacks, kein rohes `.then()`
- `const` als Standard, `let` nur bei Neuzuweisung
- Alle Funktionen: JSDoc mit `@param` und `@returns`
- Fehlerbehandlung: `AppError`-Instanzen werfen, niemals einfache Strings

### Benennung
- Dateien: kebab-case (`user-service.js`, nicht `UserService.js`)
- Variablen/Funktionen: camelCase
- Konstanten: UPPER_SNAKE_CASE
- Datenbankmodelle: PascalCase (`Tenant`, `RequestLog`)

### API-Routen
- Immer `{ data }` bei Erfolg zurueckgeben
- Immer `{ error: "message" }` bei Fehler zurueckgeben
- Passende HTTP-Statuscodes verwenden (201 fuer Create, 204 fuer Delete)
- Alle Eingaben mit express-validator validieren

### Frontend
- Nur funktionale Komponenten -- keine Klassen-Komponenten
- Custom Hooks im `/hooks`-Verzeichnis
- Geteilte Komponenten in `/components`
- Seitenebenen-Komponenten in `/pages`

Haeufige Aufgaben dokumentieren

Geben Sie der KI Schritt-fuer-Schritt-Anleitungen:

## Haeufige Aufgaben

### Neue API-Route hinzufuegen
1. `server/routes/admin/myroute.js` erstellen
2. Einen Router mit GET/POST/PUT/DELETE-Handlern exportieren
3. In `server/index.js` importieren und mit RBAC-Middleware einbinden:
   - `adminOrMaint` fuer Schreiboperationen
   - `anyUser` fuer Read-Only-Endpunkte
4. Eingabevalidierung mit Sanitize-Helfern hinzufuegen
5. Entsprechenden Service in `server/services/` erstellen oder aktualisieren

### Neues Datenbankmodell hinzufuegen
1. `server/models/MyModel.js` mit Mongoose-Schema erstellen
2. Indizes fuer haeufig abgefragte Felder hinzufuegen
3. `timestamps: true` in Schema-Optionen einfuegen
4. Sowohl das Modell als auch das Schema exportieren

### Tests ausfuehren
- Backend: `npm run test:server`
- Frontend: `npm run test:frontend`
- Alle: `npm test`
- Abdeckung: `npm run test:coverage` (mindestens 80%)

Fallstricke auflisten

Verhindern Sie, dass die KI Fehler macht, die Sie schon gesehen haben:

## Fallstricke -- Dinge, die haeufig schiefgehen

### NICHT TUN
- Nicht `process.env` direkt verwenden -- immer ueber `config.js`
- Keine Geschaeftslogik in Route-Handler -- Services verwenden
- Nicht `var` verwenden -- niemals
- Keine `.env`-Dateien committen
- Nicht den Typ `any` in TypeScript verwenden, ohne einen Kommentar warum
- Keine synchronen Dateioperationen in Request-Handlern
- Benutzereingaben nicht vertrauen -- immer mit `sanitize.js` bereinigen

### AUFPASSEN BEI
- MongoDB-Injection: immer parametrisierte Abfragen verwenden
- Kontextfenster: bei grossen Dateien zuerst die Datei lesen
- Import-Pfade: `.js`-Erweiterung in ESM-Imports verwenden
- Port-Konflikte: Dev-Server laeuft auf 3000, Frontend auf 5173

Profi-Tipp: Jedes Mal, wenn die KI einen Fehler macht, fuegen Sie ihn zum Fallstricke-Abschnitt hinzu. Ihre AGENTS.md wird zu einem lebendigen Dokument, das mit der Zeit klueger wird.

Agenten-Selbstverbesserung

Hier kommt die fortgeschrittene Technik: Lassen Sie die KI ihre eigenen Anweisungen verbessern.

Nach einer Coding-Sitzung fragen Sie:

Pruefe die Aenderungen, die wir gerade gemacht haben. Gab es
Konventionen oder Muster, die du durch Lesen des Codes entdecken
musstest und die in AGENTS.md dokumentiert sein sollten?

Aktualisiere AGENTS.md mit fehlenden Konventionen.

Die KI wird:

1. Analysieren, was sie waehrend der Sitzung gelernt hat
2. Muster identifizieren, die sie ableiten musste anstatt zu lesen
3. Diese Muster zu AGENTS.md hinzufuegen
4. Zukuenftige Sitzungen effizienter machen

Der positive Kreislauf:

KI verwenden → KI entdeckt Muster → AGENTS.md aktualisieren →
KI liest AGENTS.md → KI folgt Mustern → Besserer Code →
KI entdeckt weitere Muster → ...

Das ist eine der maechtigsten Techniken in der KI-gestuetzten Entwicklung.

---quiz question: Was ist der primaere Zweck von AGENTS.md? options:

• { text: "Die API fuer Endbenutzer dokumentieren", correct: false }
• { text: "Projektkonventionen definieren, damit KI-Coding-Agenten automatisch Ihrem Code-Stil folgen", correct: true }
• { text: "Deployment-Pipelines konfigurieren", correct: false } feedback: AGENTS.md bringt KI-Coding-Tools die Konventionen Ihres Projekts bei -- Code-Stil, Architekturmuster, haeufige Aufgaben und Fallstricke -- damit sie Code erzeugen, der natuerlich in Ihr Projekt passt, ohne dass Sie jedes Mal Anweisungen wiederholen muessen.

---quiz question: Was ist "Agenten-Selbstverbesserung" im Kontext von AGENTS.md? options:

• { text: "Die KI aktualisiert automatisch ihre eigenen Modellgewichte", correct: false }
• { text: "Die KI bitten, undokumentierte Muster zu identifizieren und AGENTS.md zu aktualisieren", correct: true }
• { text: "Den KI-Agenten neu installieren, um die neueste Version zu erhalten", correct: false } feedback: Nach einer Coding-Sitzung koennen Sie die KI bitten, zu ueberpruefen, welche Muster sie selbst entdecken musste, und diese zu AGENTS.md hinzuzufuegen. Das schafft einen positiven Kreislauf, bei dem jede Sitzung die naechste effizienter macht.

---quiz question: Warum sollten Sie einen "Fallstricke"-Abschnitt in AGENTS.md einfuegen? options:

• { text: "Um die Datei laenger und beeindruckender zu machen", correct: false }
• { text: "Um zu verhindern, dass die KI Fehler macht, denen Sie bereits begegnet sind", correct: true }
• { text: "Um Bugs im KI-Tool selbst zu dokumentieren", correct: false } feedback: Der Fallstricke-Abschnitt erfasst haeufige Fehler, damit die KI sie proaktiv vermeidet. Jedes Mal, wenn die KI einen Fehler macht, verhindert das Hinzufuegen zum Fallstricke-Abschnitt, dass er in zukuenftigen Sitzungen erneut auftritt.