Stack-ul pe care îl dau agentului meu AIStack-ul pe care îl dau agentului meu AIStack-ul pe care îl dau agentului meu AI

De fiecare dată când încep un proiect nou cu un agent AI de programare, îi dau același stack. Nu o listă de sugestii. O configurație fixă și obligatorie de la care agentul nu poate devia fără o aprobare explicită. Sună rigid. Este. Și tocmai această rigiditate este punctul central.

Când agentul cunoaște stack-ul de la bun început, încetează să ghicească. Reutilizează pattern-urile deja văzute în aceeași fereastră de context, se bazează pe helper-ele pe care i le-am indicat deja, și produce output care se integrează în restul codebazei fără fricțiune. Când agentul alege stack-ul, petreci primele trei ore dezbătând dacă a ales ORM-ul potrivit.

Stack-ul

Alegerile nu sunt arbitrare. Fiecare a fost făcută după lansarea în producție a cel puțin două proiecte cu ea și decizia că este suficient de bună pentru a nu mai fi reconsiderată. Acesta este criteriul: nu perfectă, suficient de bună pentru a opri reconsiderarea.

• Next.js App Router + TypeScript strict -- server components, server actions, niciun server API separat pentru majoritatea proiectelor
• Tailwind CSS -- doar clase utilitare, fără CSS-in-JS, zero overhead la runtime
• MySQL 8 sau Postgres 16 via Prisma -- Prisma pentru schemă, migrări și client type-safe; MySQL pentru proiectele care îl necesită pe Ploi, Postgres altfel
• Better Auth -- sesiune și OAuth în câteva linii, handler-ul de auth la un singur path fix pe care agentul îl cunoaște deja
• Resend -- email tranzacțional, SDK excelent, nu necesită un server dedicat
• MinIO -- object storage S3-compatibil self-hosted, rulează în Docker Compose local și pe Hetzner în producție
• Redis + BullMQ -- joburi în background cu retry-uri, control al concurenței și un pattern simplu de clasă pentru joburi
• Docker Compose -- o singură comandă pornește baza de date, Redis și MinIO local; aceleași versiuni de imagini în producție
• Ploi + Hetzner -- hosting pe VPS, management server fără efortul de ops, cost previzibil
• Cloudflare -- DNS, CDN, terminare SSL, protecție DDoS în fața a totul

De ce Fix bate Flexibil

Agentul AI este un executor fără stare. Nu poartă opinie, loialitate sau obișnuință de la o sesiune la alta. Cu o tablă goală și o instrucțiune vagă ca "adaugă un job în background", va alege alternativa BullMQ pe care a văzut-o cel mai des în datele sale de antrenament. Ar putea fi o altă abstractizare de fiecare dată. Ar putea introduce un al doilea client Redis. Ar putea intra în conflict cu session store-ul bibliotecii de autentificare.

Un stack fix elimină complet acea clasă de decizii. Agentul nu alege biblioteca pentru cozi. Folosește BullMQ pentru că AGENTS.md spune asta și pentru că clasa de bază pentru joburi există deja în codebase. Decizia a fost luată o dată, este scrisă, și agentul o citește.

AGENTS.md: Codificarea stack-ului ca memorie a agentului

Un agent AI de programare nu are memorie între sesiuni. Agentul care a configurat worker-ul tău BullMQ săptămâna trecută nu știe astăzi că există. Fără un mecanism de persistare a contextului, fiecare nouă sesiune începe de la zero și agentul reinventează pattern-uri pe care le-ai stabilit deja.

Mecanismul este un fișier. Un fișier markdown la rădăcina proiectului, încărcat în contextul agentului la începutul fiecărei sesiuni. Îl numesc AGENTS.md. Nu este documentație pentru oameni (pentru asta există README). Este memoria de lucru a agentului: stack-ul este fix, iată convențiile, iată comenzile, iată pattern-urile explicit interzise.

AGENTS.md este singurul artefact care transformă un LLM fără stare într-un colaborator conștient de proiect. Scrie-l ca și cum ar trebui să supraviețuiască unui reset complet de context între fiecare sesiune, pentru că trebuie.

Mai jos se află secțiunea efectivă de stack pe care o inserez în AGENTS.md al fiecărui proiect nou. Agentul o citește înainte de a atinge orice cod. Înlocuiește alegerea bazei de date (MySQL vs Postgres), menține totul celălalt fix.

# AGENTS.md -- Stack & Conventions for AI Coding Agents

## Stack (fixed, do not substitute without explicit approval)

- Framework : Next.js App Router, TypeScript strict mode
- Styles     : Tailwind CSS utility classes only -- no CSS-in-JS, no plain CSS files
- Database   : MySQL 8 or Postgres 16 via Prisma (schema in prisma/schema.prisma)
- Auth        : Better Auth (src/lib/auth.ts) -- do NOT roll a custom session system
- Email       : Resend SDK (src/lib/email.ts) -- transactional only, no bulk marketing
- Object store: MinIO, S3-compatible (src/lib/storage.ts)
- Queues      : BullMQ backed by Redis (src/queues/) -- background jobs only
- Environment : Docker Compose (docker-compose.yml at repo root) -- run locally with:
    docker compose up -d
- Hosting     : Ploi on Hetzner CX21+, Cloudflare in front (proxied, SSL full-strict)

## House conventions

- All server actions in src/app/actions/ -- never in route handlers or components
- API routes under src/app/api/v1/ return { data, error } -- use ApiResponse type
- BullMQ jobs extend BaseJob (src/queues/base-job.ts) -- no bare Queue instantiation
- File naming : kebab-case files, PascalCase components, camelCase utils
- No any in TypeScript -- use unknown and narrow explicitly
- No console.log in committed code -- use src/lib/logger.ts

## Commands

    npx prisma migrate dev   # apply local migrations
    npx prisma generate      # regenerate client after schema change
    docker compose up -d     # start MySQL/Postgres, Redis, MinIO
    npm run dev              # Next.js dev server
    npm run typecheck        # tsc --noEmit
    npm run lint             # ESLint + Prettier check

## Known gotchas

- Better Auth requires the auth handler at src/app/api/auth/[...all]/route.ts exactly
- MinIO presigned URLs expire in 1 h by default -- adjust in src/lib/storage.ts
- BullMQ concurrency defaults to 1 per worker -- set explicitly for each queue
- Prisma Client is a singleton -- import from src/lib/prisma.ts, never instantiate inline

Trei lucruri fac acest fișier eficient. În primul rând, este prescriptiv: "do NOT roll a custom session system" nu este o sugestie. În al doilea rând, numește calea exactă a fișierului pentru fiecare abstractizare (src/lib/auth.ts, src/lib/prisma.ts). Agentul nu trebuie să caute. În al treilea rând, listează capcanele: cele pe care le-ai descoperit pe calea grea astfel încât agentul să nu trebuiască să le redescopere.

Mediul local într-o singură comandă

Docker Compose face parte din stack dintr-un motiv specific: face mediul local un artefact de prim rang despre care agentul poate raționa. Când agentul citește AGENTS.md și vede că docker compose up -d pornește MySQL, Redis și MinIO, știe exact ce să îți spună când ceva nu funcționează. Nu trebuie să ghicească dacă ai o instalație MySQL locală sau o bază de date cloud în dezvoltare.

# docker-compose.yml (excerpt -- services the agent can rely on)
services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: 'root'
      MYSQL_DATABASE: 'app'
    ports:
      - '3306:3306'
    volumes:
      - db_data:/var/lib/mysql

  redis:
    image: redis:7-alpine
    ports:
      - '6379:6379'

  minio:
    image: minio/minio
    command: server /data --console-address ':9001'
    environment:
      MINIO_ROOT_USER: 'minio'
      MINIO_ROOT_PASSWORD: 'minio123'
    ports:
      - '9000:9000'
      - '9001:9001'
    volumes:
      - minio_data:/data

volumes:
  db_data:
  minio_data:

Aceleași versiuni de imagini rulează local și în producție pe Hetzner. Agentul cunoaște string-urile de conexiune din variabilele de mediu despre care i s-a spus să le aștepte. Nu există nicio suprafață de "funcționează doar pe mașina mea".

Familiaritate acumulată între proiecte

Adevăratul câștig nu este primul proiect. Este al cincilea. Până când ai folosit acest stack de cinci ori, AGENTS.md este rafinat. Secțiunea de capcane a prins bug-uri reale. Secțiunea de pattern-uri interzise a prevenit cel puțin două greșeli arhitecturale. Clasa de bază pentru joburi a fost extrasă într-un template partajat pe care îl poți clona.

Fiecare proiect nou moștenește disciplina acumulată a celor anterioare. Agentul vine în ziua unu deja familiarizat cu pattern-urile care ți-au luat două proiecte să le stabilești. Nu este magie. Este pur și simplu documentație care este de fapt citită.

• Începe fiecare proiect clonând template-ul AGENTS.md și ajustând alegerea bazei de date.
• Actualizează AGENTS.md ori de câte ori adaugi o nouă abstractizare, interzici un pattern sau dai de o capcană.
• Tratează-l ca pe o specificație vie: când codebase-ul se schimbă, AGENTS.md se schimbă primul.
• Încarcă-l explicit la începutul fiecărei sesiuni cu agentul -- nu presupune că agentul îl va găsi singur.

Și review-ul devine mai rapid

Un beneficiu secundar care merită menționat: code review-ul devine mai rapid când cunoști stack-ul. Nu evaluezi dacă agentul a ales o bibliotecă rezonabilă. Evaluezi doar dacă a folosit corect biblioteca agreată. Aceasta este o întrebare mult mai îngustă, și se acumulează și ea: cu cât folosești mai mult stack-ul, cu atât mai repede detectezi o deviație.

Teza este simplă: un stack fix este un multiplicator de forță pentru dezvoltarea asistată de AI. Agentul cunoaște uneltele, tu cunoști uneltele, AGENTS.md face puntea între sesiuni. Încetezi să dezbați infrastructura și începi să livrezi funcționalități. Acesta este întregul punct.