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 mengumpulkan 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 Antigravity 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 implementasi 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 oleh alur kerja SDD selama perencanaan dan analisis
• Cara menggunakan alur kerja Pengembangan Berbasis 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 aktif diaktifkan
• Penyelesaian empat codelab ADK prasyarat sebelumnya (atau pengetahuan yang setara) akan membantu memahami konteks kasus penggunaan:
• Membangun Agen AI dengan ADK: Fondasi
• Membangun Agen AI dengan ADK: Memberikan Kemampuan Tambahan dengan Alat
• Membangun Agen AI Persisten dengan ADK dan CloudSQL
• Men-deploy, Mengelola, dan Mengamati 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, gunakan banner di bagian atas codelab ini untuk mendapatkan akun penagihan uji coba yang dapat digunakan untuk tutorial ini.

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

Menginstal prasyarat

Pastikan sistem Anda memiliki executable CLI berikut:

• git
• gcloud
• uv
• npm

Petunjuk penginstalan berbeda-beda berdasarkan Sistem Operasi komputer Anda.

Meng-clone repositori starter

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>

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

PENTING! Langkah di bawah ini diberikan untuk membantu penyiapan project Google Cloud yang ditautkan ke akun Penagihan Uji Coba (ketat) dengan cepat. Jika Anda lebih memilih untuk menggunakan project sebelumnya, Anda dapat melewati langkah berikut dan melakukan langkah berikut:

Tambahkan nama project Anda sendiri sebagai variabel GOOGLE_CLOUD_PROJECT dalam file .env

Aktifkan project Anda di terminal menggunakan gcloud config set project your-project-id

Kemudian, Anda dapat langsung membuka bagian Mengaktifkan API

Jika Anda tidak yakin, lanjutkan ke bagian di bawah

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

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

Mengaktifkan API

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.

Menginstal dependensi

Kita akan menggunakan uv sebagai pengelola project Python. uv adalah pengelola project dan paket Python cepat yang ditulis dalam Rust ( docs ). 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

Menyiapkan Infrastruktur dan Data Database

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.

Kemudian, jalankan skrip scripts/setup_database.sh untuk menyiapkan semua infrastruktur yang diperlukan. Aplikasi ini akan melakukan hal berikut:

• Membuat instance Cloud SQL
• Periksa apakah instance sudah siap
• Memberikan Vertex AI izin
• Buat database
• Database benih
• Menjalankan layanan MCP Toolbox di latar belakang

chmod +x scripts/setup_database.sh
./scripts/setup_database.sh > database_setup.log 2>&1 &

Perintah ini akan menjalankan penyiapan di latar belakang. Anda dapat memeriksa output secara berkala di file database_setup.log

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 Berbasis Spesifikasi

Langkah ini menjelaskan 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)
│   │   ├── 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

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/mcp-toolbox-postgres/SKILL.md — Keterampilan yang memandu Antigravity tentang cara membuat konfigurasi tools.yaml yang tepat untuk MCP toolbox. Keterampilan ini akan mengajarkan konfigurasi terkait sources, tools , dan embeddingModels yang diperlukan untuk membangun pipeline RAG yang tepat. Keahlian ini tidak akan diaktifkan hingga Anda menambahkan frontmatter YAML yang tepat agar dikenali oleh Antigravity
• .agents/skills/repo-research/SKILL.md — Keterampilan yang mengajarkan Antigravity cara menganalisis repositori secara inkremental dan menghasilkan dokumen konteks project terstruktur. Alat ini menggunakan pendekatan 4 fase: pemindaian permukaan (hanya struktur direktori), file konfigurasi dan metadata, titik entri dan model data, lalu analisis mendalam yang ditargetkan — setiap fase berhenti dan menulis temuan sebelum melanjutkan ke fase berikutnya. Halaman ini juga 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 Berbasis 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. 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: fungsi fitur, siapa yang menggunakannya, dan apa kriteria keberhasilannya. Asisten AI bekerja berdasarkan spesifikasi tersebut — dan Anda juga harus melakukannya saat meninjau output-nya. Spesifikasi menjadi satu sumber tepercaya untuk maksud. Jika kode berbeda dari spesifikasi, Anda dapat mengetahuinya saat peninjauan. Jika persyaratan berubah, Anda harus memperbarui spesifikasi terlebih dahulu, lalu membuat ulang. Keputusan didokumentasikan, bukan diimprovisasi.

Perbedaan ini 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 ini mencakup dua fase gerbang kualitas opsional (perjelas 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, celah, 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 dalam 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. 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 harus bersyukur 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 memberikan konteks dan batasan yang diperlukan Antigravity 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 2 keterampilan (repo-research dan mcp-toolbox-postgres), tetapi tidak memiliki aturan. Nanti, kita akan membuat aturan project-context.md yang memberikan pemahaman persisten Antigravity 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 materi pengantar, 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/mcp-toolbox-postgres/SKILL.md di editor. Ganti baris komentar TODO(codelab) di bagian atas dengan frontmatter ini:

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

Catatan: Skill MCP Toolbox Postgres berisi konfigurasi yang tepat untuk sources, tools, dan embedding models

Buka .agents/skills/repo-research/SKILL.md di editor. Ganti 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/mcp-toolbox-postgres/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.

Menginstal Keterampilan yang Tersedia Secara Publik

Keterampilan Lembar Cheat ADK

Sebelumnya, kita memeriksa keterampilan yang kita buat sendiri ( keterampilan repo-research dan mcp-toolbox-postgres). Namun, ada banyak keterampilan lain yang berguna untuk mendukung pengembangan software kami dan dapat diinstal dengan mudah ke agen coding kami. Misalnya, dalam tutorial ini, kita perlu berinteraksi dengan ADK, sehingga kita memerlukan pengetahuan yang tepat tentang cara membangun dengan ADK. Mari kita instal skill dokumentasi ADK menggunakan perintah berikut

npx skills add google/adk-docs

Kemudian, Anda akan diminta mengonfirmasi penginstalan seperti yang ditunjukkan di bawah

Tekan y untuk melanjutkan ke perintah berikutnya guna memilih keterampilan yang akan diinstal seperti yang ditunjukkan di bawah. Untuk saat ini, kita hanya akan menggunakan adk-cheatsheet (tekan spasi untuk memilih, lalu enter untuk mengonfirmasi)

Kemudian, cukup klik Enter untuk opsi lain guna mengaktifkan penginstalan default dan menginstal skill di project saat ini

Anda akan melihat keterampilan ADK baru yang ditambahkan ke direktori .agents/skills, yaitu adk-cheatsheet

Keterampilan Manusia Purba

Salah satu keahlian yang berguna untuk mengurangi penggunaan token adalah keahlian manusia purba ini . Keterampilan ini dapat memotong token output dari agen,sehingga menjadi kombinasi yang baik saat Anda menggunakan pengembangan berbasis spesifikasi penuh seperti tutorial ini

npx skills add JuliusBrussee/caveman

Seperti sebelumnya, pilih keahlian caveman di sini untuk saat ini

Kemudian, cukup klik Enter untuk opsi lain guna mengaktifkan penginstalan default dan menginstal skill di project saat ini

Sekarang, kita sudah mengonfigurasi 4 keterampilan dan siap memulai perjalanan SDD

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

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, and communicate efficiently

Antigravity mencocokkan permintaan Anda dengan keterampilan repo-research dan caveman ( perintah untuk berkomunikasi secara efisien), 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: tumpukan 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: "Riset 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 dijalankan 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 ditujukan 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 pengamatan, 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).

5. Siklus SDD — Fitur Tambahkan Reservasi

Langkah ini membahas siklus SDD lengkap untuk menambahkan pemesanan reservasi ke agen concierge restoran. Anda mengarahkan Antigravity 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 dengan bantuan 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 "Klarifikasi 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 menemukan ambiguitas, kriteria penerimaan yang tidak ada, dan persyaratan yang kurang ditentukan. Meminta klarifikasi yang ditargetkan — setiap jawaban 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 lanjutkan ke perencanaan.

Merencanakan penerapan

Jalankan alur kerja perencanaan:

/speckit.plan Update the restaurant concierge agent to multi agent architecture which separate responsibilities for handling menu and reservations. Use your ADK and MCP toolbox skill to implement it properly

Antigravity 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

Antigravity 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 tidak ada, tugas yang mungkin bertentangan, atau kesenjangan antara persyaratan spesifikasi dan pekerjaan yang direncanakan. Atasi masalah kritis sebelum menerapkan.

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

6. 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 selesai. 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. 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) alih-alih mengupdate 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. Lakukan migrasi database untuk menggabungkan tabel baru dan mulai ulang Toolbox untuk mengambil definisi alat baru di tools.yaml. Hentikan proses Toolbox yang ada, lalu mulai proses baru:

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

Anda dapat memeriksa log output di database_setup.log untuk mengetahui apakah Antigravity menghasilkan kode dan konfigurasi yang benar atau tidak. Jika Anda mengalami error, coba berinteraksi dengan agen untuk memperbaikinya

Jika semuanya berjalan lancar, kita dapat memulai 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>/.

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

8. Selamat!

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

Yang Anda bangun

• Agen ADK petugas informasi 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 Berbasis 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 selama jangka waktu terbatas dengan menggunakan perintah ini gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}