توسعه مبتنی بر مشخصات با Antigravity CLI - گردش‌های کاری ساختاریافته عامل‌ها با مهارت‌ها و MCP

۱. مقدمه

کدنویسی Vibe-code برای یک MVP سریع است - اما اضافه کردن ویژگی‌ها به آن با ارائه پیشنهادات بیشتر، دلیل شکست پروژه‌ها است. شما به روشی نیاز دارید تا ساختار و زمینه دنیای واقعی را به توسعه مبتنی بر هوش مصنوعی وارد کنید. اینجاست که Antigravity CLI وارد می‌شود - یک عامل کدنویسی هوش مصنوعی که در ترمینال شما اجرا می‌شود. این عامل به خودی خود می‌تواند پایه کد شما را درک کند، دستورات را اجرا کند و فایل‌ها را ویرایش کند. قدرت واقعی آن از آنچه به آن وصل می‌کنید ناشی می‌شود:

  • مهارت‌ها به عامل، روش‌شناسی و دانش دامنه می‌دهند - مهارت روش‌شناسی، گردش‌های کاری توسعه ساختاریافته را تقویت می‌کند، در حالی که مهارت دامنه، دانش دقیق API را فراهم می‌کند تا عامل دچار توهم نشود.
  • سرورهای MCP به عامل، اتصالات زنده با سیستم‌های خارجی می‌دهند - به آن اجازه می‌دهند طرحواره‌های واقعی را بررسی کند، پرس‌وجوها را اجرا کند و کار خود را در برابر داده‌های واقعی اعتبارسنجی کند، به جای اینکه به دانش آموزشی قدیمی تکیه کند.

مهارت‌ها نحوه تفکر عامل را شکل می‌دهند؛ MCP آنچه را که عامل می‌تواند ببیند و با آن تعامل داشته باشد، شکل می‌دهد. این دو با هم، یک عامل کدنویسی همه منظوره را به عاملی تبدیل می‌کنند که از یک گردش کار ساختاریافته مبتنی بر داده‌های دنیای واقعی پیروی می‌کند. این آزمایشگاه کدنویسی شما را در این ترکیب، از نصب افزونه‌ها گرفته تا ارائه یک ویژگی، همراهی می‌کند.

آنچه خواهید ساخت

الگوهای موجود در این آزمایشگاه کد - نصب مهارت‌های لازم برای روش‌شناسی و دانش دامنه، اتصال سرورهای MCP برای دسترسی به داده‌های زنده و اجرای یک چرخه توسعه مبتنی بر مشخصات - صرف نظر از زبان، چارچوب یا محصولات Google Cloud، برای هر ویژگی که با Antigravity CLI می‌سازید، اعمال می‌شوند. برای ملموس کردن این الگوها، شما یک مثال خاص را بررسی می‌کنید: اضافه کردن ادغام BigQuery به داشبورد تحلیلی تجارت الکترونیک.

برنامه‌ی اولیه یک برنامه‌ی وب FastAPI است که داده‌های فروش را از فایل‌های CSV استاتیک می‌خواند و نمودارها (روند درآمد، محصولات برتر، تفکیک وضعیت سفارش، عملکرد دسته‌بندی) را رندر می‌کند. در پایان، برنامه داده‌های زنده را از BigQuery - انبار داده‌ی بدون سرور Google Cloud - که به شما امکان می‌دهد کوئری‌های SQL را روی مجموعه داده‌های بزرگ بدون مدیریت زیرساخت اجرا کنید، جستجو می‌کند. به طور خاص، شما به مجموعه داده‌ی thelook_ecommerce متصل می‌شوید و کاتالوگ کامل سفارشات، محصولات و مشتریانی را که یک CSV با ۵۰۰ ردیف نمی‌تواند ارائه دهد، باز می‌کنید. شما این ویژگی را کاملاً از طریق Antigravity CLI، با راهنمایی مهارت‌ها و MCP، می‌سازید.

5acdeb09cd9d5960.png

پیکربندی عاملی که ما با Antigravity CLI استفاده خواهیم کرد، به این شکل خواهد بود.

5e3dd8629e65e6ce.png

آنچه یاد خواهید گرفت

  • نحوه استفاده از Antigravity CLI در Cloud Shell - راه‌اندازی، پیمایش TUI و اجرای دستورات اسلش
  • مهارت‌های عامل چیست و چگونه الگوی افشای تدریجی (فراداده → دستورالعمل‌ها → منابع) زمینه را کارآمد نگه می‌دارد
  • سه دسته مهارت: روش‌شناسی (ابرقدرت‌ها)، کارایی (غارنشین) و دانش تخصصی (گوگل/مهارت‌ها)
  • MCP چیست و چگونه یک سرور MCP از راه دور (BigQuery MCP) را برای Antigravity CLI پیکربندی کنیم؟
  • نحوه اجرای یک چرخه توسعه مبتنی بر مشخصات: مشخص کردن → برنامه ریزی → پیاده سازی
  • (اختیاری) نحوه عملکرد زیر-عامل‌ها در Antigravity CLI و نحوه مدیریت آنها
  • نحوه ادغام کتابخانه کلاینت پایتون google-cloud-bigquery در یک برنامه FastAPI
  • (اختیاری) نحوه استقرار برنامه در Cloud Run با استفاده از Antigravity CLI با مهارت دامنه

پیش‌نیازها

  • یک حساب کاربری گوگل کلود
  • آشنایی اولیه با پایتون، API های REST و دستورات ترمینال

۲. محیط خود را آماده کنید

این مرحله مخزن اولیه را کلون می‌کند، پروژه Google Cloud شما را پیکربندی می‌کند و APIهای مورد نیاز شما را فعال می‌کند.

پوسته ابری را باز کنید

Cloud Shell را در مرورگر خود باز کنید. Cloud Shell یک محیط از پیش پیکربندی شده با تمام ابزارهای مورد نیاز برای این آزمایشگاه کد را فراهم می‌کند. در صورت درخواست، روی تأیید (Authorize) کلیک کنید.

سپس روی « مشاهده » -> « ترمینال » کلیک کنید تا ترمینال باز شود. رابط کاربری شما باید شبیه به این باشد.

۸۶۳۰۷fac5da2f077.png

این رابط اصلی ما خواهد بود، IDE در بالا، ترمینال در پایین

دایرکتوری کاری خود را تنظیم کنید

مخزن همراه که شامل کد آغازین این codelab است را کلون کنید:

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

این مخزن شامل یک برنامه داشبورد تجارت الکترونیک کامل و کارآمد است که از فایل‌های CSV استاتیک می‌خواند. در طول این آزمایشگاه کد، شما از Antigravity CLI برای اضافه کردن ادغام BigQuery به عنوان یک ویژگی جدید استفاده می‌کنید.

800c260f0be6933c.png

فایل‌ها و دایرکتوری‌های کلیدی:

  • src/main.py — برنامه FastAPI با نقاط پایانی API که داده‌های داشبورد را ارائه می‌دهند
  • src/data_service.py - لایه داده‌ای که با استفاده از pandas از فایل‌های CSV می‌خواند
  • src/templates/dashboard.html — قالب Jinja2 با مصورسازی‌های Chart.js
  • data/ — فایل‌های CSV استاتیک ( orders.csv ، products.csv ، order_items.csv ) که شامل زیرمجموعه کوچکی از داده‌های تجارت الکترونیک هستند

این برنامه یک داشبورد فقط خواندنی و سرراست است: main.py نقاط پایانی API را تعریف می‌کند، data_service.py فایل‌های CSV را می‌خواند و داده‌های ساختاریافته را برمی‌گرداند، و dashboard.html آن داده‌ها را به صورت نمودار رندر می‌کند. ادغام BigQuery که شما می‌سازید، data_service.py را با ماژولی جایگزین می‌کند که به جای خواندن فایل‌های استاتیک، داده‌های زنده را پرس‌وجو می‌کند.

پیکربندی ترمینال

ایجاد پروژه گوگل کلود (اختیاری)

برای ایجاد یک پروژه جدید، می‌توانید این کار را از رابط کاربری Cloud Console با کلیک روی Project Picker در بالا سمت چپ و کلیک روی New Project انجام دهید.

e2411959f960166b.png

یا اگر روش سریع‌تری می‌خواهید، دستور زیر را در ترمینال اجرا کنید

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

این یک پروژه Google Cloud با شناسه پروژه تصادفی ایجاد می‌کند. این دستور شناسه پروژه تولید شده را نمایش می‌دهد - بعداً از آن به عنوان YOUR_PROJECT_ID در پیکربندی استفاده کنید.

فعال کردن ترمینال

حالا باید ترمینال خود را با پروژه گوگل کلود انتخاب شده پیکربندی کنیم. دستور زیر را اجرا کنید تا پروژه‌های موجود خود را فهرست کنید و شناسه پروژه‌ای را که می‌خواهید انتخاب کنید، پیدا کنید.

gcloud projects list

لیستی مانند این نشان داده خواهد شد، شناسه پروژه‌ای را که استفاده خواهید کرد به خاطر بسپارید یا کپی کنید.

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

حالا دستور زیر را اجرا کنید تا یک اسکریپت برای فعال کردن ترمینال ایجاد شود (یا می‌توانید خودتان این فایل را ایجاد کنید)

cloudshell edit configure_terminal.sh

سپس کد زیر را در اسکریپت کپی کنید

#!/bin/bash

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

به جای YOUR_PROJECT_ID ، شناسه پروژه خود را قرار دهید. دستور قبلی، شناسه پروژه را نیز به عنوان یک متغیر محیطی برای استفاده در سراسر codelab صادر می‌کند. پس از آن، فایل را ذخیره و اجرا کنید.

bash configure_terminal.sh

با بررسی متن زرد رنگ کنار دایرکتوری کاری خود در اعلان ترمینال Cloud Shell، مطمئن شوید که پروژه به درستی تنظیم شده است. باید شناسه پروژه شما نمایش داده شود.

8205fa68a1d749d7.png

فعال کردن API های مورد نیاز

در مرحله بعد، ما با BigQuery که مربوط به سناریوی مورد استفاده ما است، تعامل خواهیم داشت. API های Google Cloud مورد نیاز برای این آزمایشگاه کد را فعال کنید:

gcloud services enable bigquery.googleapis.com

این API ما را قادر می‌سازد تا به Bigquery دسترسی پیدا کنیم. حالا بیایید مجموعه داده‌های اولیه خود را برای این سناریوی codelab آماده کنیم.

۳. مجموعه داده BigQuery را تنظیم کنید

سناریو این است: شرکت شما از قبل داده‌های تجارت الکترونیک خود را در BigQuery ذخیره کرده است - سفارشات، محصولات و اقلام سفارش. شما یک برنامه برای نمایش داشبورد داده‌های سفارش توسعه می‌دهید، اما در حال حاضر فقط یک خلاصه کوچک CSV از این داده‌ها را می‌خواند تا بتوانید در ابتدا روی ظاهر برنامه تمرکز کنید. اکنون، می‌خواهید آن را ارتقا دهید تا مستقیماً از BigQuery برای کل مجموعه داده‌ها پرس‌وجو کند.

برای شبیه‌سازی این، شما از TheLook E-commerce استفاده می‌کنید - یک مجموعه داده عمومی تحت مدیریت گوگل با داده‌های تجارت الکترونیک مصنوعی واقع‌گرایانه (بیش از ۱۲۵۰۰۰ سفارش، بیش از ۲۹۰۰۰ محصول). شما جداول مربوطه را در نمونه BigQuery پروژه خود کپی می‌کنید تا به عنوان "داده‌های شرکت شما" عمل کنند.

در Cloud Shell، ما از قبل bq CLI داریم که می‌توانیم از آن برای تعامل مستقیم با BigQuery استفاده کنیم، از این رو می‌توانیم مستقیماً داده‌های خود را آماده کنیم.

یک مجموعه داده در پروژه خود ایجاد کنید:

bq mk --dataset $GOOGLE_CLOUD_PROJECT:thelook_ecommerce

سه جدول از مجموعه داده عمومی را در مجموعه داده جدید خود کپی کنید:

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

تأیید کنید که جداول در مجموعه داده شما هستند:

bq ls $GOOGLE_CLOUD_PROJECT:thelook_ecommerce

شما باید سه جدول را در لیست ببینید: orders ، order_items و products . 

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

برای تأیید دسترسی به داده‌ها، یک کوئری آزمایشی سریع اجرا کنید:

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

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

شما باید تعداد سفارش‌ها را بالای ۱۰۰۰۰۰ ببینید.

۴. اجرای برنامه وب اولیه

قبل از ارتقاء برنامه، بیایید آن را در وضعیت فعلی‌اش اجرا کنیم تا ببینیم داشبورد مبتنی بر CSV چگونه به نظر می‌رسد.

uv یک پکیج سریع پایتون و مدیر پروژه است که با زبان Rust نوشته شده است ( docs ). این codelab از آن برای سرعت و سادگی استفاده می‌کند. اگر از cloudshell برای این آموزش استفاده می‌کنید، از قبل در نمونه نصب شده است. اگر می‌خواهید آن را برای سیستم محلی خود نصب کنید، به این آموزش مراجعه کنید.

وابستگی‌های پروژه را نصب کنید که محیط مجازی را نیز برای شما آماده می‌کند:

uv sync

پس از آن، اگر با پایتون آشنا هستید، به جای اجرای دستور python ، هر دستور را با uv binary اجرا خواهیم کرد. سرور توسعه FastAPI را اجرا کنید:

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

با استفاده از قابلیت پیش‌نمایش وب Cloud Shell، داشبورد را در مرورگر خود باز کنید. روی دکمه پیش‌نمایش وب (آیکون چشم در نوار ابزار Cloud Shell) کلیک کنید و پیش‌نمایش را روی پورت ۸۰۸۰ انتخاب کنید.

53758c68d6505e7a.png

داشبورد چهار پنل نمودار را نمایش می‌دهد:

  • روند درآمد - نمودار خطی که درآمد روزانه را در محدوده تاریخ در داده‌های CSV نشان می‌دهد
  • محصولات برتر بر اساس درآمد - نمودار میله‌ای افقی که محصولات را بر اساس کل فروش رتبه‌بندی می‌کند
  • تفکیک وضعیت سفارش - نموداری دوناتی شکل که توزیع سفارشات تکمیل‌شده، ارسال‌شده، در حال پردازش، لغوشده و مرجوع‌شده را نشان می‌دهد
  • عملکرد دسته‌بندی - نمودار میله‌ای افقی که درآمد را بر اساس دسته‌بندی محصول نشان می‌دهد

به نشان منبع داده: CSV در سربرگ توجه کنید. کارت‌های خلاصه، مجموع‌های محاسبه‌شده از ۵۰۰ سفارش و حدود ۷۵۰ مورد سفارش را نشان می‌دهند - زیرمجموعه کوچکی از مجموعه داده‌های کامل TheLook. محدوده تاریخ به اکتبر-دسامبر ۲۰۲۳ محدود شده است.

این برنامه پایه ماست، حالا آن را ارتقا می‌دهیم تا با کمک Antigravity CLI با BigQuery ادغام شود.

۵. تنظیم رابط خط فرمان آنتی‌گراویتی

این مرحله رابط خط فرمان Antigravity را معرفی می‌کند، رابط کاربری ترمینال را بررسی می‌کند و سه دسته افزونه را برای بهبود گردش کار توسعه ما نصب می‌کند. در طول مسیر، شما یاد می‌گیرید که مهارت‌های عامل و MCP چیست و چگونه قابلیت‌های یک عامل کدنویسی هوش مصنوعی را گسترش می‌دهند.

رابط خط فرمان ضد جاذبه چیست؟

رابط خط فرمان آنتی‌گراویتی (Antigravity CLI) نوعی از عامل کدنویسی هوش مصنوعی گوگل است: آنتی‌گراویتی برای ترمینال. این یک رابط کاربری ترمینال (TUI) سبک وزن است که در زبان Go ساخته شده و به همان رابطی که برنامه دسکتاپ Antigravity 2.0 را تغذیه می‌کند، متصل می‌شود. این رابط، کدبیس شما را می‌خواند، دستورات را اجرا می‌کند، فایل‌ها را ویرایش می‌کند و از طریق MCP به ابزارهای خارجی متصل می‌شود - همه اینها از طریق ترمینال.

اگر برای این آموزش از Cloud Shell استفاده می‌کنید، Antigravity CLI از قبل روی آن نصب شده است. می‌توانید با اجرای دستور زیر آن را بررسی کنید.

agy --help

جزئیات گزینه‌های دستور زیر را نشان می‌دهد. 

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

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

اجرای رابط خط فرمان آنتی‌گراویتی

حالا، اگر برای اولین بار از Antigravity CLI استفاده می‌کنید، باید آن را راه‌اندازی کنیم. در تب ترمینال جدید خود، آن را اجرا کنید.

agy

اگر برای اولین بار آن را اجرا کنید، از شما می‌خواهد که روش احراز هویت را انتخاب کنید.

5606b640b9bed9c3.png

برای این آموزش، بیایید Google OAuth استفاده کنیم، از شما می‌خواهد که یک URL را باز کنید که در آن از شما خواسته می‌شود حساب گوگلی را که برای ورود به سیستم استفاده خواهید کرد، انتخاب کنید.

e42183f1ccc5771a.png

پس از کلیک روی تأیید اعتبار، حساب گوگل خود را انتخاب کرده و Sign In کلیک کنید.

572b1d06151b55fa.png

رشته‌ای برای کپی شدن به شما نشان داده می‌شود، برای کپی کردن آن Copy to Clipboard کلیک کنید.

590d375c71f62a0e.png

سپس آن را مانند تصویر زیر در Antigravity CLI prompt قرار دهید.

a807ff24fbf278b4.png

پس از آن، از شما خواسته می‌شود که یک تم رنگی و توافق‌نامه برای مدت استفاده انتخاب کنید.

3a7cd90438c94f5c.png

همچنین از شما خواسته می‌شود که به دایرکتوری فضای کاری فعلی اعتماد کنید، فقط آن را بپذیرید و ما آماده ادامه هستیم. این ورودی اصلی ما برای تعامل با Antigravity CLI در ترمینال خواهد بود.

9e1e03543e8063c.png

فعلاً، بیایید از رابط خط فرمان Antigravity خارج شویم و به بخش بعدی برویم.

۶. شخصی‌سازی - مهارت‌های عامل

Antigravity CLI به صورت پیش‌فرض می‌تواند کدبیس شما را بخواند، دستورات shell را اجرا کند و فایل‌ها را ویرایش کند - این ابزار یک گردش کار توسعه مبتنی بر مشخصات داخلی محدود دارد و دانش آن از APIهای خاص به داده‌های آموزشی‌اش محدود می‌شود. برای کاری مانند ادغام BigQuery در یک برنامه موجود، دو شکاف وجود دارد:

  1. شکاف فرآیند - بدون ساختار، Antigravity CLI ممکن است مستقیماً به نوشتن کد بپردازد. برای اصلاحات کوچک، این خوب است. برای ویژگی‌ای که چندین فایل و نقطه پایانی را لمس می‌کند، در نهایت با پیاده‌سازی‌های متناقض، موارد حاشیه‌ای از دست رفته و عدم وجود مستندسازی از آنچه تصمیم گرفته شده یا دلیل آن، مواجه خواهید شد.
  2. شکاف دانش — داده‌های آموزشی مدل ممکن است شامل الگوهای منسوخ‌شده‌ی کتابخانه‌ی کلاینت BigQuery، فراخوانی‌های API منسوخ‌شده یا طرحواره‌های جدول نادرست باشد. هیچ راهی برای بررسی ظاهر فعلی مجموعه داده‌ی واقعی وجود ندارد.

مهارت‌ها شکاف فرآیند را پر می‌کنند. یک مهارت روش‌شناسی توسعه مانند superpowers چرخه‌ی مشخص-برنامه‌ریزی-پیاده‌سازی را اجرا می‌کند - عامل تا زمانی که شما یک مشخصات را تأیید نکنید، کدی نخواهد نوشت. یک مهارت دامنه مانند bigquery-basics مستندات API به‌روز و تحت مدیریت گوگل را فراهم می‌کند، بنابراین عامل از الگوهای صحیح کتابخانه‌ی کلاینت استفاده می‌کند.

سرورهای MCP شکاف دانش را در زمان اجرا پر می‌کنند. BigQuery MCP به عامل (agent) یک اتصال زنده به مجموعه داده‌های واقعی شما می‌دهد - می‌تواند جداول را فهرست کند، انواع ستون‌ها را بررسی کند و پرس‌وجوهای نمونه را اجرا کند. عامل از داده‌های طرحواره واقعی کار می‌کند، نه حدس و گمان.

بیایید عمیق‌تر در مورد این دو بدانیم

مهارت‌های عامل

مهارت‌های عامل (Agent Skills) یک قالب سبک و باز برای گسترش قابلیت‌های عامل هوش مصنوعی با دانش و گردش‌های کاری تخصصی است. هر مهارت یک دایرکتوری قابل حمل و کنترل‌شده با نسخه با یک فایل SKILL.md است - قراردادی قابل خواندن توسط ماشین که نحوه انجام یک کار خاص توسط عامل را تعریف می‌کند.

یک فهرست مهارت‌ها به این شکل است: 

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

در اصل، یک مهارت پوشه‌ای است که حاوی یک فایل SKILL.md است. این فایل شامل فراداده (حداقل نام و توضیحات) و دستورالعمل‌هایی است که به یک عامل می‌گوید چگونه یک کار خاص را انجام دهد. مهارت‌ها همچنین می‌توانند اسکریپت‌ها، مطالب مرجع، قالب‌ها و سایر منابع را در خود جای دهند.

این فایل SKILL.md مربوط به مهارت bigquery-basics است که بعداً در این آزمایشگاه کد از آن استفاده خواهید کرد: 

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

# BigQuery Basics

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

متن اصلی YAML (نام + توضیحات + فراداده) چیزی است که Antigravity CLI در هنگام راه‌اندازی بارگذاری می‌کند - فراداده سبک. بدنه markdown زیر --- مجموعه دستورالعمل کامل است که فقط زمانی بارگذاری می‌شود که Antigravity یک کار مرتبط با BigQuery را تشخیص دهد.

افشای تدریجی

مهارت‌ها از یک الگوی افشای تدریجی سه لایه استفاده می‌کنند که از اشباع پنجره محتوا جلوگیری می‌کند:

  1. لایه ۱ (کشف): در هنگام راه‌اندازی، Antigravity فقط فراداده‌های YAML را برای هر مهارت نصب‌شده می‌خواند. این برنامه می‌داند که آن مهارت وجود دارد - نه بیشتر.
  2. لایه ۲ (فعال‌سازی): وقتی وظیفه شما با شرح یک مهارت مطابقت دارد، AGY کل SKILL.md را در متن فعال خود می‌خواند. اکنون می‌داند چه کاری باید انجام دهد .
  3. لایه ۳ (اجرا): در صورت نیاز، Antigravity به اسکریپت‌ها، مثال‌ها یا منابع مهارت دسترسی پیدا می‌کند. اکنون می‌داند چگونه این کار را انجام دهد .

فقط دانش مرتبط در زمان مناسب بارگذاری می‌شود. به عنوان مثال، مهارتی برای استقرار Cloud Run هنگام کار بر روی یک پرس‌وجوی BigQuery، زمینه را اشغال نمی‌کند.

سه دسته مهارت

انواع مختلفی از مهارت‌های عامل‌ها وجود دارد. در این آزمایشگاه کد، ما از سه مهارت استفاده خواهیم کرد که هر کدام نشان‌دهنده یک دسته مهارت متفاوت هستند:

دسته بندی

مهارت‌ها

هدف

دانش دامنه

گوگل/مهارت‌ها

آنچه نماینده در مورد فناوری‌های خاص می‌داند

روش‌شناسی

ابرا/ابرقدرت‌ها

چگونه توسعه دهیم - توسعه، برنامه‌ریزی و آزمایش مبتنی بر مشخصات را اجرا می‌کند

کارایی

جولیوس بروسه/غارنشین

چگونه می‌توان از توکن‌ها به طور مؤثر استفاده کرد؟

google/skills مهارت‌های عامل شخص ثالث را که توسط گوگل برای محصولات گوگل نگهداری می‌شود، ارائه می‌دهد. به عنوان مثال، به عامل دانش دقیق و به‌روزی در مورد APIهای BigQuery، الگوهای استقرار Cloud Run و سایر خدمات می‌دهد. بدون مهارت‌های دامنه، عامل به داده‌های آموزشی متکی است که ممکن است قدیمی یا ناقص باشند - مهارت‌های دامنه جایگزین حدس و گمان با مستندات فعلی می‌شوند.

obra/superpowers یک پیاده‌سازی خودرأی از گردش کار توسعه مبتنی بر مشخصات (SDD) است. بدون یک چارچوب SDD، وقتی یک ویژگی را توصیف می‌کنید، عامل‌ها مستقیماً به سراغ کد می‌روند - که برای اصلاحات کوچک کار می‌کند اما برای هر چیز بزرگتری نتایج متناقض و دشوار برای نگهداری ایجاد می‌کند. SDD یک چرخه ساختاریافته را اعمال می‌کند: روشن کردن الزامات → نوشتن مشخصات → ایجاد یک طرح → پیاده‌سازی بر اساس مشخصات. هر مرحله یک مصنوع قابل بررسی تولید می‌کند. عامل تا زمانی که مشخصات را تأیید نکنید، شروع به کدنویسی نمی‌کند. چارچوب‌های SDD دیگری نیز وجود دارند - spec-kit ، agent-skills و موارد دیگر - که هر کدام نظرات متفاوتی در مورد چرخه مشخص کردن-برنامه ریزی-پیاده سازی دارند. این codelab از superpowers به ​​عنوان یک مثال ملموس استفاده می‌کند. نظم اساسی (قبل از کدنویسی، مشخص کردن و برنامه‌ریزی کنید) صرف نظر از اینکه کدام چارچوب را انتخاب می‌کنید، اعمال می‌شود.

JuliusBrussee/caveman خروجی عامل را تا 75٪ فشرده می‌کند. این ابزار کلمات اضافی، تعارفات و توضیحات طولانی را حذف می‌کند و در عین حال تمام محتوای فنی را دست نخورده نگه می‌دارد. توکن‌های کمتر در هر پاسخ به معنای تبادلات پربارتر در هر جلسه و پاسخ‌های سریع‌تر است. آن را با /caveman یا با دستور دادن به عامل برای صحبت کارآمد فعال کنید. این ابزار به طور خودکار برای هشدارهای امنیتی و اقدامات برگشت‌ناپذیر غیرفعال می‌شود.

نصب مهارت‌های عامل

نصب رسمی مهارت‌های گوگل

ابتدا، بیایید مهارت‌های ضروری گوگل را که با آنها تعامل خواهیم داشت، نصب کنیم. در این آموزش، فناوری اصلی که به آن خواهیم پرداخت Bigquery و Cloud Run است. بنابراین بیایید این مهارت‌ها را نصب کنیم. برای نصب این مهارت‌ها از دستور npx skills استفاده خواهیم کرد.

npx skills add google/skills

این یک رابط کاربری ترمینال تعاملی باز می‌کند، مهارت‌های زیادی وجود دارد. از کلیدهای جهت‌نما و کلید فاصله برای انتخاب مهارت‌های مورد نیاز برای این آزمایشگاه کد استفاده کنید.

8b6b0deb5fe07dfd.png

bigquery-basics و cloud-run-basics را پیدا کنید و برای انتخاب آنها روی Space کلیک کنید. کادر باید مانند تصویر زیر به رنگ خاکستری تیره باشد.

4fa62a7341444be5.png

سپس، در انتخاب عامل‌ها، فقط روی Enter کلیک کنید تا از انتخاب صرف نظر شود زیرا Antigravity CLI به طور پیش‌فرض از قبل گنجانده شده است.

c16e7ed1be8ad91b.png

و بیایید محدوده نصب پروژه را انتخاب کنیم، این کار مهارت‌ها را در زیر پوشه .agents در دایرکتوری کاری ما نصب می‌کند.

6c84cee31651dffc.png

در نهایت برای پایان نصب، روی Enter کلیک کنید و با Yes پاسخ دهید. در صورت تمایل، اگر مهارت‌های زیادی پیکربندی کرده‌اید، می‌توانید برای نصب مهارت find-skills نیز Yes را انتخاب کنید.

4709e3a1ad34a27d.png

نصب مهارت‌های شخص ثالث به عنوان افزونه

در مرحله بعد، مهارت‌های obra/superpowers و JuliusBrussee/caveman را نصب خواهیم کرد. این مهارت‌ها به عنوان افزونه‌های Antigravity CLI پشتیبانی می‌شوند، از این رو می‌توانیم آنها را با استفاده از این دستورات نصب کنیم.

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

سپس، می‌توانیم با استفاده از دستور زیر، نصب را تأیید کنیم

agy plugin list

این خروجی‌ها را نشان خواهد داد 

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

اینها مهارت‌های ما را نهایی کردند. بیایید به سراغ مهارت بعدی برویم.

7. شخصی‌سازی - ابزارهای MCP

e7b9be2e1c98b4db.png

MCP (پروتکل زمینه مدل) یک پروتکل باز است که نحوه کشف و تعامل عامل‌های هوش مصنوعی با ابزارهای خارجی را استاندارد می‌کند. این پروتکل یک مدل کلاینت-سرور را تعریف می‌کند: عامل میزبان یک کلاینت MCP است و ابزارها توسط سرورهای MCP در معرض دید قرار می‌گیرند. هر کلاینت سازگار با MCP می‌تواند از هر سرور سازگار با MCP استفاده کند - عامل برای هر ابزار به کد یکپارچه‌سازی سفارشی نیاز ندارد.

MCP از معماری کلاینت-سرور استفاده می‌کند:

  • میزبان - برنامه‌ای که مدل هوش مصنوعی در آن قرار دارد (در این مورد Antigravity CLI)
  • کلاینت - مؤلفه‌ای در میزبان که ارتباطات MCP را مدیریت می‌کند (در Antigravity CLI تعبیه شده است)
  • سرور - یک برنامه سبک که قابلیت‌ها را در اختیار هوش مصنوعی قرار می‌دهد (در مورد ما، از سرور مدیریت‌شده BigQuery MCP گوگل کلود استفاده خواهیم کرد)

وقتی Antigravity CLI بعداً گردش کار SDD را در این آزمایشگاه کد اجرا می‌کند، به دانش دقیقی از طرحواره مجموعه داده BigQuery - نام جداول، انواع ستون‌ها، روابط - نیاز دارد. BigQuery MCP به Antigravity CLI اجازه می‌دهد تا طرحواره زنده را مستقیماً بررسی کند. این کار مشخصات و کدی را تولید می‌کند که به جداول و ستون‌های واقعی اشاره دارند، نه به جداول و ستون‌های خیالی.

پیکربندی مدیریت‌شده‌ی BigQuery MCP

گوگل یک سرور مدیریت‌شده‌ی BigQuery MCP را روی زیرساخت Google Cloud میزبانی می‌کند - نیازی به راه‌اندازی محلی نیست (می‌توانید سایر محصولات Google Cloud را که در این مستندات پشتیبانی می‌شوند، بررسی کنید). با ایجاد فایل پیکربندی MCP در دایرکتوری پروژه خود، Antigravity CLI را برای اتصال به آن پیکربندی کنید:

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

این پیکربندی به AGY می‌گوید:

  • سرور BigQuery MCP ( serverUrl ) را از کجا پیدا کنیم؟
  • برای استفاده از اعتبارنامه‌های گوگل برای احراز هویت ( authProviderType )

این پیکربندی در سطح فضای کاری ( .agents/mcp_config.json ) قرار دارد.

می‌توانیم پیکربندی را از داخل Antigravity CLI تأیید کنیم، ابتدا آن را اجرا می‌کنیم.

agy

سپس، با اجرای دستور slash /mcp پیکربندی را تأیید کنید.

/mcp

چیزی شبیه به این را نشان خواهد داد

a7ef228bfcbb5280.png

سپس، برای خروج از تعامل دستور اسلش، Esc را فشار دهید

فعلاً از Antigravity CLI خارج شوید (دو بار Ctrl+D را فشار دهید)

۸. توسعه ویژگی‌ها با توسعه مبتنی بر مشخصات

با نصب مهارت‌ها/افزونه‌ها و اتصال BigQuery MCP، اکنون می‌توانید از گردش کار توسعه مبتنی بر مشخصات برای تعیین رسمی ویژگی ادغام BigQuery استفاده کنید. این مرحله‌ای است که در آن « قبل از کدنویسی مشخص کنید » ملموس می‌شود.

مطمئن شوید که Antigravity CLI را وارد می‌کنید و برای این نسخه آزمایشی، ما به همه ابزارها اجازه اجرای این پرچم را می‌دهیم.

agy --dangerously-skip-permissions

حالت غارنشین را فعال کنید

قبل از شروع چرخه SDD، حالت غارنشین را فعال کنید تا استفاده از توکن در طول گردش کار چند مرحله‌ای کارآمد باشد:

/caveman:caveman

پاسخ‌های Antigravity CLI مختصر و مفید می‌شوند - کلمات پرکننده و تعارفات حذف می‌شوند و در عین حال تمام محتوای فنی حفظ می‌شود. توکن‌های کمتر در هر مبادله به معنای مکالمات پربارتر در همان سهمیه است.

8e6965ae2207147e.png

مشخصات SDD را شروع کنید

درخواست ویژگی را از طریق رابط خط فرمان Antigravity ارسال کنید:

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

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

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

مهارت ابرقدرت‌ها به طور خودکار هنگام تشخیص یک درخواست در سطح ویژگی فعال می‌شود. AGY به جای پرش مستقیم به کد، وارد چرخه SDD می‌شود.

رابط خط فرمان آنتی‌گراویتی (Antigravity CLI) فرآیندی را برای درک پروژه فعلی و جمع‌آوری اطلاعات مورد نیاز آغاز می‌کند. خواهید دید که دستوراتی مانند ListDir و Read مانند شکل زیر اجرا می‌کند.

۳۱۰۲۹۴۹f۹۲۹df۹۶۷.png

و همچنین از اتصال BigQuery MCP که قبلاً راه‌اندازی کرده‌ایم برای یافتن طرحواره مجموعه داده‌ها استفاده خواهد کرد.

7fbc061a07058d24.png

این کار تضمین می‌کند که Antigravity CLI قبل از شروع توسعه، زمینه صحیحی داشته باشد.

شفاف‌سازی الزامات

رابط خط فرمان ضد جاذبه (Antigravity CLI) ممکن است سوالات متمرکزی در مورد محدوده ویژگی بپرسد. سوالات معمول عبارتند از:

  • شناسه پروژه چگونه باید پیکربندی شود؟
  • نمودار روند درآمد چگونه باید تجمیع و نمایش داده شود؟
  • چگونه باید به ادغام نزدیک شد؟ Direct SQL در مقابل Local Pandas

شما می‌توانید با توجه به توصیه‌های نماینده، به این سوالات پاسخ دهید.

۹۱fb44a131f927e9.png4d5e5ffbc81644a5.png

مشخصات را بررسی کنید

پس از شفاف‌سازی، یک سند مشخصات رسمی تولید می‌کند. اگر دستورالعمل‌ها را به درستی دنبال کند، از قرارداد مهارت obra/superpowers پیروی می‌کند که در آن سند مشخصات را در دایرکتوری docs/superpowers/specs مانند شکل زیر ایجاد می‌کند.

86e0a2f86a956497.png

سند مشخصات شبیه به این خواهد بود 

# BigQuery Integration Design Specification

## Overview

This document specifies ...

## Architecture

The application currently reads ...

## Data Schema & Sources

All tables reside in the BigQuery ...

...

پس از بررسی این، باید مشخصات را تأیید کنیم تا به مرحله برنامه‌ریزی برسیم.

74cde3e9b4c95b88.png

proceed with the specs

مرحله برنامه‌ریزی و اجرای زیرعامل‌ها

پس از تأیید مشخصات توسط شما، Antigravity CLI آن را به یک طرح پیاده‌سازی تجزیه می‌کند که در دایرکتوری docs/superpowers/plans نوشته خواهد شد.

727b92a4eca89106.png

اسناد طرح موارد مختلفی مانند مثال زیر را فهرست می‌کنند:

  • فایل‌هایی برای تغییر
  • فایل‌هایی برای ایجاد/به‌روزرسانی
  • تغییرات وابستگی
  • تجزیه وظیفه

همچنین توصیه می‌شود از subagent driven development استفاده شود که توسط Antigravity CLI پشتیبانی می‌شود - به جای اینکه یک عامل واحد همه کارها را به صورت متوالی انجام دهد، Antigravity CLI می‌تواند وظایف را به زیرعامل‌های تخصصی واگذار کند. در طول پیاده‌سازی، ممکن است زیرعامل‌هایی مانند موارد زیر را مشاهده کنید:

  • مجری وظیفه - کد مربوط به یک وظیفه خاص از طرح را می‌نویسد
  • بررسی‌کننده وظایف - کد پیاده‌سازی شده را با توجه به مشخصات بررسی می‌کند.
  • بررسی‌کننده نهایی کد - قبل از تکمیل، یک بررسی جامع در مورد تمام تغییرات انجام می‌دهد

751df4f6d964e42b.png

اگر از شما چنین سوالی شد، با این پاسخ دهید

Use subagent driven development

بعداً خواهیم دید که به زیر-عامل‌ها تفویض اختیار شده است تا وظایف را یکی یکی انجام دهند.

fb4a986dbceaec96.pngb2e74e769f9ff4bf.png620d12e9056f621b.png

بعد از مدتی توسعه تمام می‌شود (احتمالاً پس از ایجاد عامل Final Code Reviewer ). سپس می‌توانیم نتیجه را بررسی کنیم.

بررسی دفترچه راهنمای برنامه به‌روزرسانی شد

پس از اتمام تمام کارها، می‌توانیم برنامه‌ی به‌روزرسانی‌شده را بررسی کنیم. با دو بار فشردن Ctrl+D از Antigravity CLI خارج شوید، سپس دستور زیر را اجرا کنید

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

اکنون باید ببینید که Total Orders نمایش داده شده > 120K سفارش است و در صورت موفقیت‌آمیز بودن توسعه، با BigQuery یکپارچه شده است.

20398466e2d8a70f.png

تبریک! اکنون شما با موفقیت BigQuery را با کمک کامل Antigravity CLI با برنامه وب خود ادغام کرده‌اید.

۹. (اختیاری) استقرار در Cloud Run با Antigravity CLI

این داشبورد به صورت محلی از طریق پیش‌نمایش وب Cloud Shell کار می‌کند. این مرحله اختیاری، آن را به عنوان یک سرویس وب عمومی در Cloud Run مستقر می‌کند - که نشان می‌دهد چگونه مهارت‌های Antigravity CLI از توسعه به عملیات گسترش می‌یابد.

مهارت cloud-run-basics (از افزونه google/skills که قبلاً نصب کردید) به Antigravity CLI دانشی در مورد الگوهای استقرار Cloud Run، الزامات Dockerfile، اتصال پورت و پرچم‌های gcloud run deploy می‌دهد. استقرار مبتنی بر منبع ( gcloud run deploy --source . ) با یک دستور ساخته و مستقر می‌شود - Cloud Build به طور خودکار کانتینرسازی را مدیریت می‌کند.

فعال کردن APIهای Cloud Run

API های مورد نیاز برای استقرار را فعال کنید:

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

سپس، وارد Antigravity CLI شوید.

agy --dangerously-skip-permissions

فعال کردن Antigravity CLI برای استقرار

بیایید به آن دستور دهیم که برنامه‌های ما را مستقر کند

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

این مهارت cloud-run-basics را می‌خواند تا بفهمد الزامات استقرار برنامه وب پروژه فعلی چیست.

a5ef955de2d71c91.png

پس از اتمام، تأیید می‌کند که استقرار موفقیت‌آمیز بوده و خلاصه‌ای از فرآیند استقرار که قبلاً اجرا شده است را مانند مثال زیر به شما ارائه می‌دهد. می‌توانید با URL ارائه شده به برنامه خود دسترسی پیدا کنید.

b58fb8f5f2023264.png

اکنون شما یک برنامه زنده دارید که به طور کامل مستقر شده و با کمک Antigravity CLI قابل دسترسی است.

۱۰. جمع‌بندی

شما یک داشبورد تجارت الکترونیک را از فایل‌های CSV استاتیک به داده‌های زنده BigQuery ارتقا دادید - بدون اینکه کد برنامه را با دست بنویسید. Antigravity CLI پیاده‌سازی را از طریق یک گردش کار توسعه منظم و مبتنی بر مشخصات، با هدایت مهارت‌های قابل استفاده مجدد و اتصال زنده به داده‌های شما از طریق MCP، انجام داد.

آنچه آموخته‌اید

  • نحوه استفاده از Antigravity CLI در Cloud Shell برای توسعه با کمک هوش مصنوعی
  • مهارت‌های کارشناس چیست و چگونه افشای تدریجی، پنجره‌ی زمینه را کارآمد نگه می‌دارد
  • سه دسته مهارت: روش‌شناسی (ابرقدرت‌ها)، کارایی (غارنشین)، دانش تخصصی (گوگل/مهارت‌ها)
  • MCP چیست و چگونه BigQuery MCP را برای دسترسی زنده به داده‌ها پیکربندی کنیم؟
  • چگونه یک چرخه توسعه مبتنی بر مشخصات (مشخص کردن → برنامه‌ریزی → پیاده‌سازی) را به جای کدنویسی پویا اجرا کنیم؟
  • چگونه Antigravity CLI می‌تواند sub-agent ایجاد کند تا توسعه متمرکزتر و کارآمدتر شود

تمیز کردن

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع ایجاد شده در این codelab، می‌توانید منابع را به صورت جداگانه یا کل پروژه را حذف کنید.

The easiest way to clean up is to delete the project. This removes all resources associated with the project.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Option 2: Delete individual resources

If you want to keep the project but remove only the resources created in this codelab:

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