Antigravity ve Spec-kit ile Spesifikasyona Dayalı ADK Aracı Geliştirme

1. Giriş

Mevcut bir aracıya özellik eklemek (yeni bir veritabanı destekli özellik) genellikle standart kod yazmak, entegrasyonları bağlamak ve her şeyi kod tabanında zaten bulunan kalıplarla tutarlı tutmak anlamına gelir. Antigravity, bu sürecin her aşamasını hızlandırır: İhtiyacı olan bağlamı oluşturmak için kod tabanınızı analiz eder, incelemeniz için yapılandırılmış spesifikasyonlar ve uygulama planları üretir ve kod değişikliklerini yürütür. Tüm bunlar, yeniden kullanılabilir beceriler ve pazarlık edilemez ilkeleri uygulayan bir proje anayasası olarak yakalamanıza yardımcı olduğu alan bilgisiyle yönlendirilir. Bu codelab'de, spec-kit'e yoğun bir şekilde referans veren spesifikasyon dokümanlarını desteklemek için yeni bir döngü sunarak Antigravity'nin spesifikasyon odaklı geliştirme paradigmasını güçlendirme yöntemi tanıtılmaktadır.

Ne oluşturacaksınız?

Tam bir SDD döngüsü aracılığıyla rezervasyon kaydı eklenen, yerel olarak çalışan bir restoran konsiyerj uygulaması:

  • Rezervasyon: Yeni MCP Toolbox veritabanı araçları ve Cloud SQL reservations tablosuyla desteklenen bu özellik sayesinde konuklar masa ayırtabilir ve rezervasyonları kontrol edebilir.
  • (Zorlu görev) – Ajan için kendi kullanıcı arayüzünüzü geliştirin
  • (Zorluk) – Antigravity aracısının yardımıyla Google Cloud'da dağıtım yapma

Başlangıç kodu, menü araması (MCP Toolbox aracılığıyla anahtar kelime + semantik) ve beslenme tercihi takibi (ToolContext aracılığıyla) özelliklerine sahip çalışan bir ADK aracısı sağlar. Uygulama kodunu manuel olarak yazmadan genişletirsiniz. Antigravity, spesifikasyonlarınıza göre uygulamayı yönetir.

404869b603fff6ab.png

Neler öğreneceksiniz?

  • Antigravity'nin mevcut bir kod tabanını anlaması için proje bağlamını nasıl başlatacağınız
  • Alan bilgisini (ör. ADK codelab kalıpları) yeniden kullanıma hazır hale getiren Antigravity becerileri oluşturma
  • SDD iş akışlarının planlama ve analiz sırasında doğruladığı bir proje anayasası nasıl oluşturulur?
  • Antigravity'de özellikleri sistematik olarak eklemek için Spesifikasyon Odaklı Geliştirme (SDD) iş akışlarını kullanma
  • MCP Toolbox aracılığıyla ADK aracısını yeni veritabanı destekli araçlarla genişletme

Ön koşullar

2. Ortamınızı Kurma

Bu adımda başlangıç deposu klonlanır, Google Cloud ile kimlik doğrulaması yapılır, Cloud SQL veritabanı sağlanır ve yerel Antigravity ortamınız hazırlanır.

Ön koşulları yükleme

Sisteminizde aşağıdaki CLI yürütülebilir dosyasının bulunduğundan emin olun:

Yükleme talimatı, makinenizin işletim sistemine göre farklılık gösterir.

Başlangıç deposunu klonlama

Antigravity'de (veya sistem terminalinizde) bir terminal açın. Eşlik eden depoyu klonlayın ve dizine girin:

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

Klonlanan depoyu Antigravity'de açın. File (Dosya) -> Open Folder (Klasörü Aç) -> klonlanan sdd-adk-agents-agy dizinini seçin.

Yukarı akış uzaktan deposunu kaldırın. SDD iş akışları, özellik spesifikasyonları için git dalları oluşturur. Uzak depoyu kaldırmak, başlangıç deposuna yanlışlıkla göndermeyi önler:

git remote remove origin

Google Cloud ile kimlik doğrulama

İki kimlik doğrulama komutu çalıştırın. Her ikisi de OAuth için bir tarayıcı açar:

gcloud auth login
gcloud auth application-default login

Antigravity'yi yerel olarak kullandığınız için kimlik doğrulama işlemini manuel olarak yaparsınız. auth login, gcloud KSA'nın kimliğini doğrular. application-default login, uygulamanızın kullandığı Google Cloud SDK'larının kimliğini doğrular. ADK'nın Vertex AI çağrıları ve Cloud SQL Python bağlayıcısı, her ikisi de Uygulama Varsayılan Kimlik Bilgileri'ne dayanır.

Google Cloud projenizi oluşturma

Proje kurulum komut dosyasını çalıştırmadan önce konum değişkenlerini .env konumuna yazın:

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env
  • GOOGLE_CLOUD_LOCATION=global, Vertex AI / Gemini API çağrıları için kullanılır.
  • REGION=us-central1, Cloud SQL ve diğer GCP altyapısı için kullanılır.

Proje kurulum komut dosyasını indirip çalıştırın. Deneme faturalandırmasıyla bir Google Cloud projesi oluşturur veya doğrular, proje kimliğini .env içine kaydeder ve ardından kaynaklandırır:

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 etkinleştiriliyor

Gerekli API'leri etkinleştirin:

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

Bağımlıları yükleme

Python proje yöneticisi olarak uv'ı kullanacağız. uv, Rust ile yazılmış hızlı bir Python paketi ve proje yöneticisidir ( dokümanlar ). Bu codelab'de hız ve basitlik için kullanılır. Python bağımlılıklarını yükleyin:

uv sync

Ardından, ADK aracısının .env dosyasını proje yapılandırmanızla güncelleyin:

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

Veritabanı Altyapısını ve Verileri Hazırlama

Veritabanı şifresini ayarlayın ve .env'ya ekleyin:

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

Ardından, gereken tüm altyapıyı hazırlamak için scripts/setup_database.sh komut dosyasını çalıştırın. Bu işlem sonucunda:

  • Cloud SQL örneği oluşturma
  • Örneğin hazır olup olmadığını kontrol etme
  • Vertex AI izinleri verme
  • Veritabanı oluştur
  • Kaynak veritabanı
  • MCP Toolbox hizmetini arka planda çalıştırma
chmod +x scripts/setup_database.sh
./scripts/setup_database.sh > database_setup.log 2>&1 &

Bu komut, kurulumu arka planda çalıştırır. Çıkışı database_setup.log dosyasında düzenli olarak kontrol edebilirsiniz.

Artık üzerinde çalışabileceğimiz gerekli başlangıç ADK aracı deposunun tamamına sahibiz. Şimdi de her şey hazır olana kadar beklerken sonraki bölümde Antigravity ve spesifikasyon odaklı geliştirme hakkında daha fazla konuşalım.

3. Başlangıç Kodunu Keşfetme ve Spesifikasyon Odaklı Geliştirme Modelini Anlama

Bu adımda, başlangıç kodu yapısı açıklanır, Spec-Driven Development metodolojisi tanıtılır, veritabanı başlatılır ve genişletmeye başlamadan önce temel aracının çalıştığı doğrulanır.

Proje yapısı

Klonlanan depo projesini Antigravity düzenleyicide açın ve dizin düzenini inceleyin:

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

Önemli dosyalar

Aracı uygulama dosyaları

  • restaurant_concierge/agent.py: Temel aracı. MCP Toolbox veritabanı araçlarını LlmAgent ile ToolContext tabanlı beslenme tercihi takibini birleştiren bir çözüm. Aracı, Araç Kutusu sunucusundaki tüm araçları yükler ve durumu yönetmek için ToolContext kullanan iki Python işlevi (save_dietary_preference, get_dietary_preferences) ekler.
  • tools.yaml: MCP Araç Kutusu araç tanımları. Üç menü arama aracı tanımlanır: anahtar kelime araması (search_menu), pgvector aracılığıyla semantik arama (semantic_search_menu) ve kategori filtresi (get_menu_by_category). Henüz rezervasyon araçları yoktur. Bunları daha sonra eklersiniz.
  • server.py: ADK'ye FastAPI nesnesi olarak nasıl erişebileceğinizi gösteren minimal bir FastAPI sunucusu. ADK'daki get_fast_api_app(), SSE akışı ve oturum yönetimi API'leri için /run_sse dahil olmak üzere yerleşik uç noktalar sağlar.

Antigravity Files

  • .agents/skills/mcp-toolbox-postgres/SKILL.md: Antigravity'ye MCP araç kutusu için uygun tools.yaml yapılandırmasının nasıl oluşturulacağı konusunda rehberlik eden bir beceri. Bu beceri, uygun RAG ardışık düzeni oluşturmak için gereken sources , tools ve embeddingModels yapılandırmasıyla ilgili bilgileri öğretir. Bu beceri, Antigravity tarafından tanınacak uygun YAML ön materyali eklenene kadar etkinleştirilmez.
  • .agents/skills/repo-research/SKILL.md: Antigravity'ye bir depoyu artımlı olarak nasıl analiz edeceğini ve yapılandırılmış bir proje bağlamı belgesi oluşturacağını öğreten bir beceri. 4 aşamalı bir yaklaşım kullanılır: yüzey taraması (yalnızca dizin ağacı), yapılandırma ve meta veri dosyaları, giriş noktaları ve veri modelleri, ardından hedeflenen ayrıntılı incelemeler. Her aşama, bir sonrakine geçmeden önce durur ve bulguları yazar. Ayrıca, daha sonra YAML ön materyali ekleyene kadar devre dışıdır. Etkinleştirildikten sonra, mimari, çalışma zamanı bağımlılıkları, API yüzeyi ve alan sözlüğünü kapsayan kapsamlı bir oryantasyon belgesi olan .agents/rules/project-context.md oluşturmak için bu özelliği kullanın.

Spesifikasyon Odaklı Geliştirme: Antigravity'nin yerleşik planlamasından yapılandırılmış SDD'ye

Yapay zeka kodlama asistanları, istemden kod oluşturmayı kolaylaştırır. Risk: Bir özelliği tek bir cümleyle açıklıyorsunuz, asistan yüzlerce satır yazıyor ve doğru göründüğü için bunu kabul ediyorsunuz. Bu bazen "sezgisel kodlama" olarak adlandırılır. Çıkışın işe yarayıp yaramadığına göre kabul edip reddederek hislerinize göre yönlendirirsiniz. Prototip oluşturma ve tek kullanımlık komut dosyaları için hızlıdır. Kod tabanı büyüdüğünde, özellikler etkileşime girdiğinde veya haftalar sonra kodu tekrar ziyaret ettiğinizde ve bir kararın neden verildiğini yeniden oluşturamadığınızda bozulur.

b2a0753229d08ef3.png

Spesifikasyona Dayalı Geliştirme (SDD), bu döngüye yapı ekler. Kod oluşturulmadan önce bir spesifikasyon yazarsınız: Özelliğin ne yaptığı, kime hizmet ettiği, başarı ölçütlerinin ne olduğu. Yapay zeka asistanı bu spesifikasyona göre çalışır. Çıktısını incelerken siz de bu spesifikasyona göre çalışırsınız. Spesifikasyon, amaç için tek doğruluk kaynağı haline gelir. Kod, spesifikasyondan farklıysa bunu inceleme sırasında yakalarsınız. Gereksinimler değişirse önce spesifikasyonu günceller, ardından yeniden oluşturursunuz. Kararlar doğaçlama değil, belgelenmiş olmalıdır.

Bu bir değiş tokuş işlemidir: SDD, sezgisel kodlamaya kıyasla özellik başına daha yavaştır. Kodu yazmadan önce dokümanları yazarsınız. Ancak bu çabanın karşılığı katlanarak artar. Kod tabanında gelecekte yapılacak her değişiklik bağlamlı olur, yapay zeka tarafından oluşturulan her uygulama incelenebilir bir sözleşmeye sahip olur ve iş ortaklarını (insan veya yapay zeka) hafızadan kararları açıklamak yerine spesifikasyonlara yönlendirerek dahil edebilirsiniz.

Antigravity, spesifikasyon odaklı geliştirme ilkelerine zaten uymaktadır. Temsilciyi Planlama moduna ayarladığınızda herhangi bir kod yazmadan önce iki öğe üretir:

  • Uygulama Planı: Önerilen teknik yaklaşım, dosya değişiklikleri ve mimari kararlara genel bakış 632169a236bc62cc.png
  • Görev listesi: İş öğelerinin yapılandırılmış dökümü

795e47f4d98ae074.png

Antigravity, yürütmeden önce bu yapıları inceleyip onaylamanızı ister. Önce planlama, sonra uygulama döngüsü, spesifikasyona dayalı geliştirmenin temelini oluşturur: Kodu spesifikasyonlar yönlendirir, bunun tersi geçerli değildir.

Bu codelab'de, GitHub'ın spesifikasyona dayalı geliştirme çerçevesi olan spec-kit'e dayalı, görüşe dayalı ve sürüm kontrollü bir iş akışıyla bu temel daha da ileriye taşınıyor. Her özellik, her yapının git içinde inceleyebileceğiniz, düzenleyebileceğiniz ve izleyebileceğiniz bağımsız bir doküman olduğu kasıtlı bir ardışık düzenden geçer. İşlem hattında, sorunları uygulama sorunlarına dönüşmeden önce yakalayan iki isteğe bağlı kalite kontrolü aşaması (açıklama ve analiz) bulunur:

Aşama

Artifact

Purpose

/speckit.specify

spec.md

NE inşa edeceğinizi tanımlayın (kullanıcıya yönelik, teknolojiden bağımsız)

/speckit.clarify (isteğe bağlı)

Son güncelleme: spec.md

Yeterince belirtilmemiş alanları belirleme, hedefli açıklama soruları sorma, yanıtları tekrar spesifikasyona kodlama

/speckit.plan

plan.md, data-model.md, research.md

Nasıl oluşturulacağını tasarlama (teknik yaklaşım, veri modelleri, araştırma)

/speckit.tasks

tasks.md

Planı sıralı ve uygulanabilir adımlara ayırın

/speckit.analyze (isteğe bağlı)

Analiz raporu

Uygulamadan önce görevlerdeki riskleri, eksikleri veya gözden kaçan uç durumları inceleyin.

/speckit.implement

Kod değişiklikleri

Görevleri tamamlayın ve her birini işaretleyin.

c0164b540ee0afa1.png

Her yapıt, specs/<feature-branch>/ içinde dosya olarak kalıcı hale getirilir, git'te sürüm kontrolü yapılır ve yeniden kullanılabilir. Bir görüşme kesintiye uğrarsa veya kararları daha sonra tekrar gözden geçirmek isterseniz spesifikasyon belgeleri her zaman kullanılabilir. Bu belgeler, sohbet geçmişinde yer almaz.

Başlangıç deposu, .agents/workflows/ içinde bu SDD iş akışlarını ve .specify/templates/ içinde şablonları içerir. Bunları daha sonra aracıya özellik eklemek için kullanırsınız.

4. Antigravity ile Bootstrap Proje Bağlamı

Şimdi de günlük işimize "biraz daha yakın" bir koşulla durumu simüle edelim:

  • İyi yönetilmeyen depo
  • README eski
  • Belgeler sık sık güncellenmiyor

Bu tür durumlarda ilk olarak Antigravity'nin üzerinde çalışmasını istediğimiz projeyle ilgili bir harita veya bağlam oluştururuz. Bu adımda, Antigravity'ye mevcut bir kod tabanını derinlemesine anlama yeteneği kazandırmak için bir yaklaşım örneği gösterilmektedir. Bu yaklaşımda, depoyu analiz eden ve proje bağlamı belgesi oluşturan bir beceri oluşturulur.

Ayrıca, SDD iş akışlarının doğrulama yaptığı, pazarlığa açık olmayan ilkeler olan proje anayasasını da oluşturur. Bunlar, Antigravity'ye daha sonraki SDD döngüleri için gereken bağlamı ve kısıtlamaları sağlar.

Antigravity bağlam hiyerarşisi

Antigravity, her biri farklı bir kapsama sahip üç bağlam düzeyi kullanır:

  • Kurallar (.agents/rules/): Her zaman etkin olan talimatlar. Bu çalışma alanındaki her görüşmede bu kurallar görülür ( etkinleştirdiyseniz). Kuralları, mimari kararlar, kodlama standartları veya teknoloji yığını bilgileri gibi proje genelinde bağlam için kullanın.
  • Beceriler (.agents/skills/): İhtiyaç duyduğunuzda bilgi edinin. Antigravity, bir beceriyi yalnızca mevcut görev becerinin description alanıyla eşleştiğinde yükler. Alana özgü referans materyalleri için becerileri kullanın.
  • İş akışları (.agents/workflows/): / komutlarıyla tetiklenen kayıtlı istemler. SDD ardışık düzeni gibi tekrarlanabilir çok adımlı işlemler için iş akışlarını kullanın.

Becerileri etkinleştirme

Başlangıç deposunda .agents/skills/ içinde önceden yazılmış iki beceri bulunur. Ayrıntılı talimatlar içerir ancak gerekli YAML ön matter'ı yerine TODO(codelab) yorumlarıyla başlar. Antigravity, ön bilgiler olmadan bu kitapları keşfedemez.

Yerçekimine karşı koyma becerileri için dosyanın en üstünde iki alan içeren bir YAML ön madde bloğu gerekir:

  • name: Beceri için benzersiz tanımlayıcı
  • description: Antigravity'nin belirli bir istek için hangi becerinin yükleneceğine karar verirken eşleştirdiği doğal dil özeti

.agents/skills/mcp-toolbox-postgres/SKILL.md dosyasını düzenleyicide açın. En üstteki TODO(codelab) yorum satırlarını şu ön maddeyle değiştirin:

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

.agents/skills/repo-research/SKILL.md dosyasını düzenleyicide açın. En üstteki TODO(codelab) yorum satırlarını şu ön maddeyle değiştirin:

---
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.
---

Her iki becerinin de geçerli ön maddeye sahip olduğunu doğrulayın:

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

Her biri, name: ve description: alanlarını saran --- sınırlayıcılarını göstermelidir. Sınırlayıcılar veya alanlar eksikse Antigravity, beceriyi tanımaz.

Her iki beceri de isteğe bağlı olarak yüklenir. Antigravity, isteğinizi description alanıyla eşleştirir ve yalnızca alakalı olduğunda talimatların tamamını alır.

Herkese açık becerileri yükleme

ADK Hızlı Başvuru Kılavuzu Becerileri

Daha önce kendi oluşturduğumuz becerileri ( repo-research ve mcp-toolbox-postgres becerileri) inceledik. Ancak yazılım geliştirmemizi desteklemek için yararlı olan ve kodlama aracımıza kolayca yüklenebilen birçok başka beceri de vardır. Örneğin, bu eğitimde ADK ile etkileşim kurmamız gerektiği için ADK ile nasıl geliştirme yapılacağı hakkında bilgi sahibi olmamız gerekir. Aşağıdaki komutu kullanarak ADK dokümanı becerisini yükleyelim.

npx skills add google/adk-docs

Ardından, yüklemeyi onaylamanız istenir.

b9caa6a8cb1cdbee.png

Aşağıda gösterildiği gibi, hangi becerilerin yükleneceğini seçmek için sonraki isteme geçmek üzere y düğmesine basın. Şimdilik yalnızca adk-cheatsheet (seçmek için boşluk tuşuna, onaylamak için Enter tuşuna basın)

eccdab31618ab6a2.png

Ardından, varsayılan yüklemeyi etkinleştirmek ve beceriyi mevcut projenize yüklemek için diğer seçeneği Enter tuşuna basarak seçin.

Yeni ADK becerisinin .agents/skills dizinine eklendiğini görürsünüz. Bu dizin adk-cheatsheet

Caveman Skills

Token kullanımını azaltmak için yararlı becerilerden biri mağara adamı becerisidir . Bu beceri,çıkış jetonunu aracıdan kesebilir ve bu eğiticideki gibi tam bir Spec-driven Development (Özellik Odaklı Geliştirme) kullandığınızda iyi bir kombinasyon oluşturabilir.

npx skills add JuliusBrussee/caveman

Daha önce olduğu gibi, şimdilik caveman becerisini seçelim.

7a5d9fdfb287837e.png

Ardından, varsayılan yüklemeyi etkinleştirmek ve beceriyi mevcut projenize yüklemek için diğer seçeneği Enter tuşuna basarak seçin.

Şimdiye kadar 4 beceri yapılandırılmış ve SDD yolculuğumuza başlamaya hazır olmalıdır.

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

Proje bağlamını oluşturma

Kurallar dizininin bulunduğundan emin olun:

mkdir -p .agents/rules

Antigravity'nin Agent Manager/Chat kutusunda (düzenleyici modunda ctrl + L tuşuna basın) yeni bir görüşme başlatın. Tür:

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

Antigravity, isteğinizi repo-research ve caveman becerisiyle ( verimli iletişim kurma komutu) eşleştirir ve kod tabanını sistematik olarak analiz etmeye başlar. Yapılandırma dosyalarını, kaynak kodunu ve belgeleri okur, ardından proje bağlamı şablonunu bulgularıyla doldurur.

İşlem tamamlandığında düzenleyicide .agents/rules/project-context.md simgesini açın. Proje hakkında somut bilgiler içerir: teknoloji yığını (Python 3.12, ADK, MCP Toolbox, Cloud SQL), proje yapısı, veri modeli (pgvector ile menu_items tablosu) ve harici entegrasyonlar.

9949388b3e1f401a.png

Proje anayasasını belirleme

SDD iş akışları, planlama ve analiz sırasında .specify/memory/constitution.md konumundaki bir proje anayasasına referans verir. /speckit.plan iş akışı, buna karşı "Anayasa Kontrolü" gerçekleştirir ve /speckit.analyze ihlalleri KRİTİK olarak işaretler. Anayasa, yer tutucu jetonlarla boş bir şablon olarak bırakılırsa bu kontrollerin doğrulayacağı hiçbir şey olmaz. Planlar ve analizler koruma olmadan çalışır.

Anayasa, üzerinde pazarlık yapılamayan proje ilkelerini tanımlar. Bu, tek bir geliştirici tarafından yönetilen küçük bir depo olduğundan anayasa bu kapsamı yansıtmalıdır. İşleri basit ve tutarlı tutun, aşırı mühendislikten kaçının.

Antigravity'nin Agent Manager'ında yeni bir görüşme başlatın. Anayasa iş akışını çalıştırın:

/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, anayasa şablonunu somut ilkelerle doldurur, bir sürüm (1.0.0) atar ve SDD şablonlarında tutarlılık kontrolü yapar.

Oluşturulan anayasayı .specify/memory/constitution.md adresinde inceleyin. Üç ilkenin mevcut olduğunu ve net bir şekilde belirtildiğini doğrulayın.

276113749cd30834.png

5. SDD Cycle — Add Reservation Feature

Bu adımda, restoranın müşteri temsilcisi aracısına rezervasyon yaptırma işlevini eklemek için eksiksiz bir SDD döngüsü açıklanmaktadır. Her aşamada (belirtme, netleştirme, planlama, görevler, analiz etme, uygulama) Antigravity'yi yönlendirerek her bir yapının bir öncekinin üzerine nasıl inşa edildiğini gözlemlersiniz. Bu, codelab'in temel öğrenme deneyimidir.

Özelliği belirtin

Antigravity'nin Agent Manager'ında yeni bir görüşme başlatın. /speckit.specify İş akışı komutunu özellik açıklamasıyla birlikte yazın:

/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, bir özellik dalı oluşturur, bir spesifikasyon belgesi oluşturur ve kalite doğrulaması yapar. Antigravity, açıklama soruları sorarsa bunları yukarıdaki özellik açıklamasına göre yanıtlayın.

Spesifikasyon, NASIL sorusuna değil, NE ve NEDEN sorularına odaklanır. SQL tablolarından, tools.yaml veya ADK API'lerinden bahsetmeden kullanıcı deneyimini ("Konuklar adlarını, parti boyutunu, tarihi ve saati belirterek rezervasyon yapabilir") açıklıyor. Uygulama ayrıntıları planlama aşamasında belirlenir.

Oluşturulan spesifikasyonu specs/<branch-name>/spec.md adresinde inceleyin. İşlevsel gereksinimleri ve başarı ölçütlerini karşıladığını doğrulayın.

4ea3f72f9dfb4d35.png

Spesifikasyonu netleştirin (isteğe bağlı)

Şartnamede yeterince belirtilmemiş alanları belirlemek ve çözmek için netleştirme iş akışını çalıştırın:

/speckit.clarify

Antigravity, spesifikasyonda belirsizlikler, eksik kabul ölçütleri ve yeterince belirtilmemiş koşullar olup olmadığını tarar. Kısa bir seçim veya ifadeyle yanıtlanabilen, hedefe yönelik açıklama soruları sorar. Yanıtlarınız doğrudan spesifikasyona geri kodlanır. Böylece planlama başlamadan önce spesifikasyon daha hassas hale gelir.

Uygulamayı planlama

Planlama iş akışını çalıştırın:

/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, iki aşamada teknik bir plan oluşturur:

  1. Araştırma aşaması: Mevcut kod tabanıyla ilgili bilinmeyenleri çözer, research.md oluşturur.
  2. Tasarım aşaması: data-model.md (rezervasyon öğesi tanımı) oluşturur ve project-context.md öğesini günceller.

Antigravity, planlama sırasında adk-agent-development becerisini kullanmalıdır. Önemli çıktıları inceleyin:

  • specs/<branch-name>/plan.md: Hangi dosyaların değiştirileceği, hangi kalıpların izleneceği gibi teknik yaklaşım
  • specs/<branch-name>/data-model.md: Rezervasyon öğesi tanımı (sütunlar, türler, ilişkiler)
  • specs/<branch-name>/research.md — alınan kararlar ve gerekçeler

d9996ccbb3211078.png

Görev oluşturma

Görevler iş akışını çalıştırma

/speckit.tasks

Antigravity, planı specs/<branch-name>/tasks.md içinde sıralı bir görev listesine böler. Görevler, kimlikler, öncelik işaretleri ve dosya yolları içeren katı bir kontrol listesi biçiminde olmalıdır. Örneğin:

- [ ] [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

Görevler aşamalar halinde düzenlenir: Kurulum → Temel → Kullanıcı Hikayeleri → İyileştirme. Nelerin oluşturulacağını ve değiştirileceğini anlamak için görev listesini tarayın.

9fcdb822d8279ddf.png

Görevleri analiz etme (isteğe bağlı)

Görevlerdeki riskleri ve eksikleri incelemek için analiz iş akışını çalıştırın:

/speckit.analyze

Antigravity, görev listesini spesifikasyon ve plana göre kontrol ederek eksik uç durumları, çakışabilecek görevleri veya spesifikasyonun gereksinimleri ile planlanan çalışma arasındaki boşlukları arar. Uygulamadan önce kritik sorunları giderin.

6. Uygulama

Uygulama iş akışını çalıştırın:

/speckit.implement

Antigravity, nihai bir uygulama planı ve görev yapısı sunar. Devam etmek için inceleyip onaylayın.

adc1e3d098bd1638.png

306448e70f61ab51.png

Antigravity, görevleri tamamladıkça her birini işaretler. Tamamlandığında, eksiksiz bir rehber sunar.

48cc7752817a54c7.png

Kod değişikliklerini test etme

Uygulama tamamlandıktan sonra temel değişikliklerin yapıldığını doğrulayın. Dosya adları ve içerikleri farklılık gösterebilir ancak tools.yaml ve agent.py'deki gibi şu kalıplar bulunmalıdır:

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

Aşağıdakine benzer bir çıkış görürsünüz:

...
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
...

agent.py için

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

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

Şuna benzer değişiklikler görebilirsiniz:

...
- **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,
...

Değişiklikler, başlangıç veritabanı komut dosyasını etkilemelidir. Güncellenen komut dosyası, reservations tablosu mevcut değilse bu tabloyu oluşturmalıdır. Yeni tablonun oluşturulduğunu onaylayan bir çıkış görmeniz gerekir (mevcut menu_items verileri korunur).

Bu noktaya kadar her şey yolunda giderse özelliği ADK aracısı geliştirme kullanıcı arayüzünde test edebiliriz. Yeni tabloyu dahil etmek için veritabanı taşıma işlemini yapalım ve tools.yaml'daki yeni araç tanımlarını almak için araç kutusunu yeniden başlatalım. Mevcut Toolbox işlemlerini durdurup yeni bir işlem başlatın:

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

Antigravity'nin doğru kod ve yapılandırma oluşturup oluşturmadığını database_setup.log çıkış günlüğünden kontrol edebilirsiniz. Hatayla karşılaşırsanız düzeltmek için temsilciyle etkileşime geçmeyi deneyin.

Her şey yolunda giderse ADK geliştirme kullanıcı arayüzünü başlatabiliriz:

uv run adk web .

Tarayıcınızda http://localhost:8000 adresini açın ve aşağıdaki istemlerle test edin:

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

Do I have any upcoming reservations?

d9815389df37ed1a.png

f38a944851e28c29.png

Şimdi Ctrl+C tuşuna iki kez basarak ADK geliştirici kullanıcı arayüzünü durdurun.

7. Meydan okumalar (isteğe bağlı)

Artık SDD iş akışının tamamını biliyorsunuz. Test edin:

  • Restoran konsiyerji için web sohbeti arayüzü oluşturmak üzere ikinci bir SDD döngüsü çalıştırın. Bu kez adım adım talimatlar olmadan.
  • Üretim senaryosu için aracınızı Cloud Run'a dağıtma

İpuçları

  • Projenin ön uç çerçevesi yok. Antigravity, vanilla HTML/CSS/JS önermelidir. React veya benzeri bir şey önerirse basitliğe yönlendirin (Anayasanızdaki "basit tut" ilkesi bunu yakalamalıdır).
  • ADK sunucusu, akış için /run_sse ve oturum yönetimi için /apps/{app_name}/users/{user_id}/sessions uç noktalarını kullanıma sunar. Antigravity, bunları proje bağlamından keşfeder.
  • Uygulamadan sonra, statik dosya bağlama işleminin çalışması için sunucuyu uv run uvicorn server:app --host 0.0.0.0 --port 8080 (adk web değil) ile başlatın.
  • http://localhost:8080/static/index.html adresinde test edin.
  • Referans codelab'lerde ADK aracısının nasıl dağıtılacağı ve kalıcı hale getirileceği zaten gösteriliyor. Antigravity'ye bu konuda referans verin.

8. Tebrikler!

Antigravity'nin SDD iş akışlarını kullanarak, uygulama kodu yazmadan, tamamen rezervasyon kaydıyla bir restoran konsiyerji ADK aracısı oluşturdunuz.

Oluşturduğunuz öğeler

  • Menü arama, semantik arama, beslenme tercihi takibi ve rezervasyon yapma özelliklerine sahip bir restoran konsiyerji ADK aracısı
  • Bir proje bağlamı dokümanı oluşturan ve bunu koruyan, depo araştırması için kullanılan bir Antigravity becerisi
  • Planlama ve analiz sırasında pazarlığı mümkün olmayan ilkeleri uygulayan bir proje anayasası
  • Belirt → Açıkla → Planla → Görevler → Analiz et → Uygula iş akışını gösteren eksiksiz bir SDD döngüsü

Öğrendikleriniz

  • Mevcut bir kod tabanına sistematik olarak özellik eklemek için Antigravity'de spesifikasyon odaklı geliştirme iş akışlarını kullanma
  • Alan bilgisini paketleyerek sohbetlerde yeniden kullanmaya olanak tanıyan Antigravity becerileri oluşturma
  • Antigravity'nin mimari, kalıplar ve teknoloji seçimleri hakkında bilinçli kararlar alabilmesi için proje bağlamını nasıl başlatacağınız
  • SDD iş akışlarının doğrulama yapacağı bir proje anayasası oluşturma
  • MCP Toolbox aracılığıyla ADK aracısını yeni veritabanı destekli araçlarla genişletme

Temizleme

Çalışan yerel işlemleri durdurma (Toolbox):

pkill -f toolbox 2>/dev/null

Devam eden ücretlerden kaçınmak için Cloud SQL örneğini silin:

gcloud sql instances delete restaurant-db --quiet

İsteğe bağlı olarak, projenin tamamını silebilirsiniz:

gcloud projects delete $GOOGLE_CLOUD_PROJECT