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 sviluppatori AI autonomi 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, dalle specifiche tecniche al deployment finale, utilizzando un potente flusso di lavoro skills.md e agents.md.

Invece di essere vincolati a uno stack tecnologico specifico o di scrivere script di orchestrazione Python complessi, utilizzeremo un approccio Zero-Code intuitivo in cui i requisiti seguono 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. Competenza e skills.md: una directory dedicata in cui definisci solide capacità tecniche e regole di trasferimento degli artefatti come file .md modulari.
  3. Workflow (workflows/): per definire comandi slash personalizzati che collegano senza problemi i membri del tuo team di 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

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

Cosa proverai a fare

  • Come separare il prompt engineering dell'AI dal codice dell'applicazione.
  • Come creare un agente che si mette in pausa attivamente per interpretare i commenti e le modifiche degli utenti all'interno dei file Markdown generati.
  • Come creare competenze di generazione ed esecuzione del deployment di codice dinamico e indipendente dal linguaggio.
  • Come creare comandi macro personalizzati (workflow) in un IDE agentico.

Che cosa ti serve

Prima di iniziare

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

2. Inizializzare l'area 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 l'area di lavoro:

  1. Apri l'IDE Antigravity.
  2. Apri Gestione agenti. In qualsiasi momento, puoi passare da Gestione agenti all'editor premendo CMD+E (Mac) o CTRL+E (Windows) oppure tramite i pulsanti Apri editor e Apri gestione agenti in alto a destra nella barra dei menu. .
  3. Fai clic su + Apri area di lavoro.

Per avviare una nuova conversazione all'interno di un'area di lavoro, seleziona l'area di lavoro desiderata dalla scheda Avvia conversazione o premi il pulsante Più accanto al nome dell'area di lavoro nella barra laterale.

45e7241be5552e42.png

  1. Fai clic su Apri nuova area di lavoro, assegna all'area di lavoro il nome skills-codelab e seleziona una directory locale. In questo modo, l'agente avrà una cartella principale specifica in cui creare i file senza ingombrare altri progetti. Al termine, vai alla visualizzazione Editor e poi ai passaggi (5), (6) e (7).

d84ba507939a5efc.png

  1. Fai clic con il tasto destro del mouse e crea una cartella skills-codelab.
  2. Al suo interno, crea due directory: production_artifacts e app_build.
  3. Crea una directory .agents e, al suo interno, 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 questo aspetto:

7234ea48c2b175a7.png

A cosa servono queste nuove cartelle?

  • .agents/: si tratta di una directory speciale riconosciuta in modo nativo da Antigravity. Inserendo i file qui, estendi il comportamento AI integrato di Antigravity.
  • skills/: questa cartella viene utilizzata per archiviare manuali di istruzioni tecniche specifiche (file .md) per l'AI. In questo modo, l'AI sa come eseguire attività specifiche come scrivere codice o eseguire il deployment di app, sostituendo un prompt enorme e confuso con passaggi modulari.
  • production_artifacts/: si tratta della cartella condivisa in cui i membri del nostro team automatizzato inseriranno intenzionalmente i file da leggere per l'agente successivo.
  • app_build/: l'area di lavoro designata 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. Definire il team (agents.md)

Innanzitutto, dobbiamo indicare 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 persone diverse?

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

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

  1. Il Product Manager (@pm): si concentra solo sul quadro generale. Scrive il file Technical_Specification.md e gestisce il processo di approvazione avanti e indietro con te (l'essere umano).
  2. L'ingegnere Full-Stack (@engineer): non si preoccupa della pianificazione, ma prende le specifiche del PM e si concentra interamente sulla scrittura di codice di alta qualità in qualsiasi linguaggio tu approvi.
  3. L'ingegnere QA (@qa): agisce come un nuovo set di occhi. Anziché scrivere nuove funzionalità, il suo unico obiettivo è trovare dipendenze mancanti, errori di sintassi o bug logici nel codice dell'ingegnere.
  4. Il DevOps Master (@devops): si concentra rigorosamente sull'ambiente di runtime. Sa 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 la sua responsabilità esatta nella pipeline.
  • I tratti gli conferiscono una personalità comportamentale, indicandogli come agire (ad es. "sviluppatore senior 10x" o "paranoico per la sicurezza").
  • I vincoli fungono da rigidi guardrail (ad es. "non scrivere mai codice", "segui rigorosamente l'architettura approvata").

La strutturazione dei 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 questo aspetto:

4. Programmare le competenze specializzate (skills/)

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

1. Competenza di specifica

Questa competenza funge da punto di partenza. L'agente PM la utilizza per intervistarti e definire l'architettura prima di scrivere qualsiasi 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 "Approval Gate". Anziché creare l'intera app in una sola volta e sperare che sia corretta, l'AI riceve istruzioni esplicite per mettere in pausa, attendere la tua approvazione finale e rileggere attivamente il documento se hai lasciato commenti in linea.

2. La competenza di generazione Full-Stack

Questa competenza è il costruttore 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 nelle specifiche.

3. La competenza di 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.

GenAI commette naturalmente piccoli errori di sintassi quando scrive grandi quantità di codice. Se disponiamo di una competenza di controllo separata il cui unico compito è cercare errori, aumentiamo notevolmente la percentuale di successo dell'esecuzione dell'applicazione finale.

4. La competenza di deployment dinamico

Questa competenza 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 modo sicuro i comandi del terminale nativo.

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

(Facoltativo) 5. La competenza di deployment di Cloud Run

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

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

A cosa serve un comando slash personalizzato?

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

Anziché chiedere manualmente all'AI passo dopo passo ("Agisci come PM e scrivi una specifica..." poi "Ok, ora agisci come ingegnere e scrivi codice..."), il comando /startcycle funge da orchestratore automatizzato. Collega senza problemi le persone 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 questo aspetto:

de21eeb6012ddbcd.png

6. Avviare la reazione a catena

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

Chiedi ad Antigravity:

  1. Nella casella di chat di Gestione agenti, digita / per aprire il menu dei comandi personalizzati. Seleziona o digita startcycle.
  2. Dai 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, redige una specifica solida e ti chiede l'approvazione.
  2. Apri Technical_Specification.md nell'editor IDE, aggiungi alcune note (ad es. "Usiamo Python anziché Node") e chiedi all'agente di rielaborarlo. Il file verrà rivisto autonomamente.
  3. Una volta approvato, Gemini passa in modo nativo il contesto all'ingegnere, utilizzando le specifiche approvate per scrivere il codice backend/frontend.
  4. Diventa l'ingegnere QA, corregge eventuali bug e salva il codice finale.
  5. Infine, il DevOps Master installa dinamicamente i moduli e pubblica l'applicazione nel browser.

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

11defe4c48e874cc.png

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

b9af07291806ae60.png

7. Riepilogo e passaggi successivi

Complimenti! Hai imparato come inserire cicli di iterazione collaborativa e generazione di applicazioni full-stack dinamiche in una pipeline agentica.

In questo codelab abbiamo trattato i seguenti argomenti:

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