15 settembre 2026

Perché la tua AI scrive codice mediocre (e come farla lavorare davvero bene nel tuo repo)

Il problema raramente è “il prompt”: quasi sempre è il contesto che stai alimentando male. La soluzione è un Agent/Claude.md minimale, ben linkato e aggiornabile.

Se la tua AI ripete sempre gli stessi errori, spesso non è colpa del modello: è colpa della configurazione che gli stai inviando a ogni richiesta. In molti progetti l’Agent.md (o Claude.md/Gemini.md) diventa una discarica di regole, checklist, convenzioni duplicate e istruzioni non pertinenti. Risultato: contesto enorme, token sprecati, qualità che cala e decisioni incoerenti. In questo articolo vediamo come strutturare correttamente i file di contesto: tenere l’Agent.md piccolo, spostare le convenzioni in documenti dedicati, usare link interni per caricare solo ciò che serve e mantenere una descrizione del repo ad alto livello per evitare documentazione che invecchia male. Con una strategia incrementale (aggiungere regole solo quando emergono problemi reali) ottieni output più prevedibili e più “in stile progetto”.

Il sintomo: “qualsiasi cosa faccia, la AI sbaglia sempre allo stesso modo”

Quando un assistente di coding continua a:

  • ignorare convenzioni del progetto,
  • proporre pattern incoerenti,
  • generare codice “giusto” ma fuori contesto,
  • ripetere errori già corretti in passato,

la reazione tipica è: ritoccare il prompt, aggiungere altre regole, installare “skill” e aggiungere documentazione ovunque.

Il punto è che, in molti strumenti, non stai inviando solo il testo del prompt. Ogni richiesta porta con sé un pacchetto di contesto che include file e istruzioni “di sistema” del progetto. Se quel pacchetto è progettato male, stai chiedendo al modello di ragionare con una valanga di rumore.

Il contesto che finisce davvero dentro ogni richiesta

In una configurazione comune (indipendentemente dal vendor), la richiesta effettiva tende a includere:

  • System prompt: istruzioni di alto livello su come l’AI deve comportarsi (spesso non modificabile).
  • Agent.md (o varianti come Claude.md, Gemini.md, cloud.md): un file al root che viene iniettato ad ogni prompt.
  • Skills: set di markdown che l’agente carica quando deve svolgere task specifici.
  • Documentazione e/o codice: file letti “a richiesta” per risolvere il problema (README, docs interne, file sorgenti).
  • Il tuo prompt: quello che scrivi tu.

Il punto cruciale è questo:

Se l’Agent.md è grande, disordinato o contraddittorio, “avvelena” tutte le richieste, anche quelle semplici.

L’errore più comune: Agent.md come “lista infinita di bullet point”

In tanti repository l’Agent.md nasce piccolo e poi cresce così:

  1. l’AI sbaglia una cosa,
  2. qualcuno aggiunge una regola in fondo,
  3. si ripete per mesi.

Il risultato tipico è un file enorme con:

  • sezioni duplicate (stesse regole scritte in due punti diversi),
  • regole altamente specifiche che valgono solo in rarissimi casi,
  • checklist operative (code review, release, PR, ecc.) che non servono nella maggior parte dei task,
  • convenzioni di stack diverse mescolate (es. React + Angular + altro) che confondono l’agente.

Perché è un problema anche se hai una context window enorme

Anche se i modelli moderni gestiscono tanti token, nella pratica:

  • più contesto = più costo (token sprecati a ogni richiesta),
  • più contesto = più rumore (peggiora la precisione e la coerenza),
  • superata una certa soglia, la qualità tende a degradare: non perché “non ci sta”, ma perché il modello deve scegliere cosa pesare e cosa ignorare.

La regola d’oro: Agent.md deve essere piccolo e “routing-based”

L’Agent.md non dovrebbe contenere tutte le regole del mondo. Dovrebbe invece:

  1. descrivere il progetto in poche righe,
  2. fissare 2–3 decisioni globali (es. package manager),
  3. indicare dove trovare le convenzioni dettagliate (link a file doc dedicati).

In pratica, Agent.md diventa un indice.

Esempio di struttura consigliata

  • Descrizione breve del progetto (1–2 frasi)
  • Tooling globale (es. “Usiamo pnpm”, “Usiamo Vitest”, “Formatter: Prettier”)
  • Layout ad alto livello (cartelle principali, senza scendere ai singoli file)
  • Link alle convenzioni:
    • docs/conventions/react.md
    • docs/conventions/typescript.md
    • docs/conventions/css.md
    • docs/testing.md
    • docs/delivery/pr-checklist.md
    • ecc.

Così l’agente carica (o tu gli fai caricare) solo la parte che serve al task corrente.

Spostare le regole “a consumo” in documenti dedicati

Un metodo semplice e molto efficace:

  • ogni volta che nell’Agent.md compare una sezione “verticale” (CSS, testing, API, React…),
  • spostala in docs/... in un file dedicato,
  • e lascia nell’Agent.md solo il link.

Questo porta tre vantaggi immediati:

  1. riduci i token fissi (quelli inviati sempre),
  2. eviti duplicazioni (una regola sta in un posto solo),
  3. rendi la manutenzione più facile (modifichi la doc giusta quando serve).

Anche le checklist di delivery non dovrebbero stare in Agent.md

Se hai regole tipo:

  • “quando finisci, aggiorna la documentazione”,
  • “esegui lint/test”,
  • “scrivi un summary per la PR”,

sono utili, ma non sempre. Metterle in Agent.md significa “spammare” quelle istruzioni anche quando stai solo chiedendo di rinominare una variabile.

Meglio creare, ad esempio, docs/delivery/submitting-pr.md e linkarlo.

Attenzione al layout: alto livello sì, mappa file no

Avere in Agent.md una sezione “Repository layout” è spesso utile, ma con un limite:

  • bene: descrizione macro (frontend in apps/web, backend in apps/api, librerie in packages/*)
  • male: riferimenti granulari a file specifici (“il componente X è in src/components/X.tsx”)

I path cambiano spesso. Un Agent.md con dettagli troppo specifici invecchia male e crea un altro problema: istruzioni obsolete che guidano l’AI verso file che non esistono più o architetture superate.

Non farti generare l’Agent.md “leggendo tutto il repo”

Chiedere all’AI di scandire il repository e produrre un Agent.md completo sembra comodo, ma spesso genera:

  • documenti verbosi,
  • regole generiche e inutili,
  • tanti dettagli che non sono davvero convenzioni (solo “osservazioni”).

Meglio partire minimal:

  • 1–2 frasi sul progetto,
  • package manager,
  • qualche indicazione globale,
  • poi crescere in modo incrementale.

Strategia incrementale: aggiungi regole solo quando emerge un errore reale

La tentazione è “prevenire” ogni possibile sbaglio con una lista infinita. Funziona meglio l’opposto:

  1. parti con un Agent.md piccolo,
  2. fai lavorare l’AI,
  3. quando noti un comportamento sbagliato ricorrente, scrivi una regola mirata nel documento giusto (TypeScript, React, API, testing…)
  4. linka quel documento dall’Agent.md.

Così costruisci un set di convenzioni che:

  • è aderente al tuo progetto,
  • resta leggibile,
  • migliora davvero l’output perché non diluisce le istruzioni importanti.

Sintesi operativa

  • Agent.md non è un manuale, è un indice: deve restare corto.
  • Sposta convenzioni e checklist in docs dedicate e linkale.
  • Evita duplicazioni e sezioni “raramente utili” nel contesto fisso.
  • Mantieni il layout ad alto livello per non creare documentazione obsoleta.
  • Evolvi le regole solo in risposta a problemi osservati.

Quando il contesto fisso diventa pulito e minimale, i prompt smettono di essere una lotta continua: l’AI lavora con meno rumore, sceglie meglio cosa applicare e produce codice più coerente con lo stile del repository. La qualità, nella pratica quotidiana, fa un salto molto più grande di qualsiasi “prompt magico”.