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 şekilde referans veren spesifikasyon belgelerini güçlendirmek için yeni bir döngü sunarak Antigravity'nin spesifikasyon odaklı geliştirme paradigmasını güçlendirmenin bir yolu 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
reservationstablosuyla 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, 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şlatabilirsiniz?
- Antigravity becerileri oluşturma ve alan bilgisini (ör. ADK belgeleri, üçüncü taraf becerileri) yeniden kullanıma yönelik paketleyen MCP'yi yapılandırma
- 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
- Yerel makinenizde Google Antigravity ve
gityüklü olmalıdır. - Etkin bir faturalandırma hesabı olan 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) daha önce tamamlamış olmanız faydalı olacaktır:
- ADK ile Yapay Zeka Ajanları Oluşturma: Temel Bilgiler
- ADK ile Yapay Zeka Ajanları Oluşturma: Araçlarla Güçlendirme
- ADK ve Cloud SQL ile kalıcı yapay zeka ajanları oluşturma
- Cloud Run'da ADK aracısını dağıtma, yönetme ve gözlemleme
- Araç Olarak Veritabanı: ADK, MCP Toolbox ve Cloud SQL ile Ajan Tabanlı RAG
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 tüm başlangıç ADK aracı deposuna sahibiz. Şimdi her şeyin hazır olmasını beklerken bir 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ıLlmAgentileToolContexttabanlı beslenme tercihi takibiyle birleştiren bir çözüm. Aracı, Araç Kutusu sunucusundaki tüm araçları yükler ve durumu yönetmek içinToolContextkullanan 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),pgvectoraracı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'dakiget_fast_api_app(), SSE akışı ve oturum yönetimi API'leri için/run_ssedahil 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 gerekensources,toolsveembeddingModelsyapı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.mdoluş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 destekli 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.
Spesifikasyona Dayalı Geliştirme (SDD), bu döngüye yapı kazandırır. 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şdur: SDD, sezgisel 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) hafızadan kararları açıklamak yerine spesifikasyonlara yönlendirerek dahil edebilirsiniz.
Antigravity, spesifikasyon odaklı geliştirme ilkelerine zaten uymaktadır. Ajanı Planlama moduna ayarladığınızda herhangi bir kod yazmadan önce iki yapı üretir:
- Uygulama Planı: Önerilen teknik yaklaşım, dosya değişiklikleri ve mimari kararlara genel bakış
- 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 olan spec-kit'e dayalı, görüşe dayalı 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 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 |
|
| NE inşa edeceğinizi tanımlayın (kullanıcıya yönelik, teknolojiden bağımsız) |
| Son güncelleme: | Yeterince belirtilmemiş alanları belirleme, hedeflenmiş açıklama soruları sorma, yanıtları tekrar spesifikasyona kodlama |
|
| Nasıl oluşturulacağını tasarlama (teknik yaklaşım, veri modelleri, araştırma) |
|
| Planı sıralı ve uygulanabilir adımlara ayırın |
| Analiz raporu | Uygulamadan önce görevlerdeki riskleri, eksikleri veya gözden kaçan uç durumları inceleyin. |
| 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 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ı hakkında derinlemesine bilgi vermek için bir yaklaşım örneği gösterilmektedir. Bu yaklaşımda, depoyu analiz eden ve bir 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 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 becerinindescriptionalanı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/ dilinde ö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ı aşağıdaki ö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ı 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/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.
ADK Docs MCP'yi yapılandırma
Kodlama aracımızın ADK aracımızı nasıl geliştireceği konusunda doğru bilgiye sahip olmasını sağlamak için ADK belgelerine uygun erişim izni verilmesi gerekir. ADK dokümanları MCP sunucusunu ayarlayarak bu özelliği etkinleştirebiliriz .
Öncelikle Antigravity düzenleyicisinde sağ üstteki aracı penceresinde "üç nokta" simgesini bulup tıklayın. MCP için yapılandırma seçeneklerini ve bu şekilde özelleştirme seçeneklerini görürsünüz. MCP'yi tıklayın.
\
Ardından, Manage MCP servers düğmesini tıklayın.
MCP sunucusu yapılandırmaları sekmesi açılır. Ardından View Raw Config düğmesini tıklayın.
mcp_config.json dosyası açılır. Şimdi bu yapılandırmayı dosyaya kopyalayıp yapıştırın.
{
"mcpServers": {
"adk-docs-mcp": {
"command": "uvx",
"args": [
"--from",
"mcpdoc",
"mcpdoc",
"--urls",
"AgentDevelopmentKit:https://adk.dev/llms.txt",
"--transport",
"stdio"
]
}
}
}
Bu kurulum, kodlama aracısının MCP sunucusu kullanarak ADK belgelerinde arama yapmasına ve bunları okumasına olanak tanır.
Herkese açık becerileri yükleme
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.
Caveman Skills
Token kullanımını azaltmak için faydalı 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.
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/ ├── 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.
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 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.
5. SDD Cycle — Add Reservation Feature
Bu adımda, restoranın concierge aracısına rezervasyon eklemek için eksiksiz bir SDD döngüsü açıklanmaktadır. Her aşamada (belirleme, 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 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 ele alınır.
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, 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. Utilize your access to ADK Docs tools and MCP toolbox skill to implement it properly
Antigravity, iki aşamada teknik bir plan oluşturur:
- Araştırma aşaması: Mevcut kod tabanıyla ilgili bilinmeyenleri çözer,
research.mdoluşturur. - Tasarım aşaması:
data-model.md(rezervasyon öğesi tanımı) oluşturur veproject-context.mdöğesini günceller.
Antigravity, planlama sırasında ADK Dokümanları MCP araçlarını ve MCP Araç Kutusu Dokümanları 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şımspecs/<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ö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 gereklilikleri ile planlanan çalışma arasındaki boşlukları arar. Uygulamadan önce kritik sorunları ele alın.
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.
Antigravity, görevleri tamamladıkça her birini işaretleyerek yürütür. 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. 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?
Şimdi Ctrl+C tuşuna iki kez basarak ADK geliştirici kullanıcı arayüzünü durdurun.
7. Zorluklar (isteğe bağlı)
Artık SDD iş akışının tamamını biliyorsunuz. Test edin:
- Restoran konsiyerji hizmeti için bir web sohbet 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}/sessionsuç 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 webdeğil) ile başlatın. http://localhost:8080/static/index.htmladresinde 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ı aracılığıyla, 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
- Antigravity becerileri oluşturma ve MCP'yi yapılandırma
- 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):
lsof -ti:5000 | xargs kill -9 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