Développement basé sur les spécifications avec la CLI Antigravity : workflows d'agent structurés avec des compétences et MCP

1. Introduction

Le vibe-coding d'un MVP est rapide, mais l'ajout de fonctionnalités en lançant plus de requêtes au hasard est la façon dont les projets échouent. Vous avez besoin d'un moyen d'intégrer de la structure et du contexte réel dans le développement assisté par l'IA. C'est là qu'intervient Antigravity CLI, un agent de codage IA qui s'exécute dans votre terminal. Seul, il peut comprendre votre base de code, exécuter des commandes et modifier des fichiers. Sa véritable puissance réside dans ce que vous y branchez :

• Les compétences fournissent à l'agent une méthodologie et des connaissances sur le domaine. Une compétence méthodologique impose des workflows de développement structurés, tandis qu'une compétence de domaine fournit des connaissances précises sur les API afin que l'agent ne fasse pas d'hallucinations.
• Les serveurs MCP fournissent à l'agent des connexions en direct à des systèmes externes, ce qui lui permet d'inspecter des schémas réels, d'exécuter des requêtes et de valider son travail par rapport à des données réelles au lieu de s'appuyer sur des connaissances d'entraînement obsolètes.

Les compétences déterminent comment l'agent réfléchit, tandis que MCP détermine ce que l'agent peut voir et avec quoi il peut interagir. Ensemble, ils transforment un agent de codage à usage général en un agent qui suit un workflow structuré basé sur des données réelles. Cet atelier de programmation vous explique comment combiner ces éléments, de l'installation de plug-ins à la livraison d'une fonctionnalité.

Objectifs de l'atelier

Les modèles de cet atelier de programmation (installation de compétences pour la méthodologie et les connaissances du domaine, connexion de serveurs MCP pour l'accès aux données en direct et exécution d'un cycle de développement basé sur les spécifications) s'appliquent à toutes les fonctionnalités que vous créez avec Antigravity CLI, quels que soient la langue, le framework ou les produits Google Cloud. Pour concrétiser ces modèles, vous allez travailler sur un exemple spécifique : l'ajout de l'intégration BigQuery à un tableau de bord d'analyse d'e-commerce.

L'application de démarrage est une application Web FastAPI qui lit les données de vente à partir de fichiers CSV statiques et affiche des graphiques (tendances des revenus, meilleurs produits, répartition de l'état des commandes, performances par catégorie). À la fin, l'application interroge les données en direct de BigQuery, l'entrepôt de données sans serveur de Google Cloud qui vous permet d'exécuter des requêtes SQL sur de grands ensembles de données sans gérer l'infrastructure. Plus précisément, vous vous connectez à l'ensemble de données thelook_ecommerce, ce qui vous permet d'accéder à l'intégralité du catalogue de commandes, de produits et de clients qu'un fichier CSV de 500 lignes ne peut pas fournir. Vous allez créer cette fonctionnalité entièrement à l'aide de la CLI Antigravity, guidé par les compétences et MCP.

La configuration de l'agent que nous utiliserons avec la CLI Antigravity se présentera comme suit :

Points abordés

• Utiliser Antigravity CLI dans Cloud Shell : lancer l'interface utilisateur textuelle, y naviguer et exécuter des commandes slash
• Que sont les compétences des agents et comment le modèle de divulgation progressive (métadonnées → instructions → ressources) permet de maintenir l'efficacité du contexte
• Trois catégories de compétences : méthodologie (superpouvoirs), efficacité (homme des cavernes) et connaissances du domaine (google/skills)
• Qu'est-ce que MCP et comment configurer un serveur MCP distant (BigQuery MCP) pour Antigravity CLI
• Exécuter un cycle de développement axé sur les spécifications : spécifier → planifier → implémenter
• (Facultatif) Fonctionnement et gestion des sous-agents dans la CLI Antigravity
• Intégrer la bibliothèque cliente Python google-cloud-bigquery à une application FastAPI
• (Facultatif) Déployer l'application sur Cloud Run à l'aide d'Antigravity CLI avec une compétence de domaine

Prérequis

• Un compte Google Cloud
• Connaître les bases de Python, des API REST et des commandes de terminal

2. Configurer votre environnement

Cette étape clone le dépôt de démarrage, configure votre projet Google Cloud et active les API dont vous avez besoin.

Ouvrir Cloud Shell

Ouvrez Cloud Shell dans votre navigateur. Cloud Shell fournit un environnement préconfiguré avec tous les outils dont vous avez besoin pour cet atelier de programmation. Cliquez sur Autoriser lorsque vous y êtes invité.

Ouvrir Cloud Shell

Cliquez ensuite sur Afficher > Terminal pour ouvrir le terminal.Votre interface devrait ressembler à ceci :

Ce sera notre interface principale, avec l'IDE en haut et le terminal en bas.

Configurer votre répertoire de travail

Clonez le dépôt associé contenant le code de démarrage de cet atelier de programmation :

💻 Copiez et exécutez cette commande dans le terminal.

git clone https://github.com/alphinside/sdd-agy-bigquery-dashboard.git
cloudshell workspace sdd-agy-bigquery-dashboard && cd sdd-agy-bigquery-dashboard

Ce dépôt contient une application de tableau de bord e-commerce complète et fonctionnelle qui lit des fichiers CSV statiques. Tout au long de cet atelier de programmation, vous utiliserez Antigravity CLI pour ajouter l'intégration BigQuery en tant que nouvelle fonctionnalité.

Voici les fichiers et répertoires clés :

• src/main.py : application FastAPI avec des points de terminaison d'API qui fournissent des données de tableau de bord
• src/data_service.py : couche de données qui lit les fichiers CSV à l'aide de Pandas
• src/templates/dashboard.html : modèle Jinja2 avec visualisations Chart.js
• data/ : fichiers CSV statiques (orders.csv, products.csv, order_items.csv) contenant un petit sous-ensemble de données e-commerce

L'application est un tableau de bord en lecture seule simple : main.py définit les points de terminaison de l'API, data_service.py lit les fichiers CSV et renvoie des données structurées, et dashboard.html affiche ces données sous forme de graphiques. L'intégration BigQuery que vous créez remplace data_service.py par un module qui interroge les données en direct au lieu de lire des fichiers statiques.

Configurer le terminal

Créer un projet Google Cloud ( facultatif)

❗ Passez cette section si vous disposez déjà de votre projet Google Cloud.

Pour créer un projet, vous pouvez le faire depuis l'interface utilisateur de la console Cloud en cliquant sur le sélecteur de projet en haut à gauche, puis sur New Project.

OU,si vous souhaitez une méthode plus rapide, exécutez la commande suivante dans le terminal.

💻 Copiez et exécutez cette commande dans le terminal.

PROJECT_ID="sdd-agy-cli-$(openssl rand -hex 5)"
gcloud projects create "$PROJECT_ID"
echo $PROJECT_ID

Cela créera un projet Google Cloud avec un ID de projet aléatoire. La commande génère l'ID du projet. Utilisez-le comme YOUR_PROJECT_ID dans la configuration ultérieurement.

Activer le terminal

Nous devons maintenant configurer notre terminal avec le projet Google Cloud sélectionné. Exécutez la commande suivante pour lister les projets disponibles et trouver l'ID du projet que vous souhaitez sélectionner.

💻 Copiez et exécutez cette commande dans le terminal.

gcloud projects list

Une liste s'affiche. Mémorisez ou copiez l'ID du projet que vous allez utiliser.

PROJECT_ID: alvin-exploratory-2
NAME: alvin-exploratory-2
PROJECT_NUMBER: 109790610330

Exécutez maintenant la commande suivante pour créer un script permettant d'activer le terminal ( ou vous pouvez simplement créer ce fichier vous-même).

💻 Copiez et exécutez cette commande dans le terminal.

cloudshell edit configure_terminal.sh

Copiez ensuite le code suivant dans le script.

📄 Copiez ce code dans le fichier et enregistrez-le.

Remplacez la valeur YOUR_PROJECT_ID par l'ID du projet sélectionné à l'étape précédente.

#!/bin/bash

gcloud config set project YOUR_PROJECT_ID
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
echo $GOOGLE_CLOUD_PROJECT

Remplacez YOUR_PROJECT_ID par l'ID du projet. La commande précédente exporte également l'ID du projet en tant que variable d'environnement pour l'utiliser tout au long de l'atelier de programmation. Enregistrez ensuite le fichier et exécutez-le.

💻 Copiez et exécutez cette commande dans le terminal.

bash configure_terminal.sh

Remarque : Si vous fermez ou redémarrez votre terminal ou votre page Web, n'oubliez pas d'exécuter à nouveau cette commande pour configurer votre terminal.

Vérifiez que le projet est correctement défini en examinant le texte jaune à côté de votre répertoire de travail dans l'invite du terminal Cloud Shell. L'ID de votre projet devrait s'afficher.

Activer les API requises

Nous allons ensuite interagir avec BigQuery, qui est lié à notre scénario d'utilisation. Activez les API Google Cloud nécessaires pour cet atelier de programmation :

💻 Copiez et exécutez cette commande dans le terminal.

gcloud services enable bigquery.googleapis.com

Remarque : L'activation des API peut prendre un certain temps. Vous n'avez besoin d'effectuer cette opération qu'une seule fois par projet.

Cette API nous permettra d'accéder à BigQuery. Préparons maintenant notre ensemble de données initial pour le scénario de cet atelier de programmation.

3. Configurer l'ensemble de données BigQuery

Voici le scénario : votre entreprise stocke déjà des données d'e-commerce dans BigQuery (commandes, produits et articles commandés). Vous développez une application pour afficher le tableau de bord des données de commande, mais pour le moment, elle ne lit qu'un petit extrait CSV de ces données afin que vous puissiez vous concentrer sur le frontend dans un premier temps. Vous souhaitez maintenant le mettre à niveau pour interroger directement BigQuery afin d'obtenir l'ensemble de données complet.

Pour simuler cela, vous utilisez TheLook E-commerce, un ensemble de données public géré par Google qui contient des données d'e-commerce synthétiques réalistes (plus de 125 000 commandes et plus de 29 000 produits). Vous copiez les tables concernées dans l'instance BigQuery de votre propre projet afin qu'elles servent de "données de votre entreprise".

Dans Cloud Shell, nous disposons déjà de l'interface de ligne de commande bq que nous pouvons utiliser pour interagir directement avec BigQuery. Nous pouvons donc préparer directement nos données.

Créez un ensemble de données dans votre projet :

💻 Copiez et exécutez cette commande dans le terminal.

bq mk --dataset $GOOGLE_CLOUD_PROJECT:thelook_ecommerce

Copiez les trois tables de l'ensemble de données public dans votre nouvel ensemble de données :

💻 Copiez et exécutez cette commande dans le terminal.

bq cp bigquery-public-data:thelook_ecommerce.orders $GOOGLE_CLOUD_PROJECT:thelook_ecommerce.orders
bq cp bigquery-public-data:thelook_ecommerce.order_items $GOOGLE_CLOUD_PROJECT:thelook_ecommerce.order_items
bq cp bigquery-public-data:thelook_ecommerce.products $GOOGLE_CLOUD_PROJECT:thelook_ecommerce.products

Vérifiez que les tables se trouvent dans votre ensemble de données :

💻 Copiez et exécutez cette commande dans le terminal.

bq ls $GOOGLE_CLOUD_PROJECT:thelook_ecommerce

Vous devriez voir trois tables listées : orders, order_items et products.

   tableId     Type    Labels   Time Partitioning   Clustered Fields  
 ------------- ------- -------- ------------------- ------------------ 
  order_items   TABLE                                                  
  orders        TABLE                                                  
  products      TABLE

Exécutez une requête de test rapide pour vérifier que les données sont accessibles :

💻 Copiez et exécutez cette commande dans le terminal.

bq query --nouse_legacy_sql \
  "SELECT COUNT(*) as total_orders FROM \`$GOOGLE_CLOUD_PROJECT.thelook_ecommerce.orders\`"

+--------------+
| total_orders |
+--------------+
|       125957 |
+--------------+

Vous devriez voir un nombre de commandes supérieur à 100 000.

4. Exécuter l'application Web initiale

Avant de mettre à niveau l'application, exécutons-la dans son état actuel pour voir à quoi ressemble le tableau de bord basé sur les fichiers CSV.

uv est un gestionnaire de packages et de projets Python rapide écrit en Rust ( documentation). Cet atelier de programmation l'utilise pour des raisons de rapidité et de simplicité. Si vous utilisez Cloud Shell pour ce tutoriel, il est déjà préinstallé dans l'instance. Consultez ce tutoriel si vous souhaitez l'installer pour votre

Installez les dépendances du projet, ce qui préparera également l'environnement virtuel pour vous :

💻 Copiez et exécutez cette commande dans le terminal.

uv sync

Ensuite, si vous connaissez Python, au lieu d'exécuter une commande python, nous exécuterons chaque commande avec le binaire uv. Lancez le serveur de développement FastAPI :

💻 Copiez et exécutez cette commande dans le terminal.

uv run uvicorn src.main:app --host 0.0.0.0 --port 8080

Ouvrez le tableau de bord dans votre navigateur à l'aide de la fonctionnalité Aperçu sur le Web de Cloud Shell. Cliquez sur le bouton Aperçu sur le Web (icône en forme d'œil dans la barre d'outils Cloud Shell), puis sélectionnez Prévisualiser sur le port 8080.

Conseil : Pour utiliser l'aperçu Web dans Cloud Shell, cliquez sur le bouton Aperçu Web (icône carrée avec un œil) dans la barre d'outils Cloud Shell, puis sélectionnez Prévisualiser sur le port 8080.

Le tableau de bord affiche quatre panneaux de graphiques :

• Tendance des revenus : graphique en courbes indiquant les revenus quotidiens au cours de la période spécifiée dans les données CSV
• Principaux produits par revenu : graphique à barres horizontales classant les produits par ventes totales
• Répartition de l'état des commandes : graphique en anneau montrant la répartition des commandes "Terminées", "Expédiées", "En cours de traitement", "Annulées" et "Retournées"
• Performances par catégorie : graphique à barres horizontales indiquant les revenus par catégorie de produits

Notez le badge Source de données : CSV dans l'en-tête. Les fiches récapitulatives affichent les totaux calculés à partir de 500 commandes et d'environ 750 articles de commande, ce qui représente un petit sous-ensemble de l'ensemble de données TheLook complet. La période est limitée à octobre-décembre 2023.

Il s'agit de notre application de référence. Nous allons maintenant la mettre à niveau pour l'intégrer à BigQuery à l'aide de l'interface de ligne de commande Antigravity.

Remarque : Pour l'instant, arrêtons le processus de l'application Web actuelle en cliquant deux fois sur Ctrl + C.

5. Configurer la CLI Antigravity

Cette étape présente Antigravity CLI, explique l'interface utilisateur du terminal et installe trois catégories de plug-ins pour améliorer notre workflow de développement. Vous découvrirez ce que sont les compétences agentiques et le MCP, et comment ils étendent les capacités d'un agent de codage IA.

Qu'est-ce que la CLI Antigravity ?

Antigravity CLI est une variante de l'agent de codage IA de Google : Antigravity pour le terminal. Il s'agit d'une interface utilisateur de terminal (TUI) légère, conçue en Go, qui se connecte au même harnais d'agent que celui de l'application de bureau Antigravity 2.0. Il lit votre base de code, exécute des commandes, modifie des fichiers et se connecte à des outils externes via MCP, le tout depuis le terminal.

Si vous utilisez Cloud Shell pour ce tutoriel, l'interface de ligne de commande Antigravity est déjà préinstallée. Pour le vérifier, exécutez la commande suivante :

💻 Copiez et exécutez cette commande dans le terminal.

agy --help

Les détails des options de commande suivantes s'affichent :

Usage of agy:
  --add-dir                       Add a directory to the workspace (repeatable) (default [])
  -c                              Short alias for --continue
  --continue                      Continue the most recent conversation
  --conversation                  Resume a previous conversation by ID
  --dangerously-skip-permissions  Auto-approve all tool permission requests without prompting
  -i                              Short alias for --prompt-interactive
  --log-file                      Override CLI log file path
  --model                         Model for the current CLI session
  --new-project                   Create a new project for this session
  -p                              Short alias for --print
  --print                         Run a single prompt non-interactively and print the response
  --print-timeout                 Timeout for print mode wait (default 5m0s)
  --project                       Project ID for the current CLI session
  --prompt                        Alias for --print
  --prompt-interactive            Run an initial prompt interactively and continue the session
  --sandbox                       Run in a sandbox with terminal restrictions enabled

Available subcommands:
  changelog       Show changelog and release notes
  help            Show help for subcommands
  install         Configure environment paths and shell settings
  models          List available models
  plugin          Manage plugins (install, uninstall, list, enable, disable)
  plugins         Alias for plugin
  update          Update CLI

Lancer la CLI Antigravity

Nous devons maintenant configurer l'interface de ligne de commande Antigravity si vous l'utilisez pour la première fois. Dans le nouvel onglet du terminal, lancez-le.

💻 Copiez et exécutez cette commande dans le terminal.

agy

Si vous l'exécutez pour la première fois, vous serez invité à sélectionner la méthode d'authentification.

Pour ce tutoriel, utilisons Google OAuth. Vous serez invité à ouvrir une URL et à sélectionner le compte Google que vous utiliserez pour vous connecter.

Après avoir cliqué sur "Authentifier", sélectionnez le compte Google, puis cliquez sur Sign In.

Une chaîne à copier s'affiche. Cliquez sur Copy to Clipboard pour la copier.

Collez-le ensuite dans l'invite de commande Antigravity CLI, comme indiqué ci-dessous.

Remarque : Utilisez Ctrl+Shift+V OU effectuez un clic droit, puis sélectionnez Paste pour copier dans le terminal.

Vous serez ensuite invité à sélectionner un thème de couleurs et à accepter les conditions d'utilisation.

Vous serez également invité à faire confiance au répertoire de l'espace de travail actuel. Acceptez-le et nous pourrons continuer. Il s'agit de l'entrée principale pour notre interaction avec la CLI Antigravity dans le terminal.

Pour l'instant, quittons l'interface de ligne de commande Antigravity et passons à la section suivante.

Remarque : Appuyez deux fois sur Ctrl+D pour quitter.

6. Personnalisation : compétences de l'agent

La CLI Antigravity est prête à l'emploi. Elle peut lire votre code, exécuter des commandes shell et modifier des fichiers. Elle dispose d'un workflow de développement limité basé sur les spécifications et sa connaissance des API spécifiques est limitée à ce qui se trouve dans ses données d'entraînement. Pour une tâche comme l'intégration de BigQuery dans une application existante, deux lacunes apparaissent :

1. Manque de processus : sans structure, l'interface de ligne de commande Antigravity peut passer directement à l'écriture de code. Pas de problème pour les petites corrections. Pour une fonctionnalité qui touche plusieurs fichiers et points de terminaison, vous vous retrouvez avec des implémentations incohérentes, des cas extrêmes manquants et aucune documentation sur ce qui a été décidé ni pourquoi.
2. Lacunes dans les connaissances : les données d'entraînement de modèle peuvent inclure des schémas de bibliothèque cliente BigQuery obsolètes, des appels d'API obsolètes ou des schémas de table incorrects. Il n'a aucun moyen de vérifier à quoi ressemble le jeu de données actuel.

Les compétences comblent le manque de processus. Une compétence de méthodologie de développement telle que superpowers impose un cycle de spécification, de planification et d'implémentation : l'agent n'écrit pas de code tant que vous n'avez pas approuvé une spécification. Une compétence de domaine telle que bigquery-basics fournit une documentation d'API actuelle et gérée par Google afin que l'agent utilise les modèles de bibliothèque cliente appropriés.

Les serveurs MCP comblent le manque de connaissances au moment de l'exécution. BigQuery MCP offre à l'agent une connexion directe à votre ensemble de données réel. Il peut lister les tables, inspecter les types de colonnes et exécuter des exemples de requêtes. L'agent fonctionne à partir de données de schéma réelles, et non de suppositions.

Examinons ces deux

Compétences agentiques

Les compétences agentiques sont un format ouvert et léger qui permet d'étendre les capacités des agents IA avec des connaissances et des workflows spécialisés. Chaque compétence est un répertoire portable et contrôlé par version avec un fichier SKILL.md, un contrat lisible par machine qui définit la façon dont l'agent gère une tâche spécifique.

Voici à quoi ressemble un répertoire de skills :

skills/<skill-name>/
├── SKILL.md          # Required: YAML frontmatter + workflow instructions
├── scripts/          # Optional: helper scripts
├── references/       # Optional: reference implementations
├── assets/           # Optional: templates or assets
└── ...                # Any additional files or directories

Une compétence est un dossier contenant un fichier SKILL.md. Ce fichier inclut des métadonnées (nom et description, au minimum) et des instructions indiquant à un agent comment effectuer une tâche spécifique. Les compétences peuvent également regrouper des scripts, des documents de référence, des modèles et d'autres ressources.

Voici le fichier SKILL.md de la compétence bigquery-basics que vous utiliserez plus tard dans cet atelier de programmation :

---
name: bigquery-basics
metadata:
  category: BigDataAndAnalytics
description: >-
  Manages datasets, tables, and jobs in BigQuery. Use when you need to interact
  with BigQuery, run SQL queries, manage BigQuery resources (datasets, tables,
  views), or perform basic data ingestion and analysis.
---

# BigQuery Basics

[Detailed instructions about BigQuery APIs, SQL patterns,
 client library usage, data ingestion patterns, etc.]

Le frontmatter YAML (nom, description et métadonnées) est ce que l'interface de ligne de commande Antigravity charge au démarrage. Il s'agit de métadonnées légères. Le corps Markdown sous --- correspond à l'ensemble complet d'instructions, qui n'est chargé que lorsqu'Antigravity détecte une tâche liée à BigQuery.

Dévoilement progressif

Les compétences utilisent un modèle de divulgation progressive à trois niveaux qui empêche la saturation de la fenêtre de contexte :

1. Couche 1 (découverte) : au démarrage, Antigravity ne lit que les métadonnées YAML de chaque compétence installée. Il sait que la compétence existe, mais rien de plus.
2. Niveau 2 (activation) : lorsque votre tâche correspond à la description d'une compétence, AGY lit l'intégralité de SKILL.md dans son contexte actif. Il sait maintenant quoi faire.
3. Couche 3 (exécution) : si nécessaire, Antigravity accède aux scripts, aux exemples ou aux ressources de la compétence. Il sait désormais comment faire.

Seules les connaissances pertinentes sont chargées au bon moment. Une compétence pour le déploiement Cloud Run ne consomme pas de contexte lorsque vous travaillez sur une requête BigQuery, par exemple.

Trois catégories de compétences

Il existe de nombreux types de compétences d'agent. Dans cet atelier de programmation, nous utiliserons trois compétences, chacune représentant une catégorie différente :

Catégorie	Compétences	Purpose
Connaissances du domaine	google/skills	Ce que l'agent sait sur les technologies spécifiques
Méthodologie	obra/superpowers	Comment développer : applique le développement piloté par les spécifications, la planification et les tests
Efficacité	JuliusBrussee/caveman	Efficacité de l'utilisation des jetons

google/skills fournit des compétences d'agent first party gérées par Google pour les produits Google. Par exemple, il fournit à l'agent des connaissances précises et à jour sur les API BigQuery, les modèles de déploiement Cloud Run et d'autres services. Sans compétences de domaine, l'agent s'appuie sur des données d'entraînement qui peuvent être obsolètes ou incomplètes. Les compétences de domaine remplacent les devinettes par une documentation à jour.

obra/superpowers est une implémentation directive d'un workflow de développement axé sur les spécifications (SDD, Specification-Driven Development). Sans framework SDD, les agents passent directement au code lorsque vous décrivez une fonctionnalité. Cela fonctionne pour les petites corrections, mais produit des résultats incohérents et difficiles à maintenir pour les tâches plus importantes. La conception axée sur les données impose un cycle structuré : clarifier les exigences → rédiger une spécification → générer un plan → implémenter selon la spécification. Chaque étape produit un artefact pouvant être examiné. L'agent ne commencera à coder que lorsque vous aurez approuvé la spécification. Il existe d'autres frameworks SDD, tels que spec-kit, agent-skills et d'autres, chacun ayant une opinion différente sur le cycle spécifier-planifier-implémenter. Cet atelier de programmation utilise les superpouvoirs comme exemple concret. La discipline sous-jacente (spécifier et planifier avant de coder) s'applique quel que soit le framework choisi.

JuliusBrussee/caveman compresse les résultats de l'agent jusqu'à 75%. Il supprime les mots de remplissage, les formules de politesse et les explications trop détaillées, tout en conservant la substance technique. Moins de jetons par réponse signifie des échanges plus productifs par session et des réponses plus rapides. Activez-le avec /caveman ou en demandant à l'agent de parler efficacement. Elle se désactive automatiquement pour les avertissements de sécurité et les actions irréversibles.

Installation des compétences agentiques

Installation de Google Skills

Commençons par installer les compétences Google nécessaires avec lesquelles nous allons interagir. Dans ce tutoriel, les principales piles technologiques que nous aborderons sont BigQuery et Cloud Run. Installons ces compétences. Nous allons utiliser la commande npx skills pour installer

💻 Copiez et exécutez cette commande dans le terminal.

npx skills add google/skills

Une interface utilisateur de terminal interactif s'ouvre. Elle propose de nombreuses compétences. Utilisez les touches fléchées et la barre d'espace pour sélectionner les compétences dont vous avez besoin pour cet atelier de programmation.

Recherchez bigquery-basics et cloud-run-basics, puis cliquez sur Espace pour les sélectionner. La case doit être grisée comme indiqué ci-dessous.

Ensuite, sur la page de sélection des agents, cliquez simplement sur Entrée pour ignorer la sélection, car l'interface CLI Antigravity est déjà incluse par défaut.

Sélectionnons le champ d'installation Project (Projet). Les compétences seront installées dans le répertoire .agents de notre répertoire de travail.

Enfin, cliquez sur Entrée pour répondre Oui et terminer l'installation. Si vous avez configuré de nombreuses skills, vous pouvez également répondre Oui pour installer la skill find-skills.

Installation de skills tiers en tant que plug-ins

Ensuite, nous allons installer les compétences obra/superpowers et JuliusBrussee/caveman. Ces compétences peuvent être installées en tant que plug-ins Antigravity CLI. Vous pouvez donc les installer à l'aide de ces commandes.

💻 Copiez et exécutez cette commande dans le terminal.

agy plugin install https://github.com/obra/superpowers
agy plugin install https://github.com/JuliusBrussee/caveman

Nous pouvons ensuite vérifier l'installation à l'aide de la commande suivante :

💻 Copiez et exécutez cette commande dans le terminal.

agy plugin list

Les résultats suivants s'affichent :

{
  "imports": [
    {
      "name": "superpowers",
      "source": "gemini-cli",
      "importedAt": "2026-07-06T01:50:36Z",
      "components": [
        "skills",
        "hooks"
      ]
    },
    {
      "name": "caveman",
      "source": "gemini-cli",
      "importedAt": "2026-07-06T01:50:37Z",
      "components": [
        "skills",
        "agents",
        "commands"
      ]
    }
  ]
}

Cela a finalisé la configuration de nos compétences. Passons à la suivante.

7. Personnalisation : outils MCP

MCP (Model Context Protocol) est un protocole ouvert qui standardise la façon dont les agents d'IA découvrent les outils externes et interagissent avec eux. Il définit un modèle client-serveur : l'agent héberge un client MCP et les outils sont exposés par les serveurs MCP. N'importe quel client compatible avec MCP peut utiliser n'importe quel serveur compatible avec MCP. L'agent n'a pas besoin de code d'intégration personnalisé pour chaque outil.

MCP utilise une architecture client-serveur :

• Hôte : application dans laquelle réside le modèle d'IA (CLI Antigravity dans ce cas)
• Client : composant de l'hôte qui gère la communication MCP (intégré à la CLI Antigravity)
• Serveur : programme léger qui expose des fonctionnalités à l'IA ( dans notre cas, nous utiliserons le serveur MCP BigQuery géré par Google Cloud).

Lorsque l'interface de ligne de commande Antigravity exécutera le workflow SDD plus loin dans cet atelier de programmation, elle aura besoin d'informations précises sur le schéma de l'ensemble de données BigQuery (noms de tables, types de colonnes, relations). BigQuery MCP permet à l'interface de ligne de commande Antigravity d'inspecter directement le schéma actif. Cela permet de générer des spécifications et du code qui font référence à des tables et des colonnes réelles, et non à des tables et des colonnes imaginaires.

Configuration MCP gérée de BigQuery

Google héberge un serveur MCP BigQuery géré sur l'infrastructure Google Cloud. Aucune configuration locale n'est requise ( vous pouvez consulter les autres produits Google Cloud compatibles dans cette documentation). Configurez la CLI Antigravity pour qu'elle s'y connecte en créant le fichier de configuration MCP dans le répertoire de votre projet :

💻 Copiez et exécutez cette commande dans le terminal.

mkdir -p .agents
cat > .agents/mcp_config.json << EOF
{
  "mcpServers": {
    "bigquery": {
      "serverUrl": "https://bigquery.googleapis.com/mcp",
      "transport": "http",
      "authProviderType": "google_credentials"
    }
  }
}
EOF

Cette configuration indique à AGY d'effectuer les opérations suivantes :

• Où trouver le serveur MCP BigQuery (serverUrl)
• Pour utiliser les identifiants Google pour l'authentification (authProviderType)

La configuration se trouve au niveau de l'espace de travail (.agents/mcp_config.json).

Nous pouvons vérifier la configuration depuis l'interface de ligne de commande Antigravity. Exécutons-la d'abord.

💻 Copiez et exécutez cette commande dans le terminal.

agy

Vérifiez ensuite la configuration en exécutant la commande à barre oblique /mcp.

🤖 Copiez et exécutez la commande suivante dans l'interface de ligne de commande Antigravity.

/mcp

Vous devriez voir quelque chose comme ceci :

Appuyez ensuite sur Esc pour quitter l'interaction avec la commande à barre oblique.

Remarque : Dans Cloud Shell, le serveur MCP BigQuery géré utilise automatiquement les identifiants par défaut de l'application (ADC) de votre Cloud Shell. Aucune configuration OAuth supplémentaire n'est requise. Si vous utilisez votre environnement local, vous devez authentifier votre commande CLI gcloud et exécuter la commande suivante :

💻 Copiez et exécutez cette commande dans le terminal

gcloud auth application-default login

Important! Par défaut, le serveur MCP BigQuery n'est PAS en lecture seule. Il peut exécuter n'importe quel code SQL généré par l'agent, y compris les instructions destructives (DROP, DELETE, TRUNCATE). Dans cet atelier de programmation, vous interrogez un ensemble de données public qui ne vous appartient pas. Les opérations destructives échouent donc en raison des autorisations. Pour une utilisation en production, consultez Contrôler l'utilisation de l'outil MCP avec IAM pour appliquer un accès en lecture seule.

Quittez la CLI Antigravity (appuyez deux fois sur Ctrl+D) pour le moment.

8. Développement de fonctionnalités avec le développement basé sur les spécifications

Une fois les compétences/plug-ins installés et le MCP BigQuery connecté, vous pouvez utiliser le workflow de développement basé sur les spécifications pour spécifier formellement la fonctionnalité d'intégration BigQuery. C'est à cette étape que l'expression "spécifier avant de coder" devient concrète.

Assurez-vous de saisir la CLI Antigravity. Pour cette démonstration, nous autoriserons l'exécution de tous les outils avec ce flag.

💻 Copiez et exécutez cette commande dans le terminal.

agy --dangerously-skip-permissions

Important : Cette option est dangereuse, car elle autorise toutes les actions. Pour en savoir plus sur les paramètres de production, consultez cette documentation. Nous n'utiliserons ce tutoriel que pour accélérer la progression de l'atelier.

Activer le mode homme des cavernes

Avant de commencer le cycle SDD, activez le mode "homme des cavernes" pour que l'utilisation des jetons reste efficace tout au long du workflow en plusieurs étapes :

🤖 Copiez et exécutez la commande suivante dans Antigravity.

/caveman:caveman

Les réponses de l'interface de ligne de commande Antigravity deviennent laconiques, en supprimant les mots de remplissage et les formules de politesse, tout en conservant la substance technique. Moins de jetons par échange signifie des conversations plus productives dans la même limite.

Démarrer la spécification SDD

Invitez la CLI Antigravity à répondre à la demande de fonctionnalité :

🤖 Copiez et exécutez la commande suivante dans Antigravity

I want to add a BigQuery integration feature to this e-commerce dashboard app. Currently it reads
from CSV files in the data/ directory. I want to replace the CSV reads with live queries
against the thelook_ecommerce dataset in my BigQuery project using the
google-cloud-bigquery Python client library.

The dashboard should show the same panels (revenue trend, top products, order status,
category performance) but with the full dataset instead of the 500-row CSV subset.

Follow spec-driven-development for development workflow, ensure spec and plan docs created following the superpowers standard in current working directory; also use Bigquery MCP to figure out the data schema.

La compétence Super pouvoirs s'active automatiquement lorsqu'elle détecte une demande au niveau d'une fonctionnalité. AGY entre dans le cycle SDD au lieu de passer directement au code.

Important : Note que la génération d'agents d'IA est dynamique et peut produire des résultats différents les uns des autres

L'interface de ligne de commande Antigravity lancera le processus pour comprendre le projet actuel et recueillir le contexte requis. Vous verrez la commande ListDir et Read s'exécuter, comme indiqué ci-dessous.

Il utilisera également la connexion BigQuery MCP que nous avons configurée précédemment pour trouver le schéma de l'ensemble de données.

Cela garantit que l'interface de ligne de commande Antigravity dispose du contexte approprié avant de commencer le développement.

Précisions sur les exigences

Antigravity CLI peut poser des questions ciblées sur le champ d'application de la fonctionnalité. Voici quelques exemples de questions typiques :

• Comment configurer l'ID du projet ?
• Comment le graphique "Tendance des revenus" doit-il être agrégé et affiché ?
• Comment aborder l'intégration ? SQL direct vs Pandas local

Vous pouvez répondre à ces questions en suivant les recommandations de l'agent.

Important : Notez qu'au milieu du processus, Antigravity effectuera des opérations et des configurations Git, car nous utilisons l'indicateur --dangerously-skip-permissions. Ceci n'est valable que pour le tutoriel. Pour un workflow réel, nous devons nous en occuper nous-mêmes.

Consulter les spécifications

Après avoir obtenu des éclaircissements, il produira un document de spécifications formel. Si vous suivez correctement les instructions, vous respecterez la convention de compétence obra/superpowers, qui consiste à créer un document de spécifications dans le répertoire docs/superpowers/specs, comme indiqué ci-dessous.

Le document de spécification doit ressembler à ceci :

# BigQuery Integration Design Specification

## Overview

This document specifies ...

## Architecture

The application currently reads ...

## Data Schema & Sources

All tables reside in the BigQuery ...

...

Important : Note que la génération d'agents d'IA est dynamique et peut produire des résultats différents les uns des autres

Après avoir examiné ces informations, nous devons confirmer les spécifications pour passer à la phase de planification.

🤖 Copiez et exécutez la commande suivante dans Antigravity

proceed with the specs

Phase de planification et exécution des sous-agents

Une fois que vous avez approuvé la spécification, l'interface de ligne de commande Antigravity la décompose en un plan d'implémentation qui sera écrit dans le répertoire docs/superpowers/plans.

Les documents du forfait listent plusieurs éléments, comme dans l'exemple ci-dessous :

• Fichiers à modifier
• Fichiers à créer/mettre à jour
• Modifications de la dépendance
• Découpage des tâches

Il recommandera également d'utiliser subagent driven development, qui est compatible avec Antigravity CLI. Au lieu d'un seul agent effectuant tout séquentiellement, Antiravity CLI peut déléguer des tâches à des sous-agents spécialisés. Lors de l'implémentation, vous pouvez voir des sous-agents tels que :

• Implémenteur de tâches : écrit le code pour une tâche spécifique du plan.
• Relecteur de tâches : examine le code implémenté par rapport à la spécification
• Relecteur final du code : effectue une révision globale de toutes les modifications avant la finalisation.

Remarque : Nous vous recommandons vivement d'utiliser un sous-agent ici, car il peut isoler des tâches spécifiques et les décharger dans leurs propres fenêtres de contexte, ce qui évite d'encombrer le thread principal avec la sortie d'exécution. Cela permet également une exécution parallèle.

Si vous recevez une invite de ce type, répondez comme suit :

🤖 Copiez et exécutez la commande suivante dans Antigravity

Use subagent driven development

Nous verrons plus tard que les sous-agents sont chargés de sélectionner les tâches une par une.

Remarque : Vous pouvez toujours discuter dans le fil principal pendant que le sous-agent est en cours d'exécution. Vous pouvez inspecter chaque contexte et détail de sous-agent actif à l'aide de la commande suivante :

🤖 Copiez et exécutez la commande suivante dans Antigravity

/agents

Conseil : Si vous rencontrez des problèmes de quota, vous pouvez vérifier l'utilisation du modèle avec la commande /usage et passer au modèle qui dispose encore d'un quota avec la commande /model . Saisissez ensuite continues pour relancer le processus.

Vous souhaitez changer d'adresse e-mail ? Vous pouvez exécuter la commande /logout . Notez que vous serez redirigé vers un autre fil de discussion. Exécutez ensuite la commande /resume pour trouver la conversation récente sur le développement de cette fonctionnalité d'atelier de programmation.

Au bout d'un moment, le développement sera terminé ( probablement après la génération de l'agent Final Code Reviewer). Nous pouvons ensuite inspecter le résultat.

Important : Si vous êtes invité à transférer les modifications vers le dépôt distant, veuillez refuser.

Mise à jour de l'examen manuel des applications

Une fois toutes les tâches terminées, nous pouvons vérifier l'application mise à jour. Quittez l'interface de ligne de commande Antigravity en appuyant deux fois sur Ctrl+D, puis exécutez la commande suivante.

💻 Copiez et exécutez cette commande dans le terminal.

bash configure_terminal.sh && uv run uvicorn src.main:app --host 0.0.0.0 --port 8080

Si le développement est réussi, vous devriez maintenant voir Total Orders affiché avec plus de 120 000 commandes et intégré à BigQuery.

Félicitations ! Vous avez réussi à intégrer BigQuery à votre application Web grâce à l'aide complète de la CLI Antigravity.

9. (Facultatif) Déployer sur Cloud Run avec Antigravity CLI

❗ Important : Pour cette section, vous devez disposer d'un projet Cloud avec un compte de facturation actif.

Le tableau de bord fonctionne localement via l'aperçu Web de Cloud Shell. Cette étape facultative permet de déployer l'application sur Cloud Run en tant que service Web accessible publiquement. Elle montre comment les compétences de domaine de l'interface de ligne de commande Antigravity s'étendent du développement aux opérations.

La compétence cloud-run-basics (du plug-in google/skills que vous avez installé précédemment) fournit à l'interface de ligne de commande Antigravity des informations sur les modèles de déploiement Cloud Run, les exigences Dockerfile, la liaison de ports et les indicateurs gcloud run deploy. Le déploiement basé sur la source (gcloud run deploy --source .) compile et déploie en une seule commande. Cloud Build gère automatiquement la conteneurisation.

Activer les API Cloud Run

Activez les API requises pour le déploiement :

💻 Copiez et exécutez cette commande dans le terminal.

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com

Saisissez ensuite "CLI Antigravity".

💻 Copiez et exécutez cette commande dans le terminal.

agy --dangerously-skip-permissions

Important : Cette option est dangereuse, car elle autorise toutes les actions. Pour en savoir plus sur les paramètres de production, consultez cette documentation. Nous n'utiliserons ce tutoriel que pour accélérer la progression de l'atelier.

Inviter la CLI Antigravity à déployer

Demandons-lui de déployer nos applications.

🤖 Copiez et exécutez la commande suivante dans Antigravity

Deploy this application to Cloud Run, name the service "bigquery-dashboard" and make it publicly accessible

Il lira la compétence cloud-run-basics pour comprendre les exigences de déploiement de l'application Web du projet en cours.

Une fois l'opération terminée, il vérifie que le déploiement a réussi et vous fournit un récapitulatif du processus de déploiement précédemment exécuté, comme dans l'exemple ci-dessous. Vous pouvez accéder à votre application avec l'URL fournie.

Vous avez maintenant déployé et rendu accessible votre application en direct à l'aide de l'interface CLI Antigravity.

10. Conclusion

Vous avez migré un tableau de bord d'e-commerce de fichiers CSV statiques vers des données BigQuery en direct, sans écrire de code d'application à la main. L'interface de ligne de commande Antigravity a géré l'implémentation grâce à un workflow de développement discipliné basé sur les spécifications, guidé par des compétences réutilisables et une connexion en direct à vos données via MCP.

Connaissances acquises

• Utiliser Antigravity CLI dans Cloud Shell pour le développement assisté par l'IA
• Découvrez ce que sont les compétences des agents et comment la divulgation progressive permet de maintenir l'efficacité de la fenêtre de contexte.
• Trois catégories de compétences : méthodologie (superpouvoirs), efficacité (homme des cavernes), connaissances du domaine (google/skills)
• Qu'est-ce que MCP et comment configurer BigQuery MCP pour accéder aux données en direct
• Exécuter un cycle de développement axé sur les spécifications (spécifier → planifier → implémenter) au lieu du vibe coding
• Comment la CLI Antigravity peut générer des sous-agents pour rendre le développement plus ciblé et efficace

Nettoyage

Pour éviter que les ressources créées dans cet atelier de programmation ne soient facturées sur votre compte Google Cloud, vous pouvez supprimer les ressources individuelles ou l'intégralité du projet.

Option 1 : Supprimer le projet (recommandé)

Le moyen le plus simple de libérer de l'espace consiste à supprimer le projet. Toutes les ressources associées au projet sont supprimées.

💻 Copiez et exécutez cette commande dans le terminal.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Important : Vous pouvez annuler cette opération de suppression pendant une durée limitée à l'aide de la commande gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}.

Option 2 : Supprimer des ressources individuelles

Si vous souhaitez conserver le projet, mais supprimer uniquement les ressources créées dans cet atelier de programmation :

💻 Copiez et exécutez cette commande dans le terminal.

bq rm -r -f $GOOGLE_CLOUD_PROJECT:thelook_ecommerce
gcloud run services delete bigquery-dashboard --region us-central1 --quiet