So erstellst du die perfekte AGENTS.md (inkl. Template)

Vielleicht kennst du das Problem.

Dein KI-Coding-Assistant versteht dein Projekt einfach nicht richtig. Du wechselst von Claude zu Cursor, dann zu Continue.dev, und musst jedes Mal wieder bei Null anfangen mit den Erklärungen.

Oder noch schlimmer, du hast eine aufwendige CLAUDE.md geschrieben. Claude Code liest sie nativ, bei anderen Tools ist die Unterstützung aber uneinheitlich. Vor einem Wechsel musst du deshalb prüfen, welche Regeln das neue Tool tatsächlich lädt.

Eine mögliche gemeinsame Basis ist AGENTS.md. Die Markdown-Datei kann Projektregeln bündeln, aber die Unterstützung unterscheidet sich je nach Tool.

In diesem Artikel zeige ich dir, wie du eine klare AGENTS.md erstellst und mit der Kompatibilitätsmatrix prüfst, wo sie sinnvoll ist.

1. Was ist eine AGENTS.md-Datei?

AGENTS.md ist eine Markdown-Konvention für KI-Coding-Instruktionen. Stell sie dir wie eine README-Datei vor, die sich an ein unterstützendes Tool richtet.

Das Geniale daran ist simpel.

Die Datei besteht aus einfachem Markdown ohne besondere Syntax. Ein Tool muss AGENTS.md aber ausdrücklich unterstützen oder dafür konfiguriert sein, damit es die Anweisungen lädt.

AGENTS.md ist für gemeinsam genutzte Regeln praktisch. Ob sie für dein Setup geeignet ist, zeigt erst die Unterstützung der Tools, die dein Team tatsächlich verwendet.

Einige Tools unterstützen Anweisungen in Unterordnern oder eine Hierarchie. Andere laden nur eine festgelegte Datei. Prüfe dieses Verhalten vor dem Einsatz mehrerer AGENTS.md-Dateien.

2. Welche Tools unterstützen welchen Standard?

Der Bereich der KI-Coding-Tools ist fragmentiert. Jedes Tool kocht sein eigenes Süppchen. Hier siehst du auf einen Blick, welche Konfigurationsstandards von welchen Tools unterstützt werden.

Die Matrix zeigt unterschiedliche native, teilweise und fehlende Unterstützung. Wähle die Dateien deshalb nach dem konkreten Tool aus, statt von einer einheitlichen Konvention auszugehen.

Meine Empfehlung für maximale Kompatibilität

So gehst du bei mehreren Tools kontrolliert vor:

# AGENTS.md nur anlegen, wenn noch keine Datei vorhanden ist
if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'AGENTS.md existiert bereits. Führe gemeinsame Regeln manuell zusammen.'
else
  cp CLAUDE.md AGENTS.md
fi

# CLAUDE.md für Claude Code behalten
# GEMINI.md für Gemini CLI behalten, falls du es verwendest

# Gemeinsame Regeln künftig in den betroffenen Dateien manuell abgleichen

3. Aufbau und Struktur einer AGENTS.md

AGENTS.md ist bewusst einfach gehalten. Kein YAML-Frontmatter, keine spezielle Syntax. Nur sauberes Markdown.

Nach dutzenden Iterationen hat sich diese Struktur als optimal erwiesen:

# Projektname

Kurze Beschreibung des Projekts und seiner Hauptziele.

## Development Environment
- Build-Befehle und Skripte
- Testing-Instruktionen
- Wichtige Dependencies

## Code Style Guidelines
- Formatierungs-Regeln
- Naming Conventions
- Architektur-Patterns

## Project Context
- Wichtige Dateien und deren Zweck
- Ungewöhnliche Patterns oder Gotchas
- Performance-kritische Bereiche

## Testing Instructions
- Test-Runner-Befehle
- Coverage-Anforderungen
- CI/CD-Prozesse

Diese Dinge solltest du vermeiden:

• Zu viele Details (> 500 Zeilen werden oft ignoriert)
• Veraltete Informationen (nichts ist schlimmer als falsche Instruktionen)
• Tool-spezifische Syntax (bleibt bei Standard-Markdown)
• Sensible Informationen (keine Secrets oder Credentials!)

4. Schritt für Schritt zur perfekten AGENTS.md

Jetzt wird's praktisch. Ich zeig dir, wie du in wenigen Minuten eine AGENTS.md erstellst.

4.1 Projekt-Analyse: Was muss die KI wissen?

Bevor du loslegst, stell dir diese Fragen:

1. Was sind die häufigsten Aufgaben in deinem Projekt?
2. Welche Fehler macht die AI immer wieder?
3. Was ist ungewöhnlich an deinem Setup?
4. Welche Standards sind dir wichtig?

Die Antworten darauf gehören in deine AGENTS.md.

4.2 Das Universal-Template

Hier ist mein bewährtes Template, das du direkt kopieren und anpassen kannst:

# [Projektname]

[Ein-Satz-Beschreibung was das Projekt macht]

## Development Setup

```bash
# Installation
npm install  # oder yarn/pnpm

# Development
npm run dev

# Build
npm run build

# Tests
npm test
```

## Tech Layers

- **Framework**: [z. B. Next.js 15, React 18]
- **Language**: [z. B. TypeScript mit strict mode]
- **Styling**: [z. B. Tailwind CSS v4]
- **Database**: [z. B. PostgreSQL mit Prisma]
- **Testing**: [z. B. Jest + React Testing Library]

## Project Structure

```
src/
├── app/          # Next.js App Router
├── components/   # Reusable UI components
├── lib/          # Utilities and services
├── hooks/        # Custom React hooks
└── types/        # TypeScript type definitions
```

## Code Standards

### General Rules
- Prefer TypeScript over JavaScript
- Use functional components with hooks
- Follow ESLint configuration
- Write tests for new features

### Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Utilities: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE_CASE
- Types/Interfaces: PascalCase with suffix (UserType)

### File Organization
- Colocate tests with source files
- Group related components in folders
- Use index.ts for clean imports

## Important Patterns

### API Calls
Always use the API client from lib/api:
```typescript
import { apiClient } from '@/lib/api'
const data = await apiClient.get('/endpoint')
```

### State Management
- Use React Context for global state
- Prefer local state when possible
- Consider Zustand for complex state

## Testing Guidelines

- Write tests alongside implementation
- Focus on user behavior, not implementation
- Maintain > 80% coverage for critical paths
- Use data-testid for reliable selection

## Common Pitfalls to Avoid

- DON'T: Create new files unless necessary
- DON'T: Use console.log in production code
- DON'T: Ignore TypeScript errors
- DON'T: Skip tests for „simple“ features
- DO: Check existing components before creating new ones
- DO: Follow established patterns in the codebase
- DO: Keep functions small and focused

## Performance Considerations

- Lazy load heavy components
- Use React.memo for expensive renders
- Optimize images with next/image
- Monitor bundle size

## Veröffentlichung

- Main branch deploys to production
- PR previews on Vercel
- Environment variables in .env.local
- Secrets managed via Vercel dashboard

## Additional Resources

- Architecture decisions: docs/architecture.md
- API documentation: docs/api.md
- Component library: Storybook at localhost:6006

4.3 Anpassung an dein Projekt

Das Template ist nur der Start. Hier ist mein bewährter Prozess zur Anpassung:

1. Woche 1: Nutze das Basis-Template
2. Täglich: Notiere wenn die AI etwas falsch macht
3. Wöchentlich: Update die AGENTS.md mit den Erkenntnissen
4. Nach 1 Monat: Große Überarbeitung basierend auf Erfahrungen

Ein Beispiel aus meiner Praxis. Nach 2 Wochen hatte ich 15 spezifische Regeln für mein Next.js-Blog-System hinzugefügt. Die AI-Fehlerquote sank um 70 %.

5. Häufige Anfängerfehler vermeiden

Diese Fehler sehe ich immer wieder (und habe sie teilweise selbst gemacht):

1. Zu allgemein bleiben: „Write good code“ bringt nichts. Sei spezifisch: „Use async/await instead of .then() chains“
2. Informationsüberflutung: Lange Dateien sind schwer zu pflegen und veralten leicht. Bleib bei den Regeln, die dein Tool für die jeweilige Aufgabe wirklich braucht, und verlinke für Details auf die passende Dokumentation.
3. Vergessen zu updaten: Dein Projekt entwickelt sich, aber die AGENTS.md bleibt alt = Chaos
4. Tool-spezifische Features: Nutze nur Standard-Markdown für maximale Kompatibilität
5. Keine Beispiele: Zeig der AI wie es richtig geht mit Code-Beispielen
6. Sensible Daten: Niemals API-Keys oder Passwörter in AGENTS.md!

6. Profi-Tipps für fortgeschrittene Nutzung

Zeit für die Advanced-Tricks aus meiner täglichen Praxis.

6.1 Hierarchische AGENTS.md für große Projekte

project/
├── AGENTS.md                 # Globale Projekt-Regeln
├── frontend/
│   └── AGENTS.md            # Frontend-spezifisch
├── backend/
│   └── AGENTS.md            # Backend-spezifisch
└── tests/
    └── AGENTS.md            # Test-spezifisch

Einige Tools laden die nächstgelegene Datei, andere nicht. Prüfe das mit einem kleinen Testprojekt und der Dokumentation deines Tools, bevor du bereichsspezifische Regeln darauf aufbaust.

6.2 Dynamische Sections für verschiedene Modi

## Mode: Development
- Use verbose logging
- Include debug statements
- Skip optimization

## Mode: Production
- No console.log statements
- Optimize for performance
- Include error tracking

## Mode: Testing
- Mock external services
- Use test database
- Verbose test output

6.3 Team-Synchronisation mit Git

AGENTS.md gehört ins Repository, aber mit System:

# Project Guidelines

[... Haupt-Content ...]

---
## Changelog
<!-- Team-Updates dokumentieren -->
- 2025-09-26: Added TypeScript strict rules (FH)
- 2025-09-20: Updated test coverage requirements (TM)
- 2025-09-15: Initial version (FH)

## Personal Overrides
<!-- Diese Section NICHT committen -->
<!-- Lokal in AGENTS.personal.md auslagern -->

6.4 Performance-Monitoring

So misst du den Impact deiner AGENTS.md:

• Tracke AI-Fehlerrate vor/nach Updates
• Messe Zeit bis zur korrekten Lösung
• Dokumentiere wiederkehrende Probleme

Vergleiche die Ergebnisse vor und nach einer Änderung mit wiederkehrenden Aufgaben. So erkennst du, ob die Anweisungen tatsächlich helfen.

7. Migration von bestehenden Systemen

Du hast bereits eine CLAUDE.md oder andere Konfiguration? Übernimm gemeinsame Regeln schrittweise und behalte die nativen Dateien der verwendeten Tools.

Gemeinsame Regeln aus CLAUDE.md übernehmen

# AGENTS.md nur anlegen, wenn noch keine Datei vorhanden ist
if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'AGENTS.md existiert bereits. Führe gemeinsame Regeln manuell zusammen.'
else
  cp CLAUDE.md AGENTS.md
fi

# Tool-spezifische Regeln in den jeweiligen nativen Dateien behalten
# Jede Datei mit der Dokumentation des verwendeten Tools testen

Von mehreren Configs zu einer AGENTS.md

Viele Projekte haben .cursorrules, .claude/config, etc. So konsolidierst du alles:

1. Sammle alle existierenden Configs
2. Identifiziere Überschneidungen
3. Gemeinsame Regeln mit klarer Struktur in AGENTS.md übertragen
4. Native Dateien für die verwendeten Tools beibehalten
5. Jedes Tool mit einer repräsentativen Aufgabe testen

8. Konfiguration langfristig pflegen

Tool-Unterstützung und Dateinamen können sich ändern. Mit diesen Regeln bleibt deine Konfiguration nachvollziehbar:

• Dokumentation prüfen: Vor jeder Umstellung die aktuelle Tool-Dokumentation lesen
• Gemeinsame Regeln abgleichen: Änderungen in den betroffenen Dateien bewusst übernehmen
• Tests wiederholen: Nach einem Tool-Update mit einer repräsentativen Aufgabe prüfen
• Tool-spezifische Regeln trennen: Native Dateien für ihre jeweiligen Tools beibehalten

Mein Rat: Starte mit einer kurzen, klaren Datei und erweitere sie erst, wenn dein Tool sie nachweislich verwendet.

Fazit: AGENTS.md bewusst einsetzen

Eine gut gepflegte Anweisungsdatei kann wiederkehrende Projektregeln sichtbar machen und Abstimmung sparen.

Eine vollständige, automatische Kompatibilität gibt es nicht. Die Dateinamen, Ladepfade und Prioritäten unterscheiden sich zwischen den Tools.

Übernimm das Template nur als Ausgangspunkt und passe es an die Dokumentation und den Arbeitsablauf deines Tools an.