Zum Hauptinhalt springen
AGENTS.md-Dateien bieten eine einfache Möglichkeit, Cascade kontextsensitive Anweisungen zu geben, die automatisch angewendet werden, abhängig davon, in welchem Verzeichnis sie sich in deinem Projekt befinden. Dies ist besonders nützlich, um verzeichnisspezifische Programmierleitlinien, Architekturentscheidungen oder Projektkonventionen festzuhalten.

​
Wie es funktioniert

Wenn du eine Datei AGENTS.md (oder agents.md) erstellst, erkennt Windsurf sie automatisch und speist sie in dieselbe Rules-Engine ein, die auch .windsurf/rules/ antreibt — nur dass der Aktivierungsmodus hier anhand des Dateispeicherorts statt über Frontmatter abgeleitet wird:
  • Stammverzeichnis: Wird als always-on-Regel behandelt — der vollständige Inhalt wird bei jeder Nachricht in den System-Prompt von Cascade aufgenommen.
  • Unterverzeichnisse: Werden als glob-Regel mit dem automatisch generierten Muster <directory>/** behandelt — der Inhalt wird nur angewendet, wenn Cascade Dateien innerhalb dieses Verzeichnisses liest oder bearbeitet.
Dieser ortsbasierte Geltungsbereich macht AGENTS.md ideal, um gezielte Anleitung bereitzustellen, ohne eine einzelne globale Konfigurationsdatei zu überladen.

​
Erstellen einer AGENTS.md-Datei

Erstelle einfach eine Datei mit dem Namen AGENTS.md oder agents.md im gewünschten Verzeichnis. Die Datei ist normales Markdown; spezielles Frontmatter ist nicht erforderlich.

​
Beispielaufbau

my-project/
├── AGENTS.md                    # Globale Anweisungen für das gesamte Projekt
├── frontend/
│   ├── AGENTS.md                # Anweisungen speziell für Frontend-Code
│   └── src/
│       └── components/
│           └── AGENTS.md        # Anweisungen speziell für Komponenten
├── backend/
│   └── AGENTS.md                # Anweisungen speziell für Backend-Code
└── docs/
    └── AGENTS.md                # Anweisungen für die Dokumentation

​
Beispielinhalt

Hier ist ein Beispiel für eine AGENTS.md-Datei in einem React-Komponentenverzeichnis: 
# Component Guidelines

When working with components in this directory:

- Use functional components with hooks
- Follow the naming convention: ComponentName.tsx for components, useHookName.ts for hooks
- Each component should have a corresponding test file: ComponentName.test.tsx
- Use CSS modules for styling: ComponentName.module.css
- Export components as named exports, not default exports

## File Structure

Each component folder should contain:
- The main component file
- A test file
- A styles file (if needed)
- An index.ts for re-exports

​
Erkennung und Geltungsbereich

Windsurf erkennt AGENTS.md-Dateien in deinem Workspace automatisch:
  • Workspace-Scan: Alle AGENTS.md-Dateien innerhalb deines Workspaces und seiner Unterverzeichnisse werden erkannt
  • Git-Repository-Unterstützung: Für Git-Repositories durchsucht Windsurf außerdem übergeordnete Verzeichnisse bis zum Git-Root-Verzeichnis
  • Unabhängig von der Groß-/Kleinschreibung: Sowohl AGENTS.md als auch agents.md werden erkannt

​
Automatisches Scoping

Der wichtigste Vorteil von AGENTS.md ist das automatische Scoping anhand des Dateipfads:
DateipfadGeltungsbereich
Workspace-Root-VerzeichnisGilt für alle Dateien (immer aktiv)
/frontend/Gilt, wenn du mit Dateien unter /frontend/** arbeitest
/frontend/components/Gilt, wenn du mit Dateien unter /frontend/components/** arbeitest
Das bedeutet, dass du mehrere AGENTS.md-Dateien auf unterschiedlichen Ebenen haben kannst, die jeweils zunehmend spezifische Anleitungen für das entsprechende Verzeichnis bereitstellen.

​
Best Practices

Um das Beste aus AGENTS.md-Dateien herauszuholen:
  • Anweisungen fokussiert halten: Jede AGENTS.md-Datei sollte Anweisungen enthalten, die für den Zweck ihres Verzeichnisses relevant sind
  • Klare Formatierung verwenden: Aufzählungen, Überschriften und Codeblöcke erleichtern es Cascade, den Anweisungen zu folgen
  • Konkret sein: Konkrete Beispiele und explizite Konventionen funktionieren besser als vage Richtlinien
  • Redundanz vermeiden: Wiederhole globale Anweisungen nicht in Dateien in Unterverzeichnissen; sie werden aus den übergeordneten Verzeichnissen übernommen

​
Richtlinien für Inhalte

# Good Example
- Use TypeScript strict mode
- All API responses must include error handling
- Follow REST naming conventions for endpoints

# Less Effective Example
- Write good code
- Be careful with errors
- Use best practices

​
Vergleich mit Rules

Auch wenn sowohl AGENTS.md als auch Rules Anweisungen für Cascade bereitstellen, erfüllen sie unterschiedliche Zwecke:
MerkmalAGENTS.mdRules
SpeicherortIn Projektverzeichnissen.windsurf/rules/ oder global
GeltungsbereichAutomatisch basierend auf DateispeicherortManuell (glob, immer aktiv, Entscheidung des AI-Modells, manuell)
FormatEinfaches MarkdownMarkdown mit Frontmatter
Am besten geeignet fürverzeichnisspezifische KonventionenQuerschnittsthemen, komplexe Aktivierungslogik
Verwende AGENTS.md, wenn du einfache, ortsbasierte Anweisungen möchtest. Verwende Rules, wenn du mehr Kontrolle darüber benötigst, wann und wie Anweisungen angewendet werden.