L’integrazione degli agenti basati su modelli di linguaggio di grande dimensione (LLM) nei flussi di ingegneria del software ha evidenziato i limiti dei tradizionali approcci di manipolazione del codice.
La maggior parte delle architetture agentiche di prima generazione opera attraverso primitive testuali generiche, affidandosi a ricerche basate su espressioni regolari e sostituzioni di testo ancorate ai numeri di riga.
Questa metodologia si rivela intrinsecamente fragile nei sistemi software di dimensioni aziendali, dove la rifattorizzazione di un’interfaccia o lo spostamento di un modulo richiede aggiornamenti coordinati su decine di file sorgente. L’assenza di comprensione sintattica porta frequentemente a errori di compilazione, deriva sintattica e un consumo sproporzionato della finestra di contesto, causato dalla necessità di rileggere interamente i file sorgente per ogni singola modifica.
In questo contesto si colloca Serena, un toolkit open source concepito e sviluppato da Oraios AI, società d’infrastruttura per l’intelligenza artificiale con sede a Monaco di Baviera.
Rilasciato sotto licenza MIT e reso disponibile sulla piattaforma GitHub, il progetto ha registrato una rapida adozione, superando le 24.000 stelle e raggiungendo oltre 1.600 fork.
Serena si sovrappone ai tradizionali ambienti di sviluppo integrando lo standard open Model Context Protocol (MCP) e posizionandosi come l’IDE nativo per gli agenti di programmazione.
Operating a livello di simbolo anziché di sequenza di caratteri, l’infrastruttura sfrutta la struttura relazionale dell’albero di sintassi astratta (AST) e dei server di linguaggio, permettendo all’agente di interrogare, ristrutturare e modificare il codice sorgente con la medesima precisione e consapevolezza semantica di uno sviluppatore umano nell’uso di un IDE professionale.
L’innovazione chiave di questo approccio consiste nel trasformare operazioni multi-step altamente soggette a errore in singole chiamate API atomiche e deterministiche.
Dal punto di vista della complessità computazionale e dell’efficienza dei token, il passaggio da un’ispezione testuale non strutturata a un’analisi simbolica riduce il carico informativo trasferito al modello.
Architettura del Sistema e Duplice Engine di Analisi Semantica
L’infrastruttura di Serena si articola attorno a una rete server MCP in grado di comunicare con i client host attraverso il protocollo Standard I/O (stdio) oppure mediante endpoint HTTP/SSE dedicati. La capacità di comprendere e manipolare la struttura profonda del codice è garantita da due motori di intelligence indipendenti e selezionabili in base ai vincoli operativi o alle licenze d’uso.
Il motore primario e predefinito è il backend basato sul Language Server Protocol (LSP), completamente aperto e integrato. Questo strato astrae le interazioni con oltre 40 server di linguaggio ufficiali, supportando linguaggi quali Python, TypeScript, Java, Go, Rust, C/C++, C#, Elixir, Haskell, Scala, Swift, Kotlin e Zig. Tramite questo backend, Serena gestisce la scansione dei simboli, il recupero delle dichiarazioni, l’individuazione delle implementazioni e l’esecuzione di verifiche diagnostiche direttamente sul codice in lavorazione.
Il secondo motore è rappresentato dal plugin Serena per JetBrains (Plugin ID 28946 sul JetBrains Marketplace), un backend avanzato a pagamento che connette il server MCP a un’istanza attiva di un IDE della suite JetBrains, come IntelliJ IDEA, PyCharm, WebStorm o GoLand. Sfruttando i motori d’analisi statica proprietari di JetBrains, questo backend sblocca capacità di rifattorizzazione estese (come lo spostamento di file e classi con aggiornamento automatico dei pacchetti, l’inlining dei simboli e la rimozione propagata del codice non utilizzato) e abilita una sessione di debugging interattivo tramite interfaccia REPL.
| Dimensione Architetturale | Backend Language Server Protocol (LSP) | Backend Plugin JetBrains |
| Modello di Licenza e Distribuibilità | Open source e gratuito (Licenza MIT) | Modello commerciale con periodo di prova gratuito |
| Copertura Linguaggi e Framework | Supporto per oltre 40 linguaggi tramite LSP dedicati | Tutti i linguaggi e i framework supportati dall’IDE JetBrains attivo |
| Operazioni di Modifica e Refactoring | Rinomina simboli, sostituzione corpo simbolo, inserimenti relativi | Refactoring completo: spostamento (move), inlining, rinomina directory/file |
| Navigazione e Struttura Dipendenze | Analisi confinata al workspace e dichiarazioni locali | Ricerca nelle dipendenze esterne di progetto e gerarchie di tipo avanzate |
| Capabilities di Debugging | Non disponibili | Debugger REPL interattivo con breakpoint e valutazione espressioni |
| Prerequisiti Infrastrutturali | Esecuzione gestita di processi server LSP locali | Istanza IDE JetBrains aperta e sincronizzata sullo stesso workspace |
Tassonomia degli Strumenti MCP e Ottimizzazione dell’Efficienza dei Token
La suite di strumenti esposta da Serena attraverso l’interfaccia MCP è progettata per coprire l’intero ciclo di vita dell’interazione con il codebase. L’infrastruttura classifica questi strumenti in categorie funzionali specializzate, riducendo al minimo le ambiguità per l’agente e massimizzando l’accuratezza operativa.
I tool dedicati al retrieval simbolico consentono all’agente di esplorare l’architettura logica senza caricare il contenuto integrale dei file sorgente. Le funzioni come find_symbol ed get_symbols_overview forniscono una mappa sintattica del file, permettendo al modello di individuare le firme delle funzioni, le strutture dati e le classi. Strumenti come find_referencing_symbols e find_implementations consentono di ricostruire la rete di dipendenze prima di apportare una modifica, azzerando il rischio di rompere contratti di interfaccia esistenti.
Sul fronte dell’editing e del refactoring, Serena abbandona le sovrascrizioni di testo imprecise. Attraverso replace_symbol_body, l’agente invia esclusivamente la nuova implementazione del corpo di una funzione o di un metodo; il server MCP si fa carico di identificare il nodo sintattico corrispondente all’interno del file e di sostituirlo mantenendo intatti gli attributi, i commenti di documentazione e le formattazioni periferiche. Analogamente, strumenti come insert_after_symbol e insert_before_symbol permettono l’iniezione sicura di nuovo codice adiacente a simboli esistenti.
Quando viene impiegato il backend JetBrains, la categoria degli strumenti estesi introduce jet_brains_move e jet_brains_safe_delete. Il primo consente di spostare moduli o classi aggiornando automaticamente tutte le direttive d’importazione nel progetto, mentre il secondo esegue una verifica statica preliminare garantendo che l’eliminazione di un simbolo avvenga solo in assenza di riferimenti attivi nel codice.
Per garantire la continuità operativa in sessioni di lavoro prolungate, Serena integra un sistema nativo di gestione della memoria. Tale modulo permette all’agente di consultare e aggiornare file in formato Markdown memorizzati nella cartella .serena/memories/. Questo meccanismo viene impiegato per conservare decisioni di progettazione, vincoli architetturali, indicazioni stilistiche e mappe mentali del repository, evitando che l’agente debba ricostruire il contesto all’inizio di ogni nuova interazione. Infine, per mantenere la compatibilità generale, l’architettura include strumenti di utilità di base come search_for_pattern, read_file ed execute_shell_command. Tali strumenti vengono tuttavia disabilitati in automatico quando Serena opera all’interno di harness avanzati che già offrono interfacce native per il file system o la shell.
| Nome dello Strumento | Categoria di Appartenenza | Descrizione dell’Operazione | Backend Richiesto |
find_symbol | Symbol Tools | Esegue una ricerca globale o locale di simboli sintattici | LSP / JetBrains |
get_symbols_overview | Symbol Tools | Restituisce la struttura gerarchica dei simboli di un file | LSP / JetBrains |
find_referencing_symbols | Symbol Tools | Individua tutti i simboli che fanno riferimento al target | LSP / JetBrains |
replace_symbol_body | Symbol Tools | Sostituisce atomicamente il blocco di codice interno a un simbolo | LSP / JetBrains |
rename_symbol / jet_brains_rename | Symbol / JetBrains | Rinomina un simbolo e aggiorna tutte le referenze nel progetto | LSP (solo simboli) / JetBrains (esteso a file/dir) |
jet_brains_move | JetBrains Tools | Sposta simboli o file aggiornando automaticamente gli import | Esclusivo JetBrains |
jet_brains_debug | JetBrains Tools | Gestisce la sessione di debugging interattivo tramite REPL | Esclusivo JetBrains |
write_memory / read_memory | Memory Tools | Archivia o recupera informazioni persistenti sul contesto di progetto | Nativo Serena (Indipendente) |
execute_shell_command | Command Tools | Esegue comandi di sistema per avviare test, linter o build | Nativo Serena (Indipendente) |
Architettura di Configurazione Multi-Livello, Contesti e Ciclo di Vita del Progetto
La flessibilità operativa di Serena è garantita da un sistema di configurazione composito e stratificato basato su file YAML, ideato per adattarsi sia alle preferenze globali dell’utente sia alle esigenze specifiche dei singoli repository. La gerarchia di configurazione si sviluppa su quattro livelli sequenziali, dove le impostazioni più specifiche sovrascrivono quelle definite ai livelli superiori.
In cima alla gerarchia si trova la configurazione globale, memorizzata nel file serena_config.yml posizionato nella directory utente (~/.serena/ su sistemi Linux e macOS, oppure %USERPROFILE%\.serena\ su ambienti Windows).
Questo file stabilisce il backend di linguaggio predefinito, le impostazioni della dashboard web, le regole di ignore sintattico a livello di sistema e i parametri dei timeout di esecuzione. Al livello immediatamente successivo si colloca la configurazione di progetto, definita nel file .serena/project.yml presente nella radice del repository.
Questo file consente di specificare i linguaggi di programmazione attivi, il backend dedicato per il progetto, le regole di scrittura e i comandi di attivazione automatica dell’ambiente. Per evitare che personalizzazioni legate alla macchina locale vengano tracciate nel sistema di controllo versione, Serena supporta il file .serena/project.local.yml, il quale viene ignorato da git ed estende o sovrascrive le direttive del progetto.
Al di sotto della struttura dei file si trovano le configurazioni applicate a tempo di esecuzione tramite riga di comando, strutturate attraverso i concetti di contesti e modalità. I contesti adattano il set di strumenti e le istruzioni iniziali allo specifico client MCP in uso.
Tra i contesti preconfigurati si evidenziano desktop-app (orientato ad applicazioni desktop come Claude Desktop), agent (calibrato per agenti autonomi privi di supervisione umana continua), ide-assistant (ottimizzato per l’integrazione all’interno di ambienti VSCode o Cursor) e contesti dedicati quali claude-code e codex. Le modalità rappresentano invece frammenti di configurazione componibili e attivabili simultaneamente, capaci di affinare il prompt di sistema e filtrare l’accessibilità degli strumenti. Una modalità può ad esempio disabilitare gli strumenti di modifica del codice per forzare l’agente a operare in un regime di sola lettura e ispezione architetturale.
L’adozione di Serena all’interno di un repository segue un ciclo di vita strutturato. La prima fase prevede la creazione esplicita o implicita del progetto tramite la CLI di Serena (serena project create), durante la quale l’infrastruttura analizza il codice sorgente, rileva i linguaggi presenti e genera la cartella di metadati .serena/.
Successivamente, quando si utilizza il backend LSP, viene eseguita l’indicizzazione dei simboli tramite il comando serena project index. Questa operazione esegue il pre-caching della tabella dei simboli per evitare latenze durante la prima interazione dell’agente. Durante la fase di onboarding, Serena inizializza il sistema di memoria creando un file denominato memory_maintenance. Questo documento definisce le convenzioni di formattazione e le regole stilistiche che l’agente deve rigorosamente rispettare ogni volta che genera o aggiorna altre memorie di progetto.
Per garantire l’efficacia delle operazioni dell’agente, il repository deve rispettare precise pratiche di ingegneria del software. L’infrastruttura beneficia enormemente di codebase ben strutturate e modulari, mentre evidenzia limitazioni di performance di fronte a classi monolitiche prive di separazione delle responsabilità. È inoltre raccomandato iniziare le sessioni di lavoro partendo da uno stato di git pulito e da una suite di test funzionante, in modo che l’agente possa eseguire i test tramite la shell e verificare autonomamente la correttezza dei propri interventi.
Integrazione Ecosistemica e Mitigazione dell’Instruction Drift nei Modelli di Frontiera
Serena si distingue per un’elevata interoperabilità all’interno dell’ecosistema degli strumenti di intelligenza artificiale per sviluppatori. L’adozione del Model Context Protocol le consente di integrarsi senza soluzione di continuità con client terminali come Claude Code, Codex CLI, OpenCode e Gemini CLI; con plugin per ambienti di sviluppo quali Cursor, VSCode (tramite estensioni come Cline o Roo Code) e JetBrains AI Assistant; e con client desktop o web come Claude Desktop, Codex App e OpenWebUI.
Un aspetto critico emerso durante l’impiego dei modelli di frontiera di nuova generazione concerne il fenomeno dell’instruction drift o bias verso gli strumenti nativi. Modelli avanzati eseguiti all’interno dei propri ambienti CLI mostrano la tendenza a prediligere comandi bash grezzi (grep, cat, sed) a scapito degli strumenti simbolici esposti via MCP, compromettendo la precisione delle operazioni di refactoring.
Per contrastare questo fenomeno e garantire che il modello utilizzi programmaticamente gli strumenti semantici, Serena mette a disposizione una combinazione di override dei prompt e sistemi di intercettazione basati su hook. L’avvio dell’agente può essere eseguito passando una sovrascrittura esplicita del prompt di sistema tramite il comando serena prompts print-cc-system-prompt-override, riallineando l’attenzione del modello verso l’uso delle chiamate simboliche mcp__serena__*. Parallelamente, l’utility serena-hooks si integra nel ciclo di vita dell’agente intercettando gli eventi chiave.
L’evento di avvio sessione (SessionStart) invoca il comando di attivazione del progetto, preparando il server MCP e la memoria contestuale. L’evento di pre-esecuzione dello strumento (PreToolUse) gestisce due flussi distinti: quando il modello tenta di invocare comandi bash tradizionali, l’hook inietta nel contesto un promemoria prioritario che ricorda all’agente l’esistenza e la convenienza degli strumenti simbolici di Serena; quando invece il modello invoca uno strumento nativo di Serena, l’hook automatizza l’approvazione dei permessi all’interno della configurazione del client, azzerando le interruzioni per l’utente umano. Infine, l’evento di chiusura sessione (SessionEnd) gestisce la pulizia delle risorse e il rilascio dei server di linguaggio allocati.
Benchmark Comparativi, Impatto Operativo e Prospettive Future
I benchmark condotti da Oraios AI e da valutatori indipendenti su modelli di punta confermano significativi incrementi prestazionali derivanti dall’adozione dell’infrastruttura simbolica. Le valutazioni hanno confrontato le prestazioni di modelli quali Claude Opus 4.6 in Claude Code, GPT-5.4 in Codex CLI e GPT-5.4 in Copilot CLI eseguiti con e senza il supporto di Serena su task di ingegneria del software di complessità medio-alta.
I dati indicano una netta riduzione del numero di interazioni conversazionali necessarie per completare interventi di rifattorizzazione complessi. La possibilità di rinominare un simbolo o di spostare un modulo tramite una singola chiamata API riduce fino al 60% i passaggi operativi rispetto all’approccio basato su ricerche regex sequenziali e tentativi di applicazione delle patch. Inoltre, la drastica diminuzione dell’invio di testo integrale dei file si traduce in un risparmio medio di token per sessione compreso tra il 35% e il 50%, estendendo la capacità dell’agente di operare su repository di vaste dimensioni senza saturare la finestra di contesto.
Ciononostante, l’adozione di un’architettura simbolica comporta alcune considerazioni pratiche. L’installazione e la configurazione iniziale dei server di linguaggio richiedono una comprensione dell’ambiente di runtime locale, presentando una curva di apprendimento leggermente superiore rispetto all’uso di agenti basati su sola chat. Inoltre, la qualità dell’analisi semantica rimane condizionata dalla maturità del Language Server specifico per il linguaggio in uso. Per modifiche estremamente semplici o confinate a file di testo non strutturato, l’overhead di inizializzazione dei server LSP può rendere l’approccio simbolico meno immediato rispetto a una diretta modifica testuale.
L’evoluzione di Serena e del Model Context Protocol segna un passaggio fondamentale nell’architettura degli strumenti per lo sviluppo software assistito da intelligenza artificiale. Superando le limitazioni dell’editing testuale ingenuo e fornendo agli agenti l’accesso diretto alla struttura sintattica e relazionale del codice, l’infrastruttura creata da Oraios AI stabilisce un nuovo standard di precisione, efficienza e affidabilità per l’ingegneria del software generativa.