Lo Stack che Consegno al Mio Agente AILo Stack che Consegno al Mio Agente AILo Stack che Consegno al Mio Agente AI

Ogni volta che inizio un nuovo progetto con un agente AI, gli consegno lo stesso stack. Non una lista di suggerimenti. Una configurazione fissa e obbligatoria da cui l'agente non può deviare senza un'approvazione esplicita. Sembra rigido. Lo è. E questa rigidità è esattamente il punto.

Quando l'agente conosce lo stack fin dall'inizio, smette di fare ipotesi. Riutilizza i pattern che ha già visto nella stessa finestra di contesto, si affida agli helper che gli ho già indicato, e produce output che si inserisce nel resto del codebase senza attrito. Quando l'agente può scegliere lo stack, passi le prime tre ore a discutere se ha scelto l'ORM giusto.

Lo Stack

Le scelte non sono arbitrarie. Ognuna è stata fatta dopo aver messo in produzione almeno due progetti con essa e aver deciso che era abbastanza buona da smettere di riconsiderarla. Questo è il criterio: non perfetta, abbastanza buona da smettere di riconsiderarla.

• Next.js App Router + TypeScript strict -- server components, server actions, nessun server API separato per la maggior parte dei progetti
• Tailwind CSS -- solo classi di utilità, nessun CSS-in-JS, zero overhead a runtime
• MySQL 8 o Postgres 16 via Prisma -- Prisma per lo schema, le migrazioni e il client type-safe; MySQL per i progetti che ne hanno bisogno su Ploi, Postgres negli altri casi
• Better Auth -- sessione e OAuth in poche righe, l'handler auth in un unico percorso fisso che l'agente già conosce
• Resend -- email transazionali, SDK eccellente, non richiede un server dedicato
• MinIO -- object storage S3-compatibile self-hosted, gira in Docker Compose in locale e su Hetzner in produzione
• Redis + BullMQ -- job in background con retry, controllo della concorrenza e un semplice pattern di classe per i job
• Docker Compose -- un solo comando avvia database, Redis e MinIO in locale; stesse versioni delle immagini in produzione
• Ploi + Hetzner -- hosting su VPS, gestione del server senza il peso delle operazioni, costo prevedibile
• Cloudflare -- DNS, CDN, terminazione SSL, protezione DDoS davanti a tutto

Perché il Fisso Batte il Flessibile

L'agente AI è un esecutore stateless. Non porta opinioni, preferenze o abitudini da una sessione all'altra. Con una lavagna bianca e un'istruzione vaga come "aggiungi un job in background", sceglierà l'alternativa a BullMQ che ha visto più spesso nei suoi dati di addestramento. Potrebbe essere una diversa astrazione ogni volta. Potrebbe introdurre un secondo client Redis. Potrebbe conflittuare con il session store della libreria di autenticazione.

Uno stack fisso elimina completamente quella classe di decisioni. L'agente non sceglie la libreria per le code. Usa BullMQ perché l'AGENTS.md lo indica e perché la classe base per i job esiste già nel codebase. La decisione è stata presa una volta, è scritta, e l'agente la legge.

L'AGENTS.md: Codificare lo Stack come Memoria dell'Agente

Un agente AI non ha memoria tra le sessioni. L'agente che ha configurato il tuo worker BullMQ la settimana scorsa oggi non sa che esiste. Senza un meccanismo per persistere il contesto, ogni nuova sessione parte da zero e l'agente reinventa pattern che hai già stabilito.

Il meccanismo è un file. Un file markdown alla radice del progetto, caricato nel contesto dell'agente all'inizio di ogni sessione. Lo chiamo AGENTS.md. Non è documentazione per gli esseri umani (per quello c'è il README). È memoria di lavoro per l'agente: lo stack è fisso, ecco le convenzioni, ecco i comandi, ecco i pattern esplicitamente vietati.

L'AGENTS.md è il singolo artefatto che trasforma un LLM stateless in un collaboratore consapevole del progetto. Scrivilo come se dovesse sopravvivere a un azzeramento della finestra di contesto tra ogni sessione, perché lo fa.

Di seguito è riportata l'effettiva sezione stack che incollo nell'AGENTS.md di ogni nuovo progetto. L'agente la legge prima di toccare qualsiasi codice. Sostituisci la scelta del database (MySQL vs Postgres), mantieni tutto il resto fisso.

# 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

Tre cose rendono questo file efficace. Prima, è prescrittivo: "do NOT roll a custom session system" non è un suggerimento. Secondo, nomina il percorso esatto del file per ogni astrazione (src/lib/auth.ts, src/lib/prisma.ts). L'agente non deve andare a cercarlo. Terzo, elenca le criticità: quelle che hai scoperto nel modo difficile affinché l'agente non debba riscoprirle.

L'Ambiente Locale in un Unico Comando

Docker Compose fa parte dello stack per una ragione specifica: rende l'ambiente locale un artefatto di prima classe su cui l'agente può ragionare. Quando l'agente legge AGENTS.md e vede che docker compose up -d avvia MySQL, Redis e MinIO, sa esattamente cosa dirti quando qualcosa non funziona. Non deve ipotizzare se hai un'installazione MySQL locale o un database cloud in sviluppo.

# 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:

Le stesse versioni delle immagini girano in locale e in produzione su Hetzner. L'agente conosce le stringhe di connessione dalle variabili d'ambiente che gli viene detto di aspettarsi. Non c'è alcuna superficie di "funziona solo sulla mia macchina".

Familiarità che si Accumula tra i Progetti

Il vero guadagno non è il primo progetto. È il quinto. Quando hai usato questo stack cinque volte, l'AGENTS.md è raffinato. La sezione sulle criticità ha intercettato bug reali. La sezione sui pattern vietati ha prevenuto almeno due errori architetturali. La classe base per i job è stata estratta in un template condiviso che puoi clonare.

Ogni nuovo progetto eredita la disciplina accumulata dei precedenti. L'agente arriva il giorno uno già conoscendo i pattern che ti hanno richiesto due progetti per stabilire. Non è magia. È solo documentazione che viene effettivamente letta.

• Inizia ogni progetto clonando il template AGENTS.md e adattando la scelta del database.
• Aggiorna l'AGENTS.md ogni volta che aggiungi una nuova astrazione, vieti un pattern, o incappi in una criticità.
• Trattalo come una specifica viva: quando il codebase cambia, l'AGENTS.md cambia prima.
• Caricalo esplicitamente all'inizio di ogni sessione dell'agente -- non assumere che l'agente lo trovi da solo.

Anche la Revisione Diventa Più Veloce

Un beneficio secondario che vale la pena nominare: la code review diventa più veloce quando conosci lo stack. Non stai valutando se l'agente ha scelto una libreria sensata. Stai solo valutando se ha usato correttamente la libreria concordata. È una domanda molto più circoscritta, e si accumula anche quella: più a lungo usi lo stack, più velocemente individui una deviazione.

La tesi è semplice: uno stack fisso è un moltiplicatore di forza per lo sviluppo assistito da AI. L'agente conosce gli strumenti, tu conosci gli strumenti, l'AGENTS.md fa da ponte tra le sessioni. Smetti di dibattere sull'infrastruttura e inizia a spedire funzionalità. Questo è tutto.