Skip to main content
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

Beispielinhalt

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

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

Vergleich mit Rules

Auch wenn sowohl AGENTS.md als auch Rules Anweisungen für Cascade bereitstellen, erfüllen sie unterschiedliche Zwecke: 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.