Reguli Cursor: Cum să scrii fișiere .cursor/rules care funcționează cu adevărat

Reguli Cursor: Cum să scrii fișiere .cursor/rules care funcționează cu adevărat

Fiecare utilizator Cursor se lovește de același obstacol. AI-ul generează cod care funcționează din punct de vedere tehnic, dar ignoră convențiile proiectului tău, folosește căi de import greșite, modele învechite și componente structurate complet diferit față de restul bazei de cod. Regulile Cursor remediază această problemă oferind AI-ului un context persistent despre modul în care funcționează proiectul tău.

Ce sunt Regulile Cursor și de ce contează?

Regulile Cursor sunt fișiere markdown care acționează ca un prompt de sistem permanent, injectat înainte de fiecare interacțiune cu AI-ul: chat, autocompletare, generare de cod, totul. Gândește-te la ele ca la documentație de onboarding pentru AI. În loc să corectezi aceleași greșeli la fiecare sesiune, scrii instrucțiunea o singură dată și aceasta rămâne valabilă.

Vechea abordare consta într-un singur fișier .cursorrules în rădăcina proiectului. Aceasta încă funcționează, dar este depreciată. Sistemul actual utilizează un director .cursor/rules/ cu fișiere individuale .mdc (Markdown Cursor), fiecare fiind delimitat pentru situații specifice. Aceasta este o configurare mult mai bună deoarece nu înghesui toate instrucțiunile într-un singur fișier uriaș; împarți regulile în funcție de responsabilitate, iar Cursor încarcă doar pe cele relevante pentru ceea ce faci în acel moment.

Dacă ai lucrat cu ingineria contextului pentru instrumente AI, conceptul îți este familiar: un context de intrare mai bun produce rezultate semnificativ mai bune. Regulile reprezintă ingineria contextului pentru întregul flux de lucru de dezvoltare.

Configurarea primului tău fișier de reguli

Creează directorul .cursor/rules/ în rădăcina proiectului tău:

mkdir -p .cursor/rules

Fiecare regulă este un fișier .mdc cu frontmatter YAML urmat de conținut markdown. Iată scheletul:

---
description: "When this rule should apply"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Your instructions go here in plain markdown.

Trei câmpuri din frontmatter controlează totul:

Poți crea reguli și direct prin Cursor: tastează /create-rule în chat și descrie ceea ce dorești. Totuși, scrierea lor manual îți oferă un control mai mare.

Cele patru tipuri de reguli explicate

Modul în care o regulă se activează depinde de configurația sa din frontmatter. Există patru moduri, iar alegerea celui potrivit contează pentru bugetul ferestrei de context.

Always Apply (Aplică întotdeauna)

---
alwaysApply: true
---

Încărcat în fiecare singură cerere către AI. Folosește-l cu prudență, pentru fundamentalele la nivel de proiect, precum declararea stivei tehnologice sau convențiile critice care se aplică peste tot. Fiecare regulă mereu activă consumă tokeni din fiecare interacțiune, indiferent dacă este relevantă sau nu.

Auto-Attached (Bazat pe Glob)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

Se activează doar atunci când editezi fișiere care corespund modelelor glob. Acesta este tipul de regulă „cal de povară”. Convențiile tale pentru componentele React se încarcă atunci când ești în fișiere de componente, modelele tale API se încarcă atunci când ești în handler-e de rute, iar regulile de testare se încarcă atunci când scrii teste.

Agent-Requested (Inteligent)

---
description: "Database migration patterns using Drizzle ORM"
alwaysApply: false
---

Fără globs, fără always-apply, doar o descriere. Agentul Cursor citește descrierea și decide dacă regula este relevantă pentru sarcina curentă. Dacă îi ceri să scrie o migrare, va prelua această regulă. Dacă formatezi un buton, o va omite. Acest lucru funcționează surprinzător de bine pentru reguli care nu se mapază clar pe căile fișierelor.

Manual

---
---

Niciun câmp din frontmatter setat (sau frontmatter gol). Aceste reguli se activează doar atunci când le menționezi explicit cu @nume-regula în chat. Sunt bune pentru instrucțiuni rare, dar importante, cum ar fi listele de verificare pentru deploy sau ghidurile de refactorizare de care ai nevoie doar ocazional.

Modele Glob care funcționează cu adevărat

Globs determină care fișiere declanșează regulile auto-atașate. Dacă le greșești, regulile fie nu se declanșează niciodată, fie se declanșează peste tot. Iată ce funcționează:

# All TypeScript files in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Only component files
globs: ["**/components/**/*.tsx"]

# Python files, excluding tests
globs: ["**/*.py", "!**/test_*.py"]

# Multiple specific directories
globs: ["src/api/**", "src/services/**"]

Câteva capcane din utilizarea reală:

• src/* se potrivește doar cu un singur nivel de director. Aproape întotdeauna vei dori src/**/* pentru potrivire recursivă.
• *.js nu se va potrivi cu fișierele .jsx sau .ts. Fii explicit cu extensiile.
• Globs trebuie să fie o listă YAML. Sintaxa cu acolade, precum {src,lib}/**/*.ts, poate eșua silențios; rămâi la intrări separate în listă.
• Prefixul ! exclude modele, ceea ce este util pentru ignorarea fișierelor generate sau a codului legacy.

Exemple practice de reguli

Aici teoria întâlnește realitatea. Acestea sunt reguli pe care le poți introduce într-un proiect și vei vedea imediat o îmbunătățire a output-ului AI.

Regulă de bază la nivel de proiect (Always Apply)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

Păstrează acest lucru sub 30 de linii. Este încărcat cu fiecare cerere, așa că fiecare cuvânt costă tokeni.

Regulă pentru componente React (Auto-Attached)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Fetch direct în componentă, fără useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Regulă API Python (Auto-Attached)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Regulă serviciu Go (Auto-Attached)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## Gestionarea „taxei” de tokeni

Iată ceva pe care majoritatea ghidurilor Cursor îl omit: fiecare regulă pe care o scrii costă tokeni. Un proiect cu 20 de reguli mereu active ar putea consuma **peste 2.000 de tokeni per cerere** doar pentru instrucțiuni, înainte ca AI-ul să se uite măcar la codul tău.

Acest aspect contează deoarece contextul chat-ului Cursor este de aproximativ 20.000 de tokeni în modul standard. Dacă regulile tale consumă 25% din acest total, ai pierdut un sfert din „spațiul de gândire” al AI-ului pentru întrebarea ta reală. Vei observa o calitate mai slabă a output-ului pe măsură ce regulile se acumulează, în special în conversațiile mai lungi.

Trei principii mențin sănătoasă bugetul de tokeni:

**1. Folosește agresiv regulile auto-atașate și cele solicitate de agent.** Doar declararea stivei tehnologice a proiectului ar trebui să fie mereu activă. Restul ar trebui să se încarce condiționat. Acea regulă pentru componente React? Nu trebuie să fie în context atunci când scrii migrări SQL.

**2. Scrie dens, nu verbose.** Înlocuiește „Se recomandă puternic ca dezvoltatorii să folosească interfețe TypeScript în locul aliasurilor de tip atunci când definesc contractele API publice” cu „Preferă `interface` în locul `type` pentru API-urile publice.” AI-ul nu are nevoie de persuasiune, are nevoie de instrucțiuni.

**3. Aplică Regula celor Trei.** Codifică un model ca regulă doar după ce AI-ul greșește de trei ori. Dacă Cursor gestionează deja corect convențiile tale de denumire fără o regulă, sare peste regulă. Fiecare regulă inutilă este context risipit.

Poți monitoriza utilizarea tokenilor în bara de stare din partea de jos a panoului de chat Cursor. Uită-te când se apropie de 100%; acesta este semnalul tău să elimini regulile inutile.

## Organizarea regulilor pentru un proiect real

Un proiect de producție necesită de obicei 5-8 fișiere de reguli. Iată o structură care funcționează bine:

```text
.cursor/rules/
  base.mdc            # Tech stack, always-apply (< 30 lines)
  components.mdc      # React/Vue patterns, glob to component dirs
  api.mdc             # Backend conventions, glob to API dirs
  database.mdc        # ORM patterns, glob to models/migrations
  testing.mdc         # Test conventions, glob to test files
  deployment.mdc      # CI/CD patterns, manual trigger
  personal.mdc        # Your preferences (gitignored)

Fă commit la totul în controlul versiunilor, cu excepția personal.mdc. Astfel, întreaga echipă beneficiază de același comportament AI, ceea ce este scopul principal. După cum spune un utilizator din forumul Cursor, regulile bune înseamnă că „accepti mai multe sugestii așa cum sunt, cu output care se potrivește convențiilor tale din prima încercare.”

Dacă lucrezi cu alte instrumente de codare AI alături de Cursor, conceptele se transferă direct. Claude Code folosește CLAUDE.md, GitHub Copilot are fișiere de instrucțiuni, iar Windsurf are propriul format, dar principiul de bază este identic.

Cum funcționează precedența regulilor

Când mai multe reguli se aplică aceluiași fișier, Cursor urmează o ierarhie clară:

Regulile de echipă sunt disponibile în planurile Team și Enterprise. Acestea sunt setate în dashboard-ul Cursor de către administratori și aplicate în întreaga organizație; dezvoltatorii individuali nu le pot dezactiva.

În cadrul regulilor de proiect, dacă două reguli se aplică aceluiași fișier și intră în conflict, comportamentul nu este strict definit. În practică, regulile încărcate mai târziu tind să aibă prioritate. Numerotarea fișierelor (001-base.mdc, 002-components.mdc) îți oferă o ordonare predictibilă.

Greșeli comune și cum să le repari

După ce am citit zeci de discuții din comunitate și am testat reguli în diverse proiecte, acestea sunt greșelile care îi blochează cel mai des pe oameni:

Scrierea unor reguli prea vagi. „Scrie cod curat” nu îi spune AI-ului nimic. „Folosește exporturi numite, nu exporturi default. Structurează componentele astfel: importuri, tipuri, funcție, sub-componente” îi oferă ceva concret de executat.

Setarea tuturor regulilor pe always-apply. Primul impuls este să setezi alwaysApply: true pentru fiecare regulă. Rezistă impulsului. Auditează-ți regulile trimestrial; dacă ai mai mult de 2-3 reguli mereu active, probabil risipești tokeni.

Uitarea de a testa regulile. După scrierea unei reguli, deschide un fișier relevant și cere-i Cursor să genereze ceva care ar trebui să urmeze regula. Dacă nu o face, modelul glob ar putea fi greșit, sau instrucțiunea nu este suficient de clară.

Nedocumentarea anti-pattern-urilor. A-i spune AI-ului ce să facă este jumătate din treabă. A-i spune ce să nu facă este cealaltă jumătate. Include o secțiune „NU face aceste lucruri” în fiecare regulă, cu exemple explicite ale abordării greșite.

Ignorarea salvării regulilor în UI. O eroare cunoscută face ca editările regulilor să dispară. Dacă modificările dispar, închide complet Cursor, selectează „Override” (Suprascrie) în popup-ul pentru modificările nesalvate și redeschide aplicația.

Reguli Cursor vs CLAUDE.md vs AGENTS.md

Cursor nu este singurul instrument care folosește fișiere de instrucțiuni. Iată cum se compară formatele pentru cei care lucrează cu mai mulți asistenți de codare AI:

Avantajul Cursor este granularitatea. CLAUDE.md și AGENTS.md sunt mai simple, ele încarcă totul mereu. Cursor îți permite să încarci regulile potrivite la momentul potrivit, ceea contează odată ce setul de instrucțiuni depășește câteva sute de linii.

Pentru o privire mai profundă asupra modului în care contextul modelează output-ul AI în aceste instrumente, ghidul nostru de inginerie a contextului detaliază principiile care se aplică indiferent de editorul pe care îl folosești.

Întrebări frecvente (FAQ)

Este .cursorrules depreciat?

Da. Singurul fișier .cursorrules din rădăcina proiectului încă funcționează, dar Cursor recomandă migrarea către fișiere .cursor/rules/*.mdc. Noul format suportă modele glob, încărcare condiționată și o organizare mai bună. Migrează prin împărțirea fișierului monolitic în reguli focalizate.

Ce extensie de fișier ar trebui să folosesc, .mdc sau .md?

Folosește .mdc pentru fișierele care includ frontmatter YAML (descriere, globs, alwaysApply). Fișierele plain .md funcționează și ele în directorul de reguli, dar nu suportă metadatele frontmatter care permit încărcarea condiționată.

Câte reguli ar trebui să aibă un proiect?

Cinci până la opt este numărul ideal pentru majoritatea proiectelor. O regulă de bază mereu activă, trei până la patru reguli auto-atașate delimitate pe tip de fișier și una sau două reguli manuale pentru sarcini speciale. Mai mult de 10 reguli înseamnă de obicei că unele pot fi consolidate sau eliminate.

Regulile Cursor afectează autocompletarea și completarea cu Tab?

Regulile se aplică interacțiunilor de chat și agent. Regulile Utilizator nu se aplică editărilor inline (Cmd/Ctrl+K), iar regulile generally nu impactează sugestiile de autocompletare Cursor Tab. Ele sunt cele mai eficiente în sesiunile de chat și Composer.

Pot partaja reguli între mai multe proiecte?

Da, prin funcția Remote Rules din Cursor. Mergi la Cursor Settings > Rules, Commands, selectează „Remote Rule (GitHub)” și lipește URL-ul unui repository. Regulile se sincronizează automat când sursa repo se actualizează. Alternativ, menține un repo comun de reguli și creează symlink-uri în fiecare proiect.

Care este lungimea maximă recomandată a unei reguli?

Documentația Cursor sugerează păstrarea regulilor individuale sub 500 de linii. În practică, țintește sub 100 de linii per regulă. Regulile mai scurte sunt mai ușor de întreținut și costă mai puțini tokeni. Dacă o regulă depășește 150 de linii, împarte-o în două reguli focalizate.

Regulile funcționează cu toate modelele AI din Cursor?

Regulile funcționează cu fiecare model suportat de Cursor: Claude, GPT-4o, Gemini și altele. Regulile sunt injectate ca context la nivel de sistem, indiferent de modelul selectat. Comportamentul modelului poate varia, dar regulile în sine sunt agnostice față de model.

Cum depanez o regulă care nu funcționează?

Mai întâi, verifică dacă modelul glob se potrivește cu fișierul tău; deschide fișierul și verifică dacă regula apare în panoul de context. În al doilea rând, testează cu o întrebare directă care ar trebui să declanșeze regula. În al treilea rând, încearcă să setezi temporar alwaysApply: true pentru a confirma că conținutul regulii funcționează. Dacă da, problema este modelul glob.

Ar trebui să fac commit la .cursor/rules în git?

Absolut. Scopul regulilor de proiect este consistența la nivel de echipă. Fă commit la totul din .cursor/rules/, cu excepția fișierelor de preferințe personale. Adaugă personal.mdc în .gitignore pentru setările individuale care nu ar trebui să se aplice tuturor.

Pot folosi regulile Cursor alături de servere MCP?

Da, și se completează reciproc foarte bine. Regulile definesc cum ar trebui AI-ul să scrie cod, în timp ce serverele MCP oferă AI-ului acces la instrumente externe și date. O regulă ar putea spune „folosește întotdeauna clientul nostru intern API”, în timp ce un server MCP permite AI-ului să interogheze efectiv acel API în timpul dezvoltării.

Dacă funcțiile AI sunt în planurile tale, aceasta este specialitatea noastră: echipa de integrare AI Techsy transformă sistemele LLM din prototip în producție. Dorești o a doua opinie despre stiva ta tehnologică? Obține o consultație gratuită.

Surse

• Documentația Reguli Cursor
• Trigger.dev, Cum să scrii Reguli Cursor excelente
• Forum Cursor, Cele mai bune practici și depanare Reguli MDC
• Peakvance, Ghid pentru Reguli Cursor: Taxa de Tokeni
• awesome-cursor-rules-mdc pe GitHub