Saltar al contenido principal
Los archivos AGENTS.md proporcionan una forma sencilla de darle a Cascade instrucciones sensibles al contexto que se aplican automáticamente según dónde se encuentre el archivo dentro de tu proyecto. Esto es especialmente útil para definir guías de codificación específicas de un directorio, decisiones de arquitectura o convenciones del proyecto.

​
Cómo funciona

Cuando creas un archivo AGENTS.md (o agents.md), Windsurf lo detecta automáticamente y lo incorpora al mismo motor de Rules que impulsa .windsurf/rules/, solo que con el modo de activación inferido a partir de la ubicación del archivo en lugar del frontmatter:
  • Directorio raíz: Se trata como una regla siempre activa — el contenido completo se incluye en el prompt del sistema de Cascade en cada mensaje.
  • Subdirectorios: Se tratan como una regla glob con un patrón generado automáticamente de <directory>/** — el contenido se aplica solo cuando Cascade lee o edita archivos dentro de ese directorio.
Este alcance basado en la ubicación hace que AGENTS.md sea ideal para proporcionar instrucciones específicas sin sobrecargar un único archivo de configuración global.

​
Creación de un archivo AGENTS.md

Basta con crear un archivo llamado AGENTS.md o agents.md en el directorio deseado. El archivo usa Markdown normal y no requiere ningún frontmatter especial.

​
Ejemplo de estructura

my-project/
├── AGENTS.md                    # Instrucciones globales para todo el proyecto
├── frontend/
│   ├── AGENTS.md                # Instrucciones específicas para el código del frontend
│   └── src/
│       └── components/
│           └── AGENTS.md        # Instrucciones específicas para los componentes
├── backend/
│   └── AGENTS.md                # Instrucciones específicas para el código del backend
└── docs/
    └── AGENTS.md                # Instrucciones para la documentación

​
Contenido de ejemplo

Aquí tienes un ejemplo de archivo AGENTS.md para un directorio de componentes de 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

​
Descubrimiento y definición del alcance

Windsurf detecta automáticamente archivos AGENTS.md en todo tu workspace:
  • Escaneo del workspace: Se detectan todos los archivos AGENTS.md dentro de tu workspace y sus subdirectorios
  • Compatibilidad con repositorios Git: Para repositorios Git, Windsurf también busca en los directorios padre hasta la raíz del repositorio
  • Sin distinción entre mayúsculas y minúsculas: Se reconocen tanto AGENTS.md como agents.md

​
Alcance automático

El beneficio principal de AGENTS.md es el alcance automático basado en la ubicación de los archivos:
Ubicación del archivoAlcance
Raíz del workspaceSe aplica a todos los archivos (siempre activo)
/frontend/Se aplica al trabajar con archivos en /frontend/**
/frontend/components/Se aplica al trabajar con archivos en /frontend/components/**
Esto significa que puedes tener varios archivos AGENTS.md en distintos niveles, cada uno proporcionando instrucciones cada vez más específicas para sus respectivos directorios.

​
Mejores prácticas

Para aprovechar al máximo los archivos AGENTS.md:
  • Mantén las instrucciones bien enfocadas: Cada AGENTS.md debe contener instrucciones relevantes para el propósito de su directorio
  • Usa un formato claro: Las viñetas, encabezados y bloques de código hacen que a Cascade le resulte más fácil seguir las instrucciones
  • Sé específico: Los ejemplos concretos y las convenciones explícitas funcionan mejor que las pautas vagas
  • Evita la redundancia: No repitas instrucciones globales en los archivos de subdirectorios; estos las heredan de los directorios padre

​
Pautas de contenido

# 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

​
Comparación con Rules

Si bien tanto AGENTS.md como Rules proporcionan instrucciones a Cascade, tienen propósitos diferentes:
CaracterísticaAGENTS.mdRules
UbicaciónEn los directorios del proyecto.windsurf/rules/ o global
AlcanceAutomático según la ubicación del archivoManual (glob, siempre activo, decisión del modelo, manual)
FormatoMarkdown sin metadatosMarkdown con frontmatter
Mejor paraConvenciones específicas de un directorioAspectos transversales, lógica de activación compleja
Usa AGENTS.md cuando quieras instrucciones simples basadas en la ubicación. Usa Rules cuando necesites más control sobre cuándo y cómo se aplican las instrucciones.