Guida alla scrittura
Questa guida è il complemento pratico dei capitoli di architettura e del riferimento del linguaggio. Laddove l’architettura spiega perché Aggrega ha la forma che ha e il riferimento specifica che cosa significa ciascun campo, questa guida insegna come mettersi all’opera e scrivere — quale entità usare, in quale ordine, e come la CLI e un assistente IA ti aiutano a ottenere un file corretto con il minimo attrito.
La guida è scritta per due pubblici contemporaneamente: una persona che scrive a mano in un editor e un assistente IA che scrive per conto di una persona tramite il server Model Context Protocol. Entrambi seguono lo stesso ciclo e leggono le stesse superfici di riferimento, quindi le pagine seguenti servono a entrambi.
Leggi in questo ordine
- Scrivere i file di Aggrega — il ciclo di authoring end-to-end: scegli il tuo ruolo, impara la forma, crea lo scheletro, compila i campi, valida, esegui la build. Inizia da qui.
- Personas — i quattro ruoli di authoring che collaborano (sviluppatore, architetto, operations, operatore) e l’impostazione «indicazione, non imposizione» che li sottende.
- Entità per ruolo — ogni tipo di entità associato al ruolo che tipicamente lo possiede, così sai in quale file va ciascun aspetto.
- Installazione — installa il binario
aggrega, con i comandi per primi; la sua sezione sul collegamento rimanda a Collega il server MCP. - Usare Aggrega in Visual Studio Code — l’estensione Aggrega per Visual Studio Code: di cosa ha bisogno, la pagina di benvenuto, i suoi pannelli e il grafo della topologia, e ogni impostazione e comando.
Importazione parte da un progetto che hai già in un altro formato e ne ricava una bozza di questi file, che potrai rivedere e compilare.
Imparare Aggrega colloca questa guida in un percorso attraverso tutta la documentazione.
Lavorare con un assistente IA
- Configura Aggrega con il tuo assistente IA — un unico prompt da incollare in un assistente in grado di eseguire comandi, così che installi Aggrega, aggiunga la skill di Aggrega e si colleghi da solo al server.
- Collega il server MCP — la voce del server client per client, dove la tiene ciascun client, un server raggiunto via HTTPS e come verificare il collegamento.
- La skill di Aggrega — le istruzioni che un assistente carica per Aggrega: come installarle e tenerle aggiornate.
- Che cosa può fare il tuo assistente con Aggrega — ciò che il server collegato permette a un assistente di leggere, verificare, compilare e pubblicare.
Come le superfici dell’assistente si relazionano a questa guida
Il server aggrega mcp espone questa guida, il riferimento del linguaggio e i JSON Schema come risorse che un assistente legge prima di scrivere YAML, oltre a strumenti che creano lo scheletro delle entità e le validano. I prompt di authoring integrati dell’assistente rimandano a queste pagine invece di ripeterle, così questa guida è l’unica sede in prosa del metodo di authoring. Vedi Scrivere i file di Aggrega per il ciclo e Collega il server MCP per il collegamento.