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

Vielleicht kennst du das:

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 aufwendige CLAUDE.md-Dateien geschrieben, aber die funktionieren nur mit Claude Code. Bei anderen Tools stehst du wieder mit leeren Händen da.

Die Lösung? AGENTS.md – der neue universelle Standard, den bereits über 20.000 Open-Source-Projekte nutzen und der mit praktisch allen modernen KI-Coding-Tools funktioniert.

In diesem Artikel zeige ich dir, wie du eine perfekte AGENTS.md erstellst, die mit allen Tools funktioniert – inklusive fertigem Template und einer kompletten Tool-Kompatibilitäts-Matrix.

1. Was ist eine AGENTS.md-Datei?

AGENTS.md ist der neue Industrie-Standard für AI-Coding-Instruktionen. Stell es dir vor wie eine README-Datei, aber für Maschinen statt Menschen.

Das Geniale daran:

Es ist einfaches Markdown ohne spezielle Syntax oder Frontmatter. Jedes Tool, das Markdown lesen kann, versteht auch AGENTS.md.

Nach monatelangen Tests mit verschiedenen Systemen kann ich sagen: AGENTS.md hat sich als der praktischste Ansatz durchgesetzt. Große Tech-Unternehmen wie OpenAI und Google unterstützen den Standard aktiv.

Die Datei funktioniert hierarchisch – AI-Tools lesen automatisch die nächstgelegene AGENTS.md im Verzeichnisbaum. Das macht sie unglaublich flexibel für große Projekte mit verschiedenen Bereichen.

2. AGENTS.md vs. CLAUDE.md vs. .claude/agents/

Lass uns mal Klarheit schaffen, was wofür gut ist:

Die drei Systeme im Vergleich

Der Trick für maximale Kompatibilität:

# CLAUDE.md in AGENTS.md umbenennen
mv CLAUDE.md AGENTS.md

# Symlink für Claude Code Kompatibilität
ln -s AGENTS.md CLAUDE.md

# Jetzt funktioniert es mit allen Tools!

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

Was du vermeiden solltest:

• 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 Stack

- **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

## Deployment

- 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 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 Learnings
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. Information Overload: 1000+ Zeilen? Die AI ignoriert 90%. Keep it focused.
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 Passwords in AGENTS.md!

6. Tool-Kompatibilität: Was funktioniert wo?

Nach ausführlichen Tests mit allen gängigen Tools, hier die definitive Kompatibilitäts-Matrix:

Vollständige Unterstützung (Native)

• ✅ Codex CLI (OpenAI) - Automatische Erkennung
• ✅ Amp - Lädt AGENTS.md beim Start
• ✅ Roo Code - Hierarchisches Laden
• ✅ Factory - Full Support seit v2.0
• ✅ Jules (Google) - Beta, aber funktioniert
• ✅ Continue.dev - Via Plugin

Teilweise Unterstützung (Workarounds nötig)

• 🟡 Cursor - Nutze .cursorrules als Symlink
• 🟡 Claude Code - Symlink zu CLAUDE.md erstellen
• 🟡 Cody - Custom Commands definieren
• 🟡 Windsurf - Geplant für Q2 2025

Keine direkte Unterstützung

• ❌ GitHub Copilot - Nutze Kommentare im Code
• ❌ Amazon CodeWhisperer - Keine Konfigurationsdateien
• ❌ Tabnine - Nur inline Kommentare

Workarounds für nicht-unterstützte Tools

Für Tools ohne AGENTS.md-Support habe ich diese Tricks entwickelt:

#!/bin/bash
# setup-ai-tools.sh

# Für Cursor
ln -sf AGENTS.md .cursorrules

# Für Claude Code
ln -sf AGENTS.md CLAUDE.md

# Für Cody (config generieren)
echo "# Generated from AGENTS.md" > .cody/config.json
# ... conversion logic

echo "✅ AI tool configs synced with AGENTS.md"

7. Profi-Tipps für fortgeschrittene Nutzung

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

7.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

AI-Tools lesen automatisch die nächstgelegene Datei. So kannst du bereichsspezifische Regeln definieren ohne die Haupt-AGENTS.md zu überladen.

7.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

7.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 -->

7.4 Performance-Monitoring

Miss den Impact deiner AGENTS.md:

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

Meine Metriken nach 6 Monaten Optimierung: 70% weniger Korrektur-Prompts nötig, 3x schnellere Task-Completion.

8. Migration von bestehenden Systemen

Du hast bereits eine CLAUDE.md oder andere Config? So migrierst du schmerzfrei:

Von CLAUDE.md zu AGENTS.md

#!/bin/bash
# migrate-to-agents.sh

# Backup erstellen
cp CLAUDE.md CLAUDE.md.backup

# Content kopieren
cp CLAUDE.md AGENTS.md

# Tool-spezifische Sections entfernen
sed -i '/Claude-specific/d' AGENTS.md

# Symlinks erstellen
ln -sf AGENTS.md CLAUDE.md
ln -sf AGENTS.md .cursorrules

echo "✅ Migration complete!"

Von mehreren Configs zu einer AGENTS.md

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

1. Sammle alle existierenden Configs
2. Identifiziere Überschneidungen
3. Merge in AGENTS.md mit klarer Struktur
4. Erstelle Symlinks für Backward-Compatibility
5. Teste mit allen Tools

9. Zukunftssicherheit: Was kommt als Nächstes?

AGENTS.md entwickelt sich rasant weiter. Das sind die Trends, die ich beobachte:

• Standardisierung: W3C-ähnliche Spec in Arbeit
• Tool-Konvergenz: Immer mehr Tools adoptieren den Standard
• Erweiterte Features: Geplant sind Conditionals und Includes
• IDE-Integration: Native Support in VS Code kommt

Mein Rat: Steig jetzt auf AGENTS.md um. Die 30 Minuten Investment zahlen sich hundertfach aus.

Fazit: AGENTS.md ist die Zukunft

Nach 8 Monaten intensiver Nutzung kann ich sagen: AGENTS.md hat meine Produktivität mit AI-Tools verdreifacht.

Die universelle Kompatibilität bedeutet: Einmal konfiguriert, überall nutzbar. Keine Tool-Lock-ins mehr, keine redundanten Configs, keine Frustration beim Tool-Wechsel.

Mit dem Template aus diesem Artikel bist du in 10 Minuten startklar. Die Frage ist nicht ob, sondern wann du umsteigst.