Antigravity और Spec-kit की मदद से, स्पेसिफ़िकेशन के आधार पर ADK एजेंट डेवलप करना

1. परिचय

किसी मौजूदा एजेंट में नई सुविधाएं जोड़ने का मतलब है कि आपको बॉयलरप्लेट लिखना होगा, इंटिग्रेशन सेट अप करने होंगे, और यह पक्का करना होगा कि सब कुछ कोडबेस में पहले से मौजूद पैटर्न के मुताबिक हो. यह एक नई सुविधा है, जो डेटाबेस पर आधारित है. Antigravity, इस प्रोसेस के हर चरण को तेज़ करता है: यह आपके कोडबेस का विश्लेषण करके, ज़रूरी कॉन्टेक्स्ट बनाता है. साथ ही, समीक्षा के लिए स्ट्रक्चर्ड स्पेसिफ़िकेशन और लागू करने की योजनाएं बनाता है. इसके अलावा, यह कोड में बदलाव करता है. यह सब, डोमेन की जानकारी के आधार पर किया जाता है. यह जानकारी, दोबारा इस्तेमाल की जा सकने वाली स्किल और प्रोजेक्ट के संविधान के तौर पर कैप्चर की जाती है. प्रोजेक्ट के संविधान में, ऐसे सिद्धांत शामिल होते हैं जिन पर कोई समझौता नहीं किया जा सकता. इस कोडलैब में, Antigravity के स्पेसिफ़िकेशन पर आधारित डेवलपमेंट पैराडाइम को बेहतर बनाने का तरीका बताया गया है. इसके लिए, एक नया साइकल जोड़ा गया है, ताकि स्पेसिफ़िकेशन के दस्तावेज़ को बेहतर बनाया जा सके. इसमें spec-kit का इस्तेमाल किया जाता है

आपको क्या बनाना है

स्थानीय तौर पर चल रहा रेस्टोरेंट कॉन्सियर्ज ऐप्लिकेशन, जिसमें एसडीडी के पूरे साइकल के ज़रिए बुकिंग की सुविधा जोड़ी गई है:

• रिज़र्वेशन की बुकिंग — मेहमान टेबल बुक करते हैं और रिज़र्वेशन की जांच करते हैं. इसके लिए, नए MCP टूलबॉक्स डेटाबेस टूल और Cloud SQL reservations टेबल का इस्तेमाल किया जाता है
• (चैलेंज) – एजेंट के लिए अपना यूज़र इंटरफ़ेस (यूआई) डेवलप करें
• (चैलेंज) – Antigravity एजेंट की मदद से, Google Cloud पर डिप्लॉय करना

स्टार्टर कोड, मेन्यू खोजने की सुविधा देने वाला ADK एजेंट उपलब्ध कराता है. इसमें कीवर्ड + एमसीपी टूलबॉक्स के ज़रिए सिमैंटिक और ToolContext के ज़रिए खाने-पीने की प्राथमिकताओं को ट्रैक करने की सुविधा मिलती है. इसे ऐप्लिकेशन कोड को मैन्युअल तरीके से लिखे बिना बढ़ाया जा सकता है. Antigravity, आपकी खास बातों के आधार पर इसे लागू करता है.

आपको क्या सीखने को मिलेगा

• प्रोजेक्ट के कॉन्टेक्स्ट को बूटस्ट्रैप करने का तरीका, ताकि Antigravity को मौजूदा कोडबेस के बारे में जानकारी मिल सके
• डोमेन की जानकारी देने वाली Antigravity स्किल बनाने का तरीका (जैसे, ADK कोडलैब पैटर्न) को फिर से इस्तेमाल करने के लिए
• प्रोजेक्ट का ऐसा कॉन्स्टिट्यूशन सेट करने का तरीका जिसके आधार पर, एसडीडी वर्कफ़्लो, प्लानिंग और विश्लेषण के दौरान पुष्टि करते हैं
• Antigravity में, सिस्टमैटिक तरीके से सुविधाएं जोड़ने के लिए, स्पेसिफ़िकेशन-ड्रिवन डेवलपमेंट (एसडीडी) वर्कफ़्लो का इस्तेमाल कैसे करें
• MCP टूलबॉक्स की मदद से, डेटाबेस पर आधारित नए टूल का इस्तेमाल करके, ADK एजेंट को कैसे बढ़ाया जा सकता है

ज़रूरी शर्तें

• आपके कंप्यूटर पर Google Antigravity और git इंस्टॉल हो
• मुफ़्त में आज़माने की सुविधा वाले बिलिंग खाते से जुड़ा Google Cloud खाता
• इस्तेमाल के उदाहरण के बारे में समझने के लिए, ADK के चार ज़रूरी कोडलैब (या इसके बराबर की जानकारी) को पूरा करना मददगार होगा:
• ADK की मदद से एआई एजेंट बनाना: बुनियादी जानकारी
• ADK की मदद से एआई एजेंट बनाना: टूल की मदद से बेहतर बनाना
• ADK और CloudSQL की मदद से, लगातार काम करने वाले एआई एजेंट बनाना
• Cloud Run पर ADK एजेंट को डिप्लॉय, मैनेज, और मॉनिटर करना
• डेटाबेस को टूल के तौर पर इस्तेमाल करना: ADK, MCP टूलबॉक्स, और Cloud SQL के साथ एजेंटिक RAG

2. अपना एनवायरमेंट सेट अप करना

अहम जानकारी:

इस ट्यूटोरियल के लिए, चालू बिलिंग खाते वाला Google Cloud प्रोजेक्ट ज़रूरी है. अगर आपके पास अब तक कोई खाता नहीं है, तो कृपया इस ट्यूटोरियल के लिए बिलिंग का ट्रायल खाता पाने के लिए, यहां दिया गया तरीका अपनाएं:

1. गुप्त विंडो खोलें
2. अगर आपको किसी वर्कशॉप सेशन में शामिल होना है, तो रिडेंप्शन पोर्टल का यूआरएल आम तौर पर सेशन में दिया जाएगा. इसके अलावा, बिना शुल्क आज़माने वाले बिलिंग खाते के रिडेंप्शन पोर्टल पर जाकर भी इसे ऐक्सेस किया जा सकता है
3. अपने निजी Gmail खाते से लॉग इन करें ( Google Workspace / अन्य ईमेल पते काम नहीं करेंगे! )
4. रिडीम करने के सिलसिलेवार निर्देशों का पालन करें

इस चरण में, स्टार्टर रिपॉज़िटरी को क्लोन किया जाता है, Google Cloud से पुष्टि की जाती है, Cloud SQL डेटाबेस उपलब्ध कराया जाता है, और आपके लोकल Antigravity एनवायरमेंट को तैयार किया जाता है.

ध्यान दें: यह कोडलैब, आपकी लोकल मशीन पर Google Antigravity में पूरी तरह से चलता है. सेटअप में, gcloud सीएलआई कमांड का इस्तेमाल करके मैन्युअल तरीके से पुष्टि करना शामिल है

स्टार्टर रिपॉज़िटरी का क्लोन बनाना

Antigravity (या अपने सिस्टम टर्मिनल) में एक टर्मिनल खोलें. साथ में काम करने वाली रिपो को क्लोन करें और डायरेक्ट्री डालें:

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

क्लोन की गई रिपॉज़िटरी को Antigravity में खोलें. File->Open Folder->क्लोन की गई डायरेक्ट्री sdd-adk-agents-agy चुनें

अपस्ट्रीम रिमोट को हटाएं. SDD वर्कफ़्लो, सुविधा की खास बातों के लिए git ब्रांच बनाते हैं. रिमोट हटाने से, गलती से स्टार्टर रिपॉज़िटरी में पुश करने से रोका जा सकता है:

git remote remove origin

अहम जानकारी: इस कोडलैब में SDD के वर्कफ़्लो, सुविधा की खास बातों को व्यवस्थित करने के लिए git ब्रांच का इस्तेमाल करते हैं. origin रिमोट को हटाने से, यह पक्का किया जा सकता है कि आपकी स्थानीय शाखाएं और कमिट स्थानीय बनी रहें. अगर आपको अपने काम का बैक अप लेना है, तो अपना रिमोट जोड़ें: git remote add origin <your-repo-url>

ज़रूरी शर्तें पूरी करना

ज़रूरी शर्तों वाली स्क्रिप्ट चलाएँ. यह git, curl, gcloud, uv, Python 3.12, और MCP Toolbox की जांच करता है. अगर ये मौजूद नहीं हैं, तो उन्हें इंस्टॉल करता है:

bash scripts/setup_prerequisites.sh

ध्यान दें: सभी ज़रूरी शर्तें पूरी करने के लिए, कुछ समय लगेगा. डाउनलोड पूरा होने तक इंतज़ार करें. इस दौरान, अगले सेक्शन पर जाने के लिए नया टैब खोलें

Google Cloud की मदद से पुष्टि करना

पुष्टि करने के लिए दो कमांड चलाएं. दोनों OAuth के लिए ब्राउज़र खोलते हैं:

gcloud auth login
gcloud auth application-default login

ध्यान दें: अनुमति चुनने के लिए कहा जाने पर, दूसरी OAuth कमांड पर. सभी विकल्प देखें

ध्यान दें: पुष्टि करने के लिए, उसी ईमेल का इस्तेमाल करें जिसका इस्तेमाल आपने बिना शुल्क आज़माने की अवधि वाले बिलिंग खाते का दावा करने के लिए किया था

Antigravity के साथ स्थानीय तौर पर काम करने के लिए, आपको मैन्युअल तरीके से पुष्टि करनी होगी. auth login, gcloud सीएलआई की पुष्टि करता है. application-default login आपके ऐप्लिकेशन में इस्तेमाल किए जाने वाले Google Cloud SDK की पुष्टि करता है. ADK के Vertex AI कॉल और Cloud SQL Python कनेक्टर, दोनों ही ऐप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल पर निर्भर करते हैं.

Google Cloud प्रोजेक्ट सेट अप करना

प्रोजेक्ट सेटअप स्क्रिप्ट चलाने से पहले, .env में जगह की जानकारी वाले वैरिएबल लिखें:

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

• GOOGLE_CLOUD_LOCATION=global का इस्तेमाल, Vertex AI / Gemini API कॉल के लिए किया जाता है.
• REGION=us-central1 का इस्तेमाल Cloud SQL और अन्य GCP इंफ़्रास्ट्रक्चर के लिए किया जाता है

प्रोजेक्ट सेटअप स्क्रिप्ट डाउनलोड करें और उसे चलाएं. यह फ़ंक्शन, बिना किसी शुल्क के आज़माने की सुविधा के लिए Google Cloud प्रोजेक्ट बनाता है या उसकी पुष्टि करता है. साथ ही, प्रोजेक्ट आईडी को .env में सेव करता है. इसके बाद, इसे सोर्स करता है:

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

ज़रूरी एपीआई चालू करें:

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

ध्यान दें: एपीआई चालू होने में कुछ समय लग सकता है. आपको हर प्रोजेक्ट के लिए सिर्फ़ एक बार ऐसा करना होगा.

Cloud SQL को चालू करना

डेटाबेस का पासवर्ड सेट करें और उसे .env में जोड़ें:

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

अहम जानकारी: ऊपर दिया गया हार्डकोड किया गया पासवर्ड, सिर्फ़ ट्यूटोरियल के लिए है. प्रोडक्शन एनवायरमेंट में, क्रेडेंशियल को सुरक्षित तरीके से सेव करने के लिए Secret Manager जैसी किसी सेवा का इस्तेमाल करें. साथ ही, रनटाइम में उन्हें रेफ़रंस करें. कभी भी सोर्स कंट्रोल में, प्लेनटेक्स्ट सीक्रेट सबमिट न करें.

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 &

Vertex AI ML इंटिग्रेशन के लिए, db-custom-1-3840 टियर कम से कम ज़रूरी है. --enable-google-ml-integration फ़्लैग की मदद से, Cloud SQL सीधे तौर पर एसक्यूएल से Gemini के एम्बेडिंग मॉडल को कॉल कर सकता है. इससे सिमैंटिक सर्च की सुविधा काम करती है.

ध्यान दें: इस कमांड को पूरा होने में करीब पांच मिनट लगते हैं. यह बैकग्राउंड में चलती है. इसे इस टर्मिनल टैब में चलने दें. साथ ही, अगले चरणों के लिए एक नया टर्मिनल टैब खोलें.

डिपेंडेंसी इंस्टॉल करना

नया टर्मिनल टैब खोलें. पक्का करें कि आप अब भी क्लोन किए गए रेपो प्रोजेक्ट डायरेक्ट्री में हों और एनवायरमेंट वैरिएबल फिर से लोड करें:

source .env

हम uv का इस्तेमाल, Python प्रोजेक्ट मैनेजर के तौर पर करेंगे. uv एक तेज़ Python पैकेज और प्रोजेक्ट मैनेजर है. इसे Rust में लिखा गया है ( दस्तावेज़ ). इस कोडलैब में, इसे तेज़ी से और आसानी से इस्तेमाल करने के लिए इस्तेमाल किया जाता है. Python की डिपेंडेंसी इंस्टॉल करें:

uv sync

इसके बाद, ADK एजेंट की .env फ़ाइल को अपने प्रोजेक्ट के कॉन्फ़िगरेशन के साथ अपडेट करें:

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

अब हमारे पास, काम करने के लिए ज़रूरी सभी स्टार्टर एडीके एजेंट रिपो होने चाहिए. अब आइए, अगले सेक्शन में एंटीग्रैविटी और स्पेसिफ़िकेशन के आधार पर डेवलपमेंट के बारे में ज़्यादा जानें. इस दौरान, हम सभी चीज़ों के तैयार होने का इंतज़ार करेंगे

3. स्टार्टर कोड एक्सप्लोर करना और स्पेसिफ़िकेशन के आधार पर डेवलपमेंट के बारे में समझना

इस चरण में, स्टार्टर कोड स्ट्रक्चर के बारे में बताया गया है. साथ ही, स्पेसिफ़िकेशन के आधार पर डेवलपमेंट करने के तरीके के बारे में बताया गया है. इसमें डेटाबेस को सीड किया जाता है और यह पुष्टि की जाती है कि एजेंट को बढ़ाने से पहले, वह ठीक से काम कर रहा है.

प्रोजेक्ट का स्ट्रक्चर

क्लोन किए गए repo प्रोजेक्ट को Antigravity एडिटर में खोलें और डायरेक्ट्री लेआउट की समीक्षा करें:

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

मुख्य फ़ाइलें

एजेंट के आवेदन से जुड़ी फ़ाइलें

• restaurant_concierge/agent.py — यह मुख्य एजेंट होता है. एक LlmAgent जो MCP Toolbox के डेटाबेस टूल को ToolContext पर आधारित डाइट से जुड़ी प्राथमिकताओं को ट्रैक करने की सुविधा के साथ जोड़ता है. एजेंट, टूलबॉक्स सर्वर से सभी टूल लोड करता है. साथ ही, दो Python फ़ंक्शन (save_dietary_preference, get_dietary_preferences) जोड़ता है, जो स्थिति को मैनेज करने के लिए ToolContext का इस्तेमाल करते हैं.
• tools.yaml — MCP टूलबॉक्स टूल की परिभाषाएं. मेन्यू में खोज के लिए तीन टूल तय किए गए हैं: कीवर्ड खोज (search_menu), pgvector के ज़रिए सिमैंटिक खोज (semantic_search_menu), और कैटगरी फ़िल्टर (get_menu_by_category). फ़िलहाल, बुकिंग के लिए कोई टूल मौजूद नहीं है. इन्हें बाद में जोड़ा जाएगा
• server.py — यह एक छोटा FastAPI सर्वर है. इसमें दिखाया गया है कि ADK को FastAPI ऑब्जेक्ट के तौर पर कैसे ऐक्सेस किया जा सकता है. ADK से get_fast_api_app(), बिल्ट-इन एंडपॉइंट उपलब्ध कराता है. इनमें एसएसई स्ट्रीमिंग और सेशन मैनेजमेंट एपीआई के लिए /run_sse शामिल है.

Antigravity Files

• .agents/skills/adk-agent-development/SKILL.md — यह पहले से कॉन्फ़िगर की गई एक स्किल है, जिसे Antigravity ने जनरेट किया है. इसमें चारों ADK कोडलैब से, कम शब्दों में जानकारी दी गई है. यह फ़िलहाल चालू नहीं है (इसमें YAML फ़्रंटमैटर मौजूद नहीं है). आपको इसे बाद में अपडेट करना होगा. ADK एजेंट की सुविधाओं और उनके उदाहरणों से जुड़ा काम पता चलने पर, Antigravity इस स्किल को अपने-आप लोड कर देता है. यह वह जानकारी है जो बाद में बुकिंग की सुविधा प्लान करते समय, Antigravity का मार्गदर्शन करती है
• .agents/skills/repo-research/SKILL.md — यह एक ऐसी स्किल है जो Antigravity को, किसी रिपॉज़िटरी का धीरे-धीरे विश्लेषण करने और स्ट्रक्चर्ड प्रोजेक्ट कॉन्टेक्स्ट दस्तावेज़ बनाने का तरीका सिखाती है. यह चार चरणों वाली प्रोसेस का इस्तेमाल करता है: सिर्फ़ डायरेक्ट्री ट्री को स्कैन करना, कॉन्फ़िगरेशन और मेटाडेटा फ़ाइलें, एंट्री पॉइंट और डेटा मॉडल, और फिर टारगेट किए गए डीप डाइव — हर चरण के बाद, अगले चरण पर जाने से पहले, नतीजे सेव किए जाते हैं. ADK की स्किल की तरह, यह भी तब तक बंद रहती है, जब तक बाद में YAML फ़्रंटमैटर नहीं जोड़ा जाता. चालू हो जाने के बाद, इसका इस्तेमाल करके .agents/rules/project-context.md जनरेट करें. यह एक ऐसा दस्तावेज़ है जिसमें आर्किटेक्चर, रनटाइम डिपेंडेंसी, एपीआई सर्फ़ेस, और डोमेन की शब्दावली के बारे में पूरी जानकारी दी गई है.

स्पेसिफ़िकेशन के आधार पर डेवलपमेंट: Antigravity की बिल्ट-इन प्लानिंग से लेकर स्ट्रक्चर्ड SDD तक

एआई कोडिंग असिस्टेंट की मदद से, प्रॉम्प्ट से कोड जनरेट करना आसान हो जाता है. जोखिम: आपने किसी सुविधा के बारे में एक वाक्य में बताया, Assistant ने उसके बारे में सैकड़ों लाइनें लिख दीं, और आपने उसे स्वीकार कर लिया, क्योंकि वह सही लग रही थी. इसे कभी-कभी "वाइब कोडिंग" कहा जाता है. इसमें, आपको अपने हिसाब से काम करना होता है. साथ ही, यह तय करना होता है कि जनरेट किए गए जवाब को स्वीकार करना है या नहीं. यह प्रोटोटाइप और थ्रोअवे स्क्रिप्ट के लिए तेज़ है. जब कोडबेस बढ़ता है, जब सुविधाएं इंटरैक्ट करती हैं या जब कुछ हफ़्तों बाद कोड को फिर से देखा जाता है और यह पता नहीं चलता कि कोई फ़ैसला क्यों लिया गया था, तो यह काम नहीं करता.

स्पेसिफ़िकेशन के आधार पर डेवलपमेंट (एसडीडी) इस लूप में स्ट्रक्चर जोड़ता है. कोई भी कोड जनरेट करने से पहले, आपको एक स्पेसिफ़िकेशन लिखना होता है. इसमें यह जानकारी शामिल होती है: सुविधा क्या करती है, यह किसके लिए है, और सफलता के मानदंड क्या हैं. एआई असिस्टेंट, उस स्पेसिफ़िकेशन के हिसाब से काम करता है. साथ ही, आपको भी उसके आउटपुट की समीक्षा करते समय, उस स्पेसिफ़िकेशन को ध्यान में रखना होता है. स्पेसिफ़िकेशन, इंटेंट के लिए एकमात्र भरोसेमंद सोर्स बन जाता है. अगर कोड, स्पेसिफ़िकेशन से अलग है, तो समीक्षा के दौरान आपको इसकी जानकारी मिल जाएगी. अगर ज़रूरी शर्तों में बदलाव होता है, तो पहले स्पेसिफ़िकेशन अपडेट करें. इसके बाद, फिर से जनरेट करें. फ़ैसले दस्तावेज़ में लिखे जाते हैं, न कि अचानक लिए जाते हैं.

एसडीडी, वाइब कोडिंग की तुलना में हर सुविधा के लिए ज़्यादा समय लेता है. कोडिंग करने से पहले, दस्तावेज़ बनाए जाते हैं. हालांकि, इससे फ़ायदा मिलता है. आने वाले समय में कोडबेस में किए जाने वाले हर बदलाव के बारे में जानकारी होती है. एआई से जनरेट किए गए हर कोड की समीक्षा की जा सकती है. साथ ही, सहयोगी (इंसान या एआई) को शामिल किया जा सकता है. इसके लिए, उन्हें स्पेसिफ़िकेशन के बारे में बताना होता है. इसके बजाय, उन्हें यह बताना होता है कि फ़ैसले किस आधार पर लिए गए.

Antigravity, स्पेसिफ़िकेशन के हिसाब से डेवलपमेंट के सिद्धांतों का पहले से ही पालन करता है. एजेंट को प्लानिंग मोड पर सेट करने पर, वह कोई भी कोड लिखने से पहले दो आर्टफ़ैक्ट बनाता है:

• लागू करने का प्लान — इसमें तकनीकी तरीके, फ़ाइल में किए जाने वाले बदलावों, और आर्किटेक्चर से जुड़े फ़ैसलों के बारे में खास जानकारी दी जाती है
• टास्क की सूची — काम के आइटम का स्ट्रक्चर्ड ब्रेकडाउन

Antigravity, इन आर्टफ़ैक्ट को लागू करने से पहले, आपसे इनकी समीक्षा करने और इन्हें स्वीकार करने के लिए कहता है. प्लान-फिर-लागू करने वाला यह लूप, स्पेसिफ़िकेशन-ड्रिवन डेवलपमेंट का मुख्य हिस्सा है: स्पेसिफ़िकेशन, कोड को गाइड करते हैं, न कि कोड, स्पेसिफ़िकेशन को गाइड करते हैं.

यह कोडलैब, spec-kit पर आधारित राय पर आधारित, वर्शन कंट्रोल किए गए वर्कफ़्लो के साथ उस फ़ाउंडेशन को आगे बढ़ाता है. spec-kit, GitHub का स्पेसिफ़िकेशन-ड्रिवन डेवलपमेंट फ़्रेमवर्क है. हर सुविधा एक खास पाइपलाइन से गुज़रती है. इसमें हर आर्टफ़ैक्ट एक स्टैंडअलोन दस्तावेज़ होता है. इसकी समीक्षा की जा सकती है, इसमें बदलाव किया जा सकता है, और इसे git में ट्रैक किया जा सकता है. पाइपलाइन में क्वालिटी-गेट के दो वैकल्पिक चरण (जानकारी देना और विश्लेषण करना) शामिल होते हैं. ये चरण, समस्याओं को लागू करने से पहले ही उनका पता लगा लेते हैं:

चरण	आर्टफ़ैक्ट	मकसद
/speckit.specify	spec.md	यह तय करना कि क्या बनाना है (उपयोगकर्ता के लिए, टेक्नोलॉजी से जुड़ी जानकारी के बिना)
/speckit.clarify (ज़रूरी नहीं)	spec.md अपडेट किया गया	उन क्षेत्रों की पहचान करना जिनके बारे में कम जानकारी दी गई है, जानकारी पाने के लिए सवाल पूछना, और जवाबों को वापस स्पेसिफ़िकेशन में कोड करना
/speckit.plan	plan.md, data-model.md, research.md	इसे बनाने का तरीका तय करना (तकनीकी तरीका, डेटा मॉडल, रिसर्च)
/speckit.tasks	tasks.md	प्लान को क्रम से लगाए गए, कार्रवाई किए जा सकने वाले चरणों में बांटना
/speckit.analyze (ज़रूरी नहीं)	विश्लेषण रिपोर्ट	लागू करने से पहले, टास्क में जोखिम, कमियों या छूटे हुए एज केस की समीक्षा करें
/speckit.implement	कोड में बदलाव	टास्क पूरे करें और हर टास्क के पूरा होने पर सही का निशान लगाएं

हर आर्टफ़ैक्ट को specs/<feature-branch>/ में एक फ़ाइल के तौर पर सेव किया जाता है. साथ ही, इसे git में वर्शन कंट्रोल किया जाता है और इसका दोबारा इस्तेमाल किया जा सकता है. अगर बातचीत में कोई रुकावट आती है या आपको बाद में फ़ैसलों पर दोबारा विचार करना है, तो स्पेसिफ़िकेशन दस्तावेज़ हमेशा उपलब्ध रहते हैं. ये चैट के इतिहास में नहीं छिपे होते.

ध्यान दें: Antigravity में, यूज़र इंटरफ़ेस (यूआई) में आर्टफ़ैक्ट बनाने की सुविधा पहले से मौजूद है. इससे उपयोगकर्ता, जनरेट किए गए आर्टफ़ैक्ट (इमेज भी!) पर टिप्पणी कर सकते हैं. ). इसलिए, इस ट्यूटोरियल में हम spec-kit के मूल प्रॉम्प्ट में बदलाव करके, उसे implement फ़ेज़ में बिल्ट-इन आर्टफ़ैक्ट के साथ इंटिग्रेट करते हैं

स्टार्टर रेपो में, एसडीडी के ये वर्कफ़्लो .agents/workflows/ में और टेंप्लेट .specify/templates/ में शामिल हैं. इनका इस्तेमाल बाद में एजेंट में सुविधाएं जोड़ने के लिए किया जाएगा.

4. Cloud SQL का सेटअप पूरा करें और पक्का करें कि बेस एजेंट काम कर रहा हो

उस टर्मिनल टैब पर वापस जाएं जहां Cloud SQL इंस्टेंस बनाने की कमांड चल रही है. यह प्रोसेस पूरी होने के बाद, पुष्टि करें कि इंस्टेंस तैयार है:

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

अगर आउटपुट में RUNNABLE दिखता है, तो आगे बढ़ें. अगर आपको PENDING_CREATE दिखता है, तो कुछ देर इंतज़ार करें और कमांड को फिर से चलाएं.

Cloud SQL सेवा खाते को Vertex AI का ऐक्सेस दें. यह डेटाबेस में एम्बेड करने की सुविधा के लिए ज़रूरी है:

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

डेटाबेस बनाएं:

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

आपको आउटपुट कुछ इस तरह दिखेगा

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

चेकपॉइंट: आपकी .env फ़ाइल में GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, REGION, और DB_PASSWORD शामिल हैं. Cloud SQL इंस्टेंस restaurant-db चल रहा है. toolbox आपके PATH पर उपलब्ध है (setup_prerequisites.sh ने इसे इंस्टॉल किया है). Python की डिपेंडेंसी इंस्टॉल की गई हैं.

डेटाबेस में डेटा डालना

अपने एनवायरमेंट वैरिएबल लोड करें और डेटाबेस सीड स्क्रिप्ट चलाकर स्कीमा बनाएं. साथ ही, 16 मेन्यू आइटम डालें:

source .env
uv run python scripts/seed_db.py

अनुमानित आउटपुट:

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

सिमेंटिक सर्च के लिए वेक्टर एम्बेडिंग जनरेट करें:

uv run python scripts/generate_embeddings.py

अनुमानित आउटपुट:

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

यह Cloud SQL के बिल्ट-इन embedding() फ़ंक्शन का इस्तेमाल करता है. यह google_ml_integration एक्सटेंशन के ज़रिए, सीधे एसक्यूएल से gemini-embedding-001 को कॉल करता है. 3,072 डाइमेंशन वाले वेक्टर, menu_items के embedding कॉलम में सेव किए जाते हैं. इसके लिए, ऐप्लिकेशन के लिए एम्बेडिंग कोड की ज़रूरत नहीं होती.

बेस एजेंट को टेस्ट करना

MCP Toolbox को बैकग्राउंड प्रोसेस के तौर पर शुरू करने के लिए:

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

टूलबॉक्स, डेटाबेस टूल को एचटीटीपी पर दिखाता है. एजेंट http://127.0.0.1:5000 पर इससे कनेक्ट होता है.

ADK के डेवलपर यूज़र इंटरफ़ेस (यूआई) को शुरू करें:

uv run adk web .

अपने ब्राउज़र में Dev UI खोलें. इसके बाद, इन प्रॉम्प्ट का इस्तेमाल करके एजेंट को आज़माएं:

What appetizers do you have?

जांच करना: एजेंट, डेटाबेस से क्वेरी करता है और मेन्यू आइटम दिखाता है

I'm vegetarian

जांच करें: एजेंट, खाने-पीने से जुड़ी प्राथमिकताओं को एजेंट की स्थिति में सेव करता है

Can I make a reservation for tomorrow?

जांच करें: एजेंट इसे मैनेज नहीं कर सकता (फ़िलहाल, बुकिंग के लिए कोई टूल उपलब्ध नहीं है)

Ctrl+C पर दो बार टैप करके, ADK के डेवलपर यूज़र इंटरफ़ेस (यूआई) को बंद करें. टूलबॉक्स को बैकग्राउंड में चलने दें. इसका इस्तेमाल बाद में किया जा सकता है

चेकपॉइंट: बेस एजेंट काम करता है. साथ ही, मेन्यू खोजने की सुविधा (कीवर्ड + सिमैंटिक) और खाने-पीने की प्राथमिकताओं से जुड़ी सुविधा ठीक से काम करती है. बुकिंग के अनुरोध पूरे नहीं हो पाते, क्योंकि बुकिंग के टूल मौजूद नहीं हैं. आपको प्रोजेक्ट के स्ट्रक्चर और उस कमी के बारे में पता हो जिसे आपको पूरा करना है.

5. Antigravity की मदद से प्रोजेक्ट का कॉन्टेक्स्ट बूटस्ट्रैप करना

अब, हम एक ऐसी शर्त के साथ चीज़ों को सिम्युलेट करते हैं जो हमारे रोज़ के काम से "कुछ हद तक मिलती-जुलती" है:

• रिपॉज़िटरी को सही तरीके से मैनेज नहीं किया गया है
• README फ़ाइल पुरानी है
• दस्तावेज़ों को समय-समय पर अपडेट नहीं किया जाता

ध्यान दें: अगर आपको यह समस्या नहीं हो रही है, तो समझें कि आप बहुत भाग्यशाली हैं

इस तरह की स्थिति में, हम सबसे पहले उस प्रोजेक्ट के बारे में मैप या कॉन्टेक्स्ट बनाते हैं जिस पर हमें Antigravity से काम करवाना है. इस चरण में, Antigravity को मौजूदा कोडबेस के बारे में ज़्यादा जानकारी देने का एक उदाहरण दिखाया गया है. इसके लिए, एक ऐसी स्किल बनाई जाती है जो रिपॉज़िटरी का विश्लेषण करती है और प्रोजेक्ट के कॉन्टेक्स्ट का दस्तावेज़ जनरेट करती है.

यह प्रोजेक्ट के संविधान को भी सेट अप करता है. ये ऐसे सिद्धांत होते हैं जिन पर कोई समझौता नहीं किया जा सकता. SDD वर्कफ़्लो, इनकी पुष्टि करते हैं. इन दोनों से, Antigravity को SDD साइकल के लिए ज़रूरी कॉन्टेक्स्ट और सीमाएं मिलती हैं

Antigravity कॉन्टेक्स्ट हैरारकी

Antigravity, कॉन्टेक्स्ट के तीन लेवल का इस्तेमाल करता है. हर लेवल का स्कोप अलग होता है:

• नियम (.agents/rules/): हमेशा लागू रहने वाले निर्देश. इस वर्कस्पेस में की गई हर बातचीत में, उन्हें शामिल किया जाता है ( अगर आपने इस सुविधा को चालू किया है). प्रोजेक्ट के हिसाब से कॉन्टेक्स्ट के लिए नियमों का इस्तेमाल करें. जैसे, आर्किटेक्चर से जुड़े फ़ैसले, कोडिंग के स्टैंडर्ड या टेक्नोलॉजी स्टैक की जानकारी.
• कौशल (.agents/skills/): ज़रूरत के हिसाब से जानकारी. Antigravity, किसी स्किल को सिर्फ़ तब लोड करता है, जब मौजूदा टास्क, स्किल के description फ़ील्ड से मेल खाता हो. डोमेन के हिसाब से रेफ़रंस मटीरियल के लिए, स्किल का इस्तेमाल करें.
• वर्कफ़्लो (.agents/workflows/): सेव किए गए ऐसे प्रॉम्प्ट जिन्हें / कमांड से ट्रिगर किया जाता है. बार-बार की जाने वाली कई चरणों वाली प्रोसेस के लिए वर्कफ़्लो का इस्तेमाल करें. जैसे, एसडीडी पाइपलाइन.

ध्यान दें: फ़िलहाल, प्रोजेक्ट में वर्कफ़्लो (SDD पाइपलाइन) और एक स्किल (ADK एजेंट डेवलपमेंट) है, लेकिन कोई नियम नहीं है. project-context.md नियम की मदद से Antigravity को कोडबेस के बारे में लगातार जानकारी मिलती रहती है. जैसे, कौनसी टेक्नोलॉजी इस्तेमाल की जा रही हैं, फ़ाइलों को कैसे व्यवस्थित किया गया है, और अब तक क्या बनाया गया है.

स्किल चालू करना

स्टार्टर रेपो में, .agents/skills/ में पहले से लिखी गई दो स्किल शामिल होती हैं. इनमें निर्देश तो दिए गए हैं, लेकिन ज़रूरी YAML फ्रंटमैटर के बजाय TODO(codelab) टिप्पणियां शामिल की गई हैं. फ़्रंटमैटर के बिना, Antigravity उन्हें ढूंढ नहीं सकता.

Antigravity की सुविधाओं के लिए, फ़ाइल के सबसे ऊपर YAML फ़्रंटमैटर ब्लॉक की ज़रूरत होती है. इसमें दो फ़ील्ड होते हैं:

• name — यह स्किल के लिए यूनीक आइडेंटिफ़ायर होता है
• description — आम बोलचाल की भाषा में दी गई खास जानकारी. Antigravity, किसी अनुरोध के लिए कौनसी स्किल लोड करनी है, यह तय करते समय इस जानकारी का इस्तेमाल करता है

खुलने का समय

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

एडिटर में. सबसे ऊपर मौजूद TODO(codelab) वाली दो लाइनों को इस फ़्रंटमैटर से बदलें:

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

ध्यान दें: ADK एजेंट डेवलपमेंट स्किल में, पांच ADK कोडलैब से पैटर्न और उदाहरण शामिल किए गए हैं. ये कोडलैब हैं: एजेंट स्ट्रक्चर, टूल टाइप, स्टेट मैनेजमेंट, डिप्लॉयमेंट

खुलने का समय

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

एडिटर में. सबसे ऊपर मौजूद TODO(codelab) वाली दो लाइनों को इस फ़्रंटमैटर से बदलें:

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

ध्यान दें: repo-research SKILL.md को ध्यान से पढ़ें. यहां आपकी रिपॉज़िटरी का विश्लेषण करने के लिए, एक उदाहरण प्रॉम्प्ट दिया गया है. ध्यान दें कि इंक्रीमेंटल अपडेट के नियमों को जान-बूझकर सीमित रखा गया है. अगर रिसर्च के दौरान Antigravity का कॉन्टेक्स्ट खत्म हो जाता है या बातचीत में रुकावट आती है, तो अब तक की गई रिसर्च पहले ही फ़ाइल में सेव हो जाती है. स्किल को फिर से चालू करने पर, यह वहीं से शुरू होती है जहां आपने छोड़ा था. इससे आपकी प्रोग्रेस नहीं मिटती.

चेतावनी! किसी बड़ी रिपॉज़िटरी का विश्लेषण करने से, आपका कोटा जल्दी खत्म हो सकता है!

पुष्टि करें कि दोनों स्किल में मान्य फ़्रंटमैटर मौजूद है:

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

हर एक में, name: और description: फ़ील्ड को रैप करने वाले --- डेलिमिटर दिखने चाहिए. अगर डेलिमिटर या फ़ील्ड मौजूद नहीं हैं, तो Antigravity को स्किल की पहचान करने में मुश्किल होगी.

दोनों स्किल को ज़रूरत के हिसाब से लोड किया जाता है. Antigravity, आपके अनुरोध को description फ़ील्ड से मैच करता है. साथ ही, सिर्फ़ काम के होने पर ही पूरे निर्देश दिखाता है.

प्रोजेक्ट का कॉन्टेक्स्ट जनरेट करना

पक्का करें कि नियमों की डायरेक्ट्री मौजूद हो:

mkdir -p .agents/rules

Antigravity के एजेंट मैनेजर/चैट बॉक्स में (एडिटर मोड में ctrl + L दबाएं), नई बातचीत शुरू करें. प्रकार:

Research this repository and create a project context document

Antigravity, आपके अनुरोध को repo-research स्किल से मैच करता है. इसके बाद, कोडबेस का व्यवस्थित तरीके से विश्लेषण करना शुरू करता है. यह कॉन्फ़िगरेशन फ़ाइलों, सोर्स कोड, और दस्तावेज़ों को पढ़ता है. इसके बाद, प्रोजेक्ट के कॉन्टेक्स्ट टेंप्लेट में अपनी खोज के नतीजे भरता है.

प्रोसेस पूरी होने के बाद, एडिटर में .agents/rules/project-context.md खोलें. इसमें प्रोजेक्ट के बारे में पूरी जानकारी शामिल होती है: टेक्नोलॉजी स्टैक (Python 3.12, ADK, MCP टूलबॉक्स, Cloud SQL), प्रोजेक्ट स्ट्रक्चर, डेटा मॉडल (pgvector के साथ menu_items टेबल), और बाहरी इंटिग्रेशन.

अहम जानकारी: प्रोजेक्ट के आगे बढ़ने के साथ-साथ, प्रोजेक्ट के कॉन्टेक्स्ट से जुड़ा दस्तावेज़ भी बढ़ता जाता है. नई जानकारी के साथ कॉन्टेक्स्ट को अपडेट करने के लिए, स्किल को फिर से चलाया जा सकता है. इंक्रीमेंटल अपडेट के नियमों से यह पक्का होता है कि मौजूदा कॉन्टेंट सुरक्षित रहे. नई टेक्नोलॉजी, इकाइयों, और इंटिग्रेशन को जोड़ा जाता है, न कि ओवरराइट किया जाता है.

किसी खास अपडेट के लिए, इन प्रॉम्प्ट का इस्तेमाल करें: "डेटाबेस स्कीमा के बारे में रिसर्च करो और प्रोजेक्ट के कॉन्टेक्स्ट को अपडेट करो" या "नए टूल की परिभाषाओं के साथ प्रोजेक्ट के कॉन्टेक्स्ट को अपडेट करो." हर अनुरोध से, मौजूदा दस्तावेज़ में जानकारी जुड़ती है.

प्रोजेक्ट का कॉन्स्टिट्यूशन सेट करना

एसडीडी के वर्कफ़्लो, प्लानिंग और विश्लेषण के दौरान .specify/memory/constitution.md पर मौजूद प्रोजेक्ट कॉन्स्टिट्यूशन का रेफ़रंस देते हैं. /speckit.plan वर्कफ़्लो, इसके ख़िलाफ़ "कॉन्स्टिट्यूशन चेक" चलाता है. साथ ही, /speckit.analyze उल्लंघन को गंभीर के तौर पर फ़्लैग करता है. अगर संविधान को प्लेसहोल्डर टोकन वाले खाली टेंप्लेट के तौर पर छोड़ दिया जाता है, तो इन जांचों के लिए पुष्टि करने के लिए कुछ भी नहीं होता. इसलिए, प्लान और विश्लेषण बिना किसी सुरक्षा घेरे के चलते हैं.

संविधान में, प्रोजेक्ट के ऐसे सिद्धांतों के बारे में बताया गया है जिन पर समझौता नहीं किया जा सकता. यह एक छोटी रिपो है, जिसे एक ही डेवलपर मैनेज करता है. इसलिए, कॉन्स्टिट्यूशन में इस स्कोप को शामिल किया जाना चाहिए. चीज़ों को आसान और एक जैसा रखें. साथ ही, ज़्यादा इंजीनियरिंग से बचें.

Antigravity के Agent Manager में, नई बातचीत शुरू करें. संविधान से जुड़े वर्कफ़्लो को चलाएं:

/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, संविधान के टेंप्लेट में सिद्धांतों को शामिल करता है. साथ ही, इसे वर्शन (1.0.0) असाइन करता है. इसके बाद, SDD टेंप्लेट में एक जैसा कॉन्टेंट होने की जांच करता है.

.specify/memory/constitution.md पर जाकर, जनरेट किए गए संविधान की समीक्षा करें. पुष्टि करें कि तीनों सिद्धांत मौजूद हैं और उन्हें साफ़ तौर पर बताया गया है.

ध्यान दें: संविधान में सिर्फ़ तीन सिद्धांत शामिल किए गए हैं, ताकि अकेले काम करने वाले डेवलपर के लिए इसे समझना आसान हो. /speckit.constitution वर्कफ़्लो में, धीरे-धीरे बदलाव करने की सुविधा उपलब्ध है. इसे अतिरिक्त सिद्धांतों के साथ फिर से चलाएं. यह वर्शनिंग को अपने-आप मैनेज करता है. टीम प्रोजेक्ट के लिए, कोड की समीक्षा, टेस्टिंग के तरीके, निगरानी, और एपीआई वर्शनिंग के सिद्धांत जोड़े जाते हैं.

चेकपॉइंट: .agents/rules/project-context.md में रिपॉज़िटरी के बारे में पूरी जानकारी मौजूद होती है. .agents/skills/repo-research/SKILL.md में, YAML फ़्रंटमैटर, निर्देशों, और टकराव को हल करने की सुविधा का इस्तेमाल करके, स्किल बनाने का तरीका दिखाया गया है. .specify/memory/constitution.md में प्रोजेक्ट के तीन सिद्धांत शामिल हैं. प्लान और विश्लेषण के वर्कफ़्लो, इनकी पुष्टि करते हैं. आपको कॉन्टेक्स्ट के तीन लेवल वाली हैरारकी के बारे में पता हो: नियम (हमेशा चालू रहने वाले), स्किल (मांग पर उपलब्ध), वर्कफ़्लो (स्लैश कमांड).

6. SDD Cycle — Add Reservation Feature

इस चरण में, एसडीडी का पूरा साइकल बताया गया है. इससे रेस्टोरेंट के कंसीयर्ज एजेंट को रिज़र्वेशन बुकिंग की सुविधा जोड़ने में मदद मिलेगी. आपको हर फ़ेज़ में एंटीग्रैविटी का इस्तेमाल करना होगा. जैसे, जानकारी देना, साफ़ तौर पर बताना, प्लान बनाना, टास्क, विश्लेषण करना, और लागू करना. साथ ही, यह देखना होगा कि हर आर्टफ़ैक्ट, पिछले आर्टफ़ैक्ट पर कैसे काम करता है. यह कोडलैब का मुख्य लर्निंग एक्सपीरियंस है.

अहम जानकारी! Antigravity एक एआई असिस्टेंट है. इसके जनरेट किए गए आर्टफ़ैक्ट (स्पेसिफ़िकेशन, प्लान, टास्क, कोड) इस ट्यूटोरियल में बताए गए आर्टफ़ैक्ट से अलग हो सकते हैं. फ़ाइल के नाम, सटीक एसक्यूएल स्कीमा, और कोड स्ट्रक्चर अलग-अलग हो सकते हैं. ऐसा होना सामान्य है. यह एआई की मदद से डेवलपमेंट करने की प्रोसेस का हिस्सा है. एसडीडी वर्कफ़्लो यह पक्का करता है कि हर आर्टफ़ैक्ट की समीक्षा कोड बनने से पहले ही कर ली जाए. इसलिए, अपनी समझ के हिसाब से फ़ैसला लें और ऐसे किसी भी आउटपुट को स्वीकार करें, उसमें बदलाव करें या उसे फिर से जनरेट करें जो आपकी उम्मीदों के मुताबिक न हो.

सुविधा के बारे में बताएं

Antigravity के Agent Manager में, नई बातचीत शुरू करें. सुविधा की जानकारी के साथ /speckit.specify वर्कफ़्लो कमांड टाइप करें:

/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, फ़ीचर ब्रांच बनाता है, स्पेसिफ़िकेशन दस्तावेज़ जनरेट करता है, और क्वालिटी की पुष्टि करता है. अगर Antigravity, जवाब को बेहतर बनाने के लिए सवाल पूछता है, तो ऊपर दी गई सुविधा के ब्यौरे के आधार पर उनके जवाब दो.

ध्यान दें: स्पेसिफ़िकेशन पूरा करने के बाद, Antigravity आपको "तकनीकी प्लान बनाएं" या "स्पेसिफ़िकेशन की ज़रूरी शर्तों के बारे में ज़्यादा जानकारी दें" जैसे हैंडऑफ़ दिखा सकता है. ये अगले वर्कफ़्लो फ़ेज़ (/speckit.plan या /speckit.clarify) के लिए क्यू हैं

स्पेसिफ़िकेशन में इस बात पर फ़ोकस किया जाता है कि क्या और क्यों करना है, न कि कैसे करना है. इसमें उपयोगकर्ता अनुभव के बारे में बताया गया है ("मेहमान अपना नाम, पार्टी में शामिल लोगों की संख्या, तारीख, और समय की जानकारी देकर बुकिंग कर सकते हैं"). इसमें एसक्यूएल टेबल, tools.yaml या एडीके एपीआई के बारे में नहीं बताया गया है. लागू करने से जुड़ी जानकारी, प्लानिंग के चरण में मिलती है.

specs/<branch-name>/spec.md पर जनरेट की गई खास बातों की समीक्षा करें. पुष्टि करें कि इसमें फ़ंक्शन से जुड़ी ज़रूरी शर्तें और सफलता के मानदंड शामिल हों.

स्पेसिफ़िकेशन के बारे में ज़्यादा जानकारी दें (ज़रूरी नहीं)

स्पेसिफ़िकेशन में कम जानकारी वाली जगहों का पता लगाने और उन्हें ठीक करने के लिए, जानकारी को बेहतर बनाने वाला वर्कफ़्लो चलाएं:

/speckit.clarify

Antigravity, स्पेसिफ़िकेशन को स्कैन करता है. इससे अस्पष्टताओं, ज़रूरी शर्तों के बारे में जानकारी न होने, और कम जानकारी वाली ज़रूरी शर्तों का पता चलता है. यह जवाब को बेहतर बनाने के लिए सवाल पूछता है. हर सवाल का जवाब, कुछ शब्दों या वाक्यांशों में दिया जा सकता है. आपके जवाबों को सीधे तौर पर स्पेसिफ़िकेशन में कोड किया जाता है. इससे प्लान बनाने से पहले ही, स्पेसिफ़िकेशन ज़्यादा सटीक हो जाता है.

अहम जानकारी: जवाब को बेहतर बनाने के लिए, जानकारी देने वाला चरण ज़रूरी नहीं है. हालांकि, जटिल सुविधाओं के लिए इसका सुझाव दिया जाता है. अगर आपको सीधे तौर पर स्पेसिफ़िकेशन के बारे में जानकारी है, तो सीधे प्लानिंग पर जाएं.

लागू करने का प्लान बनाना

प्लानिंग वर्कफ़्लो चलाएं:

/speckit.plan

Antigravity, दो चरणों में तकनीकी प्लान जनरेट करता है:

1. रिसर्च फ़ेज़ — इसमें मौजूदा कोडबेस के बारे में जानकारी मिलती है और research.md जनरेट होता है
2. डिज़ाइन फ़ेज़ — data-model.md (रिज़र्वेशन की इकाई की परिभाषा) बनाता है और project-context.md को अपडेट करता है

Antigravity को प्लानिंग के दौरान, adk-agent-development स्किल का इस्तेमाल करना चाहिए. मुख्य आर्टफ़ैक्ट की समीक्षा करें:

• specs/<branch-name>/plan.md — तकनीकी तरीका: किन फ़ाइलों में बदलाव करना है, किन पैटर्न का पालन करना है
• specs/<branch-name>/data-model.md — बुकिंग की इकाई की परिभाषा (कॉलम, टाइप, संबंध)
• specs/<branch-name>/research.md — लिए गए फ़ैसले और उनकी वजह

टास्क जनरेट करना

टास्क वर्कफ़्लो को रन करना

/speckit.tasks

Antigravity, प्लान को specs/<branch-name>/tasks.md में क्रम से लगाई गई टास्क की सूची में बदल देता है. टास्क, आईडी, प्राथमिकता मार्कर, और फ़ाइल पाथ के साथ चेकलिस्ट फ़ॉर्मैट का पालन करते हैं. उदाहरण के लिए:

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

टास्क को इन फ़ेज़ में बांटा गया है: सेटअप → बुनियादी → उपयोगकर्ता की कहानियां → बेहतर बनाएं. टास्क की सूची को स्कैन करके देखें कि क्या बनाया जाएगा और क्या बदला जाएगा.

टास्क का विश्लेषण करना (ज़रूरी नहीं)

जोखिमों और कमियों का पता लगाने के लिए, टास्क की समीक्षा करने के लिए विश्लेषण वाला वर्कफ़्लो चलाएं:

/speckit.analyze

Antigravity, टास्क की सूची की तुलना स्पेसिफ़िकेशन और प्लान से करता है. इससे, उसे ऐसे टास्क का पता चलता है जो सूची में शामिल नहीं हैं, ऐसे टास्क जो एक-दूसरे से टकरा सकते हैं या स्पेसिफ़िकेशन की ज़रूरी शर्तों और प्लान किए गए काम के बीच के अंतर का पता चलता है. लागू करने से पहले, गंभीर समस्याओं को ठीक करें.

अहम जानकारी: विश्लेषण करने का चरण तब सबसे ज़्यादा फ़ायदेमंद होता है, जब टास्क की सूची लंबी हो या सुविधा कई सबसिस्टम को प्रभावित करती हो. रिज़र्वेशन बुक करने जैसी सुविधाओं के लिए, तुरंत स्कैन करना काफ़ी होता है.

7. लागू करें

लागू करने का वर्कफ़्लो चलाएं:

/speckit.implement

Antigravity, लागू करने का आखिरी प्लान और टास्क आर्टफ़ैक्ट पेश करता है. आगे बढ़ने के लिए, इसकी समीक्षा करें और इसे स्वीकार करें

अहम जानकारी: इस पर सीधे टिप्पणी की जा सकती है! ऐसा सिर्फ़ Antigravity में पहले से मौजूद आर्टफ़ैक्ट की मदद से किया जा सकता है

Antigravity, टास्क पूरे करता है और हर टास्क पूरा होने पर उस पर सही का निशान लगाता है. यह प्रोसेस पूरी होने के बाद, आपको सिलसिलेवार तरीके से पूरी जानकारी दिखेगी

कोड में किए गए बदलावों को टेस्ट करना

लागू करने की प्रोसेस पूरी होने के बाद, पुष्टि करें कि मुख्य बदलाव किए गए हैं. फ़ाइल के नाम और कॉन्टेंट में अंतर हो सकता है. हालांकि, ये पैटर्न tools.yaml और agent.py में मौजूद होने चाहिए:

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

आपको इस तरह का कुछ आउटपुट दिखेगा

...
get_reservations_by_name:
      Retrieve all reservations for a guest by their name. Uses case-insensitive
      SELECT id, guest_name, party_size, reservation_datetime, special_requests, created_at
      FROM reservations
      ORDER BY reservation_datetime DESC
...

और agent.py के लिए

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

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

आपको इस तरह के बदलाव दिख सकते हैं

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

ध्यान दें: अगर grep दोनों फ़ाइलों के लिए कोई भी मैच नहीं दिखाता है, तो हो सकता है कि लागू करने के लिए अलग-अलग नाम इस्तेमाल किए गए हों. बदलावों का पूरा सेट देखने के लिए, git diff देखें. साथ ही, पुष्टि करें कि बुकिंग से जुड़ा लॉजिक जोड़ा गया है.

बदलावों का असर सीड डेटाबेस स्क्रिप्ट पर पड़ना चाहिए. आइए, इसे लागू करने की कोशिश करते हैं

source .env
uv run python scripts/seed_db.py

अगर reservations टेबल पहले से मौजूद नहीं है, तो अपडेट की गई स्क्रिप्ट को इसे बनाना चाहिए. आपको आउटपुट में यह पुष्टि दिखेगी कि नई टेबल बना दी गई है. साथ ही, मौजूदा menu_items डेटा को सुरक्षित रखा गया है.

ध्यान दें: Antigravity ने माइग्रेशन के लिए एक अलग स्क्रिप्ट बनाई हो सकती है. जैसे, scripts/create_reservations.py) को अपडेट करने के बजाय seed_db.py को अपडेट करें. git diff --name-only में नई स्क्रिप्ट देखें और उन्हें चलाएं.scripts/

अगर यहां तक सब कुछ ठीक रहता है, तो हम ADK एजेंट के Dev UI पर इस सुविधा की जांच कर सकते हैं. tools.yaml में टूल की नई परिभाषाओं को चुनने के लिए, टूलबॉक्स को रीस्टार्ट करें. Toolbox की किसी भी मौजूदा प्रोसेस को बंद करें. इसके बाद, नई प्रोसेस शुरू करें:

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

ADK के डेवलपर यूज़र इंटरफ़ेस (यूआई) को शुरू करें:

uv run adk web .

अपने ब्राउज़र में http://localhost:8000 खोलें और इन प्रॉम्प्ट का इस्तेमाल करके टेस्ट करें:

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

जांच करना: एजेंट को बुकिंग की जानकारी की पुष्टि करनी चाहिए और उसे बनाना चाहिए

Do I have any upcoming reservations?

जांच करें: एजेंट को वह बुकिंग दिखानी चाहिए जो आपने अभी की है

अब Ctrl+C को दो बार दबाकर, ADK के डेवलपर यूज़र इंटरफ़ेस (यूआई) को बंद करें.

चेकपॉइंट: एजेंट, बुकिंग और बुकिंग की जानकारी को मैनेज करता है. आपने एसडीडी का पूरा साइकल पूरा कर लिया है: जानकारी देना → साफ़ तौर पर बताना → प्लान बनाना → टास्क → विश्लेषण करना → लागू करना → टेस्ट करना. हर चरण में, specs/<branch-name>/ में वर्शन वाला आर्टफ़ैक्ट जनरेट होता है.

8. चैलेंज (ज़रूरी नहीं)

अब आपको एसडीडी का पूरा वर्कफ़्लो पता चल गया है. इसे आज़माएं:

• रेस्टोरेंट के कंसीयर्ज के लिए वेब चैट इंटरफ़ेस बनाने के लिए, दूसरा एसडीडी साइकल चलाओ. इस बार, चरण-दर-चरण निर्देशों के बिना.
• प्रोडक्शन के लिए, अपने एजेंट को Cloud Run पर डिप्लॉय करना

संकेत

• प्रोजेक्ट में कोई फ़्रंटएंड फ़्रेमवर्क नहीं है. Antigravity को वैनिला एचटीएमएल/सीएसएस/जेएस का सुझाव देना चाहिए. अगर यह React या इसी तरह के किसी अन्य टूल का सुझाव देता है, तो इसे आसान बनाने के लिए कहें. (आपके संविधान के "इसे आसान रखें" सिद्धांत के तहत, इस बात का ध्यान रखा जाना चाहिए).
• ADK सर्वर, स्ट्रीमिंग के लिए /run_sse और सेशन मैनेजमेंट के लिए /apps/{app_name}/users/{user_id}/sessions को दिखाता है. Antigravity, इन्हें प्रोजेक्ट के कॉन्टेक्स्ट से खोजता है.
• लागू करने के बाद, सर्वर को uv run uvicorn server:app --host 0.0.0.0 --port 8080 (adk web नहीं) से शुरू करें, ताकि स्टैटिक फ़ाइल माउंट हो सके.
• http://localhost:8080/static/index.html पर टेस्ट करें.
• रेफ़रंस कोडलैब में, ADK एजेंट को डिप्लॉय करने और बनाए रखने का तरीका पहले से ही बताया गया है. Antigravity को इसके रेफ़रंस दें!

9. बधाई हो!

आपने रेस्टोरेंट के कंसीयर्ज एडीएम एजेंट को बुकिंग की सुविधा दी है. यह पूरी तरह से Antigravity के SDD वर्कफ़्लो के ज़रिए किया गया है. इसमें, ऐप्लिकेशन कोड को मैन्युअल तरीके से नहीं लिखा गया है.

आपने क्या बनाया

• रेस्टोरेंट के लिए कॉन्सियर्ज एआईडीके एजेंट, जिसमें मेन्यू खोजने, सिमैंटिक सर्च करने, खाने-पीने की पसंद को ट्रैक करने, और बुकिंग करने की सुविधा हो
• Antigravity की एक ऐसी स्किल जो रिपो रिसर्च के लिए प्रोजेक्ट कॉन्टेक्स्ट दस्तावेज़ जनरेट करती है और उसे बनाए रखती है
• प्रोजेक्ट का ऐसा कॉन्स्टिट्यूशन जो प्लानिंग और विश्लेषण के दौरान, ऐसे सिद्धांतों को लागू करता है जिन पर समझौता नहीं किया जा सकता
• एसडीडी का पूरा साइकल, जिसमें यह दिखाया गया है कि जानकारी देने → साफ़ तौर पर बताने → प्लान बनाने → टास्क तय करने → विश्लेषण करने → लागू करने का वर्कफ़्लो कैसे काम करता है

आपने क्या सीखा

• Antigravity में, स्पेसिफ़िकेशन के आधार पर डेवलपमेंट के वर्कफ़्लो का इस्तेमाल करके, मौजूदा कोडबेस में सिस्टमैटिक तरीके से सुविधाएं जोड़ने का तरीका
• ऐसी एंटीग्रैविटी स्किल बनाने का तरीका जो डोमेन की जानकारी को पैकेज करती हैं, ताकि बातचीत के दौरान उनका दोबारा इस्तेमाल किया जा सके
• प्रोजेक्ट के कॉन्टेक्स्ट को बूटस्ट्रैप करने का तरीका, ताकि Antigravity आर्किटेक्चर, पैटर्न, और टेक्नोलॉजी के विकल्पों के बारे में सोच-समझकर फ़ैसले ले सके
• प्रोजेक्ट का कॉन्स्टिट्यूशन सेट करने का तरीका, जिसके आधार पर एसडीडी वर्कफ़्लो की पुष्टि की जाती है
• MCP टूलबॉक्स की मदद से, डेटाबेस पर आधारित नए टूल का इस्तेमाल करके, ADK एजेंट को कैसे बढ़ाया जा सकता है

व्यवस्थित करें

स्थानीय तौर पर चल रही सभी प्रोसेस बंद करें (टूलबॉक्स):

pkill -f toolbox 2>/dev/null

लगातार लगने वाले शुल्क से बचने के लिए, Cloud SQL इंस्टेंस मिटाएं:

gcloud sql instances delete restaurant-db --quiet

इसके अलावा, पूरा प्रोजेक्ट मिटाने का विकल्प भी है:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

अहम जानकारी: इस मिटाने की कार्रवाई को कुछ समय के लिए वापस लाया जा सकता है. इसके लिए, इस कमांड का इस्तेमाल करें gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}