Antigravity CLI ile Spesifikasyon Odaklı Geliştirme: Beceriler ve MCP ile Yapılandırılmış Ajan İş Akışları

1. Giriş

MVP'yi vibe-coding ile hızlıca oluşturabilirsiniz ancak duvara daha fazla istem atarak özellik eklemek projelerin bozulmasına neden olur. Yapay zeka destekli geliştirmeye yapı ve gerçek dünya bağlamı katmanın bir yolunu bulmanız gerekir. Antigravity CLI, tam da bu noktada devreye girer. Terminalinizde çalışan bir yapay zeka kodlama aracısıdır. Kendi başına kod tabanınızı anlayabilir, komutları çalıştırabilir ve dosyaları düzenleyebilir. Gerçek gücü, taktığınız cihazlardan gelir:

• Beceriler, ajana metodoloji ve alan bilgisi sağlar. Metodoloji becerisi, yapılandırılmış geliştirme iş akışlarını zorunlu kılarken alan becerisi, ajanın halüsinasyon görmemesi için doğru API bilgisi sağlar.
• MCP sunucuları, ajana harici sistemlerle canlı bağlantılar kurma olanağı tanır. Böylece ajan, eski eğitim bilgilerine güvenmek yerine gerçek şemaları inceleyebilir, sorgular çalıştırabilir ve çalışmasını gerçek verilere göre doğrulayabilir.

Beceriler, ajanın nasıl düşüneceğini şekillendirir. MCP ise ajanın ne görebileceğini ve neyle etkileşime girebileceğini şekillendirir. Bu araçlar, genel amaçlı bir kodlama aracısını gerçek dünya verilerine dayalı yapılandırılmış bir iş akışını takip eden bir araca dönüştürür. Bu codelab'de, eklentileri yüklemekten bir özelliği kullanıma sunmaya kadar bu kombinasyonun nasıl kullanılacağı adım adım açıklanmaktadır.

Ne oluşturacaksınız?

Bu codelab'deki kalıplar (metodoloji ve alan bilgisi için beceri yükleme, canlı veri erişimi için MCP sunucularını bağlama ve spesifikasyona dayalı geliştirme döngüsü çalıştırma), dil, çerçeve veya Google Cloud ürünlerinden bağımsız olarak Antigravity CLI ile oluşturduğunuz tüm özellikler için geçerlidir. Bu kalıpları somutlaştırmak için belirli bir örnek üzerinde çalışırsınız: e-ticaret analizleri kontrol paneline BigQuery entegrasyonu ekleme.

Başlangıç uygulaması, statik CSV dosyalarından satış verilerini okuyan ve grafikleri (gelir trendleri, en çok satan ürünler, sipariş durumu dökümü, kategori performansı) oluşturan bir FastAPI web uygulamasıdır. Uygulama, sonunda BigQuery'den canlı verileri sorgular. BigQuery, Google Cloud'un sunucusuz veri ambarıdır ve altyapı yönetmeden büyük veri kümelerinde SQL sorguları çalıştırmanıza olanak tanır. Özellikle thelook_ecommerce veri kümesine bağlanarak 500 satırlık bir CSV dosyasının sağlayamayacağı sipariş, ürün ve müşteri kataloğunun tamamına erişebilirsiniz. Bu özelliği tamamen Antigravity CLI üzerinden, beceriler ve MCP rehberliğinde oluşturursunuz.

Antigravity CLI ile kullanacağımız aracı yapılandırması şu şekilde görünür:

Neler öğreneceksiniz?

• Cloud Shell'de Antigravity CLI'yı kullanma: başlatma, TUI'de gezinme ve slash komutlarını çalıştırma
• Aracı becerileri ve aşamalı açıklama kalıbının (meta veriler → talimatlar → kaynaklar) bağlamı nasıl verimli tuttuğu
• Üç beceri kategorisi: metodoloji (süper güçler), verimlilik (mağara adamı) ve alan bilgisi (Google/beceriler)
• MCP nedir ve Antigravity CLI için uzak MCP sunucusu (BigQuery MCP) nasıl yapılandırılır?
• Spesifikasyona dayalı geliştirme döngüsü nasıl yürütülür: belirtme → planlama → uygulama
• (İsteğe bağlı) Antigravity CLI'da alt aracıların işleyiş şekli ve nasıl yönetileceği
• google-cloud-bigquery Python istemci kitaplığını FastAPI uygulamasına entegre etme
• (İsteğe bağlı) Antigravity KSA'yı kullanarak uygulamayı Cloud Run'a dağıtma

Ön koşullar

• Google Cloud hesabı
• Python, REST API'ler ve Terminal komutu hakkında temel düzeyde bilgi sahibi olma

2. Ortamınızı ayarlama

Bu adımda başlangıç deposu klonlanır, Google Cloud projeniz yapılandırılır ve ihtiyacınız olan API'ler etkinleştirilir.

Cloud Shell'i açma

Tarayıcınızda Cloud Shell'i açın. Cloud Shell, bu codelab için ihtiyacınız olan tüm araçların bulunduğu önceden yapılandırılmış bir ortam sunar. İstendiğinde Yetkilendir'i tıklayın.

Cloud Shell'i açın.

Ardından, terminali açmak için "Görünüm" -> "Terminal"i tıklayın. Arayüzünüz aşağıdaki gibi görünmelidir.

Bu, ana arayüzümüz olacak. Üstte IDE, altta terminal yer alacak.

Çalışma dizininizi ayarlama

Bu codelab'in başlangıç kodunu içeren yardımcı depoyu klonlayın:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

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

Bu depoda, statik CSV dosyalarından okuma yapan eksiksiz ve çalışan bir e-ticaret kontrol paneli uygulaması yer almaktadır. Bu codelab boyunca, yeni bir özellik olarak BigQuery entegrasyonu eklemek için Antigravity CLI'yı kullanacaksınız.

Anahtar dosyalar ve dizinler:

• src/main.py — Kontrol paneli verilerini sunan API uç noktalarına sahip FastAPI uygulaması
• src/data_service.py — pandas kullanarak CSV dosyalarından okuma yapan veri katmanı
• src/templates/dashboard.html: Chart.js görselleştirmeleri içeren Jinja2 şablonu
• data/: E-ticaret verilerinin küçük bir alt kümesini içeren statik CSV dosyaları (orders.csv, products.csv, order_items.csv)

Uygulama, basit bir salt okunur kontrol panelidir: main.py API uç noktalarını tanımlar, data_service.py CSV dosyalarını okur ve yapılandırılmış veriler döndürür, dashboard.html bu verileri grafik olarak oluşturur. Oluşturduğunuz BigQuery entegrasyonu, data_service.py yerine statik dosyaları okumak yerine canlı verileri sorgulayan bir modül kullanır.

Terminali Yapılandırma

Google Cloud projesi oluşturma ( isteğe bağlı)

❗ Google Cloud projeniz varsa bu bölümü atlayın

Yeni proje oluşturmak için Cloud Console kullanıcı arayüzünü kullanabilirsiniz. Sol üstteki proje seçiciyi tıklayıp New Project

VEYA daha hızlı bir yöntem istiyorsanız terminalde aşağıdaki komutu çalıştırın.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

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

Bu işlem, rastgele proje kimliğine sahip bir Google Cloud projesi oluşturur. Komut, oluşturulan proje kimliğini verir. Yapılandırmada daha sonra YOUR_PROJECT_ID olarak kullanın.

Terminali etkinleştirme

Şimdi de terminalimizi seçilen Google Cloud projesiyle yapılandırmamız gerekiyor. Kullanılabilir projelerinizi listelemek ve seçmek istediğiniz proje kimliğini bulmak için aşağıdaki komutu çalıştırın:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

gcloud projects list

Buna benzer bir liste gösterilir. Kullanacağınız proje kimliğini hatırlayın veya kopyalayın.

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

Şimdi terminali etkinleştirecek bir komut dosyası oluşturmak için aşağıdaki komutu çalıştırın ( veya bu dosyayı kendiniz de oluşturabilirsiniz):

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

cloudshell edit configure_terminal.sh

Ardından aşağıdaki kodu komut dosyasına kopyalayın.

📄 Bunu dosyaya kopyalayıp kaydedin.

YOUR_PROJECT_ID değerini önceki adımda seçilen proje kimliğiyle değiştirin.

#!/bin/bash

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

YOUR_PROJECT_ID yerine proje kimliğinizi yazın. Önceki komut, proje kimliğini codelab boyunca kullanılacak bir ortam değişkeni olarak da dışa aktarır. Ardından dosyayı kaydedip çalıştırın.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

bash configure_terminal.sh

Not: Terminalinizi veya web sayfanızı kapatır ya da yeniden başlatırsanız terminalinizi yapılandırmak için bu komutu tekrar çalıştırmayı unutmayın.

Cloud Shell terminal isteminde çalışma dizininizin yanındaki sarı metni kontrol ederek projenin doğru şekilde ayarlandığını doğrulayın. Proje kimliğiniz gösterilmelidir.

Gerekli API'leri etkinleştirme

Ardından, kullanım alanı senaryomuzla ilgili olan BigQuery ile etkileşim kuracağız. Bu codelab için gereken Google Cloud API'lerini etkinleştirin:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

gcloud services enable bigquery.googleapis.com

Not: API'lerin etkinleştirilmesi biraz zaman alabilir. Bunu proje başına yalnızca bir kez yapmanız gerekir.

Bu API, BigQuery'ye erişmemizi sağlar. Şimdi bu codelab senaryosu için ilk veri kümemizi hazırlayalım.

3. BigQuery veri kümesini ayarlama

Senaryo: Şirketinizde BigQuery'de depolanan e-ticaret verileri (siparişler, ürünler ve sipariş öğeleri) var. Sipariş verileri kontrol panelini göstermek için bir uygulama geliştiriyorsunuz ancak başlangıçta ön uca odaklanabilmeniz için şu anda bu verilerin yalnızca küçük bir CSV özeti okunuyor. Şimdi ise tam veri kümesi için doğrudan BigQuery'yi sorgulayacak şekilde yükseltmek istiyorsunuz.

Bunu simüle etmek için TheLook E-commerce'i kullanırsınız. Bu, Google tarafından bakımı yapılan ve gerçekçi sentetik e-ticaret verileri (125.000'den fazla sipariş, 29.000'den fazla ürün) içeren herkese açık bir veri kümesidir. İlgili tabloları kendi projenizin BigQuery örneğine kopyalarsınız. Böylece bu tablolar "şirketinizin verileri" olarak kullanılır.

Cloud Shell'de, BigQuery ile doğrudan etkileşim kurmak için kullanabileceğimiz bq CLI'sı zaten vardır. Bu nedenle, verilerimizi doğrudan hazırlayabiliriz.

Projenizde bir veri kümesi oluşturun:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

bq mk --dataset $GOOGLE_CLOUD_PROJECT:thelook_ecommerce

Herkese açık veri kümesindeki üç tabloyu yeni veri kümenize kopyalayın:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

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

Tabloların veri kümenizde olduğunu doğrulayın:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

bq ls $GOOGLE_CLOUD_PROJECT:thelook_ecommerce

orders, order_items ve products olmak üzere üç tablo listelenir.

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

Verilere erişilebildiğini doğrulamak için hızlı bir test sorgusu çalıştırın:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

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

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

100.000'den fazla sipariş sayısı görmelisiniz.

4. İlk Web Uygulamasını Çalıştırma

Uygulamayı yükseltmeden önce, CSV destekli kontrol panelinin nasıl göründüğünü görmek için uygulamayı mevcut haliyle çalıştıralım.

uv, Rust ile yazılmış hızlı bir Python paketi ve proje yöneticisidir ( dokümanlar). Bu codelab, hız ve basitlik için bu yöntemi kullanır. Bu eğitim için Cloud Shell'i kullanıyorsanız bu araç, örnekte önceden yüklenmiştir. Yerel makinenize yüklemek istiyorsanız bu eğitime bakın.

Proje bağımlılıklarını yükleyin. Bu işlem, sanal ortamı da sizin için hazırlar:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

uv sync

Bundan sonra, Python'ı biliyorsanız python komutunu yürütmek yerine her komutu uv ikili programıyla yürüteceğiz. FastAPI geliştirme sunucusunu başlatın:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

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

Cloud Shell'in Web Önizleme özelliğini kullanarak kontrol panelini tarayıcınızda açın. Web Önizlemesi düğmesini (Cloud Shell araç çubuğundaki göz simgesi) tıklayın ve 8080 numaralı bağlantı noktasında önizle'yi seçin.

İpucu: Cloud Shell'de Web Önizleme'yi kullanmak için Cloud Shell araç çubuğunda Web Önizleme düğmesini (göz simgesi) tıklayın ve 8080 bağlantı noktasında önizle'yi seçin.

Kontrol panelinde dört grafik paneli gösterilir:

• Gelir Trendi: CSV verilerindeki tarih aralığında günlük geliri gösteren çizgi grafik
• Gelire Göre En Popüler Ürünler: Ürünleri toplam satışa göre sıralayan yatay çubuk grafik
• Sipariş Durumu Dökümü: Tamamlanan, kargolanan, işlenen, iptal edilen ve iade edilen siparişlerin dağılımını gösteren bir halka grafik
• Kategori Performansı: Ürün kategorisine göre geliri gösteren yatay çubuk grafik

Başlıktaki Veri kaynağı: CSV rozetine dikkat edin. Özet kartlarında, 500 sipariş ve yaklaşık 750 sipariş öğesinden hesaplanan toplamlar gösterilir. Bu, TheLook veri kümesinin küçük bir alt kümesidir. Tarih aralığı Ekim-Aralık 2023 ile sınırlıdır.

Bu, temel uygulamamız. Şimdi Antigravity CLI yardımıyla BigQuery ile entegre olacak şekilde yükselteceğiz.

Not: Şimdilik Ctrl + C simgesini iki kez tıklayarak mevcut web uygulaması sürecini sonlandıralım.

5. Antigravity CLI'yı kurma

Bu adımda Antigravity CLI tanıtılmakta, Terminal Kullanıcı Arayüzü açıklanmakta ve geliştirme iş akışımızı hızlandırmak için üç kategoriye ait eklentiler yüklenmektedir. Bu süreçte, ajan becerilerinin ve MCP'nin ne olduğunu ve bunların yapay zeka kodlama ajanının özelliklerini nasıl genişlettiğini öğreneceksiniz.

Antigravity CLI nedir?

Antigravity CLI, Google'ın yapay zeka kodlama aracının bir varyantıdır: terminal için Antigravity. Bu, Antigravity 2.0 masaüstü uygulamasını destekleyen aynı aracı donanımına bağlanan, Go ile oluşturulmuş hafif bir Terminal Kullanıcı Arayüzü'dür (TUI). Kod tabanınızı okur, komutları çalıştırır, dosyaları düzenler ve MCP aracılığıyla harici araçlara bağlanır. Tüm bu işlemler terminalden yapılır.

Bu eğitim için Cloud Shell'i kullanıyorsanız Antigravity CLI, Cloud Shell'e önceden yüklenmiştir. Aşağıdaki komutu çalıştırarak kontrol edebilirsiniz.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

agy --help

Aşağıdaki komut seçenekleri ayrıntılarını gösterir:

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

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

Antigravity CLI'yı başlatma

Şimdi, Antigravity CLI'ı ilk kez kullanıyorsanız kurmanız gerekir. Yeni terminal sekmenizde başlatın.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

agy

İlk kez çalıştırıyorsanız kimlik doğrulama yöntemini seçmeniz istenir.

Bu eğitimde Google OAuth uygulamasını kullanalım. Bu uygulama, oturum açmak için kullanacağınız Google Hesabı'nı seçmenizi isteyen bir URL açmanızı ister.

Kimlik doğrulama'yı tıkladıktan sonra Google Hesabı'nı seçin ve Sign In simgesini tıklayın.

Kopyalanacak bir dize gösterilir. Kopyalamak için Copy to Clipboard simgesini tıklayın.

Ardından, aşağıda gösterildiği gibi Antigravity CLI istemine yapıştırın.

Not: Terminale kopyalamak için Ctrl+Shift+V VEYA sağ tıklayıp Paste simgesini kullanın.

Ardından, bir renk teması ve kullanım şartları sözleşmesi seçmeniz istenir.

Ayrıca, mevcut çalışma alanı dizinine güvenmeniz istenir. Bunu kabul ettiğinizde devam edebiliriz. Bu, terminalde Antigravity CLI ile etkileşimimizin ana girişi olacaktır.

Şimdilik Antigravity CLI'dan çıkalım ve sonraki bölüme geçelim.

Not: Çıkmak için Ctrl+D tuşuna iki kez basın.

6. Özelleştirme - Ajan Becerileri

Antigravity CLI, kutudan çıktığı haliyle kod tabanınızı okuyabilir, kabuk komutlarını çalıştırabilir ve dosyaları düzenleyebilir. Yerleşik olarak sınırlı bir spesifikasyon odaklı geliştirme iş akışına sahiptir ve belirli API'ler hakkındaki bilgisi, eğitim verilerinde yer alan bilgilerle sınırlıdır. BigQuery'yi mevcut bir uygulamaya entegre etme gibi bir görevde iki boşluk görünür:

1. Süreç boşluğu: Antigravity CLI, yapı olmadan doğrudan kod yazmaya başlayabilir. Küçük düzeltmeler için bu yöntem uygundur. Birden fazla dosyaya ve uç noktaya dokunan bir özellik için tutarsız uygulamalar, eksik uç durumlar ve neye karar verildiği ya da neden karar verildiğiyle ilgili dokümanlar olmaz.
2. Bilgi boşluğu: Model eğitim verileri, eski BigQuery istemci kitaplığı kalıplarını, kullanımdan kaldırılmış API çağrılarını veya yanlış tablo şemalarını içerebilir. Gerçek veri kümesinin şu anda nasıl göründüğünü kontrol etme yolu yoktur.

Beceriler, süreçteki boşluğu kapatır. superpowers gibi bir geliştirme metodolojisi becerisi, belirtme-planlama-uygulama döngüsünü zorunlu kılar. Yani, siz bir spesifikasyonu onaylayana kadar aracı kod yazmaz. bigquery-basics gibi bir alan becerisi, güncel ve Google tarafından bakımı yapılan API belgeleri sağlar. Böylece aracı, doğru istemci kitaplığı kalıplarını kullanır.

MCP sunucuları, çalışma zamanında bilgi boşluğunu kapatır. BigQuery MCP, ajana gerçek veri kümenize canlı bağlantı sağlar. Bu sayede tabloları listeleyebilir, sütun türlerini inceleyebilir ve örnek sorgular çalıştırabilir. Ajan, tahminlere değil gerçek şema verilerine göre çalışır.

Bu iki

Temsilci becerileri

Ajan becerileri, uzmanlık bilgisi ve iş akışlarıyla yapay zeka ajanı özelliklerini artırmak için kullanılan basit ve açık bir formattır. Her beceri, SKILL.md dosyası içeren taşınabilir ve sürüm kontrollü bir dizindir. Bu dosya, aracının belirli bir görevi nasıl ele alacağını tanımlayan, makine tarafından okunabilir bir sözleşmedir.

Beceri dizini şu şekilde görünür:

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

Temel olarak beceri, SKILL.md dosyası içeren bir klasördür. Bu dosya, meta veriler (en azından ad ve açıklama) ve bir temsilciye belirli bir görevin nasıl gerçekleştirileceğini söyleyen talimatlar içerir. Beceriler, komut dosyalarını, referans materyallerini, şablonları ve diğer kaynakları da paketleyebilir.

Bu codelab'de daha sonra kullanacağınız bigquery-basics becerisi için SKILL.md aşağıda verilmiştir:

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

# BigQuery Basics

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

YAML ön madde (ad + açıklama + meta veriler), Antigravity CLI'ın başlangıçta yüklediği hafif meta verilerdir. --- işaretinin altındaki Markdown gövdesi, yalnızca Antigravity BigQuery ile ilgili bir görev algıladığında yüklenen tam talimat setidir.

İlerleme durumu açıklaması

Beceriler, bağlam penceresinin dolmasını önleyen üç katmanlı bir aşamalı açıklama modeli kullanır:

1. 1. Katman (Keşif): Antigravity, başlatıldığında yüklü her becerinin yalnızca YAML meta verilerini okur. Beceri mevcuttur. Başka bir bilgi yoktur.
2. 2. Katman (Etkinleştirme): Göreviniz bir becerinin açıklamasıyla eşleştiğinde AGY, SKILL.md'ı etkin bağlamına okur. Artık ne yapması gerektiğini biliyor.
3. 3. Katman (Yürütme): Antigravity, gerektiğinde becerinin komut dosyalarına, örneklerine veya kaynaklarına erişir. Artık nasıl yapılacağını biliyor.

Yalnızca ilgili bilgiler doğru zamanda yüklenir. Cloud Run dağıtımı için bir beceri, örneğin bir BigQuery sorgusu üzerinde çalışırken bağlam tüketmez.

Üç beceri kategorisi

Birçok farklı türde temsilci becerisi vardır. Bu codelab'de, her biri farklı bir beceri kategorisini temsil eden üç beceri kullanacağız:

Kategori	Beceriler	Purpose
Alan Bilgisi (Domain Knowledge)	google/skills	Temsilcinin belirli teknolojiler hakkında bildikleri
Metodoloji	obra/superpowers	Nasıl geliştirilir? Spesifikasyon odaklı geliştirme, planlama ve test etme zorunlu kılınır.
Verimlilik	JuliusBrussee/caveman	Jetonları ne kadar verimli kullanacağınız

google/skills, Google ürünleri için Google tarafından sağlanan birinci taraf aracı becerilerini sunar. Örneğin, BigQuery API'leri, Cloud Run dağıtım kalıpları ve diğer hizmetler hakkında aracıya doğru ve güncel bilgiler verir. Alan becerileri olmadan, aracı eski veya eksik olabilecek eğitim verilerine dayanır. Alan becerileri, tahmin etme yerine güncel belgeleri kullanır.

obra/superpowers, spesifikasyona dayalı geliştirme (SDD) iş akışının fikir odaklı bir uygulamasıdır. Bir SDD çerçevesi olmadan, bir özelliği açıkladığınızda doğrudan koda geçilir. Bu, küçük düzeltmeler için işe yarasa da daha büyük projelerde tutarsız ve bakımı zor sonuçlar üretir. SDD, yapılandırılmış bir döngü oluşturur: gereksinimleri netleştirme → spesifikasyon yazma → plan oluşturma → spesifikasyona göre uygulama. Her aşamada incelenebilir bir yapı üretilir. Temsilci, spesifikasyonu onaylayana kadar kodlamaya başlamaz. spec-kit, agent-skills gibi başka SDD çerçeveleri de vardır. Bunların her biri, belirtme-planlama-uygulama döngüsüyle ilgili farklı görüşlere sahiptir. Bu codelab'de somut bir örnek olarak süper güçler kullanılmaktadır. Ancak, hangi çerçeveyi seçerseniz seçin temel disiplin (kodlamadan önce belirtin ve planlayın) geçerlidir.

JuliusBrussee/caveman, aracı çıkışını %75'e kadar sıkıştırır. Tüm teknik içeriği korurken dolgu kelimelerini, nezaket ifadelerini ve ayrıntılı açıklamaları kaldırır. Yanıt başına daha az jeton, oturum başına daha üretken etkileşimler ve daha hızlı yanıtlar anlamına gelir. /caveman ile veya temsilciye verimli bir şekilde konuşmasını söyleyerek etkinleştirin. Güvenlik uyarıları ve geri alınamaz işlemler için otomatik olarak devre dışı bırakılır.

Temsilci becerilerini yükleme

Resmi Google Skills'i yükleme

Öncelikle, etkileşimde bulunacağımız gerekli Google becerilerini yükleyelim. Bu eğitimde ele alacağımız temel teknoloji yığını BigQuery ve Cloud Run'dır. Bu becerileri yükleyelim. Bunu yüklemek için npx skills komutunu kullanacağız.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

npx skills add google/skills

Bu işlem, etkileşimli bir terminal kullanıcı arayüzü açar. Burada birçok beceri bulunur. Bu codelab için ihtiyacınız olan becerileri seçmek üzere ok tuşlarını ve boşluk çubuğunu kullanın.

bigquery-basics ve cloud-run-basics simgelerini bulup Boşluk'u tıklayarak seçin. Kutu, aşağıda gösterildiği gibi koyu gri renkte olmalıdır.

Ardından, aracıları seçerken Enter tuşuna basarak seçimi atlayabilirsiniz. Antigravity CLI varsayılan olarak zaten dahil edilmiştir.

Project yükleme kapsamını seçelim. Bu kapsam, çalışma dizinimizdeki .agents dizini altındaki becerileri yükler.

Son olarak, yüklemeyi tamamlamak için Evet yanıtını vererek Enter'ı tıklayın. Çok sayıda beceri yapılandırdıysanız find-skills becerisini yüklemek için isteğe bağlı olarak Evet'i de seçebilirsiniz.

Üçüncü taraf becerilerinin eklenti olarak yüklenmesi

Ardından obra/superpowers ve JuliusBrussee/caveman becerilerini yükleyeceğiz. Bu beceriler, Antigravity CLI eklentileri olarak yüklenecek şekilde desteklenir. Bu nedenle, bunları aşağıdaki komutları kullanarak yükleyebiliriz.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın

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

Ardından, aşağıdaki komutu kullanarak yüklemeyi doğrulayabiliriz.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın

agy plugin list

Bu çıktıları gösterir.

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

Bu işlemler, beceri kurulumumuzu tamamladı. Bir sonraki öğeye geçelim.

7. Özelleştirme - MCP Araçları

MCP (Model Bağlam Protokolü), yapay zeka ajanlarının harici araçları keşfetme ve bunlarla etkileşim kurma şeklini standartlaştıran açık bir protokoldür. Bu, bir istemci-sunucu modeli tanımlar: Ajan, bir MCP istemcisine ev sahipliği yapar ve araçlar MCP sunucuları tarafından kullanıma sunulur. MCP ile uyumlu tüm istemciler, MCP ile uyumlu tüm sunucuları kullanabilir. Aracının her araç için özel entegrasyon koduna ihtiyacı yoktur.

MCP, istemci-sunucu mimarisini kullanır:

• Ana makine: Yapay zeka modelinin bulunduğu uygulama (bu örnekte Antigravity CLI)
• İstemci: MCP iletişimini işleyen, ana makine içindeki bir bileşen (Antigravity CLI'ye yerleştirilmiştir)
• Sunucu: Yapay zekaya yetenekler sunan basit bir programdır ( Bu örnekte Google Cloud Managed BigQuery MCP Sunucusu'nu kullanacağız).

Antigravity CLI, bu codelab'de SDD iş akışını daha sonra çalıştırdığında BigQuery veri kümesi şeması (tablo adları, sütun türleri, ilişkiler) hakkında doğru bilgiye ihtiyaç duyar. BigQuery MCP, Antigravity CLI'nin canlı şemayı doğrudan incelemesine olanak tanır. Bu sayede, uydurulmuş değil gerçek tabloları ve sütunları referans alan spesifikasyonlar ve kodlar oluşturulur.

BigQuery Managed MCP Configuration

Google, Google Cloud altyapısında yönetilen bir BigQuery MCP sunucusu barındırır. Yerel kurulum gerekmez ( bu dokümanda desteklenen diğer Google Cloud ürünlerini inceleyebilirsiniz). Proje dizininizde MCP yapılandırma dosyasını oluşturarak Antigravity CLI'ı bağlanacak şekilde yapılandırın:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

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

Bu yapılandırma, AGY'ye şunları bildirir:

• BigQuery MCP sunucusunu bulma (serverUrl)
• Kimlik doğrulama için Google kimlik bilgilerini kullanma (authProviderType)

Yapılandırma, çalışma alanı düzeyinde bulunur (.agents/mcp_config.json).

Yapılandırmayı Antigravity CLI'dan doğrulayabiliriz. Önce çalıştıralım.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

agy

Ardından, /mcp eğik çizgi komutunu çalıştırarak yapılandırmayı doğrulayın.

🤖 Aşağıdaki komutu kopyalayıp Antigravity CLI'da çalıştırın.

/mcp

Şuna benzer bir şey gösterilir:

Ardından, eğik çizgi komutu etkileşiminden çıkmak için Esc tuşuna basın.

Not: Cloud Shell'de, yönetilen BigQuery MCP sunucusu, Cloud Shell'inizin Uygulama Varsayılan Kimlik Bilgilerini (ADC) otomatik olarak kullanır. Ek bir OAuth kurulumu gerekmez. Yerel makinenizi kullanıyorsanız gcloud CLI komutunuzun kimliğini doğrulamanız ve bu komutu çalıştırmanız gerekir.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın

gcloud auth application-default login

Important! BigQuery MCP sunucusu varsayılan olarak salt okunur DEĞİLDİR. Yıkıcı ifadeler (DROP, DELETE, TRUNCATE) dahil olmak üzere aracının oluşturduğu tüm SQL'leri yürütebilir. Bu codelab'de, sahibi olmadığınız bir herkese açık veri kümesini sorguladığınız için izinler nedeniyle yıkıcı işlemler başarısız olur. Üretimde kullanmak için salt okuma erişimini zorunlu kılmak üzere IAM ile MCP aracı kullanımını kontrol etme başlıklı makaleyi inceleyin.

Şimdilik Antigravity CLI'dan çıkın (Ctrl+D tuşuna iki kez basın).

8. Spesifikasyon Odaklı Geliştirme ile Özellik Geliştirme

Yüklü beceriler/eklentiler ve bağlı BigQuery MCP ile artık BigQuery entegrasyon özelliğini resmî olarak belirtmek için spesifikasyona dayalı geliştirme iş akışını kullanabilirsiniz. Bu adımda "kodlamadan önce belirtin" ifadesi somut hale gelir.

Antigravity CLI'yı girdiğinizden emin olun. Bu demoda, bu işaretle tüm araçların yürütülmesine izin vereceğiz.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

agy --dangerously-skip-permissions

Önemli! Bu işaret, tüm işlemlere izin vereceği için tehlikelidir. Üretim ayarlarıyla ilgili daha fazla bilgiyi bu belgelerde bulabilirsiniz. Bu bilgi yalnızca laboratuvar ilerlemesini hızlandırmak için eğitim amaçlı olarak kullanılır.

Mağara adamı modunu etkinleştirme

SDD döngüsünü başlatmadan önce, çok adımlı iş akışı boyunca jeton kullanımını verimli tutmak için mağara adamı modunu etkinleştirin:

🤖 Aşağıdaki komutu kopyalayıp Antigravity'de çalıştırın.

/caveman:caveman

Antigravity CLI'nın yanıtları, tüm teknik içeriği korurken gereksiz kelimeleri ve nezaket ifadelerini çıkararak kısa ve öz hale geliyor. Değişim başına daha az jeton, aynı kota içinde daha verimli sohbetler anlamına gelir.

SDD spesifikasyonunu başlatma

Antigravity CLI'ye özellik isteğini içeren istemi girin:

🤖 Antigravity'de aşağıdaki komutu kopyalayıp çalıştırın.

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

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

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

Süper güçler becerisi, özellik düzeyinde bir istek algıladığında otomatik olarak etkinleştirilir. AGY, doğrudan koda geçmek yerine SDD döngüsüne girer.

Önemli! Yapay zeka aracısı oluşturmanın dinamik olduğunu ve birbirinden farklı sonuçlar üretebileceğini belirtir.

Antigravity CLI, mevcut projeyi anlamak ve gerekli bağlamı toplamak için süreci başlatır. Aşağıda gösterildiği gibi ListDir ve Read gibi komutların yürütüldüğünü görürsünüz.

Ayrıca, veri kümesinin şemasını bulmak için daha önce ayarladığımız BigQuery MCP bağlantısını da kullanır.

Bu, geliştirmeye başlamadan önce Antigravity CLI'nin doğru bağlama sahip olmasını sağlar.

Şartlarla ilgili açıklama

Antigravity CLI, özellik kapsamı hakkında odaklanmış sorular sorabilir. Sık sorulan sorular:

• Proje kimliği nasıl yapılandırılmalıdır?
• Gelir trendi grafiği nasıl toplanmalı ve gösterilmelidir?
• Entegrasyona nasıl yaklaşılmalıdır? Doğrudan SQL ve yerel Pandas

Bu soruları, temsilcinin önerisi doğrultusunda yanıtlayabilirsiniz.

Önemli! Sürecin ortasında Antigravity'nin bazı git işlemleri ve yapılandırmaları yapacağını unutmayın. Bunun nedeni --dangerously-skip-permissions işaretini kullanmamızdır. Bu yalnızca eğitim amaçlıdır. Gerçek iş akışında bunu kendimiz halletmemiz gerekir.

Spesifikasyonu inceleme

Netleştirmeden sonra resmi bir spesifikasyon belgesi oluşturur. Talimatları doğru şekilde uyguluyorsa aşağıdaki gibi obra/superpowers beceri kuralını izleyerek docs/superpowers/specs dizininde spesifikasyon belgesi oluşturur.

Spesifikasyon belgesi aşağıdaki gibi görünür:

# BigQuery Integration Design Specification

## Overview

This document specifies ...

## Architecture

The application currently reads ...

## Data Schema & Sources

All tables reside in the BigQuery ...

...

Önemli! Yapay zeka aracısı oluşturmanın dinamik olduğunu ve birbirinden farklı sonuçlar üretebileceğini belirtir.

Bunu inceledikten sonra, planlama aşamasına geçebilmesi için özellikleri onaylamamız gerekiyor.

🤖 Antigravity'de aşağıdaki komutu kopyalayıp çalıştırın.

proceed with the specs

Planlama Aşaması ve Alt Aracıların Yürütülmesi

Spesifikasyonu onayladıktan sonra Antigravity CLI, bunu docs/superpowers/plans dizinine yazılacak bir uygulama planına ayırır.

Plan belgelerinde aşağıdaki örnekte olduğu gibi çeşitli bilgiler listelenir:

• Değiştirilecek dosyalar
• Oluşturulacak/güncellenecek dosyalar
• Bağımlılık değişiklikleri
• Görev dökümü

Ayrıca, her şeyi sırayla yapan tek bir aracı yerine, Antigravity CLI'nin görevleri uzmanlaşmış alt aracılara devretmesini sağlayan ve Antigravity CLI tarafından desteklenen subagent driven development kullanımını da önerir. Uygulama sırasında aşağıdaki gibi alt aracılar görebilirsiniz:

• Görev uygulayıcı: Plandaki belirli bir görev için kod yazar.
• Görev İnceleyici: Uygulanan kodu spesifikasyona göre inceler.
• Son Kod İnceleyici: Tamamlanmadan önce tüm değişiklikleri kapsayan bir inceleme yapar.

Not: Burada alt aracı kullanmanız önemle tavsiye edilir. Çünkü alt aracılar, belirli görevleri izole edip kendi bağlam pencerelerine yükleyerek ana iş parçacığının yürütme çıktısıyla karışmasını önleyebilir ve paralel yürütmeye olanak tanır.

Bu şekilde bir istem alırsanız şu yanıtı verin:

🤖 Antigravity'de aşağıdaki komutu kopyalayıp çalıştırın.

Use subagent driven development

Alt aracılar, görevleri tek tek seçme konusunda yetkilendirilir.

İpucu: Alt aracı çalışırken ana ileti dizisiyle sohbet etmeye devam edebilirsiniz. Aşağıdaki komutla etkin alt aracı bağlamlarını ve ayrıntılarını inceleyebilirsiniz.

🤖 Aşağıdaki komutu kopyalayıp Antigravity'de çalıştırın

/agents

İpucu: Kota sorunlarıyla karşılaştıysanız /usage komutuyla model kullanımını kontrol edebilir ve /model komutuyla kotası olan bir modele geçebilirsiniz . Ardından, işleme devam etmek için continues yazın.

E-posta adresini değiştirmek mi istiyorsunuz? /logout komutunu çalıştırabilirsiniz . Bu işlemin sizi farklı bir ileti dizisine yönlendireceğini unutmayın. Ardından, bu codelab özellik geliştirme hakkındaki son görüşmeyi bulmak için /resume komutunu çalıştırın.

Bir süre sonra geliştirme tamamlanır ( muhtemelen Final Code Reviewer aracısı oluşturulduktan sonra). Ardından sonucu inceleyebiliriz.

Önemli! Değişiklikleri uzak depoya göndermeniz istenirse lütfen bu isteği reddedin.

Güncellenen uygulama manuel incelemesi

Tüm görevler tamamlandıktan sonra güncellenen uygulamayı kontrol edebiliriz. Ctrl+D tuşuna iki kez basarak Antigravity CLI'dan çıkın, ardından aşağıdaki komutu çalıştırın.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın

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

Geliştirme başarılı olursa Total Orders simgesinin 120.000'den fazla sipariş gösterdiğini ve BigQuery ile entegre olduğunu görürsünüz.

Tebrikler! Artık Antigravity CLI'nın tam desteğiyle BigQuery'yi web uygulamanıza başarıyla entegre edebilirsiniz.

9. (İsteğe bağlı) Antigravity CLI ile Cloud Run'a dağıtma

❗ Önemli: Bu bölüm için etkin bir faturalandırma hesabına sahip bir Cloud projeniz olması gerekir.

Kontrol paneli, Cloud Shell Web Önizleme aracılığıyla yerel olarak çalışır. Bu isteğe bağlı adım, Antigravity CLI'nın alan becerilerinin geliştirmeden operasyonlara nasıl uzandığını göstererek uygulamayı herkese açık bir web hizmeti olarak Cloud Run'a dağıtır.

cloud-run-basics becerisi (daha önce yüklediğiniz google/skills eklentisinden) Antigravity CLI'ya Cloud Run dağıtım kalıpları, Dockerfile gereksinimleri, bağlantı noktası bağlama ve gcloud run deploy işaretleri hakkında bilgi verir. Kaynağa dayalı dağıtım (gcloud run deploy --source .) tek bir komutla derleme ve dağıtım yapar. Cloud Build, kapsüllemeyi otomatik olarak gerçekleştirir.

Cloud Run API'lerini etkinleştirme

Dağıtım için gerekli API'leri etkinleştirin:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın

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

Ardından Antigravity CLI'yı girin.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

agy --dangerously-skip-permissions

Önemli! Bu işaret, tüm işlemlere izin vereceği için tehlikelidir. Üretim ayarlarıyla ilgili daha fazla bilgiyi bu belgelerde bulabilirsiniz. Bu bilgi yalnızca laboratuvar ilerlemesini hızlandırmak için eğitim amaçlı olarak kullanılır.

Antigravity CLI'yı dağıtmaya yönlendirme

Uygulamalarımızı dağıtması için talimat verelim

🤖 Antigravity'de aşağıdaki komutu kopyalayıp çalıştırın.

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

Mevcut proje web uygulamasını dağıtmak için gerekenleri anlamak üzere cloud-run-basics becerisini okur.

İşlem tamamlandıktan sonra dağıtımın başarılı olduğunu doğrular ve daha önce yürütülen dağıtım sürecinin bir özetini (aşağıdaki örnekte gösterildiği gibi) verir. Uygulamanıza, sağlanan URL ile erişebilirsiniz.

Artık Antigravity CLI yardımıyla canlı uygulamanız tamamen dağıtıldı ve erişilebilir durumda.

10. Özet

E-ticaret kontrol panelini, uygulama kodu yazmadan statik CSV dosyalarından canlı BigQuery verilerine yükselttiniz. Antigravity CLI, yeniden kullanılabilir beceriler ve MCP aracılığıyla verilerinize canlı bağlantı sağlayan, disiplinli bir spesifikasyona dayalı geliştirme iş akışı üzerinden uygulamayı gerçekleştirdi.

Öğrendikleriniz

• Cloud Shell'de Antigravity CLI'ı kullanarak yapay zeka destekli geliştirme
• Aracı becerileri ve bağlam penceresinin verimli kalmasını sağlayan aşamalı açıklama
• Üç beceri kategorisi: metodoloji (süper güçler), verimlilik (mağara adamı), alan bilgisi (Google/beceriler)
• MCP nedir ve canlı veri erişimi için BigQuery MCP nasıl yapılandırılır?
• Sezgisel kodlama yerine spesifikasyona dayalı geliştirme döngüsü (belirtme → planlama → uygulama) yürütme
• Antigravity CLI, geliştirmeyi daha odaklı ve verimli hale getirmek için nasıl alt ajan oluşturabilir?

Temizleme

Bu codelab'de oluşturulan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız kaynakları tek tek veya projenin tamamını silebilirsiniz.

1. seçenek: Projeyi silme (önerilir)

Temizliğin en kolay yolu projeyi silmektir. Bu işlem, projeyle ilişkili tüm kaynakları kaldırır.

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Önemli: Bu silme işlemini sınırlı bir süre için geri alabilirsiniz. Bunun için şu komutu kullanın: gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}

2. seçenek: Kaynakları tek tek silme

Projeyi korumak ancak yalnızca bu codelab'de oluşturulan kaynakları kaldırmak istiyorsanız:

💻 Bunu kopyalayıp terminal kabuğunda çalıştırın.

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