Plugin per Coding Agent: Gestisci la Tua Architettura Senza Uscire dal Terminale

Il mese scorso, ho osservato uno sviluppatore del nostro team fare qualcosa che sembrava non dovesse funzionare.

Era immerso fino al collo in una sessione di refactoring in Claude Code, stava dividendo un servizio monolitico in tre servizi più piccoli. A metà del lavoro, ha scritto: "Crea tre nuovi container in Archyl — OrderService, InventoryService e NotificationService — sotto il sistema ECommerce. Aggiungi relazioni 'calls' tra OrderService e gli altri due."

Dieci secondi dopo, il C4 model in Archyl aveva tre nuovi container, correttamente collegati con le relazioni, posizionati esattamente dove dovevano essere nell'architettura. Non ha mai cambiato tab. Non ha mai aperto un browser. Ha semplicemente continuato a scrivere codice.

È stato in quel momento che ho capito che il plugin era pronto per essere rilasciato.

Il Problema del Context Switch

La documentazione dell'architettura ha un problema fondamentale di UX: vive in un posto diverso rispetto al codice.

Sei nel tuo IDE. Hai appena ristrutturato un modulo, rinominato tre servizi e diviso un database in repliche di lettura e scrittura. Il codice è fatto. Ora devi aggiornare l'architettura. Questo significa aprire Archyl nel browser, trovare il progetto giusto, navigare fino al diagramma corretto, aggiornare i container, aggiungere relazioni, magari scrivere un ADR per spiegare perché hai fatto quel cambiamento.

Ci vogliono cinque minuti. Ma quei cinque minuti hanno un costo nascosto: il context switching. Il tuo cervello deve lasciare il codice, entrare in una modalità di diagrammazione visuale, ricordare cosa hai appena fatto, tradurlo in concetti architetturali, e poi tornare a scrivere codice. La maggior parte degli sviluppatori semplicemente... non lo fa. Si dicono che aggiorneranno la documentazione dopo. Dopo non arriva mai.

Ecco perché esiste il drift architetturale. Non perché i team non si preoccupano della documentazione, ma perché lo strumento si trova nel posto sbagliato al momento sbagliato.

L'Architettura nella Tua Conversazione

Il Plugin Archyl Developer mette l'intera architettura nel contesto del tuo coding agent. È un plugin per Claude Code (e compatibile con Codex e altri agent) che insegna all'agent come usare tutti gli oltre 200 strumenti MCP di Archyl.

Cosa significa in pratica? Significa che puoi fare questo:

Durante il refactoring, di' al tuo agent di aggiornare l'architettura:

Ho appena diviso il PaymentService in PaymentProcessor e PaymentGateway.
Aggiorna l'architettura — rimuovi il vecchio container, crea i due nuovi,
e sposta tutte le relazioni esistenti sul nuovo container appropriato.

Durante la code review, chiedi informazioni sul contesto architetturale:

Ottieni il C4 model completo e dimmi quali componenti dipendono da UserRepository.
Ci sono regole di conformità che dovrei conoscere prima di modificare il data layer?

Durante la pianificazione del lavoro, verifica se la documentazione è ancora accurata:

Qual è il drift score attuale? Mostrami quali elementi sono andati in drift
e cosa pensa l'AI sia obsoleto.

Dopo una riunione di design, registra la decisione senza uscire dal terminale:

Crea un ADR: abbiamo deciso di migrare da REST a gRPC per tutte le
comunicazioni interne tra servizi. Contesto: requisiti di latenza dal team mobile.
Collegalo all'ApiGateway e a tutti i container dei servizi backend.

L'agent gestisce le chiamate MCP, gestisce gli ID dei progetti e concatena le operazioni. Tu descrivi semplicemente quello che vuoi in linguaggio naturale.

Cosa Copre il Plugin

Il plugin fornisce al tuo agent conoscenze strutturate su sette domini:

C4 Modeling — Crea e gestisci sistemi, container, componenti, elementi di codice e relazioni. L'agent comprende la gerarchia C4 e applica le convenzioni di naming corrette (PascalCase per sistemi e container, nomi esatti dei simboli per gli elementi di codice).

Documentazione — Scrivi ADR, crea documenti di progetto, definisci user flow e rivedi gli insight generati dall'AI. Gli ADR sono collegati agli elementi C4 che influenzano, così le decisioni architetturali rimangono connesse all'architettura.

Governance — Crea regole di conformità, esegui controlli di compliance e monitora il drift architetturale. L'agent può configurare le guardrail prima ancora che inizi una sessione di coding con l'AI.

Operazioni — Traccia i rilasci attraverso gli ambienti, documenta i contratti API (OpenAPI, gRPC, GraphQL), mappa i canali di eventi (Kafka, NATS, SQS) e gestisci il technology radar.

Collaborazione — Aggiungi commenti, crea change request (come le PR per l'architettura) e gestisci le whiteboard. Le discussioni sull'architettura avvengono dove avvengono le discussioni sul codice.

Cronologia — Crea snapshot, viaggia nel tempo attraverso le versioni dell'architettura e confronta le modifiche. Quando qualcuno chiede "com'era l'architettura prima della migrazione?", l'agent sa rispondere.

Integrazioni — Configura webhook per le notifiche sui cambiamenti architetturali, gestisci i widget del marketplace e visualizza l'architettura globale di tutti i progetti dell'organizzazione.

Tre Passaggi per la Configurazione

La configurazione è semplice:

1. Aggiungi il marketplace e installa il plugin:

/plugin marketplace add archyl-com/agent-skills
/plugin install archyl-developer@archyl-com-agent-skills

2. Aggiungi il server MCP al file .mcp.json del tuo progetto:

{
    "mcpServers": {
        "archyl": {
            "type": "http",
            "url": "https://api.archyl.com/mcp",
            "headers": {
                "X-API-Key": "arch_your_api_key_here"
            }
        }
    }
}

3. Riavvia il tuo agent e inizia a parlare con la tua architettura.

Tutto qui. Il plugin si carica automaticamente e l'agent sa come usare ogni strumento. Nessun file di configurazione, nessun prompt personalizzato, nessun collegamento manuale.

Perché Open Source

Il plugin è completamente open source su github.com/archyl-com/agent-skills. Ci sono diversi motivi.

Primo, trasparenza. Quando un plugin insegna a un agent AI come interagire con la tua architettura, dovresti poter leggere ogni istruzione che gli viene data. La definizione dello skill, i file di riferimento, gli esempi di workflow — è tutto lì, in semplice markdown.

Secondo, contributi. Archyl ha oltre 200 strumenti MCP, e i migliori workflow emergono dall'utilizzo reale. Quando un team scopre un pattern che funziona — ad esempio, un workflow per l'audit dell'architettura prima di un rilascio importante — può contribuirlo. Il plugin migliora perché la community lo usa.

Terzo, portabilità. Il contenuto dello skill non è vincolato a Claude Code. Funziona con qualsiasi agent che supporta il formato plugin. I manifest .claude-plugin e .codex-plugin sono entrambi inclusi. Se il mese prossimo emerge un nuovo coding agent con supporto per i plugin, il contenuto dello skill si trasferisce direttamente.

Cosa Cambia

Il cambiamento è sottile ma significativo.

Prima del plugin, la documentazione dell'architettura era un'attività separata. Scrivevi codice, poi documentavi. Due workflow, due strumenti, due modalità mentali. La documentazione era sempre un passo indietro perché era sempre un passo di distanza.

Con il plugin, la documentazione dell'architettura diventa parte della conversazione di coding. Non "aggiorni i documenti" — menzioni cosa è cambiato e l'agent se ne occupa. L'architettura resta sincronizzata non perché qualcuno si è ricordato di aggiornarla, ma perché aggiornarla è diventato senza sforzo.

Questo è particolarmente potente nei workflow agentici. Quando un agent AI apporta modifiche al tuo codebase, può simultaneamente aggiornare l'architettura. La stessa sessione che effettua il refactoring del codice aggiorna anche il C4 model, registra l'ADR ed esegue un controllo di conformità. La governance architetturale diventa una parte naturale del flusso di sviluppo, non un ripensamento.

Inizia Subito

Installa il plugin, connetti il tuo server MCP e prova a chiedere al tuo agent di descrivere la tua architettura. Poi chiedigli di fare una modifica. La prima volta che aggiorni un C4 model da una conversazione nel terminale, ti chiederai perché abbia mai funzionato in un altro modo.

Il plugin è disponibile ora. La documentazione completa si trova nelle nostre guide, e il codice sorgente è su GitHub.

La tua architettura non dovrebbe vivere in un tab diverso. Ora non deve più farlo.