Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Scrivere i file di Aggrega

In Aggrega la scrittura è un ciclo breve e ripetibile. Qualunque entità tu stia scrivendo — l’Aggregate di uno sviluppatore, il Component di un architetto, una Recipe delle operations o la Release di un operatore — le stesse cinque mosse ti portano da un file vuoto a un file validato:

  1. Scegli l’entità di cui è responsabile il tuo ruolo.
  2. Impara la sua struttura dal JSON Schema e dalla pagina di riferimento.
  3. Parti da uno scheletro anziché da un file vuoto.
  4. Compila i campi di cui è responsabile il tuo ruolo, lasciando il resto ai rispettivi responsabili.
  5. Valida, poi compila.

Questa pagina percorre il ciclo una volta, sia per chi scrive a mano sia per un assistente IA che scrive tramite il server Model Context Protocol. I due percorsi sono lo stesso ciclo sulle stesse superfici di riferimento. Entrambi richiedono il binario aggrega: Installa il binario lo installa con un solo comando.

1. Scegli l’entità di cui è responsabile il tuo ruolo

Aggrega separa la scrittura in quattro ruoli che collaborano — l’intento dello sviluppatore, il catalogo della piattaforma, le ricette dell’infrastruttura e il cablaggio del deployment. Ogni ruolo è in genere responsabile di un insieme specifico di tipi di entità. Se conosci già il tuo ruolo, passa direttamente all’entità che ti serve; altrimenti leggi Personas per i quattro ruoli ed Entità per ruolo per la mappa completa da tipo a ruolo.

La separazione è un’indicazione, non una regola imposta dal compilatore. Un autore che lavora da solo è libero di ricoprire ogni ruolo e scrivere tutte le entità in una sola sessione; il compilatore accetta qualsiasi modalità di scrittura che superi la validazione dello schema. I ruoli esistono per mantenere chiare le competenze, non per limitare ciò che puoi scrivere.

2. Impara la sua struttura

Ogni tipo di entità ha un JSON Schema canonico e una pagina di riferimento campo per campo. Leggili entrambi prima di scrivere:

  • Lo schema è la struttura esatta: campi obbligatori, valori ammessi e annidamento. Dalla riga di comando, aggrega get-schema <kind> lo stampa; aggrega get-schema --list elenca ogni tipo che puoi richiedere. Un assistente legge gli stessi byte dalla risorsa schema://<kind>. Consulta il riferimento di aggrega get-schema.
  • La pagina di riferimento spiega che cosa significa ogni campo e come i campi sono collegati tra loro. Le pagine delle entità si trovano in language-reference/entities/ — ad esempio component o aggregate. Un assistente legge la stessa pagina dalla risorsa langref://entities/<kind>.

Lo schema ti dice che cosa è strutturalmente valido; il riferimento ti dice che cosa è sensato. Leggi lo schema per evitare un rifiuto in fase di validazione e il riferimento per scrivere qualcosa che faccia ciò che intendi.

3. Parti da uno scheletro

Partire da uno scheletro è più rapido e meno soggetto a errori di un file vuoto. Un assistente collegato al server MCP chiama lo strumento scaffold con un tipo e un nome per ottenere un punto di partenza minimo che contiene ogni campo richiesto dal tipo, con un segnaposto dove un valore è ancora dovuto. Scrivendo a mano, aggrega scaffold <kind> <name> stampa lo stesso punto di partenza sullo standard output, quindi reindirizzalo in un file; oppure copia l’esempio svolto più vicino e riducilo a ciò che ti serve.

In entrambi i casi lo scheletro contiene già i campi di primo livello obbligatori (apiVersion, kind, metadata.name) nella forma corretta, così dedichi la tua attenzione ai campi di cui è responsabile il tuo ruolo anziché al codice ripetitivo.

4. Compila i campi di cui è responsabile il tuo ruolo

Compila solo i pilastri di cui è responsabile il tuo ruolo e lascia gli altri ai rispettivi responsabili. Uno sviluppatore fornisce l’intento applicativo e i valori; un architetto dichiara il contratto — i valori che uno sviluppatore può fornire, gli output che un componente fornisce, i socket che espone; le operations mappano quel contratto su un provider specifico senza modificare la superficie rivolta allo sviluppatore; un operatore cabla il deployment. Entità per ruolo indica quali pilastri appartengono a quale ruolo per ogni tipo.

Mantenere ogni valore nel pilastro controllato dal suo responsabile è ciò che permette allo stesso intento dello sviluppatore di puntare a infrastrutture diverse nei vari ambienti senza che il file dello sviluppatore cambi. È il motivo stesso per cui la superficie di scrittura è suddivisa.

Limita la descrizione a pochi paragrafi brevi. Il metadata.description di un’entità è il testo che un lettore incontra prima di sceglierla: viene pubblicato con l’entità come sua descrizione ricercabile, e aggrega search confronta una query con esso. Scrivilo per quel momento, in paragrafi brevi — in un blocco ripiegato description: >, una riga vuota ne inizia uno nuovo — dicendo che cos’è l’entità, come la usa un lettore, dove viene realizzata e che cosa non fa. Anche un limite che un lettore deve conoscere prima di scegliere l’entità va lì, espresso brevemente. Tutto il resto — perché un valore predefinito è quello che è, come si comporta un’impostazione su un target, che cosa significa un valore in ciascuna realizzazione — va nei commenti YAML accanto al campo o al blocco che spiega, dove lo leggerà chi lavora con quel campo. Nulla nel compilatore limita la lunghezza di una descrizione o agisce in base a ciò che dice, quindi mantenerla breve serve al lettore.

5. Valida, poi compila

Controlla il file prima di farci affidamento:

  • Un assistente chiama lo strumento validate, che riporta gli errori di schema e di riferimento direttamente, così può correggere la bozza prima di restituirla.
  • A mano, aggrega validate <file> verifica un singolo file di Component, Feature, Recipe, FeatureRecipe, Workload o Plugin, e aggrega validate --release <release> verifica tutto ciò che una Release raggiunge, inclusi il suo Aggregate e il suo Manifest. aggrega lint applica le regole della disciplina di pubblicazione a un’entità del catalogo, e aggrega inspect risolve e mostra ciò che vede il compilatore. Quando l’intera topologia è pronta, aggrega pull --release <release> ne risolve le dipendenze e scrive il suo lockfile, e aggrega build --release <release> compila poi la Release in artefatti per confine — una build fallita indica esattamente che cosa correggere.

Validare presto costa meno di una build fallita tardi. Scrivi, valida, correggi e solo allora compila.

Scrivere con un assistente IA

Il comando aggrega mcp esegue un server Model Context Protocol che trasforma qualsiasi client compatibile con MCP in un assistente di scrittura che conosce Aggrega. Una volta collegato, l’assistente può:

  • Assumere un ruolo tramite i prompt di scrittura integrati — uno per persona (sviluppatore, architetto, operations) più un modello mirato per singola entità. Ogni prompt inquadra il ruolo e indirizza l’assistente allo schema, alla pagina di riferimento e a questa guida, così i suoi suggerimenti restano entro i pilastri di cui è responsabile il ruolo.
  • Leggere il riferimento tramite le risorse: schema://<kind> per il JSON Schema di un tipo, langref://<path> per qualsiasi pagina di riferimento e authoring://<topic> per questa guida.
  • Agire sul tuo workspace tramite gli strumenti: scaffold per avviare uno scheletro corretto, validate per controllare una bozza, describe per ispezionare un’entità del catalogo e get-schema per recuperare uno schema per tipo.

Tutto ciò che l’assistente legge viene servito dalla tua macchina: gli schemi sono integrati nel binario, e le pagine della guida e del riferimento provengono dal pacchetto della documentazione conservato nella cache della tua macchina, che il server scarica dal registry quando si avvia e non vi trova alcuna copia. Leggere una pagina, creare uno scheletro e validare non raggiungono la rete; dove il pacchetto non può essere scaricato, gli schemi vengono comunque serviti e le pagine no. Per collegare un client, segui Collega il server MCP; Che cosa può fare il tuo assistente con Aggrega copre il resto di ciò che raggiunge. Per il comando stesso, vedi il riferimento di aggrega mcp.

Dove andare dopo