Crea pipeline di sviluppo autonome utilizzando agents.md e skills.md in Antigravity

1. Introduzione

In questo codelab, ti mostreremo come configurare un team di sviluppo AI autonomo divertente e assistito dall'AI direttamente sul tuo computer utilizzando l'IDE Antigravity. Creerai un'applicazione funzionante guidando un requisito durante l'intero ciclo di vita, dalla specifica tecnica all'implementazione finale, utilizzando un potente flusso di lavoro skills.md e agents.md.

Anziché essere vincolati a uno stack tecnologico specifico o scrivere complessi script di orchestrazione Python, utilizzeremo un approccio Zero-Code intuitivo in cui i requisiti vengono elaborati in un ciclo automatizzato basato su tre principi fondamentali di Antigravity:

1. agents.md: per definire esattamente chi fa parte del tuo team di AI (Product Manager, Frontend, QA, DevOps).
2. Competenze e skills.md: una directory dedicata in cui definisci competenze tecniche solide e regole di trasferimento degli artefatti come file .md modulari.
3. Workflows (workflows/): per definire slash command personalizzati che collegano senza problemi i membri del tuo team AI in una pipeline autonoma.

Combinando questi tre elementi in modo nativo in Antigravity, guiderai Gemini ad automatizzare completamente lo sviluppo di un'applicazione pronta per la produzione dall'inizio alla fine.

Cosa imparerai a fare

• Inizializza lo spazio di lavoro: configura il progetto in modo che venga compreso in modo approfondito da Antigravity.
• Definisci il team: crea un file agents.md per stabilire le tue persona AI specializzate.
• Programma le competenze: crea file .md dettagliati in una directory skills/ per definire regole tecniche rigorose e cicli di rielaborazione iterativi.
• Definisci workflow personalizzati: crea un comando slash /startcycle per automatizzare il workflow dello studio.
• Avvia la reazione a catena: utilizza un singolo comando per eseguire automaticamente l'intera pipeline multi-agente in modo efficiente.

Cosa proverai

• Come separare l'ingegneria dei prompt AI dal codice dell'applicazione.
• Come creare un agente che si interrompe attivamente per interpretare i commenti e le modifiche dell'utente all'interno dei file Markdown generati.
• Come sviluppare competenze di generazione e deployment di codice dinamico e indipendente dalla lingua.
• Come creare comandi macro personalizzati (flussi di lavoro) in un IDE agentico.

Che cosa ti serve

• Antigravity
• Browser Chrome
• Node.js (v18+) o Python 3.14 installato localmente
• (Facoltativo) gcloud CLI installata localmente

Prima di iniziare

Per i crediti Google Cloud: per aiutarti a utilizzare Antigravity con i progetti Google Cloud, riscatta i tuoi crediti Google Cloud senza costi utilizzando questo link. Puoi seguire le istruzioni qui per attivare il credito e creare un nuovo progetto.

1. Assicurati di aver installato l'IDE Antigravity (disponibile all'indirizzo antigravity.google).
2. Apri l'IDE Antigravity e assicurati di avere un'area di lavoro inizializzata dedicata e aggiornata.
3. Tieni aperto un terminale mentre lavori in modalità Editor.

2. Inizializza lo spazio di lavoro

Poiché Antigravity comprende in modo nativo i file di workflow inseriti nella directory .agents, la configurazione della pipeline di sviluppo autonoma è semplice come creare alcune cartelle standard.

Puoi configurare il tuo spazio di lavoro:

1. Apri l'IDE Antigravity.
2. Apri Agent Manager. In qualsiasi momento, puoi passare da Agent Manager all'editor premendo CMD+E (Mac) o CTRL+E (Windows) oppure tramite i pulsanti Apri editor e Apri Agent Manager nella parte superiore destra della barra dei menu. .
3. Fai clic su + Apri spazio di lavoro.

Per avviare una nuova conversazione all'interno di uno spazio di lavoro, seleziona lo spazio di lavoro desiderato dalla scheda Avvia conversazione o premi il pulsante Più accanto al nome dello spazio di lavoro nella barra laterale.

4. Fai clic su Apri nuovo spazio di lavoro, assegna il nome skills-codelab allo spazio di lavoro e seleziona una directory locale. In questo modo, l'agente ha una cartella principale specifica per creare file senza ingombrare altri progetti. Al termine, vai alla visualizzazione Editor e segui i passaggi (5), (6) e (7).

5. Fai clic con il tasto destro del mouse e crea una cartella skills-codelab.
6. Al suo interno, crea due directory: production_artifacts e app_build.
7. Crea una directory .agents e, al suo interno, crea le cartelle workflows e skills.

(In alternativa) Se preferisci utilizzare il terminale, puoi generare immediatamente questa struttura eseguendo:

mkdir skills-codelab && cd skills-codelab
mkdir -p .agents/workflows .agents/skills
mkdir production_artifacts app_build

Assicurati che la cartella abbia il seguente aspetto:

A cosa servono queste nuove cartelle?

• .agents/: si tratta di una directory speciale riconosciuta in modo nativo da Antigravity. Se inserisci file qui, estendi il comportamento dell'AI integrata di Antigravity.
• skills/: questa cartella viene utilizzata per archiviare manuali di istruzioni tecniche specifici (file .md) per la tua AI. In questo modo, l'AI sa come svolgere attività specifiche come scrivere codice o implementare app, sostituendo un prompt massiccio e confuso con passaggi modulari.
• production_artifacts/: questa è la nostra cartella condivisa in cui i membri del nostro team automatizzato lasceranno intenzionalmente i file da leggere per l'agente successivo.
• app_build/: lo spazio di lavoro designato per il codice dell'applicazione vero e proprio. L'agente Full-Stack Engineer genererà tutto il codice (ad esempio package.json, app.py, componenti React) e lo salverà direttamente in questa cartella, isolando l'origine dell'applicazione dalle istruzioni dell'AI.

3. Definisci il team (agents.md)

Innanzitutto, dobbiamo comunicare ad Antigravity chi sta lavorando a questo progetto. Anziché conservare le istruzioni in quattro diverse cartelle di progetto nidificate, centralizziamo l'identità del nostro team. Crea un file in .agents/agents.md:

Perché abbiamo bisogno di diverse buyer persona?

Quando chiedi a un'IA di creare un'intera applicazione da zero, può facilmente essere sopraffatta se la costringi a essere architetto, programmatore, tester e responsabile del deployment contemporaneamente. Centralizzando questi ruoli in agents.md, eviti che l'AI si confonda. Il PM si concentra solo sui requisiti, l'ingegnere solo sulla generazione del codice e il QA solo sulla correzione dei bug. Avrai a disposizione esperti specializzati per ogni fase della pipeline.

Il file agents.md risolve questo problema centralizzando le diverse buyer persona del tuo team:

1. Il Product Manager (@pm): si concentra solo sul quadro generale. Scrivono il file Technical_Specification.md e gestiscono la procedura di approvazione con te (l'essere umano).
2. L'ingegnere full-stack (@engineer): non si preoccupa della pianificazione, ma si limita a prendere le specifiche del PM e si concentra interamente sulla scrittura di codice di alta qualità nel linguaggio che approvi.
3. L'ingegnere QA (@qa): funge da nuovo punto di vista. Invece di scrivere nuove funzionalità, il loro unico obiettivo è trovare dipendenze mancanti, errori di sintassi o bug logici nel codice dell'ingegnere.
4. DevOps Master (@devops): si concentra rigorosamente sull'ambiente di runtime. Sanno come leggere il terminale, installare pacchetti (npm install, pip install) e avviare il server locale.

# 🤖 The Autonomous Development Team

## The Product Manager (@pm)
You are a visionary Product Manager and Lead Architect with 15+ years of experience.
**Goal**: Translate vague user ideas into comprehensive, robust, and technology-agnostic Technical Specifications.
**Traits**: Highly analytical, user-centric, and structured. You never write code; you only design systems.
**Constraint**: You MUST always pause for explicit user approval before considering your job done. You are highly receptive to user feedback and will enthusiastically re-write specifications based on inline comments.

## The Full-Stack Engineer (@engineer)
You are a 10x senior polyglot developer capable of adapting to any modern tech stack.
**Goal**: Translate the PM's Technical Specification into a beautiful, perfectly structured, production-ready application.
**Traits**: You write clean, DRY, well-documented code. You care deeply about modern UI/UX and scalable backend logic.
**Constraint**: You strictly follow the approved architecture. You do not make assumptions—if the spec says Python, you use Python. You always save your code into the `app_build/` directory.

## The QA Engineer (@qa)
You are a meticulous Quality Assurance engineer and security auditor.
**Goal**: Scrutinize the Engineer's code to guarantee production-readiness.
**Traits**: Detail-oriented, paranoid about security, and relentless in finding edge cases.
**Focus Areas**: You aggressively hunt for missing dependencies in configurations, unhandled promises, syntax errors, and logic bugs. You proactively fix them.

## The DevOps Master (@devops)
You are the elite deployment lead and infrastructure wizard.
**Goal**: Take the final code in `app_build/` and magically bring it to life on a local server.
**Traits**: You excel at terminal commands and environment configurations.
**Expertise**: You fluently use tools like `npm`, `pip`, or native runners. You install all necessary modules seamlessly and provide the local URL directly to the user so they can see the final product!

Nota come definiamo obiettivi, tratti e vincoli per ogni persona.

• Gli obiettivi indicano all'agente qual è la sua responsabilità esatta nella pipeline.
• I tratti gli conferiscono una personalità comportamentale, indicandogli come agire (ad es. "sviluppatore senior 10x" o "paranoico della sicurezza").
• I vincoli fungono da rigide barriere protettive (ad es. "non scrivere mai codice", "segui rigorosamente l'architettura approvata").

Strutturare i prompt in questo modo riduce drasticamente le allucinazioni dell'AI e garantisce che l'agente rispetti rigorosamente il flusso di lavoro richiesto.

Assicurati che la cartella abbia il seguente aspetto:

4. Programma le competenze specialistiche (skills/)

L'ingegneria delle istruzioni dettagliate è la chiave della magia del codice zero. Creeremo file di testo molto specifici per ogni competenza, assicurandoci che il PM torni indietro attivamente se richiedi una revisione.

1. Skill di specifica

Questa competenza funge da punto di partenza. Il PM lo utilizza per intervistarti e definire l'architettura prima che venga scritto il codice, evitando ore di programmazione potenzialmente sprecate.

Crea .agents/skills/write_specs.md:

# Skill: Write Specs

## Objective
Your goal as the Product Manager is to turn raw user ideas into rigorous technical specifications and **pause for user approval**.

## Rules of Engagement
- **Artifact Handover**: Save all your final output back to the file system.
- **Save Location**: Always output your final document to `production_artifacts/Technical_Specification.md`.
- **Approval Gate**: You MUST pause and actively ask the user if they approve the architecture before taking any further action.
- **Iterative Rework**: If the user leaves comments directly inside the `Technical_Specification.md` or provides feedback in chat, you must read the document again, apply the requested changes, and ask for approval again!

## Instructions
1. **Analyze Requirements**: Deeply analyze the user's initial idea request.
2. **Draft the Document**: Your specification MUST include:
   - **Executive Summary**: A brief, high-level overview.
   - **Requirements**: Functional and non-functional requirements.
   - **Architecture & Tech Stack**: Suggest the absolute best framework (e.g., Python/Django, Node/Express, React/Next.js) for the job and outline the layout/API structure.

   - **State Management**: Briefly outline how data should flow.
3. Save the document to disk.
4. **Halt Execution**: Explicitly ask the user: "Do you approve of this tech stack and specification? You can safely open `Technical_Specification.md` and add comments or modifications if you want me to rework anything!" Wait for their "Yes" or feedback before the sequence continues!

Nota il rigoroso "Gate di approvazione". Invece di creare l'intera app in una sola volta e sperare che sia giusta, l'AI riceve istruzioni esplicite per mettere in pausa, attendere la tua decisione finale e rileggere attivamente il documento se hai lasciato commenti in linea.

2. L'abilità di generazione full-stack

Questa competenza è il generatore principale. L'agente Engineer legge lo stack tecnologico esatto dalle specifiche del PM e crea dinamicamente tutti i file di codice frontend e backend necessari.

Crea .agents/skills/generate_code.md:

# Skill: Generate Code

## Objective
Your goal as the Full-Stack Engineer is to write the physical code based entirely on the PM's approved specification.

## Rules of Engagement
- **Dynamic Coding**: You are not limited to HTML/JS. You must write code in the exact language/framework defined in the approved `Technical_Specification.md`.
- **Save Location**: Save all your raw code, accurately retaining necessary folder structures, directly inside `app_build/`.

## Instructions
1. **Read the Spec**: Open and carefully study `production_artifacts/Technical_Specification.md`.
2. **Scaffold Structure**: Generate all core backend and frontend application files.
3. **Output**: Dump your code perfectly into the `app_build/` directory. Do not skip or summarize any code blocks. Ensure all `package.json` or `requirements.txt` files are present.

Questa competenza non ha uno stack predefinito (come Next.js o Django). Si basa esplicitamente sullo stack tecnologico dinamico scelto dal PM. Ciò significa che la tua singola competenza di generazione di codice funziona per qualsiasi framework approvato nella specifica.

3. La competenza Controllo

Questa competenza fornisce una rete di sicurezza. L'agente QA funge da revisore indipendente, con istruzioni specifiche per individuare dipendenze mancanti ed errori logici nel codice appena generato.

Crea .agents/skills/audit_code.md:

# Skill: Audit Code

## Objective
Your goal as the QA Engineer is to ensure the generated code is perfectly functional natively.

## Rules of Engagement
- **Target Context**: Your focus area is the `app_build/` directory.

## Instructions
1. **Assess Alignment**: Compare the raw code against the approved `Technical_Specification.md`.
2. **Bug Hunting**: Find and fix dependency mismatches, unhandled errors, and logic breaks.
3. **Commit Fixes**: Overwrite any flawed files in `app_build/` with your polished revisions.

L'AI generativa commette naturalmente piccoli errori sintattici quando scrive grandi quantità di codice. Se disponi di una competenza di controllo separata, il cui unico compito è cercare errori, aumentiamo notevolmente il tasso di successo dell'esecuzione dell'applicazione finale.

4. La skill di deployment dinamico

Questa skill dà vita all'applicazione. L'agente DevOps determina il tipo di app creata (Node, Python e così via) ed esegue in modo sicuro i comandi del terminale necessari per installare i moduli e avviare il server.

Crea .agents/skills/deploy_app.md:

# Skill: Deploy App

## Objective
Your goal as DevOps is to intelligently package the application and fire up a server based on the chosen stack.

## Instructions
1. **Stack Detection**: Inspect the `Technical_Specification.md` and the files in `app_build/` to figure out what stack is being used.

2. **Install Dependencies**: Use your native terminal to navigate into `app_build/` and run `npm install`, `pip install -r requirements.txt`, or whatever is appropriate!

3. **Host Locally**: Execute the appropriate native terminal command (e.g., `npm run dev`, `python3 app.py`) to start a background server.
4. **Report**: Output the clickable localhost link to the user and celebrate a successful launch!

Sfruttiamo la capacità dell'IDE di eseguire in sicurezza i comandi del terminale nativi.

L'agente si comporta come un vero ingegnere DevOps, capendo dinamicamente quale comando di installazione eseguire in base ai file che vede effettivamente nella cartella app_build/.

(Facoltativo) 5. The Cloud Run Deployment Skill

Se vuoi mettere in produzione la tua applicazione anziché eseguirla solo localmente, puoi creare un'abilità di deployment alternativa. Poiché Antigravity opera direttamente sulla tua macchina locale, l'AI può utilizzare senza problemi gcloud CLI autenticata localmente.

Crea .agents/skills/deploy_cloud_run.md:

# Skill: Deploy to Cloud Run

## Objective
Your goal as DevOps is to package the application into a container and deploy it to Google Cloud Run.

## Instructions
1. **Verify Environment**: Ensure the necessary files for the chosen tech stack are in `app_build/`.
2. **Containerize**: Use the IDE terminal to navigate to `app_build/` and run `gcloud run deploy --source .`. 
3. **Configure**: If prompted by the CLI tool, automatically select the default region and allow unauthenticated invocations so the web app is public.
4. **Report**: Output the live production Google Cloud Run URL to the user!

5. Definire un comando slash personalizzato

Che cosa fa un comando slash personalizzato?

Se salvi questo file di testo all'interno di .agents/workflows/ , registri un nuovo comando direttamente nell'interfaccia di chat di Antigravity.

Invece di chiedere manualmente all'AI di eseguire i passaggi uno alla volta ("Agisci come il PM e scrivi una specifica…" poi "Ok, ora agisci come l'ingegnere e scrivi il codice…"), il comando /startcycle funge da orchestratore automatizzato. Combina in modo fluido le tue personalità definite e le loro competenze specifiche in una sequenza continua e automatizzata. Creeremo una singola macro che gestisce il trasferimento tra gli agenti, gestendo esplicitamente il ciclo di rielaborazione per la fase PM.

Crea .agents/workflows/startcycle.md:

---
description: Start the Autonomous AI Developer Pipeline sequence with a new idea
---

When the user types `/startcycle <idea>`, orchestrate the development process strictly using `.agents/agents.md` and `.agents/skills/`.

### Execution Sequence:
1. Act as the **Product Manager** and execute the `write_specs.md` skill using the `<idea>`.
   *(Wait for the user to explicitly approve the spec. If the user provides feedback or adds comments directly to the Markdown file, act as the PM again to re-read and revise the document. Loop this step until they type "Approved").*
2. Shift context, act as the **Full-Stack Engineer**, and execute the `generate_code.md` skill.
3. Shift context, act as the **QA Engineer**, and execute the `audit_code.md` skill.
4. Shift context, act as the **DevOps Master**, and execute the `deploy_app.md` skill.

Assicurati che la cartella abbia il seguente aspetto:

6. Inizia la reazione a catena.

Con il tuo team e le regole definiti ufficialmente in Antigravity, puoi attivare l'intero flusso di lavoro senza problemi.

Prompt Antigravity:

1. Nella casella di chat di Agent Manager, digita / per aprire il menu dei comandi personalizzati. Seleziona o digita startcycle.
2. Inserisci la tua idea:

/startcycle "I need a fast, real-time chat application for customer support on my ecommerce website."

Rilassati e collabora:

1. Gemini diventa il PM, crea una specifica solida e ti chiede l'approvazione.
2. Apri Technical_Specification.md nell'editor IDE, aggiungi alcune note (ad esempio "Utilizziamo Python anziché Node") e chiedi all'agente di rielaborarlo. Il file verrà rivisto autonomamente.
3. Una volta approvata, Gemini passa in modo nativo al contesto dell'ingegnere, utilizzando le specifiche approvate per scrivere il codice di backend/frontend.
4. Diventa l'ingegnere QA, corregge eventuali bug e salva il codice finale.
5. Infine, DevOps Master installa dinamicamente i moduli e pubblica l'applicazione nel browser.

Un'esecuzione di esempio di Technical_Specification.md e l'attesa di approvazioni o commenti

Dopo l'approvazione dell'utente tramite il prompt, inizia l'intero flusso di lavoro.

7. Riepilogo e passaggi successivi

Complimenti! Hai imparato a inserire cicli di iterazione collaborativa e la generazione dinamica di applicazioni full-stack in una pipeline di agenti.

In questo codelab abbiamo trattato i seguenti argomenti:

• Come mappare le persona AI utilizzando .agents/agents.md.
• Crea cicli di rielaborazione collaborativa all'interno di .agents/skills/write_specs.md in modo che l'agente legga i tuoi commenti in Markdown incorporati.
• Costruite competenze dinamiche .md che scrivono codice in qualsiasi framework (Python, React) a seconda delle specifiche approvate.