In molte piccole imprese italiane il codice viene oggi scritto a quattro mani con un assistente di intelligenza artificiale: uno sviluppatore pone una domanda in linguaggio naturale, il modello propone una funzione, un test o una correzione, lo sviluppatore accetta o modifica. Il problema non è più ottenere una risposta, ma ottenerla sempre con la stessa qualità, con lo stesso stile e con la stessa attenzione alla manutenibilità, alla sicurezza e alla documentazione. Quando si usano strumenti diversi, come estensioni per Visual Studio Code, assistenti da terminale o interfacce desktop, ogni strumento tende a comportarsi a modo proprio e le regole interne del team si perdono. mcp-ai-agent-guidelines nasce proprio per rispondere a questo bisogno: raccogliere in un unico punto, distribuito come server aperto, un insieme di linee guida operative che gli agenti possono consultare durante il lavoro.
Cos'è e a cosa serve
mcp-ai-agent-guidelines è un progetto open source con licenza MIT, scritto in TypeScript e pensato per Node.js 22, che implementa un server conforme al Model Context Protocol, il protocollo aperto che permette a un modello o a un agente di richiedere strumenti, contesti e istruzioni a un componente esterno in modo standard. In pratica non è un modello linguistico, non è una piattaforma di sviluppo e non è un servizio cloud: è una raccolta eseguibile di buone pratiche che si presenta agli assistenti come una serie di funzioni richiamabili.
Secondo la descrizione fornita dall'autore, il server espone 19 strumenti pubblici più 3 utilità e 72 competenze interne organizzate in 16 famiglie. Questi numeri vanno presi con prudenza perché derivano solo dalla documentazione del progetto e non da una verifica indipendente, ma danno l'idea della dimensione: non un singolo prompt, bensì una libreria di comportamenti. Le aree coperte comprendono la strutturazione gerarchica delle istruzioni, l'igiene del codice, la visualizzazione di architetture e flussi con diagrammi in formato testuale Mermaid, l'ottimizzazione dell'uso della memoria e del contesto e la pianificazione di attività in stile agile.
Per una PMI, un'agenzia web o uno studio che produce software su misura per clienti, il valore dichiarato è semplice: trasformare regole oggi sparse in documenti, wiki o abitudini dei singoli in controlli richiamabili automaticamente dall'agente, senza dover riscrivere ogni volta le stesse raccomandazioni nel prompt.
Come funziona sotto il cofano
Il funzionamento segue lo schema tipico del Model Context Protocol in modalità locale. Il server viene avviato sul computer dello sviluppatore o su una macchina di laboratorio, comunica attraverso input e output standard e viene registrato come server aggiuntivo dentro un client compatibile, come Visual Studio Code con supporto MCP, un assistente desktop compatibile o un agente da riga di comando. Quando l'utente chiede all'agente di scrivere o modificare codice, l'agente può interrogare il server per ottenere la linea guida pertinente prima di generare la risposta.
Un esempio aiuta a capire. Se si chiede di creare un nuovo modulo per la gestione di ordini, l'agente può prima richiedere il modello per la scomposizione gerarchica del compito, quindi la lista di controllo per la qualità del codice, quindi il modello per generare un diagramma di sequenza e infine lo schema per suddividere il lavoro in passi verificabili. Ogni passaggio restituisce testo strutturato, esempi e criteri di accettazione che l'agente incorpora nella propria risposta. Alcuni strumenti servono a pianificare, altri a verificare, altri a documentare.
Un aspetto rilevante per i costi è che il progetto, nella configurazione descritta, non richiede una chiave di servizio esterno a pagamento per funzionare: è una libreria di istruzioni che viaggia insieme al modello già in uso. Non aggiunge quindi di per sé un ulteriore consumo di token legato a un modello remoto proprietario, ma sfrutta il modello già scelto dal team. Resta ovviamente il consumo normale del modello principale, che dipende dall'abbonamento o dall'infrastruttura adottata. La configurazione avviene tramite file di impostazione del client, con dichiarazione del comando di avvio e dei permessi concessi, pratica comune per i server MCP locali.
Casi d'uso concreti per agenzie, PMI e founder
Il primo caso d'uso è la standardizzazione delle revisioni. In un team di tre o cinque persone, tipico di un'agenzia digitale italiana, capita che ogni sviluppatore usi l'assistente in modo diverso: uno chiede codice rapido senza test, un altro chiede test molto dettagliati, un terzo non documenta. Collegando tutti allo stesso server di linee guida, il titolare o il responsabile tecnico può imporre una base comune, ad esempio intestazioni uniformi, gestione esplicita degli errori, divieto di valori scritti direttamente nel codice, generazione sistematica di un riassunto delle modifiche.
Il secondo caso è la documentazione e la comunicazione con il cliente. Molte PMI faticano a tenere aggiornati schemi architetturali e manuali. Uno degli ambiti dichiarati del progetto è proprio la generazione di visualizzazioni a partire da descrizioni testuali, utile per produrre diagrammi di flusso, schemi di componenti o mappe di processo da allegare a un'offerta o a un verbale di collaudo. Per un founder non tecnico, ricevere dal team un diagramma leggibile insieme al codice rende più facile validare un avanzamento.
Il terzo caso è la gestione del contesto su progetti lunghi. I modelli hanno una finestra di memoria limitata e tendono a dimenticare decisioni prese molte interazioni prima. Le linee guida dedicate all'ottimizzazione della memoria suggeriscono come riassumere, come suddividere un problema complesso in sotto-obiettivi e come mantenere traccia delle scelte. Per attività come la migrazione di un gestionale, il rifacimento di un sito e-commerce o l'integrazione con un sistema di fatturazione, questo approccio riduce il rischio di risposte incoerenti.
Il quarto caso è la pianificazione agile leggera. Le competenze dedicate alla pianificazione aiutano a trasformare una richiesta generica, come realizzare un'area riservata per i clienti, in epiche, storie e criteri di verifica. Non sostituiscono uno strumento di project management, ma forniscono all'agente uno schema per proporre suddivisioni sensate che il team può poi importare nei propri strumenti.
Perché conta nell'ecosistema attuale degli agenti
Il valore di questa proposta si comprende meglio se si guarda al contesto del 2026. Da un lato i protocolli aperti per collegare modelli e strumenti si stanno diffondendo rapidamente, dall'altro ogni fornitore propone il proprio assistente con comportamenti leggermente diversi. Per una piccola impresa cambiare assistente non dovrebbe significare riscrivere da zero tutte le regole di lavoro. Un server di linee guida basato su uno standard aperto promette portabilità: le stesse checklist possono essere usate da strumenti diversi, purché compatibili con lo stesso protocollo.
Conta anche per un motivo culturale. Fino a pochi anni fa la qualità del software in PMI era affidata a revisori esperti e a manuali interni. Oggi parte del codice è generata automaticamente e il rischio è una deriva silenziosa verso soluzioni che funzionano nel breve periodo ma sono difficili da mantenere. Avere checklist esplicite, versionate e condivise riporta al centro pratiche consolidate come nomi chiari, funzioni brevi, test ripetibili, separazione delle responsabilità e documentazione essenziale. In questo senso il progetto non introduce una nuova tecnologia dirompente, ma prova a industrializzare il buon senso.
Per founder e responsabili non tecnici, il messaggio è che la produttività degli assistenti non dipende solo dal modello scelto, ma dal contesto di regole in cui il modello opera. Un modello potente senza linee guida può produrre molto codice disomogeneo, mentre un modello medio guidato da standard chiari può produrre meno codice ma più affidabile e più economico da mantenere.
Limiti, maturità e dove trovarlo
La valutazione onesta richiede di sottolineare i limiti. L'autore stesso presenta il progetto come sperimentale e in fase iniziale, e invita a verificare sempre i suggerimenti rispetto alla documentazione ufficiale dei linguaggi e dei framework. Le cifre su strumenti e competenze, la compatibilità dichiarata con editor e assistenti desktop e l'efficacia reale delle checklist non sono state sottoposte a verifiche indipendenti con i soli dati disponibili. Non esistono, nelle fonti fornite, benchmark pubblici, audit di sicurezza o prove di adozione su larga scala.
Ciò significa che l'adozione in produzione va preparata con prudenza. La buona pratica è clonare il repository in un ambiente isolato senza segreti aziendali, avviarlo in prova, collegarlo come server secondario a un assistente su una copia di prova del codice e confrontare i risultati con le proprie regole interne prima di estenderlo al team. Va inoltre ricordato che si tratta di linee guida testuali: non eseguono controlli formali come un analizzatore statico, non correggono vulnerabilità da sole e non sostituiscono test, revisione umana e procedure di sicurezza.
Il progetto è distribuito con licenza MIT, che consente uso, modifica e integrazione anche in contesti commerciali secondo i termini della licenza stessa, e richiede Node.js 22 per l'esecuzione. Il punto di riferimento è il repository pubblico https://github.com/Anselmoo/mcp-ai-agent-guidelines, dove si trovano codice sorgente, istruzioni di installazione, elenco degli strumenti e note di avanzamento. Per chi valuta standard aperti per il lavoro assistito, rappresenta un esperimento interessante da studiare, da confrontare con alternative e da provare in laboratorio prima di decidere se farne una componente stabile del proprio metodo di sviluppo.