Spezifikationsgesteuerte ADK-Agentenentwicklung mit Antigravity und Spec-kit

1. Einführung

Wenn Sie einem vorhandenen Agenten Funktionen hinzufügen – in der Regel eine neue datenbankgestützte Funktion –, müssen Sie Boilerplate-Code schreiben, Integrationen einrichten und dafür sorgen, dass alles mit den Mustern in der Codebasis übereinstimmt. Antigravity beschleunigt jede Phase dieses Prozesses: Es analysiert Ihre Codebasis, um den erforderlichen Kontext zu erstellen, erstellt strukturierte Spezifikationen und Implementierungspläne zur Überprüfung und führt die Codeänderungen aus. Dabei wird es von Fachwissen geleitet, das Sie als wiederverwendbare Skills und eine Projektkonstitution erfassen können, die nicht verhandelbare Grundsätze durchsetzt. In diesem Codelab wird eine Möglichkeit vorgestellt, das Spec-driven Development-Paradigma von Antigravity zu optimieren, indem ein neuer Zyklus eingeführt wird, um die Spezifikationsdokumentation, die sich stark auf spec-kit bezieht, zu verbessern.

Aufgaben

Eine lokal ausgeführte Restaurant-Concierge-Anwendung mit Reservierungsbuchung, die über einen vollständigen SDD-Zyklus hinzugefügt wurde:

• Reservierungsbuchung: Gäste buchen Tische und prüfen Reservierungen. Dies wird durch neue MCP Toolbox-Datenbanktools und eine Cloud SQL-reservations-Tabelle unterstützt.
• (Herausforderung): Entwickeln Sie eine eigene Benutzeroberfläche für den Agent.
• (Challenge): Mit dem Antigravity-Agent in Google Cloud bereitstellen

Der Startercode enthält einen funktionierenden ADK-Agenten mit Menüsuche (Keyword + semantisch über MCP Toolbox) und Erfassung von Ernährungspräferenzen (über ToolContext). Sie können es erweitern, ohne Anwendungscode manuell zu schreiben – Antigravity übernimmt die Implementierung basierend auf Ihren Spezifikationen.

Lerninhalte

• Projektkontext so booten, dass Antigravity eine vorhandene Codebasis versteht
• Antigravity-Skills erstellen, die Domainwissen (z.B. ADK-Codelab-Muster) zur Wiederverwendung enthalten
• Festlegen einer Projektverfassung, anhand derer die SDD-Workflows während der Planung und Analyse validiert werden
• Spezifikationsbasierte Entwicklung (Spec-Driven Development, SDD) in Antigravity verwenden, um systematisch Funktionen hinzuzufügen
• ADK-Agenten mit neuen datenbankgestützten Tools über die MCP Toolbox erweitern

Vorbereitung

• Google Antigravity und git auf Ihrem lokalen Computer installiert
• Ein Google Cloud-Konto mit einem aktiven Rechnungskonto
• Es ist hilfreich, wenn Sie die vier erforderlichen ADK-Codelabs bereits abgeschlossen haben oder über entsprechende Kenntnisse verfügen, um den Kontext des Anwendungsfalls zu verstehen:
• KI-Agenten mit ADK erstellen: Grundlagen
• KI-Agenten mit ADK erstellen: Tools hinzufügen
• Persistente KI-Agenten mit ADK und Cloud SQL erstellen
• ADK-Agenten in Cloud Run bereitstellen, verwalten und beobachten
• Datenbank als Tool: agentische RAG mit ADK, MCP Toolbox und Cloud SQL

2. Umgebung einrichten

WICHTIGE HINWEISE:

Für diese Anleitung ist ein Google Cloud-Projekt mit einem aktiven Rechnungskonto erforderlich. Wenn Sie noch keines haben, können Sie über das Banner oben in diesem Codelab ein Testabrechnungskonto erstellen, das Sie für dieses Tutorial verwenden können.

In diesem Schritt wird das Starter-Repository geklont, die Authentifizierung bei Google Cloud durchgeführt, eine Cloud SQL-Datenbank bereitgestellt und Ihre lokale Antigravity-Umgebung vorbereitet.

Hinweise:Dieses Codelab wird vollständig in Google Antigravity auf Ihrem lokalen Computer ausgeführt. Die Einrichtung umfasst die manuelle Authentifizierung mit dem gcloud-CLI-Befehl.

Erforderliche Komponenten installieren

Prüfen Sie, ob auf Ihrem System die folgende ausführbare CLI-Datei vorhanden ist:

• git
• gcloud
• uv
• npm

Die Installationsanleitung variiert je nach Betriebssystem Ihres Computers.

Starter-Repository klonen

Öffnen Sie ein Terminal in Antigravity (oder das Systemterminal). Klonen Sie das Begleit-Repository und wechseln Sie in das Verzeichnis:

git clone https://github.com/alphinside/sdd-adk-antigravity-starter.git sdd-adk-agents-agy
cd sdd-adk-agents-agy

Öffnen Sie das geklonte Repository in Antigravity. Datei -> Ordner öffnen -> wählen Sie das geklonte Verzeichnis sdd-adk-agents-agy aus.

Entfernen Sie die Upstream-Fernbedienung. In den SDD-Workflows werden Git-Branches für Funktionsspezifikationen erstellt. Durch das Entfernen des Remote-Repository wird verhindert, dass versehentlich Push-Vorgänge in das Starter-Repository ausgeführt werden:

git remote remove origin

Wichtig:In den SDD-Workflows in diesem Codelab werden git-Branches verwendet, um Funktionsspezifikationen zu organisieren. Wenn Sie das Remote-Repository origin entfernen, bleiben Ihre lokalen Branches und Commits lokal. Wenn Sie Ihre Arbeit sichern möchten, fügen Sie Ihr eigenes Remote-Repository hinzu: git remote add origin <your-repo-url>

Mit Google Cloud authentifizieren

Führen Sie zwei Authentifizierungsbefehle aus. Beide öffnen einen Browser für OAuth:

gcloud auth login
gcloud auth application-default login

Hinweise:Beim zweiten OAuth-Befehl werden Sie aufgefordert, eine Berechtigung auszuwählen. Alle Optionen prüfen

Hinweise:Achten Sie darauf, dass Sie sich mit der E‑Mail-Adresse authentifizieren, mit der Sie das Rechnungskonto für den Testzeitraum beanspruchen.

Da Sie lokal mit Antigravity arbeiten, authentifizieren Sie sich manuell. auth login authentifiziert die gcloud-Befehlszeile. application-default login authentifiziert Google Cloud SDKs, die von Ihrer Anwendung verwendet werden. Sowohl die Vertex AI-Aufrufe des ADK als auch der Cloud SQL-Python-Connector basieren auf Standardanmeldedaten für Anwendungen.

Google Cloud-Projekt einrichten

Schreiben Sie die Standortvariablen in .env, bevor Sie das Setupscript zur Projekteinrichtung ausführen:

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env

• GOOGLE_CLOUD_LOCATION=global wird für Vertex AI-/Gemini API-Aufrufe verwendet.
• REGION=us-central1 wird für Cloud SQL und andere GCP-Infrastrukturen verwendet.

WICHTIG! Der folgende Schritt soll Ihnen helfen, das Google Cloud-Projekt, das mit einem Testabrechnungskonto (streng) verknüpft ist, schnell einzurichten. Wenn Sie lieber Ihr eigenes vorheriges Projekt verwenden möchten, können Sie den folgenden Schritt überspringen und stattdessen den folgenden Schritt ausführen:

Fügen Sie den Namen Ihres eigenen Projekts als Variable GOOGLE_CLOUD_PROJECT in die Datei .env ein.

Aktivieren Sie Ihr Projekt im Terminal mit gcloud config set project your-project-id.

Sie können dann direkt zum Abschnitt „API aktivieren“ springen.

Wenn Sie sich nicht sicher sind, fahren Sie mit dem nächsten Abschnitt fort.

Laden Sie das Projekt-Setupskript herunter und führen Sie es aus. Damit wird ein Google Cloud-Projekt mit Testabrechnung erstellt oder validiert und die Projekt-ID in .env gespeichert. Anschließend wird die Quelle abgerufen:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

bash setup_verify_trial_project.sh && source .env

API wird aktiviert...

Aktivieren Sie die erforderlichen APIs:

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  cloudresourcemanager.googleapis.com

Hinweise:Das Aktivieren von APIs kann einige Zeit dauern. Dies ist nur einmal pro Projekt erforderlich.

Abhängigkeiten installieren

Wir verwenden uv als Python-Projektmanager. uv ist ein schneller Python-Paket- und Projektmanager, der in Rust geschrieben wurde ( Dokumentation ). In diesem Codelab wird er aus Gründen der Geschwindigkeit und Einfachheit verwendet. Installieren Sie die Python-Abhängigkeiten:

uv sync

Aktualisieren Sie dann die Datei .env des ADK-Agents mit Ihrer Projektkonfiguration:

cat > restaurant_concierge/.env <<EOF
GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
EOF

Datenbankinfrastruktur und Daten vorbereiten

Legen Sie das Datenbankpasswort fest und fügen Sie es .env hinzu:

export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env

Wichtig:Das oben hartcodierte Passwort dient nur zu Schulungszwecken. In einer Produktionsumgebung sollten Sie Anmeldedaten sicher mit einem Dienst wie Secret Manager speichern und zur Laufzeit darauf verweisen. Übergeben Sie niemals Klartext-Secrets an die Quellcodeverwaltung.

Führen Sie dann das scripts/setup_database.sh-Skript aus, um die erforderliche Infrastruktur vorzubereiten. Dabei wird Folgendes ausgeführt:

• Cloud SQL-Instanz erstellen
• Prüfen, ob die Instanz bereit ist
• Vertex AI-Berechtigungen erteilen
• Datenbank erstellen
• Seed-Datenbank
• MCP Toolbox-Dienst im Hintergrund ausführen

chmod +x scripts/setup_database.sh
./scripts/setup_database.sh > database_setup.log 2>&1 &

Mit diesem Befehl wird die Einrichtung im Hintergrund ausgeführt. Sie können die Ausgabe regelmäßig in der Datei database_setup.log prüfen.

Jetzt sollten wir alle erforderlichen ADK-Agent-Repos haben, mit denen wir arbeiten können. Im nächsten Abschnitt geht es um Antigravity und die spezifikationsgetriebene Entwicklung.

3. Startercode ansehen und spezifikationsbasierte Entwicklung verstehen

In diesem Schritt wird die Struktur des Startcodes erläutert, die Spec-Driven Development-Methodik vorgestellt, die Datenbank mit Daten gefüllt und geprüft, ob der Basis-Agent funktioniert, bevor Sie ihn erweitern.

Projektstruktur

Öffnen Sie das geklonte Repository-Projekt im Antigravity-Editor und sehen Sie sich das Verzeichnislayout an:

sdd-adk-agents-agy/
├── .agents/
│   ├── workflows/                 # SDD slash commands (/speckit.*) – manual trigger
│   │   ├── speckit.specify.md
│   │   ├── speckit.clarify.md
│   │   ├── speckit.plan.md
│   │   ├── speckit.tasks.md
│   │   ├── speckit.analyze.md
│   │   ├── speckit.implement.md
│   │   ├── speckit.checklist.md
│   │   └── speckit.constitution.md
│   ├── skills/                   # Antigravity skills (loaded on demand, agent determined)
│   │   ├── mcp-toolbox-postgres/
│   │   │   └── SKILL.md     # MCP Toolbox config skill
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis skill
│   └── rules/               # Always-active context
├── .specify/                # spec-kit SDD templates and memory
│   ├── memory/constitution.md
│   ├── templates/
│   └── scripts/
├── restaurant_concierge/    # ADK agent package
│   ├── __init__.py
│   ├── agent.py             # LlmAgent + ToolContext tools + Toolbox integration
│   └── .env                 # Vertex AI configuration
├── server.py                # FastAPI server wrapping the agent
├── tools.yaml               # MCP Toolbox tool definitions
├── scripts/                 # Setup scripts
└── pyproject.toml

Schlüsseldateien

Dateien für die Agentenanwendung

• restaurant_concierge/agent.py: Der Kern-Agent. Ein LlmAgent, das Datenbanktools der MCP Toolbox mit der ToolContext-basierten Erfassung von Ernährungspräferenzen kombiniert. Der Agent lädt alle Tools vom Toolbox-Server und fügt zwei Python-Funktionen (save_dietary_preference, get_dietary_preferences) hinzu, die ToolContext zum Verwalten des Status verwenden.
• tools.yaml – Definitionen von MCP-Toolbox-Tools. Es sind drei Menü-Suchoptionen definiert: die Stichwortsuche (search_menu), die semantische Suche über pgvector (semantic_search_menu) und der Kategoriefilter (get_menu_by_category). Es sind noch keine Reservierungstools vorhanden. Diese fügen Sie später hinzu.
• server.py: Ein minimaler FastAPI-Server, der zeigt, wie Sie als FastAPI-Objekt auf das ADK zugreifen können. get_fast_api_app() aus dem ADK bietet integrierte Endpunkte, darunter /run_sse für SSE-Streaming und APIs für die Sitzungsverwaltung.

Antigravity-Dateien

• .agents/skills/mcp-toolbox-postgres/SKILL.md: Ein Skill, der Antigravity anleitet, wie eine korrekte tools.yaml-Konfiguration für die MCP-Toolbox erstellt wird. In diesem Kurs lernen Sie die Konfigurationen für sources, tools und embeddingModels kennen , die für die Erstellung einer geeigneten RAG-Pipeline erforderlich sind. Dieser Skill wird erst aktiviert, wenn Sie die richtige YAML-Frontmatter hinzufügen, damit er von Antigravity erkannt wird.
• .agents/skills/repo-research/SKILL.md: Eine Funktion, mit der Antigravity lernt, ein Repository inkrementell zu analysieren und ein strukturiertes Projektkontextdokument zu erstellen. Dabei wird ein 4-Phasen-Ansatz verwendet: Oberflächenscan (nur Verzeichnisbaum), Konfigurations- und Metadatendateien, Einstiegspunkte und Datenmodelle sowie gezielte Analysen. In jeder Phase werden die Ergebnisse gespeichert, bevor mit der nächsten fortgefahren wird. Sie ist auch inaktiv, bis Sie später YAML-Frontmatter hinzufügen. Rufen Sie es nach der Aktivierung auf, um .agents/rules/project-context.md zu generieren – ein umfassendes Onboarding-Dokument, das Architektur, Laufzeitabhängigkeiten, API-Oberfläche und Domänen-Glossar abdeckt.

Spezifikationsgetriebene Entwicklung: von der integrierten Planung in Antigravity zur strukturierten SDD

KI-Code-Assistenten erleichtern das Generieren von Code aus einem Prompt. Das Risiko: Sie beschreiben eine Funktion in einem Satz, der Assistent schreibt Hunderte von Zeilen und Sie akzeptieren das, weil es richtig aussieht. Das wird manchmal auch als „Vibe Coding“ bezeichnet. Sie steuern die KI dabei intuitiv und akzeptieren oder lehnen die Ausgabe ab, je nachdem, ob sie zu funktionieren scheint. Es ist schnell für Prototypen und Einwegskripts. Das funktioniert nicht mehr, wenn die Codebasis wächst, wenn Funktionen interagieren oder wenn Sie sich Wochen später Code ansehen und nicht mehr nachvollziehen können, warum eine Entscheidung getroffen wurde.

Spec-Driven Development (SDD) gibt diesem Zyklus eine Struktur. Bevor Code generiert wird, schreiben Sie eine Spezifikation: Was macht das Feature, für wen ist es gedacht und was sind die Erfolgskriterien? Der KI-Assistent arbeitet auf Grundlage dieser Spezifikation – und Sie auch, wenn Sie seine Ausgabe überprüfen. Die Spezifikation wird zur einzigen Quelle der Wahrheit für den Intent. Wenn der Code von der Spezifikation abweicht, wird dies bei der Überprüfung festgestellt. Wenn sich die Anforderungen ändern, aktualisieren Sie zuerst die Spezifikation und generieren Sie sie dann neu. Entscheidungen werden dokumentiert, nicht improvisiert.

Das ist ein echter Kompromiss: SDD ist pro Funktion langsamer als die Vibe-Codierung. Sie schreiben Dokumente, bevor Sie Code schreiben. Aber die Vorteile summieren sich: Jede zukünftige Änderung der Codebasis hat Kontext, jede KI-generierte Implementierung hat einen überprüfbaren Vertrag und Sie können Mitbearbeiter (menschlich oder KI) einarbeiten, indem Sie sie auf Spezifikationen verweisen, anstatt Entscheidungen aus dem Gedächtnis zu erklären.

Antigravity folgt bereits den Prinzipien der spezifikationsbasierten Entwicklung. Wenn Sie den Agent in den Planungsmodus versetzen, werden zwei Artefakte erstellt, bevor Code geschrieben wird:

• Implementierungsplan: Eine Übersicht über den vorgeschlagenen technischen Ansatz, Dateiänderungen und Architektur-Entscheidungen
• Aufgabenliste: eine strukturierte Aufschlüsselung von Arbeitselementen

Antigravity fordert Sie auf, diese Artefakte vor der Ausführung zu prüfen und zu genehmigen. Dieser Planungs- und Implementierungszyklus ist das Herzstück der spezifikationsgesteuerten Entwicklung: Spezifikationen leiten den Code und nicht umgekehrt.

In diesem Codelab wird diese Grundlage mit einem meinungsbasierten, versionskontrollierten Workflow auf Basis von spec-kit weiter ausgebaut – einem spezifikationsbasierten Entwicklungsframework von GitHub. Jedes Feature durchläuft eine sorgfältig durchdachte Pipeline, in der jedes Artefakt ein eigenständiges Dokument ist, das Sie in git überprüfen, bearbeiten und nachverfolgen können. Die Pipeline umfasst zwei optionale Quality-Gate-Phasen („Klären“ und „Analysieren“), in denen Probleme erkannt werden, bevor sie zu Implementierungsproblemen werden:

Phase	Artefakt	Purpose
/speckit.specify	spec.md	Definieren Sie, WAS entwickelt werden soll (nutzerorientiert, technologieunabhängig).
/speckit.clarify (optional)	Aktualisiert: spec.md	Unterbestimmte Bereiche identifizieren, gezielte Fragen zur Klärung stellen, Antworten wieder in die Spezifikation aufnehmen
/speckit.plan	plan.md, data-model.md, research.md	Entwerfen, WIE es erstellt werden soll (technischer Ansatz, Datenmodelle, Recherche)
/speckit.tasks	tasks.md	Plan in geordnete, umsetzbare Schritte unterteilen
/speckit.analyze (optional)	Analysebericht	Aufgaben vor der Implementierung auf Risiken, Lücken oder fehlende Grenzfälle prüfen
/speckit.implement	Codeänderungen	Führen Sie die Aufgaben aus und haken Sie jede ab.

Jedes Artefakt wird als Datei in specs/<feature-branch>/ gespeichert, in Git versionsverwaltet und kann wiederverwendet werden. Wenn eine Unterhaltung unterbrochen wird oder Sie später noch einmal auf Entscheidungen zurückgreifen möchten, sind die Spezifikationsdokumente immer verfügbar und nicht in einem Chatverlauf verborgen.

Hinweise:Das integrierte Antigravity-Artefakt hat eine höhere Priorität in der Benutzeroberfläche, sodass Nutzer das generierte Artefakt kommentieren können ( auch Bilder). ). Daher ändern wir in dieser Anleitung den ursprünglichen spec-kit-Prompt, um ihn in die integrierten Artefakte in implement-Phasen einzubinden.

Das Starter-Repository enthält diese SDD-Workflows in .agents/workflows/ und Vorlagen in .specify/templates/. Sie werden später verwendet, um dem Agent Funktionen hinzuzufügen.

4. Projektkontext mit Antigravity erstellen

Nun simulieren wir die Situation mit einer Bedingung, die unserem Arbeitsalltag „etwas näher“ kommt:

• Schlecht verwaltetes Repository
• README veraltet
• Dokumentationen werden nicht häufig aktualisiert

Hinweis:Wenn dies nicht auf Sie zutrifft, können Sie sich glücklich schätzen.

Als Erstes möchten wir in einer solchen Situation in der Regel eine Karte oder einen Kontext für das Projekt erstellen, an dem Antigravity arbeiten soll. In diesem Schritt wird ein Beispiel für einen Ansatz gezeigt, mit dem Antigravity ein umfassendes Verständnis einer vorhandenen Codebasis vermittelt werden kann. Dazu wird ein Skill erstellt, der das Repository analysiert und ein Projektkontextdokument generiert.

Außerdem wird die Projektverfassung eingerichtet – die nicht verhandelbaren Grundsätze, anhand derer die SDD-Workflows validiert werden. Zusammen liefern sie Antigravity den Kontext und die Einschränkungen, die für die SDD-Zyklen später erforderlich sind.

Die Antigravity-Kontexthierarchie

Antigravity verwendet drei Kontextebenen mit jeweils unterschiedlichem Umfang:

• Regeln (.agents/rules/): Immer aktive Anweisungen. In jeder Unterhaltung in diesem Arbeitsbereich sind sie zu sehen ( sofern Sie sie aktiviert haben). Verwenden Sie Regeln für projektweiten Kontext wie Architektur-Entscheidungen, Codierungsstandards oder Informationen zum Technologie-Stack.
• Kompetenzen (.agents/skills/): On-Demand-Wissen. Antigravity lädt einen Skill nur, wenn die aktuelle Aufgabe mit dem Feld description des Skills übereinstimmt. Skills für fachbereichsspezifisches Referenzmaterial verwenden
• Workflows (.agents/workflows/): Gespeicherte Prompts, die mit /-Befehlen ausgelöst werden. Verwenden Sie Workflows für wiederholbare mehrstufige Prozesse wie die SDD-Pipeline.

Hinweis:Das Projekt hat derzeit Workflows (SDD-Pipeline) und zwei Skills (repo-research und mcp-toolbox-postgres), aber keine Regeln. Später erstellen wir eine project-context.md-Regel, die Antigravity ein dauerhaftes Verständnis der Codebasis ermöglicht – welche Technologien verwendet werden, wie Dateien organisiert sind und was bisher entwickelt wurde.

Fähigkeiten aktivieren

Das Starter-Repository enthält zwei vorgefertigte Skills in .agents/skills/. Sie enthalten detaillierte Anleitungen, beginnen aber mit TODO(codelab)-Kommentaren anstelle des erforderlichen YAML-Frontmatter. Ohne Frontmatter kann Antigravity sie nicht erkennen.

Für Antigravity-Skills ist oben in der Datei ein YAML-Frontmatter-Block mit zwei Feldern erforderlich:

• name: Eine eindeutige Kennung für den Skill.
• description: Eine Zusammenfassung in natürlicher Sprache, die Antigravity abgleicht, um zu entscheiden, welcher Skill für eine bestimmte Anfrage geladen werden soll.

Öffnen Sie .agents/skills/mcp-toolbox-postgres/SKILL.md im Editor. Ersetzen Sie die Kommentarzeilen TODO(codelab) oben durch diesen Frontmatter:

---
name: mcp-toolbox-postgres
description: Configure MCP Toolbox for PostgreSQL — sources, tools, and embedding models
---

Hinweise:Der MCP Toolbox Postgres-Skill enthält die richtige Konfiguration für sources, tools und embedding models.

Öffnen Sie .agents/skills/repo-research/SKILL.md im Editor. Ersetzen Sie die Kommentarzeilen TODO(codelab) oben durch diesen Frontmatter:

---
name: repo-research
description: Analyze a repository's structure, technologies, and patterns to create or update a project context document. Use when asked to research, analyze, or understand a codebase.
---

Hinweise:Lesen Sie die Datei repo-research SKILL.md sorgfältig durch. Dies ist ein Beispiel für einen Prompt, mit dem Sie Ihr Repository analysieren können. Die Regeln für inkrementelle Updates sind bewusst konservativ gehalten. Wenn der Kontext von Antigravity während der Recherche erschöpft ist oder die Unterhaltung unterbrochen wird, wird alles, was bisher ermittelt wurde, bereits in der Datei gespeichert. Wenn Sie den Skill noch einmal aufrufen, wird er an der Stelle fortgesetzt, an der er beendet wurde.

Achtung! Wenn Sie ein großes Repository analysieren, kann Ihr Kontingent schnell aufgebraucht sein.

Prüfen Sie, ob beide Skills gültige Frontmatter haben:

head -4 .agents/skills/mcp-toolbox-postgres/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

Jedes sollte ----Trennzeichen enthalten, die die Felder name: und description: umschließen. Wenn die Trennzeichen oder Felder fehlen, erkennt Antigravity den Skill nicht.

Beide Skills werden bei Bedarf geladen: Antigravity gleicht Ihre Anfrage mit dem Feld description ab und ruft die vollständigen Anweisungen nur bei Bedarf ab.

Öffentlich verfügbare Skills installieren

ADK-Übersicht für Skills

Wir haben uns bereits Skills angesehen, die wir selbst erstellt haben ( die Skills repo-research und mcp-toolbox-postgres). Es gibt jedoch viele andere Fähigkeiten, die für die Softwareentwicklung nützlich sind und die sich problemlos in unseren Coding-Agenten integrieren lassen. In diesem Tutorial müssen wir beispielsweise mit dem ADK interagieren. Daher benötigen wir das entsprechende Wissen, um mit dem ADK zu arbeiten. Installieren wir den ADK-Dokumentations-Skill mit dem folgenden Befehl.

npx skills add google/adk-docs

Sie werden dann aufgefordert, die Installation wie unten gezeigt zu bestätigen.

Drücke y, um mit der nächsten Aufforderung fortzufahren und auszuwählen, welche Skills installiert werden sollen (siehe unten). Wählen wir jetzt nur adk-cheatsheet aus (Leertaste zum Auswählen, dann Eingabetaste zum Bestätigen).

Klicken Sie dann einfach auf Eingabe, um die Standardinstallation zu aktivieren und den Skill in Ihrem aktuellen Projekt zu installieren.

Sie sehen, dass dem Verzeichnis .agents/skills ein neuer ADK-Skill hinzugefügt wurde, nämlich adk-cheatsheet.

Höhlenmensch-Fähigkeiten

Eine der nützlichen Strategien zur Reduzierung der Token-Nutzung ist die Höhlenmensch-Strategie . Mit dieser Funktion kann das Ausgabetoken des Agents gekürzt werden. Das ist eine gute Kombination,wenn Sie eine vollständige spezifikationsgesteuerte Entwicklung wie in dieser Anleitung verwenden.

npx skills add JuliusBrussee/caveman

Wählen wir wie zuvor den Skill caveman aus.

Klicken Sie dann einfach auf Eingabe, um die Standardinstallation zu aktivieren und den Skill in Ihrem aktuellen Projekt zu installieren.

Jetzt sollten bereits vier Skills konfiguriert sein und wir können mit der SDD beginnen.

.agents/skills/
├── adk-cheatsheet
├── caveman
├── mcp-toolbox-postgres
└── repo-research

Projektkontext generieren

Prüfen Sie, ob das Verzeichnis „rules“ vorhanden ist:

mkdir -p .agents/rules

Starten Sie im Agent Manager/Chat-Feld von Antigravity (im Editormodus drücken Sie ctrl + L) eine neue Unterhaltung. Typ:

Research this repository and create a project context document, and communicate efficiently

Antigravity vergleicht Ihre Anfrage mit den Skills repo-research und caveman ( Befehl zur effizienten Kommunikation) und beginnt mit der systematischen Analyse der Codebasis. Es liest Konfigurationsdateien, Quellcode und Dokumentation und füllt dann die Vorlage für den Projektkontext mit den Ergebnissen.

Öffnen Sie .agents/rules/project-context.md nach Abschluss des Vorgangs im Editor. Es enthält konkrete Informationen zum Projekt: Technologiestack (Python 3.12, ADK, MCP Toolbox, Cloud SQL), Projektstruktur, Datenmodell (Tabelle „menu_items“ mit pgvector) und externe Integrationen.

Tipp:Das Projektkontextdokument wächst mit dem Fortschritt des Projekts. Sie können den Skill noch einmal ausführen, um den Kontext mit den neuen Ergänzungen zu aktualisieren. Die Regeln für inkrementelle Updates sorgen dafür, dass vorhandene Inhalte beibehalten werden. Neue Technologien, Einheiten und Integrationen werden angehängt und nicht überschrieben.

Verwenden Sie für gezielte Aktualisierungen spezifische Prompts: „Recherchiere das Datenbankschema und aktualisiere den Projektkontext“ oder „Aktualisiere den Projektkontext mit den neuen Tool-Definitionen“. Bei jedem Aufruf wird dem vorhandenen Dokument etwas hinzugefügt.

Projektkonstitution festlegen

In den SDD-Workflows wird während der Planung und Analyse auf eine Projektkonstitution unter .specify/memory/constitution.md verwiesen. Im /speckit.plan-Workflow wird eine „Constitution Check“-Prüfung durchgeführt und /speckit.analyze kennzeichnet Verstöße als CRITICAL. Wenn die Verfassung als leere Vorlage mit Platzhalter-Tokens belassen wird, gibt es nichts, woran die Prüfungen vorgenommen werden können. Pläne und Analysen werden ohne Schutzmaßnahmen ausgeführt.

In der Verfassung werden nicht verhandelbare Projektgrundsätze definiert. Dies ist ein kleines Repository, das von einem einzelnen Entwickler verwaltet wird. Die Verfassung sollte dies widerspiegeln. Halten Sie die Dinge einfach und einheitlich und vermeiden Sie Over-Engineering.

Starten Sie im Agent Manager von Antigravity eine neue Unterhaltung. Führen Sie den Workflow für die Verfassung aus:

/speckit.constitution This is a small restaurant concierge ADK agent maintained by one developer. Set 3 principles: (1) All database operations go through MCP Toolbox tool definitions in tools.yaml — no raw SQL in Python code, no ORM. (2) Session state uses ADK ToolContext — no custom state management, no external state stores. (3) Keep it simple — follow existing file and naming conventions exactly.

Antigravity füllt die Verfassungsvorlage mit konkreten Grundsätzen, weist eine Version (1.0.0) zu und führt eine Konsistenzprüfung für die SDD-Vorlagen durch.

Sehen Sie sich die generierte Verfassung unter .specify/memory/constitution.md an. Prüfen Sie, ob die drei Grundsätze vorhanden und klar formuliert sind.

Hinweis:Die Verfassung ist bewusst auf drei Grundsätze beschränkt, die für einen Solo-Entwickler gelten. Der /speckit.constitution-Workflow unterstützt inkrementelle Änderungen. Führen Sie ihn mit zusätzlichen Grundsätzen noch einmal aus. Die Versionsverwaltung wird automatisch übernommen. Bei einem Teamprojekt würden Sie Prinzipien für das Code Review, Testdisziplin, Observability und API-Versionsverwaltung hinzufügen.

Checkpoint : .agents/rules/project-context.md ist mit konkreten Informationen zum Repository vorhanden. .agents/skills/repo-research/SKILL.md zeigt die Erstellung von Skills mit YAML-Frontmatter, Anweisungen und Konfliktlösung. .specify/memory/constitution.md enthält drei Projektgrundsätze, anhand derer die Planungs- und Analyse-Workflows validiert werden. Sie kennen die dreistufige Kontexthierarchie: Regeln (immer aktiv), Skills (auf Abruf) und Workflows (Slash-Befehle).

5. SDD-Zyklus – Reservierungsfunktion hinzufügen

In diesem Schritt wird ein vollständiger SDD-Zyklus durchlaufen, um dem Restaurant-Concierge-Agenten die Reservierungsbuchung hinzuzufügen. Sie führen Antigravity durch die einzelnen Phasen – Spezifizieren, Klären, Planen, Aufgaben, Analysieren, Implementieren – und beobachten, wie jedes Artefakt auf dem vorherigen aufbaut. Das ist der Kern des Codelabs.

Wichtig! Antigravity ist ein KI-Assistent. Die generierten Artefakte (Spezifikationen, Pläne, Aufgaben, Code) können sich von den in dieser Anleitung beschriebenen unterscheiden. Die Dateinamen, genauen SQL-Schemas und die Codestruktur können variieren. Das ist normal und gehört zur Arbeit mit KI-gestützter Entwicklung. Im SDD-Workflow prüfen Sie jedes Artefakt, bevor es zu Code wird. Verwenden Sie Ihr Urteilsvermögen, um Ausgaben, die nicht Ihren Erwartungen entsprechen, zu akzeptieren, zu ändern oder neu zu generieren.

Funktion angeben

Starten Sie im Agent Manager von Antigravity eine neue Unterhaltung. Geben Sie den /speckit.specify Workflow-Befehl mit einer Merkmalsbeschreibung ein:

/speckit.specify Add reservation booking capability to the restaurant concierge agent. Guests should be able to make a table reservation by providing their name, party size, date, and time. They should also be able to check existing reservations. The agent should confirm reservation details before booking and handle special requests (e.g., "window seat", "birthday celebration").

Antigravity erstellt einen Feature-Branch, generiert ein Spezifikationsdokument und führt eine Qualitätsvalidierung durch. Wenn Antigravity Klärungsfragen stellt, beantworten Sie diese anhand der obigen Merkmalsbeschreibung.

Hinweis:Nach Abschluss der Spezifikation kann Antigravity Übergaben wie Build Technical Plan (Technischen Plan erstellen) oder Clarify Spec Requirements (Spezifikationsanforderungen klären) präsentieren. Diese sind ein Hinweis auf die nächste Workflowphase (/speckit.plan oder /speckit.clarify).

Die Spezifikation konzentriert sich auf WAS und WARUM, nicht auf WIE. Es wird die Nutzerfreundlichkeit beschrieben („Gäste können eine Reservierung vornehmen, indem sie ihren Namen, die Anzahl der Personen, das Datum und die Uhrzeit angeben“), ohne SQL-Tabellen, tools.yaml oder ADK-APIs zu erwähnen. Details zur Implementierung folgen in der Planungsphase.

Sehen Sie sich die generierte Spezifikation unter specs/<branch-name>/spec.md an. Prüfen Sie, ob die funktionalen Anforderungen und Erfolgskriterien berücksichtigt werden.

Spezifikation erläutern (optional)

Führen Sie den Workflow „Clarify“ aus, um unterbestimmte Bereiche in der Spezifikation zu identifizieren und zu beheben:

/speckit.clarify

Antigravity scannt die Spezifikation nach Unklarheiten, fehlenden Akzeptanzkriterien und unzureichend spezifizierten Anforderungen. Es werden gezielte Fragen zur Klärung gestellt, die jeweils mit einer kurzen Auswahl oder Formulierung beantwortet werden können. Ihre Antworten werden direkt in die Spezifikation codiert, wodurch sie präziser wird, bevor die Planung beginnt.

Tipp:Der Schritt „Klären“ ist optional, wird aber für komplexe Funktionen empfohlen. Bei einfachen Spezifikationen können Sie direkt mit der Planung beginnen.

Implementierung planen

Planungsworkflow ausführen:

/speckit.plan Update the restaurant concierge agent to multi agent architecture which separate responsibilities for handling menu and reservations. Use your ADK and MCP toolbox skill to implement it properly

Antigravity generiert einen technischen Plan in zwei Phasen:

1. Recherchedurchführung: Unbekannte Aspekte der vorhandenen Codebasis werden geklärt und research.md wird generiert.
2. Entwurfsphase: Erstellt data-model.md (Definition der Reservierungseinheit) und aktualisiert project-context.md.

Antigravity sollte bei der Planung die Fähigkeit adk-agent-development nutzen. Prüfen Sie die wichtigsten Artefakte:

• specs/<branch-name>/plan.md – der technische Ansatz: welche Dateien geändert werden müssen, welche Muster zu befolgen sind
• specs/<branch-name>/data-model.md: die Definition der Reservierungsentität (Spalten, Typen, Beziehungen)
• specs/<branch-name>/research.md – getroffene Entscheidungen und Begründung

Aufgaben generieren

Workflow „Aufgaben“ ausführen

/speckit.tasks

Antigravity unterteilt den Plan in eine geordnete Aufgabenliste in specs/<branch-name>/tasks.md. Aufgaben folgen einem strengen Checklistenformat mit IDs, Prioritätsmarkierungen und Dateipfaden, z. B.:

- [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py
- [ ] [T002] [P] Add create_reservation tool to tools.yaml
- [ ] [T003] [P] Add list_reservations tool to tools.yaml
- [ ] [T004] [P] Update agent instruction in restaurant_concierge/agent.py

Aufgaben sind in Phasen unterteilt: Einrichtung → Grundlagen → User-Storys → Optimierung. Sehen Sie sich die Aufgabenliste an, um zu verstehen, was erstellt und geändert wird.

Aufgaben analysieren (optional)

Führen Sie den Analyse-Workflow aus, um die Aufgaben auf Risiken und Lücken zu prüfen:

/speckit.analyze

Antigravity vergleicht die Aufgabenliste mit der Spezifikation und dem Plan und sucht nach fehlenden Grenzfalltests, Aufgaben, die in Konflikt stehen könnten, oder Lücken zwischen den Anforderungen der Spezifikation und der geplanten Arbeit. Beheben Sie kritische Probleme, bevor Sie die Implementierung vornehmen.

Tipp:Der Analyseschritt ist am nützlichsten, wenn die Aufgabenliste lang ist oder die Funktion mehrere Subsysteme betrifft. Bei einer fokussierten Funktion wie der Reservierungsbuchung reicht ein kurzer Scan aus.

6. Implementieren

Führen Sie den Implementierungsworkflow aus:

/speckit.implement

Antigravity präsentiert einen endgültigen Implementierungsplan und ein Aufgabenartefakt. Prüfen und genehmigen Sie sie, um fortzufahren.

Tipp:Sie können direkt darauf antworten. Dies ist nur mit dem integrierten Antigravity-Artefakt möglich.

Antigravity führt die Aufgaben aus und hakt sie ab, sobald sie erledigt sind. Nach Abschluss wird der vollständige Walkthrough angezeigt.

Codeänderungen testen

Prüfen Sie nach Abschluss der Implementierung, ob die wichtigsten Änderungen vorgenommen wurden. Die genauen Dateinamen und Inhalte können variieren, aber diese Muster sollten wie in tools.yaml und agent.py vorhanden sein:

# Verify reservation tools were added to tools.yaml
grep -i "reservation" tools.yaml

Die Ausgabe sieht ungefähr so aus:

...
get_reservations_by_name:
      Retrieve all reservations for a guest by their name. Uses case-insensitive
      SELECT id, guest_name, party_size, reservation_datetime, special_requests, created_at
      FROM reservations
      ORDER BY reservation_datetime DESC
...

Und für agent.py

# Verify agent instruction was updated
grep -i "reservation" restaurant_concierge/agent.py

# Check what files changed
git diff --name-only

Vielleicht finden Sie Änderungen wie diese:

...
- **Table Reservations**: Help guests book a table or check their existing reservations.
## Reservation Booking Rules
When a guest wants to make a reservation, collect ALL of the following before confirming:
**IMPORTANT**: Before calling `book_reservation`, you MUST:
- Only call `book_reservation` after the guest says "yes" or "confirm"
## Checking Reservations
When a guest asks to check their reservations:
- Use `get_reservations_by_name` to find their bookings
        book_reservation,
...

Hinweis:Wenn grep für keine der beiden Dateien Übereinstimmungen zurückgibt, wurde bei der Implementierung möglicherweise eine andere Namensgebung verwendet. Sehen Sie sich git diff an, um alle Änderungen zu sehen und zu prüfen, ob reservierungsbezogene Logik hinzugefügt wurde.

Die Änderungen sollten sich auf das Seed-Datenbankskript auswirken. Das aktualisierte Skript sollte die Tabelle reservations erstellen, falls sie noch nicht vorhanden ist. Sie sollten eine Ausgabe sehen, die bestätigt, dass die neue Tabelle erstellt wurde (die vorhandenen menu_items-Daten bleiben erhalten).

Hinweis:Möglicherweise hat Antigravity ein separates Migrationsskript (z.B. scripts/create_reservations.py) erstellt, anstatt seed_db.py zu aktualisieren. Suchen Sie in git diff --name-only nach neuen Skripts in scripts/ und führen Sie diese stattdessen aus.

Wenn bis dahin alles gut läuft, können wir die Funktion in der Entwickler-UI des ADK-Agents testen. Wir führen die Datenbankmigration durch, um die neue Tabelle einzufügen, und starten die Toolbox neu, damit die neuen Tooldefinitionen in tools.yaml übernommen werden. Beenden Sie alle vorhandenen Toolbox-Prozesse und starten Sie einen neuen:

lsof -ti:5000 | xargs kill -9 2>/dev/null; echo "Done"
./scripts/setup_database.sh > database_setup.log 2>&1 &

Im Ausgabelog im database_setup.log können Sie prüfen, ob Antigravity korrekten Code und eine korrekte Konfiguration generiert. Wenn ein Fehler auftritt, versuchen Sie, ihn durch Interaktion mit dem Agent zu beheben.

Wenn alles gut geht, können wir die ADK-Entwicklungsoberfläche starten:

uv run adk web .

Öffnen Sie http://localhost:8000 in Ihrem Browser und testen Sie mit diesen Prompts:

I'd like to book a table for 4 people on Friday at 7pm under the name Timmy

Prüfen:Der Kundenservicemitarbeiter sollte die Reservierungsdetails bestätigen und die Reservierung erstellen.

Do I have any upcoming reservations?

Überprüfen:Der KI-Agent sollte die gerade vorgenommene Reservierung auflisten.

Beenden Sie nun die ADK-Entwicklungsoberfläche mit Ctrl+C (zweimal).

Checkpoint:Der Agent übernimmt die Reservierungsbuchung und ‑suche. Sie haben einen vollständigen SDD-Zyklus durchlaufen: Spezifizieren → Klären → Planen → Aufgaben → Analysieren → Implementieren → Testen. In jeder Phase wurde ein versioniertes Artefakt in specs/<branch-name>/ erstellt.

7. Herausforderungen (optional)

Sie kennen jetzt den gesamten SDD-Workflow. So können Sie es ausprobieren:

• Führen Sie einen zweiten SDD-Zyklus aus, um eine Webchat-Oberfläche für den Restaurant-Concierge zu erstellen – diesmal ohne Schritt-für-Schritt-Anleitung.
• Agent für das Produktionsszenario in Cloud Run bereitstellen

Hinweise

• Das Projekt hat kein Frontend-Framework. Antigravity sollte reines HTML/CSS/JS vorschlagen. Wenn React oder Ähnliches vorgeschlagen wird, sollte es auf Einfachheit ausgerichtet werden (das Prinzip „Keep it simple“ Ihrer Verfassung sollte dies erkennen).
• Der ADK-Server stellt /run_sse für das Streaming und /apps/{app_name}/users/{user_id}/sessions für die Sitzungsverwaltung bereit. Antigravity ermittelt diese aus dem Projektkontext.
• Starten Sie den Server nach der Implementierung mit uv run uvicorn server:app --host 0.0.0.0 --port 8080 (nicht adk web), damit die Bereitstellung statischer Dateien funktioniert.
• Testen Sie unter http://localhost:8080/static/index.html.
• In den Referenz-Codelabs wird bereits gezeigt, wie ADK-Agenten bereitgestellt und beibehalten werden. Gib Antigravity-Referenzen dazu an.

8. Glückwunsch!

Sie haben einen ADK-Agenten für einen Restaurant-Concierge mit Reservierungsbuchung erweitert – vollständig über die SDD-Workflows von Antigravity, ohne Anwendungscode manuell zu schreiben.

Was Sie erstellt haben

• Ein ADK-Agent für Restaurant-Concierge mit Menüsuche, semantischer Suche, Erfassung von Ernährungspräferenzen und Reservierungsbuchung
• Eine Antigravity-Skill für die Repository-Recherche, die ein Projektkontextdokument generiert und verwaltet
• Eine Projektverfassung, die nicht verhandelbare Grundsätze während der Planung und Analyse durchsetzt
• Ein vollständiger SDD-Zyklus, der den Workflow „Spezifizieren“ → „Klären“ → „Planen“ → „Aufgaben“ → „Analysieren“ → „Implementieren“ veranschaulicht

Das haben Sie gelernt

• Spezifikationsbasierte Entwicklungsworkflows in Antigravity verwenden, um einer vorhandenen Codebasis systematisch Funktionen hinzuzufügen
• Antigravity-Skills erstellen, die Domainwissen für die Wiederverwendung in Unterhaltungen bündeln
• So wird der Projektkontext gebootstrapped, damit Antigravity fundierte Entscheidungen zu Architektur, Mustern und Technologie treffen kann
• Festlegen einer Projektverfassung, anhand derer die SDD-Workflows validiert werden
• ADK-Agenten mit neuen datenbankgestützten Tools über die MCP Toolbox erweitern

Bereinigen

Beenden Sie alle laufenden lokalen Prozesse (Toolbox):

pkill -f toolbox 2>/dev/null

Löschen Sie die Cloud SQL-Instanz, um laufende Gebühren zu vermeiden:

gcloud sql instances delete restaurant-db --quiet

Optional: Gesamtes Projekt löschen:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Wichtig:Sie können diesen Löschvorgang für einen begrenzten Zeitraum mit dem Befehl gcloud projects undelete ${GOOGLE_CLOUD_PROJECT} rückgängig machen.