Passer au contenu principal
Les fichiers AGENTS.md offrent un moyen simple de fournir à Cascade des instructions contextualisées qui s’appliquent automatiquement en fonction de l’emplacement du fichier dans votre projet. Cela est particulièrement utile pour définir des directives de code spécifiques à un répertoire, des décisions d’architecture ou des conventions de projet.

​
Fonctionnement

Lorsque vous créez un fichier AGENTS.md (ou agents.md), Windsurf le découvre automatiquement et l’intègre au même moteur de Rules qui alimente .windsurf/rules/ — à ceci près que le mode d’activation est déduit de l’emplacement du fichier plutôt que du frontmatter :
  • Répertoire racine : traité comme une règle toujours active — l’intégralité du contenu est incluse dans le prompt système de Cascade à chaque message.
  • Sous-répertoires : traités comme une règle glob avec un motif généré automatiquement de <directory>/** — le contenu n’est appliqué que lorsque Cascade lit ou modifie des fichiers dans ce répertoire.
Cette portée définie par l’emplacement fait de AGENTS.md un choix idéal pour fournir des instructions ciblées sans encombrer un unique fichier de configuration global.

​
Création d’un fichier AGENTS.md

Créez simplement un fichier nommé AGENTS.md ou agents.md dans le répertoire souhaité. Le fichier est un simple fichier Markdown, sans front matter particulière requise.

​
Structure d’exemple

my-project/
├── AGENTS.md                    # Instructions globales pour l'ensemble du projet
├── frontend/
│   ├── AGENTS.md                # Instructions spécifiques au code frontend
│   └── src/
│       └── components/
│           └── AGENTS.md        # Instructions spécifiques aux composants
├── backend/
│   └── AGENTS.md                # Instructions spécifiques au code backend
└── docs/
    └── AGENTS.md                # Instructions pour la documentation

​
Exemple de contenu

Voici un exemple de fichier AGENTS.md pour un répertoire de composants React : 
# 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

​
Découverte et définition du périmètre

Windsurf découvre automatiquement les fichiers AGENTS.md dans l’ensemble de votre workspace :
  • Analyse du workspace : Tous les fichiers AGENTS.md présents dans votre workspace et ses sous-répertoires sont détectés
  • Prise en charge des dépôts Git : Pour les dépôts Git, Windsurf recherche également dans les répertoires parents jusqu’à la racine du dépôt Git
  • Insensible à la casse : Les fichiers AGENTS.md et agents.md sont tous deux reconnus

​
Portée automatique

Le principal avantage de AGENTS.md est la portée automatique basée sur l’emplacement des fichiers :
Emplacement du fichierPortée
Racine du workspaceS’applique à tous les fichiers (toujours actif)
/frontend/S’applique lorsque vous travaillez avec des fichiers dans /frontend/**
/frontend/components/S’applique lorsque vous travaillez avec des fichiers dans /frontend/components/**
Cela signifie que vous pouvez avoir plusieurs fichiers AGENTS.md à différents niveaux, chacun fournissant des recommandations de plus en plus spécifiques pour ses répertoires respectifs.

​
Bonnes pratiques

Pour tirer pleinement parti des fichiers AGENTS.md :
  • Gardez des instructions ciblées : chaque AGENTS.md doit contenir des instructions pertinentes pour la finalité de son répertoire
  • Utilisez un formatage clair : les listes à puces, les titres et les blocs de code facilitent la compréhension des instructions par Cascade
  • Soyez précis : des exemples concrets et des conventions explicites fonctionnent mieux que des consignes vagues
  • Évitez les redondances : ne répétez pas les instructions globales dans les fichiers des sous-répertoires ; elles sont héritées des répertoires parents

​
Consignes de contenu

# Bon exemple
- Utiliser le mode strict de TypeScript
- Toutes les réponses API doivent inclure la gestion des erreurs
- Suivre les conventions de nommage REST pour les endpoints

# Exemple moins efficace
- Écrire du bon code
- Faire attention aux erreurs
- Utiliser les bonnes pratiques

​
Comparaison avec Rules

Bien que AGENTS.md et Rules fournissent tous deux des instructions à Cascade, ils ont des objectifs différents :
FonctionnalitéAGENTS.mdRules
EmplacementDans les répertoires du projet.windsurf/rules/ ou global
PortéeAutomatique en fonction de l’emplacement du fichierManuel (glob, toujours activé, décision du modèle d’IA, manuel)
FormatMarkdown simpleMarkdown avec frontmatter
Idéal pourConventions spécifiques à un répertoirePréoccupations transversales, logique d’activation complexe
Utilisez AGENTS.md lorsque vous voulez des instructions simples basées sur l’emplacement. Utilisez Rules lorsque vous avez besoin de plus de contrôle sur le moment et la manière dont les instructions sont appliquées.