Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt

Use this file to discover all available pages before exploring further.

I file AGENTS.md offrono un modo semplice per fornire a Cascade istruzioni contestuali che si applicano automaticamente in base alla posizione del file nel progetto. Questo è particolarmente utile per definire linee guida di codice specifiche per directory, decisioni architetturali o convenzioni di progetto.

Come funziona

Quando crei un file AGENTS.md (o agents.md), Devin Desktop lo rileva automaticamente e lo passa allo stesso motore di Regole che usa .windsurf/rules/ — ma con la modalità di attivazione dedotta dalla posizione del file anziché dal frontmatter:
  • Directory radice: viene trattata come una regola sempre attiva — l’intero contenuto è incluso nel prompt di sistema di Cascade in ogni messaggio.
  • Sottodirectory: vengono trattate come una regola glob con un pattern generato automaticamente del tipo <directory>/** — il contenuto viene applicato solo quando Cascade legge o modifica file all’interno di quella directory.
Questa definizione dell’ambito basata sulla posizione rende AGENTS.md ideale per fornire indicazioni mirate senza appesantire un unico file di configurazione globale.

Creare un file AGENTS.md

Ti basta creare un file chiamato AGENTS.md o agents.md nella directory desiderata. Il file usa markdown semplice e non richiede alcun frontmatter speciale.

Struttura di esempio

my-project/
├── AGENTS.md                    # Istruzioni globali per l'intero progetto
├── frontend/
│   ├── AGENTS.md                # Istruzioni specifiche per il codice frontend
│   └── src/
│       └── components/
│           └── AGENTS.md        # Istruzioni specifiche per i componenti
├── backend/
│   └── AGENTS.md                # Istruzioni specifiche per il codice backend
└── docs/
    └── AGENTS.md                # Istruzioni per la documentazione

Contenuto di esempio

Ecco un esempio di file AGENTS.md per una directory di componenti 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

Rilevamento e definizione dell’ambito

Devin Desktop rileva automaticamente i file AGENTS.md in tutto il tuo workspace:
  • Scansione del workspace: vengono rilevati tutti i file AGENTS.md presenti nel tuo workspace e nelle relative sottodirectory
  • Supporto per i repository Git: per i repository Git, Devin Desktop cerca anche nelle directory padre fino alla radice del repository
  • Senza distinzione tra maiuscole e minuscole: vengono riconosciuti sia AGENTS.md che agents.md

Definizione automatica dell’ambito

Il vantaggio principale di AGENTS.md è la definizione automatica dell’ambito in base alla posizione del file:
File LocationScope
Radice del workspaceSi applica a tutti i file (sempre attivo)
/frontend/Si applica quando si lavora con file in /frontend/**
/frontend/components/Si applica quando si lavora con file in /frontend/components/**
Ciò significa che puoi avere più file AGENTS.md a diversi livelli, ciascuno con indicazioni sempre più specifiche per la directory corrispondente.

Best practice

Per ottenere il massimo dai file AGENTS.md:
  • Mantieni le istruzioni mirate: ogni AGENTS.md dovrebbe contenere istruzioni pertinenti allo scopo della directory corrispondente
  • Usa una formattazione chiara: elenchi puntati, intestazioni e blocchi di codice rendono le istruzioni più facili da seguire per Cascade
  • Sii specifico: esempi concreti e convenzioni esplicite funzionano meglio di linee guida vaghe
  • Evita le ridondanze: non ripetere le istruzioni globali nei file delle sottodirectory; vengono ereditate dalle directory padre

Linee guida per i contenuti

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

# Esempio Meno Efficace
- Write good code
- Be careful with errors
- Use best practices

Confronto con le Regole

Sebbene sia AGENTS.md sia Regole forniscano istruzioni a Cascade, hanno scopi diversi:
FunzionalitàAGENTS.mdRegole
PosizioneNelle directory del progetto.windsurf/rules/ o globale
Definizione dell’ambitoAutomatico in base alla posizione del fileManuale (glob, sempre attivo, decisione del modello, manuale)
FormatoMarkdown sempliceMarkdown con frontmatter
Ideale perConvenzioni specifiche della directoryEsigenze trasversali, logica di attivazione complessa
Usa AGENTS.md quando vuoi istruzioni semplici basate sulla posizione. Usa le Regole quando ti serve un maggiore controllo su quando e come vengono applicate le istruzioni.