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

1. परिचय

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

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

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

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

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

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

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

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

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

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

अहम जानकारी:

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

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

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

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

पक्का करें कि आपके सिस्टम में, नीचे दी गई CLI एक्ज़ीक्यूटेबल मौजूद हो:

• git
• gcloud
• uv
• npm

आपके कंप्यूटर के ऑपरेटिंग सिस्टम के हिसाब से, इंस्टॉल करने के निर्देश अलग-अलग होते हैं.

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

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 remote remove origin

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

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 फ़ाइल में, अपने प्रोजेक्ट का नाम GOOGLE_CLOUD_PROJECT वैरिएबल के तौर पर जोड़ें

टर्मिनल में अपने प्रोजेक्ट को चालू करने के लिए, gcloud config set project your-project-id का इस्तेमाल करें

इसके बाद, सीधे एपीआई चालू करने के सेक्शन पर जाएं

अगर आपको इसके बारे में पक्के तौर पर नहीं पता है, तो नीचे दिया गया सेक्शन पढ़ें

प्रोजेक्ट सेटअप स्क्रिप्ट डाउनलोड करें और उसे चलाएं. यह फ़ंक्शन, बिना किसी शुल्क के आज़माने की सुविधा के साथ 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

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

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

हम 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

डेटाबेस इंफ़्रास्ट्रक्चर और डेटा तैयार करना

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

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

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

इसके बाद, ज़रूरी इंफ़्रास्ट्रक्चर तैयार करने के लिए, scripts/setup_database.sh स्क्रिप्ट चलाएं. इससे ये काम होंगे:

• Cloud SQL इंस्टेंस बनाना
• देखें कि इंस्टेंस तैयार है या नहीं
• Vertex AI को अनुमतियां देना
• डेटाबेस बनाना
• सीड डेटाबेस
• एमसीपी टूलबॉक्स सेवा को बैकग्राउंड में चलाने की अनुमति

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

इस कमांड से सेटअप बैकग्राउंड में चलेगा. database_setup.log फ़ाइल में जाकर, समय-समय पर आउटपुट देखा जा सकता है

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

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

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

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

• restaurant_concierge/agent.py — यह कोर एजेंट होता है. एक LlmAgent जो एमसीपी टूलबॉक्स के डेटाबेस टूल को ToolContext पर आधारित डाइट से जुड़ी प्राथमिकताओं को ट्रैक करने की सुविधा के साथ जोड़ता है. एजेंट, टूलबॉक्स सर्वर से सभी टूल लोड करता है. साथ ही, दो Python फ़ंक्शन (save_dietary_preference, get_dietary_preferences) जोड़ता है, जो ToolContext का इस्तेमाल करके स्थिति को मैनेज करते हैं.
• tools.yaml — एमसीपी टूलबॉक्स टूल की परिभाषाएं. मेन्यू में खोज के लिए तीन टूल तय किए गए हैं: कीवर्ड खोज (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/mcp-toolbox-postgres/SKILL.md — यह एक ऐसी स्किल है जो Antigravity को यह बताती है कि एमसीपी टूलबॉक्स के लिए, सही tools.yaml कॉन्फ़िगरेशन कैसे बनाया जाए. इस स्किल में, sources, tools , और embeddingModels के कॉन्फ़िगरेशन के बारे में बताया जाएगा. इनकी मदद से, सही RAG पाइपलाइन बनाई जा सकती है. यह स्किल तब तक चालू नहीं होगी, जब तक Antigravity के लिए सही YAML फ़्रंटमैटर नहीं जोड़ा जाता
• .agents/skills/repo-research/SKILL.md — यह एक ऐसी स्किल है जो Antigravity को, किसी रिपॉज़िटरी का धीरे-धीरे विश्लेषण करने और स्ट्रक्चर्ड प्रोजेक्ट कॉन्टेक्स्ट दस्तावेज़ बनाने का तरीका सिखाती है. यह चार चरणों वाली प्रोसेस का इस्तेमाल करता है: सिर्फ़ डायरेक्ट्री ट्री को स्कैन करना, कॉन्फ़िगरेशन और मेटाडेटा फ़ाइलें, एंट्री पॉइंट और डेटा मॉडल, और फिर टारगेट किए गए डीप डाइव — हर चरण के बाद, अगले चरण पर जाने से पहले, नतीजे सेव किए जाते हैं. जब तक YAML फ़्रंटमैटर नहीं जोड़ा जाता, तब तक यह सुविधा भी काम नहीं करती. चालू होने के बाद, इसे कॉल करके .agents/rules/project-context.md जनरेट करें. यह एक ऐसा दस्तावेज़ है जिसमें आर्किटेक्चर, रनटाइम डिपेंडेंसी, एपीआई सर्फ़ेस, और डोमेन की शब्दावली शामिल होती है.

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

एआई कोडिंग असिस्टेंट की मदद से, प्रॉम्प्ट से कोड आसानी से जनरेट किया जा सकता है. इसमें यह जोखिम होता है: आपने किसी सुविधा के बारे में एक वाक्य में बताया, 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 के साथ इंटिग्रेट करने के लिए, ओरिजनल spec-kit प्रॉम्प्ट में बदलाव करते हैंimplement

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

एडिटर में .agents/skills/mcp-toolbox-postgres/SKILL.md खोलें. सबसे ऊपर मौजूद TODO(codelab) वाली कॉमेंट लाइनों को इस फ़्रंटमैटर से बदलें:

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

ध्यान दें: MCP टूलबॉक्स Postgres स्किल में sources, tools, और embedding models के लिए सही कॉन्फ़िगरेशन शामिल है

एडिटर में .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/mcp-toolbox-postgres/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

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

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

सार्वजनिक तौर पर उपलब्ध स्किल इंस्टॉल करना

ADK चीटशीट की मदद से जुड़ी स्किल

हमने पहले, उन स्किल की जांच की थी जिन्हें हमने खुद बनाया था ( repo-research और mcp-toolbox-postgres स्किल). हालांकि, ऐसी कई अन्य स्किल हैं जो हमारे सॉफ़्टवेयर डेवलपमेंट के लिए फ़ायदेमंद हैं. इन्हें हमारे कोडिंग एजेंट में आसानी से इंस्टॉल किया जा सकता है. उदाहरण के लिए, इस ट्यूटोरियल में हमें ADK के साथ इंटरैक्ट करना होगा. इसलिए, हमें ADK का इस्तेमाल करके ऐप्लिकेशन बनाने के बारे में पूरी जानकारी होनी चाहिए. आइए, इस निर्देश का इस्तेमाल करके ADK के दस्तावेज़ से जुड़ी स्किल इंस्टॉल करें

npx skills add google/adk-docs

इसके बाद, आपको इंस्टॉलेशन की पुष्टि करने के लिए कहा जाएगा. यह पुष्टि इस तरह की जाएगी

अगले प्रॉम्प्ट पर जाने के लिए, y दबाएं. इसमें आपको यह चुनने का विकल्प मिलेगा कि आपको कौनसी स्किल इंस्टॉल करनी हैं. जैसे, यहां दिखाया गया है. अभी के लिए, सिर्फ़ adk-cheatsheet (चुनने के लिए स्पेस दबाएं, फिर पुष्टि करने के लिए Enter दबाएं) को चुनें

इसके बाद, डिफ़ॉल्ट रूप से इंस्टॉल करने और अपने मौजूदा प्रोजेक्ट में स्किल इंस्टॉल करने के लिए, किसी अन्य विकल्प पर Enter पर क्लिक करें

आपको दिखेगा कि .agents/skills डायरेक्ट्री में नई ADK स्किल जोड़ी गई है. यह adk-cheatsheet है

केवमैन स्किल्स

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

npx skills add JuliusBrussee/caveman

पहले की तरह, फ़िलहाल यहां caveman स्किल को चुनते हैं

इसके बाद, डिफ़ॉल्ट रूप से इंस्टॉल करने और अपने मौजूदा प्रोजेक्ट में स्किल इंस्टॉल करने के लिए, किसी अन्य विकल्प पर Enter पर क्लिक करें

अब हमारे पास चार कौशल कॉन्फ़िगर किए गए हैं और हम एसडीडी की प्रोसेस शुरू करने के लिए तैयार हैं

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

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

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

mkdir -p .agents/rules

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

Research this repository and create a project context document, and communicate efficiently

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

प्रोसेस पूरी होने के बाद, एडिटर में .agents/rules/project-context.md खोलें. इसमें प्रोजेक्ट के बारे में पूरी जानकारी दी गई है: टेक्नोलॉजी स्टैक (Python 3.12, ADK, MCP Toolbox, 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 में प्रोजेक्ट के तीन सिद्धांत शामिल हैं. प्लान और विश्लेषण के वर्कफ़्लो, इनकी पुष्टि करते हैं. आपको कॉन्टेक्स्ट के तीन लेवल वाली हैरारकी के बारे में पता हो: नियम (हमेशा चालू रहने वाले), स्किल (मांग पर उपलब्ध), वर्कफ़्लो (स्लैश कमांड).

5. 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 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, दो चरणों में तकनीकी प्लान जनरेट करता है:

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, टास्क की सूची की जांच स्पेसिफ़िकेशन और प्लान के हिसाब से करता है. इसमें, यह देखा जाता है कि कोई टास्क छूट तो नहीं गया है, कोई टास्क टकराव तो नहीं कर रहा है या स्पेसिफ़िकेशन की ज़रूरी शर्तों और प्लान किए गए काम के बीच कोई अंतर तो नहीं है. लागू करने से पहले, गंभीर समस्याओं को ठीक करें.

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

6. लागू करें

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

/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 देखें. साथ ही, पुष्टि करें कि बुकिंग से जुड़ा लॉजिक जोड़ा गया है.

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

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

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

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

database_setup.log में आउटपुट लॉग देखा जा सकता है. इससे यह पता चलता है कि Antigravity सही कोड और कॉन्फ़िगरेशन जनरेट करता है या नहीं. अगर आपको कोई गड़बड़ी मिलती है, तो उसे ठीक करने के लिए एजेंट से संपर्क करें

अगर सब कुछ ठीक रहता है, तो हम ADK dev UI शुरू कर सकते हैं:

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>/ में वर्शन वाला आर्टफ़ैक्ट जनरेट होता है.

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

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

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

संकेत

• इस प्रोजेक्ट में कोई फ़्रंटएंड फ़्रेमवर्क नहीं है. Antigravity को सामान्य एचटीएमएल/सीएसएस/जेएस का सुझाव देना चाहिए. अगर यह React या इसी तरह के किसी अन्य टूल का सुझाव देता है, तो इसे आसान टूल का सुझाव देने के लिए कहें. (आपके संविधान के "इसे आसान रखें" सिद्धांत के तहत, इस बात का ध्यान रखा जाना चाहिए).
• एडीके सर्वर, स्ट्रीमिंग के लिए /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 को इसके रेफ़रंस दें!

8. बधाई हो!

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

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

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

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

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

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

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

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} का इस्तेमाल करके, मिटाने की इस कार्रवाई को कुछ समय के लिए पहले जैसा किया जा सकता है