Context Engineering Pratico: Rules, MCP, Workflow Completo

Nell'articolo su cosa vede e non vede l'AI abbiamo smontato il motore. Abbiamo visto come funziona la context window, perché si degrada, cosa succede quando si riempie.

Oggi lo rimettiamo in moto. Questa è la guida operativa: come strutturare i file di regole, configurare MCP server, gestire le sessioni e costruire un workflow quotidiano che ti fa ottenere risultati consistenti.

Non teoria — azioni. Template pronti, pattern testati, errori da evitare.

Il Principio: Meno È Meglio, Se È Giusto

Prima di entrare nel pratico, un concetto che cambia tutto.

Il tuo agente AI ha una "RAM" limitata — la context window. Ogni token che ci metti è un token in meno per ragionare e rispondere. Questo significa che il context engineering non è aggiungere informazione — è selezionare quella giusta.

Anthropic lo dice esplicitamente nella documentazione di Claude Code: i modelli frontier riescono a seguire circa 150-200 istruzioni con ragionevole consistenza. Oltre, la qualità degrada.

Quindi la domanda non è "cosa posso aggiungere?". È "cosa posso togliere senza perdere valore?"

Livello 1: I File di Regole

Ogni tool di AI coding ha il suo sistema di istruzioni persistenti. I nomi cambiano, il concetto è lo stesso: un file che viene iniettato nel contesto a ogni sessione.

La mappa completa

AGENTS.md: Lo standard aperto

AGENTS.md è nato come convenzione proposta da OpenAI per Codex CLI, ma sta diventando uno standard de facto riconosciuto da più tool. L'idea è semplice: un singolo formato di istruzioni leggibile da qualsiasi agente AI.

Se il tuo team usa tool diversi, puoi mantenere sia il file specifico (CLAUDE.md, .cursorrules) sia un AGENTS.md con le istruzioni comuni. Non è duplicazione — è interoperabilità.

Cosa mettere nei rules file

Regola d'oro: scrivi solo ciò che l'agente non può dedurre dal codice.

L'AI è un in-context learner — se il tuo codice segue pattern consistenti, l'agente li replicherà senza che tu glielo dica. Non serve scrivere "usa TypeScript" se ogni file del progetto è .ts.

Sì, metti questo:

## Stack
- Nuxt 4.3 + @nuxt/content v3 + TailwindCSS
- Dev server: porta 3002
- Deploy: `python deploy.py`

## Comandi
- `npm run dev -- --port 3002` (dev)
- `npm run generate` (build statico)

## Convenzioni non ovvie
- I file che iniziano con `_` sono draft — filtrarli nelle query
- Content API: `queryCollection('nome').all()` (v3, NON v2)
- Immagini: 1536x1024 webp, in `public/images/{sezione}/`

## Errori noti
- NON usare `getCachedData: () => null` in useAsyncData (causa fetch vuoti)
- Path: usa `item.path` NON `item._path` (v3 breaking change)

No, non mettere questo:

## ❌ Cose che l'AI sa già
- "Scrivi codice pulito e leggibile" → sa già cos'è
- "Usa le best practice" → troppo generico, zero valore
- "Gestisci gli errori" → lo fa comunque
- "Segui i principi SOLID" → non aggiunge nulla di specifico al progetto
- L'intero README del progetto copia-incollato → spreco di token

La struttura che funziona

Dopo mesi di iterazione, questa è la struttura che produce i risultati migliori:

# CLAUDE.md

## Contesto progetto (2-3 righe)
Cos'è, per chi, una riga sullo stack.

## Comandi (lista secca)
Dev, build, test, deploy. Solo i comandi.

## Architettura (solo le parti non ovvie)
Struttura cartelle SE non è standard.
Pattern custom che l'AI non può dedurre.

## Convenzioni critiche (quelle che causano bug)
Le cose che SE l'AI non le sa, rompe qualcosa.
Ogni regola qui ha una storia di debug dietro.

## Errori noti (sezione vivente)
Bug incontrati e come risolverli.
Questa sezione cresce col tempo.

Notare cosa manca: niente saluti, niente filosofia, niente istruzioni generiche. Ogni token ha un motivo per essere lì.

Quanto deve essere lungo?

Il dato di Anthropic sui 150-200 istruzioni è un buon riferimento. In pratica:

• Progetto piccolo: 50-100 righe bastano
• Progetto medio: 100-200 righe
• Monorepo aziendale: usa la gerarchia — CLAUDE.md globale snello + .claude/rules/ per area

Se il tuo rules file supera le 300 righe, probabilmente stai descrivendo cose che l'AI può dedurre dal codice. Taglia.

Livello 2: MCP — Il Contesto Esterno

I file di regole gestiscono il contesto statico. MCP (Model Context Protocol) gestisce il contesto dinamico — tutto ciò che viene da fuori il codebase.

Cos'è MCP in 30 secondi

MCP è un protocollo standard (creato da Anthropic, ora open) che permette agli agenti AI di connettersi a tool esterni: database, API, browser, servizi. Invece di dire all'AI "vai su questo sito e copia i dati", configuri un MCP server e l'AI ci parla direttamente.

Abbiamo scritto una guida completa su come costruire un MCP server. Qui ci concentriamo sull'aspetto di context engineering: come configurarli senza inquinare il contesto.

Il problema: context pollution da MCP

Ogni MCP server che connetti aggiunge definizioni di tool nel contesto. Ogni tool ha un nome, una descrizione, parametri con schema JSON. Un singolo MCP server complesso può aggiungere migliaia di token di definizioni.

Connetti 5 MCP server e hai già consumato 10-15K token prima ancora di scrivere la prima riga di codice. In una finestra da 200K sembra poco — ma ricorda il paper NoLiMa: a 32K token la maggior parte dei modelli è già sotto il 50% della baseline.

La regola: meno server, più mirati

Non connettere tutti gli MCP server disponibili. Connetti solo quelli che ti servono per il task corrente.

Sì:

• Stai debuggando il frontend → connetti Playwright MCP per testare nel browser
• Stai lavorando sul database → connetti il database MCP
• Stai facendo deploy → connetti il server MCP per il cloud

No:

• Connettere Playwright + Database + Sentry + GitHub + Slack + Linear tutti insieme "perché magari servono"

Configurazione pratica: .mcp.json

Per Claude Code, puoi configurare MCP server a livello di progetto con un file .mcp.json nella root:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic/mcp-playwright"]
    },
    "postgres": {
      "command": "npx",
      "args": ["@anthropic/mcp-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

Questo file si committa nel repo — chiunque nel team clona il progetto e ha gli stessi MCP server configurati. È context engineering di team: tutti lavorano con lo stesso contesto.

MCP server che vale la pena avere

Nella pratica quotidiana, questi sono quelli con il miglior rapporto valore/token:

La colonna "costo in token" è il prezzo che paghi in contesto solo per avere il server connesso, anche se non lo usi. Per questo la regola è: connetti solo quello che serve adesso.

Livello 3: La Gestione delle Sessioni

Hai i rules file. Hai gli MCP server. Ora manca il pezzo più importante: come lavori giorno per giorno.

Il nemico: il Context Rot

Lo abbiamo visto nel dettaglio nell'articolo sulla context window: la qualità dell'output degrada con la lunghezza della conversazione. Non linearmente — in modo insidioso. Le prime risposte sono ottime, poi peggiorano gradualmente senza che te ne accorga.

La soluzione è semplice nella teoria, difficile nella pratica: sessioni corte e focalizzate.

La regola dei 20 minuti

Non è un numero magico, ma è un buon riferimento. Dopo 20-30 minuti di lavoro intenso con un agente, il contesto è probabilmente saturo. A quel punto hai due opzioni:

1. Continuare — e accettare che la qualità scende
2. Nuova sessione — contesto pulito, istruzioni rilette, agente fresco

La scelta giusta è quasi sempre la seconda. Ma richiede disciplina, perché il cervello umano preferisce non interrompere il flusso.

Un task, una sessione

Il pattern più efficace:

Sessione 1: "Implementa il componente UserCard"
Sessione 2: "Aggiungi i test per UserCard"
Sessione 3: "Integra UserCard nella pagina profilo"

Invece di:

Sessione unica: "Implementa UserCard, testala e integrala nel profilo"

Perché? Nella sessione unica, quando arrivi all'integrazione hai 50+ messaggi di contesto dall'implementazione e dai test — contesto che è solo rumore per il task di integrazione. Nella versione a sessioni separate, ogni task parte con contesto pulito.

Quando cambiare sessione

Cambia sessione quando:

• Cambi argomento — da frontend a backend, da feature a bug fix
• L'agente inizia a "dimenticare" — ripete errori già corretti, ignora convenzioni
• Hai completato un task — anche se il prossimo è correlato
• Senti che le risposte peggiorano — fidati dell'intuito, di solito hai ragione

Checkpoint: la memoria fuori dalla finestra

Prima di chiudere una sessione, fai scrivere all'agente un checkpoint:

"Scrivi un riassunto di quello che abbiamo fatto e delle decisioni prese
in un commento in cima al file o in un file progress.md"

Nella sessione successiva:

"Leggi progress.md e continua da dove avevamo lasciato"

È il pattern usato da Anthropic stessa per agenti di lunga durata. Manus (l'agente di Monica.im) usa un todo.md che riscrive continuamente. Non è elegante, ma funziona meglio di qualsiasi meccanismo automatico.

Livello 4: Il Workflow Completo

Mettiamo tutto insieme. Ecco il workflow quotidiano che uso e che produce risultati consistenti.

Setup iniziale del progetto (una volta)

1. Crea il rules file principale

Scrivi il CLAUDE.md (o equivalente) seguendo la struttura descritta sopra. Parti snello — 50-80 righe — e fallo crescere solo quando incontri problemi reali.

2. Configura gli MCP server essenziali

Solo quelli che usi quotidianamente. Per un progetto web tipico: Playwright per il testing visivo e basta. Aggiungi altri solo quando ne hai bisogno.

3. Crea i comandi custom

Claude Code supporta comandi custom nella cartella .claude/commands/. Sono template Markdown che puoi invocare con /nome-comando:

<!-- .claude/commands/review.md -->
Analizza il file $ARGUMENTS per:
1. Bug potenziali
2. Violazioni delle convenzioni del progetto
3. Performance issue
Suggerisci fix concreti, non generici.

Stesso concetto per Cursor (.cursor/rules/) e Codex CLI (prompt template). L'idea è: le istruzioni che ripeti spesso diventano comandi.

4. Sezione "Errori Noti" nel rules file

Inizia vuota. Ogni volta che incontri un bug causato dall'AI che non conosceva una convenzione del progetto, aggiungilo. Dopo un mese avrai la sezione più preziosa di tutto il file.

Workflow quotidiano

1. Apri terminale / IDE
2. Identifica il task (specifico, scope contenuto)
3. Nuova sessione con l'agente
4. Se serve contesto di sessioni precedenti → "leggi progress.md"
5. Lavora sul task (max 20-30 min o fino a completamento)
6. Se il task è complesso → checkpoint intermedi
7. Task completato → verifica (test, browser, review)
8. Se c'è un task correlato → nuova sessione
9. A fine giornata → aggiorna rules file se hai scoperto nuove convenzioni

Il ciclo di miglioramento

Il rules file non è statico. Evolve col progetto:

Settimana 1: CLAUDE.md base — stack, comandi, struttura
Settimana 2: Aggiungi "Errori Noti" dopo i primi bug
Settimana 3: Aggiungi convenzioni che l'AI viola ripetutamente
Settimana 4: Togli le regole che l'AI segue già da sola (le ha imparate dal codice)

Anthropic suggerisce di trattare il CLAUDE.md come un prompt da ottimizzare: periodicamente, passalo attraverso un prompt improver o semplicemente rileggilo chiedendoti "questo serve ancora?".

I 7 Pattern che Funzionano

Dopo centinaia di sessioni, questi sono i pattern operativi che producono la differenza maggiore.

1. Dai tipi, non implementazioni

In linguaggi tipizzati, fornire le interfacce e i tipi è enormemente più efficace che fornire l'implementazione:

// ✅ 15 token, massima informazione strutturale
interface User {
  id: string
  email: string
  role: 'admin' | 'user'
  createdAt: Date
}

// ❌ 200+ token per comunicare la stessa informazione
// (più l'implementazione di validazione, getter, setter...)

Un'interfaccia TypeScript di 20 righe comunica la stessa informazione strutturale di 300 righe di implementazione — usando un quindicesimo dei token.

2. Esempio mirato > file intero

Quando vuoi che l'AI replichi uno stile:

✅ "Segui questo pattern per i composable:
    const { data } = await useAsyncData('key', () => queryCollection('articles').all())
    Filtra i draft con: items.filter(i => !i.path.split('/').pop()?.startsWith('_'))"

❌ "Leggi il file pages/articoli/index.vue e fai uguale"

30 token mirati battono 300 righe di contesto. L'AI non ha bisogno dell'intero file per capire il pattern — ha bisogno dell'essenza del pattern.

3. Specifiche > esempi generici

✅ "Crea un endpoint POST /api/users con validazione Zod:
    - email: z.string().email()
    - name: z.string().min(2).max(50)
    - role: z.enum(['admin', 'user']).default('user')
    Ritorna 201 con l'utente creato, 400 con gli errori Zod."

❌ "Crea un endpoint per gli utenti, tipo quello che abbiamo per i prodotti"

La prima versione è 100% eseguibile senza ambiguità. La seconda richiede che l'AI legga l'endpoint prodotti (altri token consumati) e faccia assunzioni su cosa "tipo" significhi.

4. Contesto al momento giusto

Non caricare tutto all'inizio. Fornisci contesto quando serve:

Messaggio 1: "Implementa il componente UserCard con nome, email e avatar"
[L'AI implementa]

Messaggio 2: "Ora aggiungi il badge del ruolo. I ruoli possibili sono:
admin (badge rosso), moderator (badge giallo), user (badge grigio)"
[L'AI aggiunge]

Invece di:

Messaggio 1: "Implementa UserCard con nome, email, avatar, badge ruolo
(admin=rosso, moderator=giallo, user=grigio), menu dropdown con azioni
(edit, delete, ban), tooltip sul nome, skeleton loading, responsive
con breakpoint a 768px, dark mode..."

Il primo approccio mantiene il contesto pulito a ogni step. Il secondo affoga l'AI in specifiche che interferiscono tra loro.

5. Ridondanza mirata nell'ultimo messaggio

Il tuo messaggio più recente ha il peso maggiore nella risposta dell'AI. Se un'informazione è critica, ripetila nell'ultimo messaggio anche se l'hai già detta:

"Implementa il sorting per la tabella utenti.
IMPORTANTE: usa queryCollection v3 syntax, NON queryContent (v2)."

Anche se è nel CLAUDE.md, anche se l'hai detto 10 messaggi fa. Dopo 15+ messaggi, il contesto iniziale è nella "zona morta" (lost in the middle). La ridondanza nell'ultimo messaggio è l'antidoto.

6. Sessioni separate per task diversi

Questo è il pattern che nessuno vuole seguire e che fa la differenza maggiore:

❌ Sessione unica di 2 ore:
   "Fix il bug del login" → "Ora aggiungi la registrazione" →
   "Refactora il middleware auth" → "Scrivi i test"

✅ Quattro sessioni da 30 minuti:
   Sessione 1: "Fix il bug del login"
   Sessione 2: "Aggiungi la registrazione"
   Sessione 3: "Refactora il middleware auth"
   Sessione 4: "Scrivi i test per auth"

Nella versione a sessione unica, quando scrivi i test hai 90 minuti di contesto accumulato — inclusi tutti gli errori, i tentativi falliti, i file letti e scartati del debug. Nella versione a sessioni separate, ogni task parte fresco.

7. Il git come checkpoint naturale

Dopo ogni task completato, committa. Il commit è il checkpoint perfetto:

• Cristallizza le decisioni nel codice (non nella context window)
• Fornisce un messaggio che descrive cosa è stato fatto
• Permette di tornare indietro se il prossimo task rompe qualcosa
• Nella sessione successiva, git log e git diff danno all'AI contesto preciso

"Committa le modifiche con un messaggio che descriva cosa abbiamo fatto"
[Nuova sessione]
"Guarda gli ultimi 3 commit per capire il contesto e continua con..."

Errori Comuni e Come Evitarli

1. Il rules file enciclopedico

Errore: CLAUDE.md di 500+ righe con tutto lo scibile del progetto.

Problema: oltre 200 istruzioni la qualità degrada. Le regole importanti si perdono nel rumore.

Fix: taglia tutto ciò che l'AI può dedurre dal codice. Se dopo aver tolto una regola l'AI continua a comportarsi correttamente, quella regola non serviva.

2. "Leggi tutto il progetto"

Errore: iniziare la sessione con "leggi tutti i file nella cartella src per capire il progetto".

Problema: 15 file letti = 15 file nel contesto = contesto saturo prima di aver fatto qualsiasi cosa.

Fix: lascia che l'AI navighi on-demand. Se sa cosa deve fare (grazie al rules file), sa anche cosa leggere.

3. MCP server a pioggia

Errore: connettere 8 MCP server "perché magari servono".

Problema: migliaia di token di definizioni tool che non userai, che sottraggono spazio al contesto utile.

Fix: connetti solo quello che serve per il task corrente. Puoi sempre aggiungerne uno a metà sessione se ne hai bisogno.

4. La sessione infinita

Errore: lavorare 3 ore sulla stessa sessione cambiando topic.

Problema: Context Rot — la qualità degrada cumulativamente senza che te ne accorga.

Fix: sessioni corte e focalizzate. Un task, una sessione. Chiudi e riapri.

5. Non aggiornare mai il rules file

Errore: scrivere il CLAUDE.md una volta e non toccarlo più.

Problema: il progetto evolve, le convenzioni cambiano, l'AI continua a seguire regole obsolete.

Fix: il rules file è un documento vivente. Aggiornalo quando incontri nuovi pattern o quando regole vecchie non servono più.

Il Template: Inizia da Qui

Se vuoi partire subito, ecco un template minimale che funziona per la maggior parte dei progetti:

# CLAUDE.md

## Progetto
[Nome] - [cosa fa in una riga]. [Stack principale].

## Comandi
- Dev: `[comando dev]`
- Build: `[comando build]`
- Test: `[comando test]`
- Deploy: `[comando deploy]`

## Struttura (solo parti non standard)
[Elenca solo le cartelle/file la cui organizzazione NON è ovvia]

## Convenzioni critiche
- [Cosa che se l'AI non sa, rompe qualcosa]
- [Altra cosa che causa bug se ignorata]
- [Pattern specifico del progetto]

## Errori noti
[Inizia vuoto. Aggiungi quando li incontri]

Sono ~20 righe. Meno di 500 token. Lascia il 99.7% della finestra per il lavoro vero.

Poi cresci da qui — ma solo quando hai un motivo concreto per aggiungere qualcosa.

Il Quadro Completo

Il context engineering non è un singolo file o una singola tecnica. È un sistema a 4 livelli:

I primi due livelli li configuri una volta e li mantieni. Gli ultimi due sono abitudini quotidiane che si costruiscono con la pratica.

La differenza tra chi usa l'AI coding "bene" e chi la usa "così così" non è il tool, non è il modello, non è la dimensione della context window. È la disciplina nel gestire il contesto.

E la buona notizia è che non servono configurazioni complesse o setup elaborati. Serve un rules file snello, sessioni corte, e l'abitudine di dare all'AI il giusto contesto al momento giusto — né troppo, né troppo poco.

Fonti:

• Anthropic — Best Practices for Claude Code
• Anthropic — Context Engineering for AI Agents
• HumanLayer — Writing a Good CLAUDE.md
• Addyo Substack — Context Engineering: Bringing Engineering Discipline
• Contextual AI — Context Engineering for Your MCP Client
• CodeConductor — Context Engineering Complete Guide
• Martin Fowler — Context Engineering for Coding Agents
• Refactoring.fm — How to Manage Context in AI Coding Workflows
• Manus — Context Engineering Lessons
• PromptingGuide.ai — Context Engineering Guide