Pengembangan Agen ADK yang Didorong Spesifikasi dengan Antigravity dan Spec-kit

1. Pengantar

Menambahkan fitur ke agen yang ada — kemampuan baru yang didukung database — biasanya berarti menulis boilerplate, menghubungkan integrasi, dan menjaga semuanya tetap konsisten dengan pola yang sudah ada dalam codebase. Antigravity mempercepat setiap tahap proses ini: Antigravity menganalisis codebase Anda untuk membangun konteks yang diperlukan, menghasilkan spesifikasi terstruktur dan rencana penerapan untuk ditinjau, serta mengeksekusi perubahan kode — semuanya dipandu oleh pengetahuan domain yang membantu Anda menangkapnya sebagai keterampilan yang dapat digunakan kembali dan konstitusi project yang menerapkan prinsip-prinsip yang tidak dapat dinegosiasikan. Codelab ini memperkenalkan cara untuk meningkatkan paradigma Pengembangan yang Didorong Spesifikasi Antigravitasi dengan memperkenalkan siklus baru untuk meningkatkan dokumentasi spesifikasi yang sangat mereferensikan spec-kit

Yang akan Anda build

Aplikasi concierge restoran yang berjalan secara lokal dengan penambahan pemesanan melalui siklus SDD lengkap:

• Pemesanan reservasi — tamu memesan meja dan memeriksa reservasi, yang didukung oleh alat database MCP Toolbox baru dan tabel reservations Cloud SQL
• (Tantangan) – mengembangkan UI Anda sendiri untuk agen
• (Tantangan) – men-deploy ke Google Cloud dengan bantuan agen Antigravity

Kode awal menyediakan agen ADK yang berfungsi dengan penelusuran menu (kata kunci + semantik melalui MCP Toolbox) dan pelacakan preferensi diet (melalui ToolContext). Anda dapat memperluasnya tanpa menulis kode aplikasi secara manual — Antigravity menangani penerapan berdasarkan spesifikasi Anda.

Yang akan Anda pelajari

• Cara mem-bootstrap konteks project sehingga Antigravity memahami codebase yang ada
• Cara membuat keterampilan Antigravitasi yang mengemas pengetahuan domain (misalnya, Pola codelab ADK) untuk digunakan kembali
• Cara menetapkan konstitusi project yang divalidasi alur kerja SDD selama perencanaan dan analisis
• Cara menggunakan alur kerja Pengembangan yang Didorong Spesifikasi (SDD) di Antigravity untuk menambahkan fitur secara sistematis
• Cara memperluas agen ADK dengan alat baru yang didukung database melalui MCP Toolbox

Prasyarat

• Google Antigravity dan git diinstal di komputer lokal Anda
• Akun Google Cloud dengan akun penagihan uji coba diaktifkan
• Penyelesaian empat codelab ADK prasyarat sebelumnya (atau pengetahuan yang setara) akan membantu memahami konteks kasus penggunaan:
• Membangun Agen AI dengan ADK: Dasar-Dasar
• Membangun Agen AI dengan ADK: Melengkapi dengan Alat
• Membangun Agen AI Persisten dengan ADK dan CloudSQL
• Men-deploy, Mengelola, dan Memantau Agen ADK di Cloud Run
• Database sebagai Alat: RAG Agentic dengan ADK, MCP Toolbox, dan Cloud SQL

2. Menyiapkan Lingkungan Anda

CATATAN PENTING:

Tutorial ini memerlukan Project Google Cloud dengan akun penagihan yang aktif. Jika Anda belum memilikinya, ikuti langkah-langkah di bawah untuk mendapatkan akun penagihan uji coba yang dapat digunakan untuk tutorial ini:

1. Buka jendela samaran
2. Jika Anda bergabung dalam sesi workshop, URL portal penukaran biasanya akan diberikan dalam sesi tersebut, atau Anda dapat membuka portal penukaran akun penagihan uji coba ini
3. Login menggunakan akun Gmail pribadi Anda ( email Google Workspace / lainnya tidak akan berfungsi) )
4. Ikuti petunjuk penukaran langkah demi langkah

Langkah ini akan meng-clone repositori starter, melakukan autentikasi dengan Google Cloud, menyediakan database Cloud SQL, dan menyiapkan lingkungan Antigravity lokal Anda.

Catatan: Codelab ini berjalan sepenuhnya di Google Antigravity di komputer lokal Anda. Penyiapan mencakup autentikasi manual menggunakan perintah CLI gcloud

Meng-clone repositori awal

Buka terminal di Antigravity (atau terminal sistem Anda). Buat clone repo pendamping dan buka direktori:

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

Buka repositori yang di-clone di Antigravity. File->Open Folder->pilih direktori yang di-clone sdd-adk-agents-agy

Hapus remote upstream. Alur kerja SDD membuat cabang git untuk spesifikasi fitur — menghapus remote mencegah pengiriman yang tidak disengaja ke repositori starter:

git remote remove origin

Penting: Alur kerja SDD dalam codelab ini menggunakan cabang git untuk mengatur spesifikasi fitur. Menghapus remote origin memastikan cabang dan commit lokal Anda tetap lokal. Jika Anda ingin mencadangkan pekerjaan Anda, tambahkan remote Anda sendiri: git remote add origin <your-repo-url>

Instal prasyarat

Jalankan skrip prasyarat. Skrip ini memeriksa (dan menginstal jika tidak ada) git, curl, gcloud, uv, Python 3.12, dan MCP Toolbox:

bash scripts/setup_prerequisites.sh

Catatan: Mendownload semua prasyarat akan memerlukan waktu beberapa saat. Buka tab baru untuk melanjutkan ke bagian berikutnya sambil menunggu download selesai

Melakukan autentikasi dengan Google Cloud

Jalankan dua perintah autentikasi. Keduanya membuka browser untuk OAuth:

gcloud auth login
gcloud auth application-default login

Catatan: Pada perintah OAuth kedua, saat diminta untuk memilih izin. Periksa semua opsi

Catatan: Pastikan Anda melakukan autentikasi dengan email yang Anda gunakan untuk mengklaim akun penagihan uji coba

Karena Anda bekerja secara lokal dengan Antigravity, Anda melakukan autentikasi secara manual. auth login mengautentikasi CLI gcloud. application-default login mengautentikasi SDK Google Cloud yang digunakan aplikasi Anda — panggilan Vertex AI ADK dan konektor Python Cloud SQL sama-sama mengandalkan Kredensial Default Aplikasi.

Menyiapkan project Google Cloud

Tulis variabel lokasi ke .env sebelum menjalankan skrip penyiapan project:

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

• GOOGLE_CLOUD_LOCATION=global digunakan untuk panggilan Vertex AI / Gemini API.
• REGION=us-central1 digunakan untuk Cloud SQL dan infrastruktur GCP lainnya

Download dan jalankan skrip penyiapan project. Skrip ini membuat atau memvalidasi project Google Cloud dengan penagihan uji coba dan menyimpan project ID ke .env, lalu memanggilnya:

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

Aktifkan API yang diperlukan:

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

Catatan: Pengaktifan API mungkin memerlukan waktu beberapa saat. Anda hanya perlu melakukannya sekali per project.

Menyediakan Cloud SQL

Tetapkan sandi database dan tambahkan ke .env:

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

Penting: Sandi yang di-hardcode di atas hanya untuk tujuan tutorial. Di lingkungan produksi, simpan kredensial dengan aman menggunakan layanan seperti Secret Manager dan referensikan saat runtime — jangan pernah melakukan commit secret teks biasa ke kontrol sumber.

Buat instance Cloud SQL:

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 &

Paket db-custom-1-3840 adalah minimum yang diperlukan untuk integrasi ML Vertex AI. Flag --enable-google-ml-integration memungkinkan Cloud SQL memanggil model penyematan Gemini langsung dari SQL — hal ini mendukung fitur penelusuran semantik.

Catatan: Perintah ini memerlukan waktu sekitar 5 menit dan akan berjalan di latar belakang. Biarkan berjalan di tab terminal ini dan buka tab terminal baru untuk langkah berikutnya.

Menginstal dependensi

Buka tab terminal baru. Pastikan Anda masih berada di direktori project repo yang di-clone dan muat ulang variabel lingkungan:

source .env

Kita akan menggunakan uv sebagai pengelola project Python. uv adalah pengelola project dan paket Python yang cepat dan ditulis dalam Rust ( dokumen ). Codelab ini menggunakannya untuk kecepatan dan kesederhanaan. Instal dependensi Python:

uv sync

Kemudian, perbarui file .env agen ADK dengan konfigurasi project Anda:

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

Sekarang, kita akan memiliki semua repo agen ADK starter yang diperlukan untuk dikerjakan. Sekarang, mari kita bahas lebih lanjut Antigravity dan Pengembangan berbasis spesifikasi di bagian berikutnya sambil menunggu semuanya siap

3. Mempelajari Kode Awal dan Memahami Pengembangan yang Didorong Spesifikasi

Langkah ini membahas struktur kode awal, memperkenalkan metodologi Pengembangan yang Didorong Spesifikasi, mengisi database, dan memverifikasi bahwa agen dasar berfungsi sebelum Anda mulai memperluasnya.

Struktur project

Buka project repo yang di-clone di editor Antigravity dan tinjau tata letak direktori:

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

File kunci

File Aplikasi Agen

• restaurant_concierge/agent.py — Agen inti. LlmAgent yang menggabungkan alat database MCP Toolbox dengan pelacakan preferensi diet berbasis ToolContext. Agen memuat semua alat dari server Toolbox dan menambahkan dua fungsi Python (save_dietary_preference, get_dietary_preferences) yang menggunakan ToolContext untuk mengelola status.
• tools.yaml — Definisi alat MCP Toolbox. Tiga alat penelusuran menu ditentukan: penelusuran kata kunci (search_menu), penelusuran semantik melalui pgvector (semantic_search_menu), dan filter kategori (get_menu_by_category). Belum ada alat reservasi — Anda akan menambahkannya nanti
• server.py — Server FastAPI minimal, yang menunjukkan cara mengakses ADK sebagai objek FastAPI. get_fast_api_app() dari ADK menyediakan endpoint bawaan termasuk /run_sse untuk API streaming SSE dan pengelolaan sesi.

File Antigravity

• .agents/skills/adk-agent-development/SKILL.md — Kemampuan yang telah dikonfigurasi sebelumnya ( dibuat oleh Antigravity) yang berisi pola referensi ringkas dari keempat codelab ADK. Saat ini tidak aktif (tidak ada frontmatter YAML) – Anda harus memperbaruinya nanti. Antigravity memuat skill ini secara otomatis saat mendeteksi pekerjaan yang terkait dengan fitur agen ADK dan contohnya — ini adalah pengetahuan yang memandu Antigravity saat merencanakan fitur reservasi nanti
• .agents/skills/repo-research/SKILL.md — Keterampilan yang mengajarkan Antigravity cara menganalisis repositori secara inkremental dan menghasilkan dokumen konteks project terstruktur. Cara ini menggunakan pendekatan 4 fase: pemindaian permukaan (hanya struktur direktori), file metadata dan konfigurasi, titik entri dan model data, lalu analisis mendalam yang ditargetkan — setiap fase berhenti dan menulis temuan sebelum melanjutkan ke fase berikutnya. Seperti keterampilan ADK, keterampilan ini tidak aktif hingga Anda menambahkan frontmatter YAML nanti. Setelah diaktifkan, panggil untuk membuat .agents/rules/project-context.md — dokumen orientasi komprehensif yang mencakup arsitektur, dependensi runtime, permukaan API, dan glosarium domain.

Pengembangan yang Didorong Spesifikasi: dari perencanaan bawaan Antigravity hingga SDD terstruktur

Asisten coding AI memudahkan pembuatan kode dari perintah. Risikonya: Anda mendeskripsikan sebuah fitur dalam satu kalimat, asisten menulis ratusan baris, dan Anda menerimanya karena terlihat benar. Hal ini terkadang disebut "vibe coding" — Anda mengarahkan berdasarkan perasaan, menerima atau menolak output berdasarkan apakah output tersebut tampaknya berfungsi. Bahasa ini cepat untuk prototipe dan skrip sekali pakai. Hal ini akan rusak saat codebase berkembang, saat fitur berinteraksi, atau saat Anda kembali melihat kode beberapa minggu kemudian dan tidak dapat merekonstruksi alasan keputusan dibuat.

Pengembangan yang Didorong Spesifikasi (SDD) menambahkan struktur ke loop ini. Sebelum kode dibuat, Anda menulis spesifikasi: apa yang dilakukan fitur, siapa yang dilayaninya, apa kriteria keberhasilannya. Asisten AI bekerja berdasarkan spesifikasi tersebut — dan begitu juga Anda saat meninjau outputnya. Spesifikasi menjadi satu sumber tepercaya untuk maksud. Jika kode berbeda dari spesifikasi, Anda akan mengetahuinya saat peninjauan. Jika persyaratan berubah, Anda harus memperbarui spesifikasi terlebih dahulu, lalu membuat ulang. Keputusan didokumentasikan, bukan diimprovisasi.

Trade-off-nya nyata: SDD lebih lambat per fitur daripada pengodean getaran. Anda menulis dokumen sebelum menulis kode. Namun, manfaatnya akan berlipat ganda. Setiap perubahan pada codebase di masa mendatang memiliki konteks, setiap penerapan yang dihasilkan AI memiliki kontrak yang dapat ditinjau, dan Anda dapat mengaktifkan kolaborator (manusia atau AI) dengan mengarahkan mereka ke spesifikasi, bukan menjelaskan keputusan dari ingatan.

Antigravity sudah mengikuti prinsip pengembangan berbasis spesifikasi. Saat Anda menyetel agen ke Mode perencanaan, agen akan menghasilkan dua artefak sebelum menulis kode apa pun:

• Rencana Penerapan — ringkasan pendekatan teknis yang diusulkan, perubahan file, dan keputusan arsitektur
• Daftar Tugas — perincian item kerja yang terstruktur

Antigravity meminta Anda untuk meninjau dan menyetujui artefak ini sebelum dieksekusi. Loop rencanakan-lalu-terapkan ini adalah inti dari pengembangan berbasis spesifikasi: spesifikasi memandu kode, bukan sebaliknya.

Codelab ini melanjutkan dasar tersebut dengan alur kerja yang berpendapat dan dikontrol versinya berdasarkan spec-kit — framework pengembangan berbasis spesifikasi dari GitHub. Setiap fitur melewati pipeline yang disengaja di mana setiap artefak adalah dokumen mandiri yang dapat Anda tinjau, edit, dan lacak di git. Pipeline mencakup dua fase gerbang kualitas opsional (klarifikasi dan analisis) yang menangkap masalah sebelum menjadi masalah penerapan:

Fase	Artefak	Tujuan
/speckit.specify	spec.md	Tentukan APA yang akan dibangun (berorientasi pengguna, tidak bergantung pada teknologi)
/speckit.clarify (opsional)	Diperbarui spec.md	Mengidentifikasi area yang kurang ditentukan, mengajukan pertanyaan klarifikasi yang terarah, mengenkode jawaban kembali ke dalam spesifikasi
/speckit.plan	plan.md, data-model.md, research.md	Merancang CARA membangunnya (pendekatan teknis, model data, riset)
/speckit.tasks	tasks.md	Pecah rencana menjadi langkah-langkah yang berurutan dan dapat ditindaklanjuti
/speckit.analyze (opsional)	Laporan analisis	Tinjau tugas untuk mengetahui risiko, kekurangan, atau kasus ekstrem yang terlewat sebelum penerapan
/speckit.implement	Perubahan kode	Lakukan tugas, centang setiap tugas yang telah diselesaikan

Setiap artefak dipertahankan sebagai file di specs/<feature-branch>/, dikontrol versinya di git, dan dapat digunakan kembali. Jika percakapan terganggu atau Anda ingin meninjau kembali keputusan nanti, dokumen spesifikasi selalu tersedia, tidak tersembunyi di histori percakapan.

Catatan: Artefak bawaan antigravitasi memiliki keunggulan di UI yang memungkinkan pengguna mengomentari artefak yang dihasilkan ( bahkan gambar!). ). Oleh karena itu, dalam tutorial ini, kita akan mengubah perintah spec-kit asli untuk diintegrasikan dengan artefak bawaan dalam fase implement

Repo starter mencakup alur kerja SDD ini di .agents/workflows/ dan template di .specify/templates/. Anda akan menggunakannya nanti untuk menambahkan fitur ke agen.

4. Menyelesaikan penyiapan Cloud SQL dan Memastikan Agen Dasar Berfungsi

Beralih kembali ke tab terminal tempat perintah pembuatan Cloud SQL sedang berjalan. Setelah selesai, verifikasi bahwa instance sudah siap:

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

Jika output menampilkan RUNNABLE, lanjutkan. Jika menampilkan PENDING_CREATE, tunggu sebentar, lalu jalankan kembali perintah.

Beri akun layanan Cloud SQL akses ke Vertex AI (diperlukan untuk fungsi penyematan dalam database):

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

Membuat Database:

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

Anda akan melihat output seperti ini

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

Checkpoint: File .env Anda berisi GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, REGION, dan DB_PASSWORD. Instance Cloud SQL restaurant-db sedang berjalan. toolbox tersedia di PATH Anda (diinstal oleh setup_prerequisites.sh). Dependensi Python diinstal.

Menambahkan data ke database

Muat variabel lingkungan Anda dan jalankan skrip pengisian database untuk membuat skema dan memasukkan 16 item menu:

source .env
uv run python scripts/seed_db.py

Output yang diharapkan:

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

Membuat embedding vektor untuk penelusuran semantik:

uv run python scripts/generate_embeddings.py

Output yang diharapkan:

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

Hal ini menggunakan fungsi embedding() bawaan Cloud SQL (melalui ekstensi google_ml_integration) untuk memanggil gemini-embedding-001 langsung dari SQL. Vektor 3072 dimensi disimpan di kolom embedding dari menu_items — tidak diperlukan kode penyematan sisi aplikasi.

Menguji agen dasar

Mulai MCP Toolbox sebagai proses latar belakang:

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

Toolbox menyajikan alat database melalui HTTP. Agen terhubung ke perangkat pada http://127.0.0.1:5000.

Mulai UI dev ADK:

uv run adk web .

Buka Dev UI di browser Anda. Kemudian, uji agen dengan perintah berikut:

What appetizers do you have?

Periksa: agen membuat kueri database dan menampilkan item menu

I'm vegetarian

Periksa: agen menyimpan preferensi diet pada status agen

Can I make a reservation for tomorrow?

Periksa: agen tidak dapat menangani ini (alat reservasi belum ada)

Hentikan UI dev ADK dengan Ctrl+C dua kali. Biarkan Toolbox berjalan di latar belakang — Anda akan menggunakannya lagi nanti

Checkpoint: Agen dasar berfungsi — penelusuran menu (kata kunci + semantik) dan fungsi preferensi diet berfungsi dengan benar. Permintaan reservasi gagal karena tidak ada alat reservasi. Anda memahami struktur proyek dan kesenjangan yang akan Anda isi.

5. Memulai Konteks Project dengan Antigravity

Sekarang, mari kita simulasikan dengan kondisi yang "agak lebih dekat" dengan pekerjaan sehari-hari kita:

• Repositori tidak dikelola dengan baik
• README tidak berlaku lagi
• Dokumentasi tidak sering diperbarui

Catatan: Anda sangat beruntung jika hal ini tidak mencerminkan kondisi Anda

Hal pertama yang biasanya kita lakukan dalam situasi semacam ini adalah membuat peta atau konteks tentang project yang ingin kita kerjakan dengan Antigravity. Langkah ini menunjukkan satu contoh pendekatan tentang cara memberikan pemahaman mendalam kepada Antigravity tentang codebase yang ada dengan membuat skill yang menganalisis repositori dan membuat dokumen konteks project.

Selain itu, project ini juga menyiapkan konstitusi project — prinsip-prinsip yang tidak dapat dinegosiasikan yang divalidasi oleh alur kerja SDD. Bersama-sama, hal ini memberi Antigravity konteks dan batasan yang diperlukan untuk siklus SDD selanjutnya

Hierarki konteks Antigravity

Antigravity menggunakan tiga tingkat konteks, yang masing-masing memiliki cakupan yang berbeda:

• Aturan (.agents/rules/): Petunjuk yang selalu aktif. Setiap percakapan di ruang kerja ini akan melihatnya ( jika Anda mengaktifkannya). Gunakan aturan untuk konteks seluruh project seperti keputusan arsitektur, standar coding, atau informasi stack teknologi.
• Keterampilan (.agents/skills/): Pengetahuan sesuai permintaan. Antigravity memuat skill hanya jika tugas saat ini cocok dengan kolom description skill. Gunakan keterampilan untuk materi referensi khusus domain.
• Alur kerja (.agents/workflows/): Perintah tersimpan yang dipicu dengan perintah /. Gunakan alur kerja untuk proses multi-langkah yang dapat diulang seperti pipeline SDD.

Catatan: Project saat ini memiliki alur kerja (pipeline SDD) dan skill (pengembangan agen ADK), tetapi tidak memiliki aturan. Aturan project-context.md memberi Antigravity pemahaman persisten tentang codebase — teknologi apa yang digunakan, bagaimana file diatur, apa yang telah dibangun sejauh ini.

Mengaktifkan skill

Repositori awal mencakup dua skill yang telah ditulis sebelumnya di .agents/skills/. File tersebut berisi petunjuk mendetail, tetapi dimulai dengan komentar TODO(codelab), bukan frontmatter YAML yang diperlukan. Tanpa frontmatter, Antigravity tidak dapat menemukannya.

Keterampilan antigravitasi memerlukan blok frontmatter YAML di bagian atas file dengan dua kolom:

• name — ID unik untuk skill
• description — ringkasan bahasa alami yang dicocokkan Antigravity saat memutuskan keterampilan mana yang akan dimuat untuk permintaan tertentu

Buka

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

di editor. Ganti dua baris komentar TODO(codelab) di bagian atas dengan frontmatter ini:

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

Catatan: Keterampilan pengembangan agen ADK berisi pola dan contoh ringkas dari lima codelab ADK — struktur agen, jenis alat, pengelolaan status, deployment

Buka

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

di editor. Ganti dua baris komentar TODO(codelab) di bagian atas dengan frontmatter ini:

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

Catatan: Baca SKILL.md secara mendetail.repo-research Ini adalah salah satu contoh perintah untuk menganalisis repositori Anda. Perhatikan bahwa aturan update inkremental sengaja dibuat konservatif. Jika konteks Antigravity habis di tengah riset atau percakapan terganggu, semua yang telah ditemukan sejauh ini sudah disimpan ke file. Memanggil ulang skill akan melanjutkan dari bagian terakhir tanpa kehilangan progres.

Peringatan! Menganalisis repositori besar dapat menghabiskan kuota Anda dengan cepat.

Pastikan kedua keterampilan memiliki frontmatter yang valid:

head -4 .agents/skills/adk-agent-development/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

Setiap kolom harus menampilkan pembatas --- yang membungkus kolom name: dan description:. Jika pemisah atau kolom tidak ada, Antigravity tidak akan mengenali skill.

Kedua keterampilan dimuat sesuai permintaan — Antigravity mencocokkan permintaan Anda dengan kolom description dan menarik petunjuk lengkap hanya jika relevan.

Buat konteks project

Pastikan direktori aturan ada:

mkdir -p .agents/rules

Di kotak Agent Manager/Chat Antigravity (dalam mode editor, tekan ctrl + L), mulai percakapan baru. Jenis:

Research this repository and create a project context document

Antigravity mencocokkan permintaan Anda dengan kemampuan repo-research dan mulai menganalisis codebase secara sistematis. Alat ini membaca file konfigurasi, kode sumber, dan dokumentasi, lalu mengisi template konteks project dengan temuannya.

Setelah selesai, buka .agents/rules/project-context.md di editor. Dokumen ini berisi informasi konkret tentang project: stack teknologi (Python 3.12, ADK, MCP Toolbox, Cloud SQL), struktur project, model data (tabel menu_items dengan pgvector), dan integrasi eksternal.

Tips: Dokumen konteks project berkembang seiring perkembangan project. Anda dapat menjalankan kembali skill untuk memperbarui konteks dengan tambahan baru. Aturan update inkremental memastikan konten yang ada tetap dipertahankan — teknologi, entitas, dan integrasi baru ditambahkan, bukan ditimpa.

Untuk pembaruan yang ditargetkan, gunakan perintah tertentu: "Teliti skema database dan perbarui konteks project" atau "Perbarui konteks project dengan definisi alat baru". Setiap pemanggilan akan ditambahkan ke dokumen yang ada.

Menetapkan konstitusi project

Alur kerja SDD mereferensikan konstitusi project di .specify/memory/constitution.md selama perencanaan dan analisis. Alur kerja /speckit.plan menjalankan "Pemeriksaan Konstitusi" terhadapnya, dan /speckit.analyze menandai pelanggaran sebagai KRITIS. Jika konstitusi dibiarkan sebagai template kosong dengan token placeholder, pemeriksaan ini tidak memiliki apa pun untuk divalidasi — rencana dan analisis berjalan tanpa batasan.

Konstitusi mendefinisikan prinsip-prinsip proyek yang tidak dapat dinegosiasikan. Ini adalah repo kecil yang dikelola oleh satu developer, jadi konstitusinya harus mencerminkan cakupan tersebut — buatlah hal-hal tetap sederhana, konsisten, dan hindari rekayasa berlebihan.

Di Pengelola Agen Antigravity, mulai percakapan baru. Jalankan alur kerja konstitusi:

/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 mengisi template konstitusi dengan prinsip-prinsip konkret, menetapkan versi (1.0.0), dan menjalankan pemeriksaan konsistensi di seluruh template SDD.

Tinjau konstitusi yang dihasilkan di .specify/memory/constitution.md. Pastikan ketiga prinsip tersebut ada dan dinyatakan dengan jelas.

Catatan: Konstitusi sengaja dibuat dengan 3 prinsip yang disesuaikan untuk developer solo. Alur kerja /speckit.constitution mendukung perubahan inkremental — jalankan lagi dengan prinsip tambahan dan alur kerja ini akan menangani pembuatan versi secara otomatis. Untuk project tim, Anda akan menambahkan prinsip untuk peninjauan kode, disiplin pengujian, kemampuan observasi, dan pembuatan versi API.

Checkpoint: .agents/rules/project-context.md ada dengan informasi konkret tentang repositori. .agents/skills/repo-research/SKILL.md menunjukkan pembuatan keterampilan dengan frontmatter YAML, petunjuk, dan penyelesaian konflik. .specify/memory/constitution.md berisi tiga prinsip project yang divalidasi oleh alur kerja perencanaan dan analisis. Anda memahami hierarki konteks tiga tingkat: aturan (selalu aktif), kemampuan (sesuai permintaan), alur kerja (perintah garis miring).

6. Siklus SDD — Fitur Tambahkan Reservasi

Langkah ini membahas siklus SDD lengkap untuk menambahkan pemesanan reservasi ke agen concierge restoran. Anda mendorong Antigravitasi melalui setiap fase — tentukan, perjelas, rencanakan, tugas, analisis, terapkan — dengan mengamati cara setiap artefak dibangun berdasarkan artefak sebelumnya. Ini adalah pengalaman pembelajaran inti dari codelab.

Penting! Antigravity adalah asisten AI — artefak yang dihasilkannya (spesifikasi, rencana, tugas, kode) mungkin berbeda dengan yang dijelaskan dalam tutorial ini. Nama file, skema SQL yang tepat, dan struktur kode dapat bervariasi. Hal ini wajar dan merupakan bagian dari pengembangan yang dibantu AI. Alur kerja SDD memastikan Anda meninjau setiap artefak sebelum menjadi kode, jadi gunakan penilaian Anda untuk menerima, mengubah, atau membuat ulang output yang tidak sesuai dengan harapan Anda.

Tentukan fitur

Di Pengelola Agen Antigravity, mulai percakapan baru. Ketik perintah alur kerja /speckit.specify dengan deskripsi fitur:

/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 membuat cabang fitur, menghasilkan dokumen spesifikasi, dan menjalankan validasi kualitas. Jika Antigravity mengajukan pertanyaan klarifikasi, jawab pertanyaan tersebut berdasarkan deskripsi fitur di atas.

Catatan: Setelah menyelesaikan spesifikasi, Antigravity dapat menampilkan penyerahan seperti "Buat Rencana Teknis" atau "Perjelas Persyaratan Spesifikasi". Ini adalah isyarat untuk fase alur kerja berikutnya (/speckit.plan atau /speckit.clarify)

Spesifikasi berfokus pada APA dan MENGAPA — bukan BAGAIMANA. Deskripsi ini menjelaskan pengalaman pengguna ("Tamu dapat memesan reservasi dengan memberikan nama, jumlah rombongan, tanggal, dan waktu") tanpa menyebutkan tabel SQL, tools.yaml, atau ADK API. Detail penerapan muncul dalam fase perencanaan.

Tinjau spesifikasi yang dihasilkan di specs/<branch-name>/spec.md. Pastikan dokumen tersebut mencakup persyaratan fungsional dan kriteria keberhasilan.

Perjelas spesifikasi (opsional)

Jalankan alur kerja klarifikasi untuk mengidentifikasi dan menyelesaikan area yang kurang ditentukan dalam spesifikasi:

/speckit.clarify

Antigravity memindai spesifikasi untuk mencari ambiguitas, kriteria penerimaan yang tidak ada, dan persyaratan yang kurang ditentukan. Fitur ini mengajukan pertanyaan klarifikasi yang ditargetkan — setiap pertanyaan dapat dijawab dengan pilihan atau frasa singkat. Jawaban Anda dienkode langsung kembali ke spesifikasi, sehingga lebih presisi sebelum perencanaan dimulai.

Tips: Langkah klarifikasi bersifat opsional, tetapi direkomendasikan untuk fitur yang kompleks. Untuk spesifikasi yang mudah, langsung saja ke perencanaan.

Merencanakan penerapan

Jalankan alur kerja perencanaan:

/speckit.plan

Antigravity menghasilkan rencana teknis melalui dua fase:

1. Fase riset — menyelesaikan hal-hal yang tidak diketahui tentang codebase yang ada, menghasilkan research.md
2. Fase desain — membuat data-model.md (definisi entity reservasi) dan memperbarui project-context.md

Antigravitasi harus menggunakan keterampilan adk-agent-development selama perencanaan. Tinjau artefak utama:

• specs/<branch-name>/plan.md — pendekatan teknis: file mana yang akan diubah, pola apa yang harus diikuti
• specs/<branch-name>/data-model.md — definisi entity reservasi (kolom, jenis, hubungan)
• specs/<branch-name>/research.md — keputusan yang dibuat dan alasan

Membuat tugas

Menjalankan alur kerja tugas

/speckit.tasks

Antigravity memecah rencana menjadi daftar tugas yang berurutan di specs/<branch-name>/tasks.md. Tugas mengikuti format checklist yang ketat dengan ID, penanda prioritas, dan jalur file, misalnya:

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

Tugas diatur ke dalam beberapa fase: Penyiapan → Dasar → Cerita Pengguna → Penyempurnaan. Pindai daftar tugas untuk memahami apa yang akan dibuat dan diubah.

Menganalisis tugas (opsional)

Jalankan alur kerja analisis untuk meninjau risiko dan kesenjangan tugas:

/speckit.analyze

Antigravity memeriksa daftar tugas berdasarkan spesifikasi dan rencana, mencari kasus ekstrem yang hilang, tugas yang mungkin bertentangan, atau kesenjangan antara persyaratan spesifikasi dan pekerjaan yang direncanakan. Atasi masalah kritis sebelum menerapkan.

Tips: Langkah analisis paling berguna saat daftar tugas panjang atau fitur menyentuh beberapa subsistem. Untuk fitur yang berfokus seperti pemesanan reservasi, pemindaian cepat sudah cukup.

7. Menerapkan

Jalankan alur kerja penerapan:

/speckit.implement

Antigravity menyajikan rencana penerapan akhir dan artefak tugas. Tinjau dan setujui untuk melanjutkan

Tips: Anda dapat mengomentarinya secara langsung. Hal ini hanya dapat dilakukan dengan Artifact bawaan Antigravity

Antigravity akan menjalankan tugas, dan mencentang setiap tugas yang telah diselesaikan. Setelah selesai, panduan akan menampilkan Panduan lengkap

Menguji perubahan kode

Setelah penerapan selesai, verifikasi bahwa perubahan kunci telah dilakukan. Nama dan konten file yang tepat dapat bervariasi, tetapi pola ini harus ada seperti pada tools.yaml dan agent.py:

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

Anda akan melihat output seperti ini

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

Dan untuk agent.py

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

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

Mungkin Anda akan menemukan perubahan seperti ini

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

Catatan: Jika grep tidak menampilkan kecocokan untuk kedua file, implementasi mungkin menggunakan penamaan yang berbeda. Periksa git diff untuk melihat rangkaian lengkap perubahan dan memverifikasi bahwa logika terkait reservasi telah ditambahkan.

Perubahan ini akan memengaruhi skrip database awal, jadi mari kita coba jalankan

source .env
uv run python scripts/seed_db.py

Skrip yang diperbarui akan membuat tabel reservations jika belum ada. Anda akan melihat output yang mengonfirmasi bahwa tabel baru telah dibuat (data menu_items yang ada tetap dipertahankan).

Catatan: Antigravity mungkin telah membuat skrip migrasi terpisah (misalnya, scripts/create_reservations.py), bukan memperbarui seed_db.py. Periksa git diff --name-only untuk mengetahui apakah ada skrip baru di scripts/ dan jalankan skrip tersebut.

Jika semuanya berjalan lancar hingga saat ini, kita dapat menguji fitur di UI Dev agen ADK. Mulai ulang Toolbox untuk mengambil definisi alat baru di tools.yaml. Hentikan proses Toolbox yang ada, lalu mulai proses baru:

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

Mulai UI dev ADK:

uv run adk web .

Buka http://localhost:8000 di browser Anda dan uji dengan perintah berikut:

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

Periksa: agen harus mengonfirmasi detail pemesanan dan membuatnya

Do I have any upcoming reservations?

Periksa: agen akan mencantumkan reservasi yang baru saja Anda buat

Sekarang, hentikan UI dev ADK dengan Ctrl+C dua kali.

Checkpoint: Agen menangani pemesanan dan pencarian reservasi. Anda telah menyelesaikan siklus SDD penuh: tentukan → perjelas → rencanakan → tugas → analisis → terapkan → uji. Setiap fase menghasilkan artefak berversi di specs/<branch-name>/.

8. Tantangan (Opsional)

Sekarang Anda mengetahui alur kerja SDD lengkap. Uji:

• Jalankan siklus SDD kedua untuk membuat antarmuka chat web bagi petugas informasi restoran — kali ini tanpa panduan langkah demi langkah.
• Men-deploy agen Anda ke Cloud Run untuk skenario produksi

Petunjuk

• Project tidak memiliki framework frontend. Antigravity harus mengusulkan HTML/CSS/JS standar — jika menyarankan React atau yang serupa, dorong ke arah kesederhanaan (prinsip "tetap sederhana" dalam konstitusi Anda akan menangkap hal ini).
• Server ADK mengekspos /run_sse untuk streaming dan /apps/{app_name}/users/{user_id}/sessions untuk pengelolaan sesi. Antigravity menemukan ini dari konteks project.
• Setelah penerapan, mulai server dengan uv run uvicorn server:app --host 0.0.0.0 --port 8080 (bukan adk web) agar pemasangan file statis berfungsi.
• Uji di http://localhost:8080/static/index.html.
• Codelab referensi sudah menunjukkan cara men-deploy dan mempertahankan agen ADK, berikan referensi Antigravity untuk ini.

9. Selamat!

Anda telah memperluas agen ADK pramutamu restoran dengan pemesanan reservasi — sepenuhnya melalui alur kerja SDD Antigravity, tanpa menulis kode aplikasi secara manual.

Yang Anda bangun

• Agen ADK concierge restoran dengan penelusuran menu, penelusuran semantik, pelacakan preferensi diet, dan pemesanan reservasi
• Keterampilan Antigravity untuk riset repo yang membuat dan memelihara dokumen konteks project
• Konstitusi project yang menerapkan prinsip-prinsip yang tidak dapat dinegosiasikan selama perencanaan dan analisis
• Siklus SDD lengkap yang menunjukkan alur kerja tentukan → perjelas → rencanakan → tugas → analisis → terapkan

Yang telah Anda pelajari

• Cara menggunakan alur kerja Pengembangan yang Didorong Spesifikasi di Antigravity untuk menambahkan fitur secara sistematis ke codebase yang ada
• Cara membuat skill Antigravity yang mengemas pengetahuan domain untuk digunakan kembali di seluruh percakapan
• Cara mem-bootstrap konteks project sehingga Antigravity dapat membuat keputusan yang tepat tentang arsitektur, pola, dan pilihan teknologi
• Cara menetapkan konstitusi project yang divalidasi oleh alur kerja SDD
• Cara memperluas agen ADK dengan alat baru yang didukung database melalui MCP Toolbox

Pembersihan

Hentikan semua proses lokal yang sedang berjalan (Toolbox):

pkill -f toolbox 2>/dev/null

Hapus instance Cloud SQL untuk menghindari biaya berkelanjutan:

gcloud sql instances delete restaurant-db --quiet

Jika ingin, hapus seluruh project:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Penting: Anda dapat mengurungkan operasi penghapusan ini untuk jangka waktu terbatas dengan menggunakan perintah ini gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}