Salt la conținutul principal
Fișierele AGENTS.md oferă o modalitate simplă de a furniza instrucțiuni sensibile la context pentru Cascade, care se aplică automat în funcție de locul în care se află fișierul în proiect. Acest lucru este deosebit de util pentru a specifica ghiduri de scriere a codului specifice unui director, decizii de arhitectură sau convenții ale proiectului.

​
Cum funcționează

Când creați un fișier AGENTS.md (sau agents.md), Windsurf îl detectează automat și îl transmite către același motor de Rules care stă la baza .windsurf/rules/ — doar că modul de activare este dedus în funcție de locația fișierului, în loc să fie definit în frontmatter:
  • Directorul rădăcină: Este tratat ca o regulă mereu activă — întregul conținut este inclus în promptul de sistem al Cascade la fiecare mesaj.
  • Subdirectoare: Sunt tratate ca o regulă glob, cu un tipar generat automat de forma <directory>/** — conținutul este aplicat doar atunci când Cascade citește sau editează fișiere din acel director.
Această delimitare în funcție de locația fișierului face ca AGENTS.md să fie ideal pentru a oferi îndrumări specifice, fără a încărca un singur fișier global de configurare.

​
Crearea unui fișier AGENTS.md

Creați pur și simplu un fișier numit AGENTS.md sau agents.md în directorul dorit. Fișierul folosește markdown simplu, fără să fie necesară vreo secțiune specială de frontmatter.

​
Exemplu de structură

my-project/
├── AGENTS.md                    # Instrucțiuni globale pentru întregul proiect
├── frontend/
│   ├── AGENTS.md                # Instrucțiuni specifice pentru codul frontend
│   └── src/
│       └── components/
│           └── AGENTS.md        # Instrucțiuni specifice pentru componente
├── backend/
│   └── AGENTS.md                # Instrucțiuni specifice pentru codul backend
└── docs/
    └── AGENTS.md                # Instrucțiuni pentru documentație

​
Exemplu de conținut

Iată un exemplu de fișier AGENTS.md pentru un folder de componente React: 
# Ghid pentru Componente

Când lucrați cu componente în acest director:

- Utilizați componente funcționale cu hooks
- Respectați convenția de denumire: ComponentName.tsx pentru componente, useHookName.ts pentru hooks
- Fiecare componentă trebuie să aibă un fișier de test corespunzător: ComponentName.test.tsx
- Utilizați module CSS pentru stilizare: ComponentName.module.css
- Exportați componentele ca export-uri cu nume, nu export-uri implicite

## Structura Fișierelor

Fiecare folder de componentă trebuie să conțină:
- Fișierul principal al componentei
- Un fișier de test
- Un fișier de stiluri (dacă este necesar)
- Un index.ts pentru re-export-uri

​
Descoperire și delimitare

Windsurf descoperă automat fișierele AGENTS.md în întregul workspace:
  • Scanarea workspace-ului: Toate fișierele AGENTS.md din workspace și din subdirectoarele sale sunt detectate
  • Suport pentru repository-uri Git: Pentru repository-urile Git, Windsurf caută și în directoarele părinte până la rădăcina repository-ului Git
  • Ignorarea diferențelor între majuscule și minuscule: Atât AGENTS.md, cât și agents.md sunt recunoscute

​
Delimitare automată

Principalul beneficiu al fișierului AGENTS.md este delimitarea automată pe baza locației fișierului:
Locația fișieruluiDomeniu de aplicare
Rădăcina workspace-uluiSe aplică tuturor fișierelor (activ permanent)
/frontend/Se aplică atunci când lucrați cu fișiere în /frontend/**
/frontend/components/Se aplică atunci când lucrați cu fișiere în /frontend/components/**
Aceasta înseamnă că puteți avea mai multe fișiere AGENTS.md la niveluri diferite, fiecare oferind instrucțiuni din ce în ce mai specifice pentru directoarele respective.

​
Cele mai bune practici

Pentru a profita la maximum de fișierele AGENTS.md:
  • Mențineți instrucțiunile bine focalizate: Fiecare fișier AGENTS.md ar trebui să conțină instrucțiuni relevante pentru scopul directorului său
  • Folosiți o formatare clară: Listele cu marcatori, titlurile și blocurile de cod fac instrucțiunile mai ușor de urmat pentru Cascade
  • Fiți specifici: Exemplele concrete și convențiile explicite funcționează mai bine decât recomandările vagi
  • Evitați redundanța: Nu repetați instrucțiunile globale în fișierele din subdirectoare; acestea sunt moștenite de la directoarele părinte

​
Recomandări pentru conținut

# 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

​
Comparație cu Rules

Deși atât AGENTS.md, cât și Rules oferă instrucțiuni pentru Cascade, ele au scopuri diferite:
CaracteristicăAGENTS.mdRules
LocațieÎn directoarele proiectului.windsurf/rules/ sau global
Domeniu de aplicareAutomat, pe baza locației fișieruluiManual (glob, mereu activ, decizie a modelului, manual)
FormatMarkdown simpluMarkdown cu frontmatter
Cel mai potrivit pentruConvenții specifice directoruluiAspecte transversale, logică de activare complexă
Utilizați AGENTS.md când doriți instrucțiuni simple, bazate pe locație. Utilizați Rules când aveți nevoie de mai mult control asupra momentului și modului în care sunt aplicate instrucțiunile.