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, spec-kit'e yoğun bir şekilde referans veren spesifikasyon dokümanlarını güçlendirmek için yeni bir döngü sunarak Antigravity Spec-driven Development paradigmasını güçlendirmenin bir yolunu tanıtıyor.

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.
(Zorluk) – Temsilci için kendi kullanıcı arayüzünüzü geliştirin
(Zorluk) – Antigravity aracısının yardımıyla Google Cloud'a dağıtma

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, uygulamanızı spesifikasyonlarınıza göre gerçekleştirir.

Neler öğreneceksiniz?

Antigravity'nin mevcut bir kod tabanını anlaması için proje bağlamını nasıl başlatacağınız
Alan bilgisi içeren Antigravity becerileri oluşturma (ör. ADK codelab kalıpları)
Planlama ve analiz sırasında SDD iş akışlarının doğrulayacağı bir proje anayasası oluşturma
Antigravity'de özellikleri sistematik olarak eklemek için Spec-Driven Development (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

Yerel makinenizde Google Antigravity ve git yüklü olmalıdır.
Deneme faturalandırma hesabı etkinleştirilmiş bir Google Cloud hesabı
Kullanım alanı bağlamını anlamak için ön koşul niteliğindeki dört ADK codelab'ini (veya eşdeğer bilgileri) önceden tamamlamış olmanız faydalı olacaktır:
ADK ile Yapay Zeka Temsilcileri Oluşturma: Temel
ADK ile Yapay Zeka Temsilcileri Oluşturma: Araçlarla Güçlendirme
ADK ve Cloud SQL ile Kalıcı Yapay Zeka Temsilcileri Oluşturma
Cloud Run'da ADK Aracısını Dağıtma, Yönetme ve İzleme
Araç Olarak Veritabanı: ADK, MCP Toolbox ve Cloud SQL ile Agentic RAG

2. Ortamınızı ayarlama

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.

Başlangıç deposunu klonlama

Antigravity'de (veya sistem terminalinizde) bir terminal açın. Yardımcı 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. Dosya->Klasörü Aç->klonlanmış dizini seçin sdd-adk-agents-agy

Yukarı akış uzak 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

Ön koşulları yükleme

Ön koşul komut dosyasını çalıştırın. git, curl, gcloud, uv, Python 3.12 ve MCP Toolbox'ı kontrol eder (eksikse yükler):

bash scripts/setup_prerequisites.sh

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 ile yerel olarak çalıştığınız için kimlik doğrulama işlemini manuel olarak yaparsınız. auth login, gcloud CLI'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ı, 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, ardından proje kimliğini .env konumuna kaydedip 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

Gerekli API'leri etkinleştirin:

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

Cloud SQL'i sağlama

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

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

Cloud SQL örneğini oluşturun:

gcloud sql instances create restaurant-db \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --region=${REGION} \
  --availability-type=ZONAL \
  --tier=db-custom-1-3840 \
  --root-password=${DB_PASSWORD} \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on &

Vertex AI ML entegrasyonu için gereken minimum katman db-custom-1-3840 katmanıdır. --enable-google-ml-integration işareti, Cloud SQL'in Gemini yerleştirme modellerini doğrudan SQL'den çağırmasına olanak tanır. Bu, semantik arama özelliğini destekler.

Bağımlıları yükleme

Yeni bir terminal sekmesi açın. Klonlanan depo proje dizininde olduğunuzdan emin olun ve ortam değişkenlerini yeniden yükleyin:

source .env

Python proje yöneticisi olarak uv'ı kullanacağız. uv, Rust ile yazılmış hızlı bir Python paketi ve proje yöneticisidir ( belgeler). 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

Artık üzerinde çalışabileceğimiz, gerekli tüm başlangıç ADK aracısı deposuna sahibiz. Şimdi de her şey hazır olana kadar beklerken sonraki bölümde Antigravity ve spesifikasyona dayalı geliştirme hakkında daha fazla konuşalım.

3. Başlangıç kodunu keşfedin ve spesifikasyona dayalı geliştirme hakkında bilgi edinin

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)
│   │   ├── adk-agent-development/
│   │   │   ├── SKILL.md     # ADK patterns
│   │   │   └── examples/
│   │   │       ├── basic_agent.py
│   │   │       ├── Dockerfile
│   │   │       ├── server.py
│   │   │       ├── stateful_agent.py
│   │   │       ├── toolbox_agent.py
│   │   │       ├── tools_agent.py
│   │   │       └── tools.yaml
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis 
│   └── 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

Temsilci Uygulama Dosyaları

restaurant_concierge/agent.py: Temel aracı. MCP Toolbox veritabanı araçlarını ToolContext tabanlı beslenme tercihi takibiyle birleştiren bir LlmAgent. 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ımlanmıştır: anahtar kelime araması (search_menu), pgvector üzerinden 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/adk-agent-development/SKILL.md: Dört ADK codelab'indeki tüm referans kalıplarının özetini içeren, önceden yapılandırılmış bir beceri ( Antigravity tarafından oluşturulmuştur). Şu anda etkin değil (YAML ön materyali eksik). Bunu daha sonra güncellemeniz gerekir. Antigravity, ADK aracı özellikleriyle ve örnekleriyle ilgili bir çalışma tespit ettiğinde bu beceriyi otomatik olarak yükler. Bu bilgi, Antigravity'nin daha sonra rezervasyon özelliğini planlarken kullandığı bilgidir.
.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. ADK becerisi gibi, YAML ön materyali ekleyene kadar bu beceri de etkin değildir. Etkinleştirildikten sonra, mimari, çalışma zamanı bağımlılıkları, API yüzeyi ve alan sözlüğünü kapsayan kapsamlı bir oryantasyon belgesi (.agents/rules/project-context.md) oluşturmak için bu özelliği çağırın.

Spec-Driven Development: 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 "vibe coding" (atmosfer kodlama) olarak adlandırılır. Çıkışın işe yarayıp yaramadığına göre kabul ederek veya 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.

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 inceleme sırasında bunu 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ş: SDD, vibe kodlamaya göre ö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) kararları hafızadan açıklamak yerine spesifikasyonlara yönlendirerek dahil edebilirsiniz.

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

Uygulama Planı: Önerilen teknik yaklaşımın, dosya değişikliklerinin ve mimari kararların genel bir görünümü
Görev listesi: İş öğelerinin yapılandırılmış dökümü

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, GitHub'ın spesifikasyona dayalı geliştirme çerçevesi spec-kit'e dayalı, fikir odaklı ve sürüm kontrollü bir iş akışıyla bu temeli daha da ileriye taşı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 işlem hattından 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örevleri riskler, eksikler veya eksik uç durumlar açısından inceleyin.
`/speckit.implement`	Kod değişiklikleri	Görevleri tamamlayın ve her birini işaretleyin.

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 kullanacaksınız.

4. Cloud SQL kurulumunu tamamlama ve temel aracının işlevsel olduğundan emin olma

Cloud SQL oluşturma komutunun çalıştığı terminal sekmesine geri dönün. İşlem tamamlandıktan sonra örneğin hazır olduğunu doğrulayın:

gcloud sql instances describe restaurant-db --format="value(state)"

Çıktıda RUNNABLE gösteriliyorsa devam edin. PENDING_CREATE gösteriliyorsa kısa bir süre bekleyin ve komutu yeniden çalıştırın.

Cloud SQL hizmet hesabına Vertex AI'a erişim izni verin (veritabanı içi yerleştirme işlevi için gereklidir):

SERVICE_ACCOUNT=$(gcloud sql instances describe restaurant-db --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

Veritabanını oluşturun:

gcloud sql databases create restaurant_db --instance=restaurant-db

Çıkış şu şekilde görünmelidir:

Creating Cloud SQL database...done.
Created database [restaurant_db].
instance: restaurant-db
name: restaurant_db
project: <your-project-id>

Veritabanını başlatma

Ortam değişkenlerinizi yükleyin ve şemayı oluşturup 16 menü öğesi eklemek için veritabanı başlangıç komut dosyasını çalıştırın:

source .env
uv run python scripts/seed_db.py

Beklenen çıktı:

Creating extensions...
Creating menu_items table...
Inserting 16 menu items...
Seeded 16 menu items.
Done.

Semantik arama için vektör yerleştirmeleri oluşturma:

uv run python scripts/generate_embeddings.py

Beklenen çıktı:

Generating embeddings for 16 menu items...
Generated embeddings for 16 menu items.

Bu işlem, gemini-embedding-001 işlevini doğrudan SQL'den çağırmak için Cloud SQL'in yerleşik embedding() işlevini (google_ml_integration uzantısı aracılığıyla) kullanır. 3.072 boyutlu vektörler, menu_items tablosunun embedding sütununda depolanır. Uygulama tarafında yerleştirme kodu gerekmez.

Temel temsilciyi test etme

MCP Toolbox'ı arka plan işlemi olarak başlatın:

set -a; source .env; set +a # Export env variables to child process
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

Araç kutusu, veritabanı araçlarını HTTP üzerinden sunar. Temsilci, http://127.0.0.1:5000 adresinden cihaza bağlanır.

ADK geliştirici kullanıcı arayüzünü başlatın:

uv run adk web .

Geliştirici kullanıcı arayüzünü tarayıcınızda açın. Ardından, aşağıdaki istemlerle temsilciyi test edin:

What appetizers do you have?

I'm vegetarian

Can I make a reservation for tomorrow?

Ctrl+C tuşuna iki kez basarak ADK geliştirici kullanıcı arayüzünü durdurun. Araç kutusunu arka planda çalışır durumda bırakın. Daha sonra tekrar kullanacaksınız.

5. 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 için kullandığı, pazarlığa açık olmayan ilkeler olan proje anayasasını da oluşturur. Bunlar birlikte, Antigravity'ye daha sonraki SDD döngüleri için ihtiyaç duyduğu 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 materyali 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

Aç

.agents/skills/adk-agent-development/SKILL.md

düzenleyicide. En üstteki iki TODO(codelab) yorum satırını aşağıdaki ön maddeyle değiştirin:

---
name: adk-agent-development
description: Comprehensive guide for building, developing, and deploying AI agents using Google's Agent Development Kit (ADK) with Gemini models, covering agent creation, tools, state management, persistence, deployment, and database integration via MCP Toolbox.
---

Aç

.agents/skills/repo-research/SKILL.md

düzenleyicide. En üstteki iki TODO(codelab) yorum satırını aşağıdaki ö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/adk-agent-development/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.

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

Antigravity, isteğinizi repo-research becerisiyle 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. Bu dokümanda proje hakkında somut bilgiler yer alır: teknoloji yığını (Python 3.12, ADK, MCP Toolbox, Cloud SQL), proje yapısı, veri modeli (pgvector ile menu_items tablosu) ve harici entegrasyonlar.

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, pazarlığı mümkün olmayan 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 ve 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.

6. 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özlemliyorsunuz. 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çıklar. 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.

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, belgede 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

Antigravity, iki aşamada teknik bir plan oluşturur:

Araştırma aşaması: Mevcut kod tabanıyla ilgili bilinmeyenleri çözer, research.md oluşturur.
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. Temel çı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

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.

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

Görevleri riskler ve eksikler açısından 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.

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

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

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. Komut dosyasını yürütmeyi deneyelim.

source .env
uv run python scripts/seed_db.py

Güncellenen komut dosyası, reservations tablosu mevcut değilse bu tabloyu oluşturmalıdır. Yeni tablonun oluşturulduğunu onaylayan bir çıkış görmelisiniz (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. tools.yaml'daki yeni araç tanımlarını almak için araç kutusunu yeniden başlatın. Mevcut Toolbox işlemlerini durdurun ve yeni bir işlem başlatın:

pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

ADK geliştirici kullanıcı arayüzünü başlatın:

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?

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

8. Zorluklar (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, 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. Bu konuda Antigravity'ye referans verin.

9. Tebrikler!

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

Oluşturduğunuz içerikler

Menü arama, semantik arama, beslenme tercihi takibi ve rezervasyon yapma özelliklerine sahip bir restoran concierge ADK aracısı
Bir proje bağlamı dokümanı oluşturan ve bu dokümanı güncel tutan, 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

Antigravity'de, Spec-Driven Development iş akışlarını kullanarak mevcut bir kod tabanına sistematik olarak özellik ekleme
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 (Araç Kutusu):

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