Artifacts, conoscenza e piani di lavoro

In questa lezione esploreremo in profondità il cuore del workflow collaborativo con gli agenti di Antigravity: il sistema degli Artifacts, l’uso della conoscenza e la costruzione di piani di lavoro affidabili. Si tratta di concetti chiave per lavorare con efficacia all’interno della piattaforma, perché ci consentono di comprendere, verificare e guidare ciò che gli agenti fanno per noi – in modo trasparente, tracciabile e collaborativo.

Perché gli Artifacts sono fondamentali

Gli Artifacts rappresentano uno dei concetti chiave dell’intera piattaforma Antigravity. Ogni agente, infatti, durante il proprio lavoro, non si limita a generare codice o output finali, ma lascia dietro di sé una serie di tracce intenzionali e organizzate del proprio processo operativo. Gli artifacts sono quindi il risultato concreto e verificabile del ragionamento dell’agente, delle decisioni che ha preso e delle azioni che ha eseguito lungo tutto il ciclo di vita di un task.

A differenza di un semplice log o di un messaggio di output, un artifact è pensato per essere consultato, revisionato e discusso. È strutturato in modo da essere facilmente leggibile da esseri umani e utilizzabile come punto di riferimento stabile all’interno del workflow. In questo senso, gli artifacts fungono da vero e proprio ponte di comunicazione tra noi e gli agenti, permettendoci di osservare non solo il risultato finale, ma anche il percorso seguito per arrivarci.

Gli artifacts possono assumere forme diverse, a seconda della fase di lavoro e della natura del task. Possono essere task list, che descrivono in modo esplicito come l’agente ha scomposto un problema complesso in sotto-attività più semplici; piani di implementazione, che illustrano l’approccio tecnico scelto, le modifiche previste al codice e le dipendenze coinvolte; oppure walkthrough dettagliati, che spiegano passo dopo passo cosa è stato fatto e come verificare il corretto funzionamento del risultato.

Accanto a questi documenti testuali troviamo anche artifacts più visivi e dinamici, come screenshot, registrazioni del browser, output di test automatici o risultati di esecuzione. Questi elementi diventano fondamentali quando lavoriamo su interfacce utente, flussi interattivi o comportamenti che non possono essere valutati semplicemente leggendo il codice. Grazie a questi artifacts possiamo vedere con i nostri occhi ciò che l’agente ha prodotto, senza doverci fidare ciecamente del risultato.

Il valore principale degli artifacts sta nel fatto che ci permettono di capire chiaramente cosa l’agente ha pianificato e cosa ha effettivamente realizzato. Possiamo confrontare le intenzioni iniziali con l’esecuzione finale, individuare eventuali discrepanze, valutare la qualità delle scelte fatte e intervenire in modo mirato quando qualcosa non ci convince. In questo modo il lavoro con gli agenti diventa trasparente, controllabile e collaborativo, anziché opaco e automatizzato in modo incontrollato.

Tipologie principali di Artifacts

Task List

La task list è il primo artifact che incontriamo. Prima che l’agente faccia qualunque modifica al codice, esso:

• analizza la richiesta oggetto del task;
• scompone il lavoro in passi elementari;
• genera una task list strutturata.

Questa lista ci permette di vedere come l’agente intende affrontare il compito, separando il lavoro in fasi chiare e sequenziali. Possiamo revisionarla, commentarla o modificarla prima che l’agente inizi la generazione del codice. Un esempio di questo artefatto potrebbe essere:

Aggiungi un endpoint POST /users e mostrami la tasklist

La risposta dell'Agente potrebbe essere qualcosa di questo tipo:

1. Analizzare la struttura attuale delle route per gli utenti.
2. Identificare il pattern usato per la validazione degli input.
3. Verificare il modello dati dell’utente e i campi obbligatori.
4. Definire lo schema di validazione per il body della richiesta.
5. Implementare la logica di creazione dell’utente nel service layer.
6. Gestire i possibili errori (input non valido, duplicati, errori DB).
7. Integrare l'endpoint nel router Express esistente.
8. Scrivere test di integrazione per il nuovo endpoint.
9. Verificare che lo stile delle risposte HTTP sia coerente con il resto dell'API.

In questo modo, prima ancora di scrivere una riga di codice, possiamo già verificare che non manchino passaggi critici, come la presenza di test o una corretta gestione degli errori, controllare che l’agente abbia realmente compreso l’architettura del progetto, ad esempio la separazione tra route, service e model e intervenire per correggere o rifinire il piano nel caso in cui non rispetti i nostri standard tecnici, organizzativi o di qualità.

Implementation Plan

Dopo la task list, gli agenti producono un piano di implementazione. Questo artifact contiene:

• un’architettura di massima su come l’agente affronterà le modifiche;
• dettagli tecnici su quali file modificare, quali pattern adottare, quali librerie o moduli coinvolgere;
• considerazioni strutturali legate alle dipendenze e agli impatti sul progetto.

Il piano di implementazione è fondamentale: ci aiuta a capire e validare la strategia tecnica prima di accettare modifiche potenzialmente invasive.

Walkthrough / Verification Report

Al termine dell’implementazione, l’agente genera un walkthrough o un report di verifica. Questo artifact riassume:

• le modifiche effettuate;
• come testare le funzionalità appena implementate;
• eventuali risultati di test o considerazioni sul funzionamento.

Il walkthrough è la nostra prova finale prima di integrare definitivamente il lavoro nel codice base: ci permette di confermare che l’agente ha compreso correttamente il compito e lo ha eseguito secondo le nostre aspettative.

Artifacts visivi e testuali

Oltre ai documenti markdown classici, gli agenti di Antigravity possono produrre artefatti multimediali utili alla verifica del lavoro svolto, come screenshot delle pagine web generate o modificate, registrazioni del browser che documentano flussi dinamici e interattivi, risultati di test automatici corredati da statistiche di successo o fallimento, e diagrammi o output di terminale che aiutano a comprendere meglio il comportamento del sistema. Questi artifact visivi risultano particolarmente preziosi quando lavoriamo su interfacce utente, integrazioni tra sistemi o comportamenti dinamici difficili da valutare leggendo esclusivamente il codice.

Conclusioni

Gli artifacts sono il linguaggio con cui noi e gli agenti comunichiamo, verifichiamo, guidiamo e convalidiamo il lavoro di sviluppo nell’ambiente Antigravity. Comprendere cosa sono, come si generano, come si revisionano e come si trasformano in conoscenza condivisa è essenziale per sfruttare al massimo la piattaforma e mantenere il controllo nel nostro workflow di sviluppo software.

Nella prossima lezione vedremo Browser Subagent, strumenti e sicurezza, mettendo in pratica quanto appreso su task, artifacts e piani di lavoro.