Lucrul cu Agenți AI de Programare — Ghid Practic (2026)

Nivel 1 (Impact ridicat — Include întotdeauna)

• Prezentare generală a proiectului — stack tehnic, versiuni, scop
• Comenzi — build, test, lint, deploy (exact, copy-paste)
• Stil de cod și convenții — formatare, naming, pattern-uri
• Standarde de logging — niveluri, format, ce se loghează

Nivel 2 (Impact mediu)

• Indicatoare de arhitectură — structura folderelor, responsabilități module
• Reguli de tipul «Fă» și «Nu face» — cele mai frecvente greșeli ale agentului
• Cerințe de testare — framework, acoperire minimă, convenții

Nivel 3 (Randament descrescător)

• Ghid PR/Commit — format, convenții de mesaje
• Note de securitate — informații sensibile, practici de evitat
• Instrucțiuni de persoană — ton, nivel de detaliu

Stratul Enforce — Hooks și porți CI

Deterministice. Comenzi shell care se execută la puncte specifice din ciclul de viață. Agentul nu le poate ocoli. Exit code 2 = blocat, fără negociere.

• Folosește pentru: formatare, linting, execuție teste, scanare de securitate, blocare scrieri în fișiere sensibile

Stratul Advise — Fișiere de configurare (AGENTS.md / CLAUDE.md)

Consultative. Agentul le citește și le urmează de cele mai multe ori, dar sub presiune de context sau semnale conflictuale, poate devia.

• Folosește pentru: stil de cod, ghid de arhitectură, pattern-uri de logging, convenții de denumire

Stratul Suggest — Instrucțiuni în prompt

Efemere. Instrucțiuni contextuale în prompt-ul tău. Prioritate maximă pentru task-ul curent, dar dispar la următoarea sesiune.

• Folosește pentru: cerințe punctuale, constrângeri specifice task-ului

Pattern-ul de logging în cinci părți

Fiecare operație semnificativă ar trebui să producă un traseu structurat de log-uri care urmează aceste cinci componente:

# 1. HEADER DE RULARE — Ce pornește, cu ce parametri
logger.info("=== Început procesare cereri ===")
logger.info(f"  Mediu: {env}")
logger.info(f"  Fișier intrare: {input_file}")
logger.info(f"  Total înregistrări: {total}")

# 2. PROGRES LOT — Vizibilitate la nivel de lot
for i, batch in enumerate(batches):
    logger.info(f"  Lot {i+1}/{len(batches)}: procesare {len(batch)} elemente...")

# 3. DELIMITATOARE ELEMENT — Fiecare element semnificativ se loghează
for item in batch:
    logger.info(f"    [{item.id}] Procesare: {item.name}")
    # ... logică
    logger.info(f"    [{item.id}] Finalizat: status={result.status}")

# 4. IEȘIRE CONSOLĂ — Rezumat vizibil pentru om
print(f"\n✓ Procesate {success}/{total} cereri ({elapsed:.1f}s)")

# 5. REZUMAT RULARE — Totaluri finale structurate
logger.info("=== Rezumat rulare ===")
logger.info(f"  Reușite: {success}")
logger.info(f"  Eșuate: {failed}")
logger.info(f"  Durată: {elapsed:.1f}s")

Calitatea mesajelor de log

Mesajele de log opace sunt la fel de inutile ca lipsa totală a log-urilor. Compară:

Când să folosești logging JSON structurat în schimb

Logging-ul structurat JSON este cel mai potrivit atunci când log-urile sunt consumate de mașini (agregatori, alerte, dashboards). Pentru script-uri și tool-uri CLI, log-urile text lizibile de om sunt de obicei mai practice. Folosește logging JSON structurat când: operezi microservicii cu agregare centralizată de log-uri, ai nevoie de câmpuri de căutare consistente în mai multe servicii, sau cerințele de conformitate impun formate de log auditabile.

Comenzi utile pentru analiza log-urilor

# Găsește toate eșecurile dintr-o rulare
grep "EȘEC\|ERROR\|Eșuate" app.log

# Numără elementele procesate
grep -c "Procesare:" app.log

# Extrage rezumatele de rulare
grep -A 5 "Rezumat rulare" app.log

# Urmărește progresul în timp real
tail -f app.log | grep "Lot"

Exemplu: Auto-formatare după fiecare editare

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write|edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Exemplu: Blocare scrieri în fișiere sensibile

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "write|edit",
        "command": "echo $CLAUDE_FILE_PATH | grep -qE '\\.(env|pem|key)$' && exit 2 || exit 0"
      }
    ]
  }
}

Funcționează cu adevărat

Are nuanțe

Supraevaluat

Pasul 1: Creează AGENTS.md (30 min)

Pornește cu un template minimal și adaugă pe măsură ce descoperi ce lipsește. Un fișier de 40 de linii care acoperă comenzile, stilul de cod și logging-ul valorează mai mult decât un manifest de 300 de linii pe care agentul îl ignoră pe jumătate.

# AGENTS.md

## Prezentare proiect
- Stack: Next.js 16, TypeScript, Tailwind CSS v4, Sanity CMS
- Manager pachete: pnpm
- Node: >=20

## Comenzi
```bash
pnpm dev          # Server de dezvoltare
pnpm build        # Build producție
pnpm lint         # ESLint
pnpm test         # Vitest
```

## Stil de cod
- Formatare: prettier (se aplică la salvare)
- Imports: absolute cu alias @/
- Componente: funcționale, cu TypeScript strict
- Naming: camelCase variabile, PascalCase componente, kebab-case fișiere

## Standarde de logging
- Folosește console.error() pentru eșecuri cu context
- Fiecare funcție async are try/catch cu mesaje descriptive de eroare
- Header de rulare la intrarea în operații batch
- Include întotdeauna: ce element, ce operație, ce rezultat

## Reguli
- NU edita .env, .env.local sau fișiere .pem
- NU folosi `any` în TypeScript
- NU adăuga dependențe fără aprobare explicită
- RULEAZĂ întotdeauna pnpm lint înainte de a considera un task complet

Pasul 2: Configurează symlink-uri (5 min)

Creează symlink-uri de la AGENTS.md către fișierele specifice fiecărui instrument:

# Din rădăcina proiectului
ln -sf AGENTS.md CLAUDE.md
ln -sf AGENTS.md .windsurfrules
mkdir -p .github
ln -sf ../AGENTS.md .github/copilot-instructions.md

# Adaugă în .gitignore dacă nu vrei symlink-urile în repo
echo "CLAUDE.md" >> .gitignore
echo ".windsurfrules" >> .gitignore

Pasul 3: Adaugă hooks pentru reguli critice (15 min)

Configurează hooks în Claude Code pentru a garanta regulile care nu pot fi încălcate:

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write|edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "write|edit",
        "command": "echo $CLAUDE_FILE_PATH | grep -qE '\\.(env|pem|key)$' && exit 2 || exit 0"
      }
    ],
    "Stop": [
      {
        "command": "pnpm lint --quiet 2>&1 | tail -20"
      }
    ]
  }
}

Pasul 4: Adaugă reguli glob Cursor (opțional, 15 min)

Cursor suportă activare automată bazată pe glob, unde regulile se aplică doar fișierelor care corespund unui pattern:

---
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

# Reguli TypeScript

- Strict mode activat, fără `any`
- Exportă tipuri explicit
- Folosește pattern-uri zod pentru validare

Pasul 5: Tratează-l ca pe cod (continuu)

AGENTS.md are aceleași probleme de mentenanță ca orice documentație. Fără întreținere activă, regulile devin depășite și derutante.

• Versionează AGENTS.md în Git
• Revizuiește modificările în code review
• Curăță trimestrial: elimină regulile depășite
• Testează: după modificări, rulează o sesiune agent și verifică dacă urmează noile reguli
• Menține sub 150 de linii — dacă depășește, prioritizează

Observabilitatea codului generat

Logging adecvat, tratarea erorilor, metrici — exact ce acoperă Secțiunea 7. Aceasta este prioritatea pentru majoritatea echipelor care folosesc agenți de programare pentru a scrie cod de aplicație.

Observabilitatea agentului însuși

Trasarea raționamentului, urmărirea consumului de token-uri, evaluarea calității output-ului — instrumente precum LangSmith, Langfuse etc. Acest lucru devine relevant doar dacă construiești aplicații bazate pe LLM (chatboți, pipeline-uri RAG, workflow-uri autonome).

FĂ ACESTE ȘASE LUCRURI

• Creează un AGENTS.md în rădăcina fiecărui proiect activ (sub 150 de linii, concentrează-te pe comenzi, stil de cod, logging).
• Configurează symlink-uri către CLAUDE.md, .windsurfrules etc.
• Adaugă standarde de logging din Secțiunea 7.
• Adaugă hooks pentru tot ce trebuie să fie determinist.
• Delegă către instrumentele existente — lintere, formatoare, verificatoare de tipuri sunt surse unice de adevăr.
• Tratează AGENTS.md ca pe cod: versionează-l, revizuiește-l, curăță-l trimestrial.

OMITE DEOCAMDATĂ

• Ierarhii complexe de reguli pe mai multe fișiere
• Platforme de observabilitate pentru agenți (cu excepția cazului în care construiești sisteme de producție bazate pe LLM)
• Etichete simple de persoană
• Documentație detaliată a căilor de fișiere