פיתוח סוכנים באמצעות ADK שמבוסס על מפרט, עם Antigravity ו-Spec-kit

1. מבוא

הוספת תכונות לסוכן קיים – יכולת חדשה שמגובה במסד נתונים – בדרך כלל כרוכה בכתיבת קוד סטנדרטי, בהגדרת שילובים ובשמירה על עקביות עם התבניות שכבר נמצאות בבסיס הקוד. ‫Antigravity מאיץ כל שלב בתהליך הזה: הוא מנתח את ה-codebase כדי לבנות את ההקשר שהוא צריך, יוצר מפרטים מובנים ותוכניות הטמעה לבדיקה שלכם, ומבצע את שינויי הקוד – והכול בהתבסס על ידע בתחום שעוזר לכם לתעד ככישורים לשימוש חוזר וכמסמך מדיניות של הפרויקט שמחייב עקרונות שאי אפשר להתפשר עליהם. בשיעור Codelab הזה נציג דרך לשפר את פרדיגמת הפיתוח מבוסס-המפרט של Antigravity באמצעות מחזור חדש לשיפור תיעוד המפרט, עם הפניות רבות ל-spec-kit

מה תפַתחו

אפליקציית קונסיירז' למסעדות שפועלת באופן מקומי, עם הזמנת מקום שנוספה באמצעות מחזור SDD מלא:

• הזמנת מקומות – האורחים מזמינים שולחנות ובודקים הזמנות, בעזרת כלי מסד נתונים חדשים של MCP Toolbox וטבלה של Cloud SQL reservations
• (אתגר) – פיתוח ממשק משתמש משלכם לסוכן
• (אתגר) – פריסה ב-Google Cloud בעזרת סוכן Antigravity

קוד לתחילת הדרך מספק סוכן ADK פעיל עם חיפוש בתפריט (מילת מפתח + סמנטי באמצעות MCP Toolbox) ומעקב אחר העדפות תזונתיות (באמצעות ToolContext). אתם יכולים להרחיב את הפונקציונליות בלי לכתוב קוד אפליקציה באופן ידני – Antigravity מטפל בהטמעה על סמך המפרט שלכם.

מה תלמדו

• איך להגדיר הקשר לפרויקט כדי ש-Antigravity יבין codebase קיים
• איך ליצור מיומנויות Antigravity שכוללות ידע בתחום (למשל, תבניות של שיעורי Codelab של ADK) לשימוש חוזר
• איך מגדירים חוקה לפרויקט שתהליכי העבודה של SDD יאמתו מולה במהלך התכנון והניתוח
• איך משתמשים בתהליכי עבודה של פיתוח מונחה-מפרט (SDD) ב-Antigravity כדי להוסיף תכונות באופן שיטתי
• איך מרחיבים סוכן ADK באמצעות כלים חדשים שמגובים במסד נתונים דרך MCP Toolbox

דרישות מוקדמות

• ‫Google Antigravity ו-git מותקנים במחשב המקומי
• חשבון ב-Google Cloud עם חשבון לחיוב פעיל
• כדי להבין את ההקשר של תרחיש השימוש, מומלץ להשלים קודם את ארבעת ה-Codelabs של ADK (או ידע מקביל):
• יצירה של סוכני AI באמצעות ADK: עקרונות היסוד
• יצירה של סוכני AI באמצעות ADK: שיפורים באמצעות כלים
• יצירת סוכני AI מתמידים באמצעות ADK ו-CloudSQL
• פריסה, ניהול ובדיקה של סוכן ADK ב-Cloud Run
• מסד נתונים בתור כלי: RAG אג'נטי עם ADK,‏ MCP Toolbox ו-Cloud SQL

2. הגדרת הסביבה

הערות חשובות:

כדי לבצע את ההדרכה הזו, צריך פרויקט ב-Google Cloud עם חשבון חיוב פעיל. אם עדיין אין לכם חשבון, תוכלו להשתמש בבאנר שבראש ה-codelab הזה כדי לקבל חשבון לחיוב לתקופת ניסיון שתוכלו להשתמש בו במדריך הזה.

בשלב הזה מתבצע שיבוט של מאגר המתחילים, אימות ב-Google Cloud, הקצאה של מסד נתונים של Cloud SQL והכנה של סביבת Antigravity המקומית.

הערות: ה-codelab הזה פועל כולו ב-Google Antigravity במחשב המקומי שלכם. ההגדרה כוללת אימות ידני באמצעות פקודת gcloud CLI

התקנת דרישות מוקדמות

מוודאים שבמערכת יש את קובץ ה-CLI הבא שניתן להפעלה:

• git
• gcloud
• uv
• npm

הוראות ההתקנה משתנות בהתאם למערכת ההפעלה של המחשב.

שכפול מאגר התחלתי

פותחים טרמינל ב-Antigravity (או בטרמינל של המערכת). משכפלים את מאגר הקוד של Companion ונכנסים לספרייה:

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 ב-codelab הזה משתמשים בענפים של git כדי לארגן מפרטים של תכונות. הסרת המאגר המרוחק origin מבטיחה שההסתעפויות והשמירות המקומיות יישארו מקומיות. אם רוצים לגבות את העבודה, מוסיפים שלט רחוק משלכם: git remote add origin <your-repo-url>

אימות ב-Google Cloud

מריצים שתי פקודות אימות. שניהם פותחים דפדפן ל-OAuth:

gcloud auth login
gcloud auth application-default login

הערות: בפקודת OAuth השנייה, כשמוצגת בקשה לבחירת הרשאה. מה האפשרויות שלי?

הערות: חשוב לוודא שאתם מבצעים אימות באמצעות כתובת האימייל שבה השתמשתם כדי להפעיל את חשבון הניסיון לחיוב.

מכיוון שאתם עובדים באופן מקומי עם Antigravity, אתם צריכים לבצע אימות ידני. ‫auth login מאמת את CLI של gcloud. application-default login מאמת את ערכות ה-SDK של Google Cloud שהאפליקציה שלכם משתמשת בהן – הקריאות ל-Vertex AI של ADK והמחבר של Cloud SQL Python מסתמכים על Application Default Credentials.

הגדרת הפרויקט ב-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 שמקושר לחשבון לחיוב בתקופת ניסיון (מוגבלת). אם אתם מעדיפים להשתמש בפרויקט קודם שלכם, אתם יכולים לדלג על השלב הבא ולבצע במקומו את השלב הזה:

מוסיפים את שם הפרויקט שלכם כמשתנה GOOGLE_CLOUD_PROJECT בקובץ .env.

מפעילים את הפרויקט בטרמינל באמצעות הפקודה gcloud config set project your-project-id

אחר כך אפשר לדלג ישירות אל השלב 'הפעלת ה-API'.

אם אתם לא בטוחים, המשיכו לקטע הבא

מורידים ומריצים את סקריפט הגדרת הפרויקט. הסקריפט יוצר או מאמת פרויקט בענן ב-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

הפעלת ה-API

מפעילים את ממשקי ה-API הנדרשים:

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

הערות: הפעלת ממשקי API עשויה להימשך זמן מה. צריך לעשות את זה רק פעם אחת לכל פרויקט.

התקנת יחסי תלות

נשתמש ב-uv כמנהל פרויקטים ב-Python. ‫uv הוא מנהל פרויקטים וחבילות Python מהיר שנכתב ב-Rust ( מסמכים ). אנחנו משתמשים בו ב-codelab הזה כדי להשיג מהירות ופשטות. מתקינים את יחסי התלות של Python:

uv sync

לאחר מכן מעדכנים את קובץ .env של סוכן ה-ADK בהגדרות הפרויקט:

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
• יצירת מסד נתונים
• מסד נתונים של זרעים
• הפעלת שירות MCP Toolbox ברקע

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

הפקודה הזו תריץ את ההגדרה ברקע, ואפשר לבדוק מדי פעם את הפלט בקובץ database_setup.log

עכשיו אמור להיות לנו מאגר (repo) של סוכן ADK למתחילים, שנדרש כדי להתחיל לעבוד. עכשיו נדבר יותר על Antigravity ועל פיתוח מבוסס-מפרט בקטע הבא, בזמן שאנחנו מחכים שכל מה שצריך יהיה מוכן.

3. היכרות עם קוד ההתחלה והסבר על פיתוח מונחה-מפרט

בשלב הזה נסביר על מבנה קוד לתחילת הדרך, נציג את המתודולוגיה של פיתוח מבוסס-מפרט, נזרע את מסד הנתונים ונוודא שהסוכן הבסיסי פועל לפני שמתחילים להרחיב אותו.

מבנה הפרויקט

פותחים את פרויקט המאגר המשוכפל בעורך 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 שמשלב כלי מסד נתונים של 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. ‫get_fast_api_app() מ-ADK מספק נקודות קצה מובנות, כולל /run_sse לסטרימינג של SSE וממשקי API לניהול סשנים.

Antigravity Files

• ‫.agents/skills/mcp-toolbox-postgres/SKILL.md – מיומנות שמנחה את Antigravity איך ליצור הגדרה נכונה של קובץ tools.yaml עבור MCP Toolbox. בקורס הזה נלמד על הגדרות שקשורות ל-sources, ל-tools ולהגדרות של embeddingModels שנדרשות כדי ליצור פייפליין RAG תקין. היכולת הזו לא תופעל עד שתוסיפו YAML frontmatter מתאים כדי שהיא תזוהה על ידי Antigravity
• ‫.agents/skills/repo-research/SKILL.md – מיומנות שמלמדת את Antigravity איך לנתח מאגר באופן מצטבר וליצור מסמך הקשר מובנה של הפרויקט. הכלי משתמש בגישה של 4 שלבים: סריקה שטחית (רק עץ הספריות), קובצי תצורה ומטא-נתונים, נקודות כניסה ומודלים של נתונים, ואז בדיקות מעמיקות ממוקדות – כל שלב מסתיים וכותב את הממצאים לפני שמתקדמים לשלב הבא. הוא גם לא פעיל עד שמוסיפים לו YAML frontmatter בהמשך. אחרי ההפעלה, מפעילים אותו כדי ליצור .agents/rules/project-context.md – מסמך מקיף להצטרפות שכולל ארכיטקטורה, תלות בזמן ריצה, ממשק API ומילון מונחים של הדומיין.

פיתוח מבוסס-מפרט: מתכנון מובנה ב-Antigravity ועד לפיתוח מובנה מובנה

עוזרי תכנות מבוססי-AI מאפשרים ליצור קוד בקלות מהנחיה. הסיכון: אתם מתארים תכונה במשפט, העוזר הדיגיטלי כותב מאות שורות ואתם מאשרים את זה כי זה נראה לכם נכון. לפעמים קוראים לזה 'תכנות בשיטת Vibe coding' – אתם מנסים עד שיוצא פלט שנראה לכם טוב. הוא מהיר ליצירת אבות טיפוס ולסקריפטים חד-פעמיים. היא נשברת כשהבסיס של הקוד גדל, כשהתכונות יוצרות אינטראקציה או כשחוזרים לקוד שבועות לאחר מכן ולא מצליחים לשחזר למה התקבלה החלטה מסוימת.

פיתוח מבוסס-מפרט (SDD) מוסיף מבנה ללולאה הזו. לפני שיוצרים קוד, כותבים מפרט: מה התכונה עושה, למי היא מיועדת ומהם הקריטריונים להצלחה. העוזר הדיגיטלי מבוסס ה-AI פועל לפי המפרט הזה – וכך גם אתם כשאתם בודקים את התוצאה שלו. המפרט הופך למקור הקובע היחיד לגבי הכוונה. אם הקוד חורג מהמפרט, אפשר לזהות את זה בבדיקה. אם הדרישות משתנות, צריך לעדכן קודם את המפרט ואז ליצור מחדש את הקובץ. ההחלטות מתועדות, ולא מאולתרות.

הפשרה היא אמיתית: כל תכונה ב-SDD פועלת לאט יותר מאשר ב-תכנות בשיטת Vibe coding. אתם כותבים מסמכים לפני שאתם כותבים קוד. אבל התועלת מצטברת – לכל שינוי עתידי בבסיס הקוד יש הקשר, לכל הטמעה שנוצרה על ידי AI יש חוזה שניתן לבדיקה, ואפשר לצרף משתפי פעולה (אנושיים או AI) על ידי הפניה שלהם למפרטים במקום להסביר החלטות מהזיכרון.

‫Antigravity כבר פועל לפי עקרונות של פיתוח מונחה-מפרט. כשמגדירים את הסוכן למצב תכנון, הוא יוצר שני פריטי מידע שנוצרו בתהליך פיתוח (Artifact) לפני שהוא כותב קוד:

• תוכנית הטמעה – סקירה כללית של הגישה הטכנית המוצעת, השינויים בקובץ והחלטות הארכיטקטורה
• רשימת משימות – פירוט מובנה של פריטי עבודה

‫Antigravity מבקש לבדוק ולאשר את הארטיפקטים האלה לפני ההפעלה. הלולאה הזו של תכנון ואז הטמעה היא הליבה של פיתוח מבוסס-מפרטים: המפרטים מכוונים את הקוד, ולא להפך.

ה-Codelab הזה מתבסס על הידע הזה ומציג תהליך עבודה מבוסס-דעות עם בקרת גרסאות שמבוסס על spec-kit – מסגרת לפיתוח מבוסס-מפרטים מ-GitHub. כל תכונה עוברת פייפליין מובנה שבו כל ארטיפקט הוא מסמך עצמאי שאפשר לבדוק, לערוך ולעקוב אחריו ב-git. תהליך העבודה כולל שני שלבים אופציונליים של בקרת איכות (הבהרה וניתוח) שמאפשרים לזהות בעיות לפני שהן הופכות לבעיות בהטמעה:

שלב	Artifact	מטרה
/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

מאגר המתחילים כולל את תהליכי העבודה האלה של SDD ב-.agents/workflows/ ותבניות ב-.specify/templates/. תשתמשו בהם בהמשך כדי להוסיף תכונות לסוכן.

4. הוספת הקשר לפרויקט באמצעות Antigravity

עכשיו נדמה מצב עם תנאי ש"קצת יותר קרוב" לעבודה היומיומית שלנו:

• מאגר שלא מנוהל היטב
• קובץ README מיושן
• התיעוד לא מתעדכן לעיתים קרובות

הערה: אם המצב הזה לא משקף את המצב שלכם, סימן שאתם מאוד ברי מזל

במצב כזה, הדבר הראשון שנעשה בדרך כלל הוא ליצור מפה או הקשר לגבי הפרויקט שאנחנו רוצים ש-Antigravity יעבוד עליו. בשלב הזה מוצגת דוגמה אחת לגישה שבה אפשר להשתמש כדי להעניק ל-Antigravity הבנה מעמיקה של בסיס קוד קיים. לשם כך, יוצרים מיומנות שמנתחת את המאגר ומפיקה מסמך הקשר של הפרויקט.

הוא גם מגדיר את חוקת הפרויקט – העקרונות שאי אפשר להתפשר עליהם, שתהליכי העבודה של SDD מאמתים מולם. ביחד, הם מספקים ל-Antigravity את ההקשר והאילוצים שהוא צריך למחזורי ה-SDD בהמשך

היררכיית ההקשר של Antigravity

‫Antigravity משתמש בשלוש רמות של הקשר, שלכל אחת מהן היקף שונה:

• כללים (.agents/rules/): הוראות שתמיד פעילות. כל שיחה במרחב העבודה הזה רואה אותם ( אם הפעלתם אותם). כדאי להשתמש בכללים כדי לספק הקשר רחב יותר לפרויקט, כמו החלטות לגבי ארכיטקטורה, תקני קידוד או מידע על סטאק תוכנות.
• כישורים (.agents/skills/): ידע על פי דרישה. ‫Antigravity טוען מיומנות רק כשהמשימה הנוכחית תואמת לשדה description של המיומנות. שימוש במיומנויות כדי לקבל חומר עזר ספציפי לדומיין.
• תהליכי עבודה (.agents/workflows/): הנחיות שמורות שמופעלות באמצעות פקודות /. אפשר להשתמש בתהליכי עבודה לתהליכים חוזרים של כמה שלבים, כמו צינור ה-SDD.

הערה: לפרויקט יש כרגע תהליכי עבודה (פייפליין SDD) ו-2 מיומנויות (repo-research ו-mcp-toolbox-postgres), אבל אין לו כללים. בהמשך ניצור project-context.md כלל שיאפשר ל-Antigravity להבין את בסיס הקוד באופן עקבי – אילו טכנולוגיות נמצאות בשימוש, איך הקבצים מאורגנים ומה נבנה עד עכשיו.

הפעלת היכולות

מאגר התחלה כולל שתי מיומנויות שנכתבו מראש ב-.agents/skills/. הן מכילות הוראות מפורטות, אבל מתחילות בהערות TODO(codelab) במקום ב-YAML frontmatter הנדרש. ללא frontmatter, ‏ Antigravity לא יכול לגלות אותם.

כדי להשתמש במיומנויות אנטי-כבידה, צריך להוסיף לחלק העליון של הקובץ בלוק frontmatter בפורמט YAML עם שני שדות:

• ‫name – מזהה ייחודי של המיומנות
• ‫description – סיכום בשפה טבעית ש-Antigravity משווה אליו כדי להחליט איזו מיומנות לטעון עבור בקשה מסוימת

פותחים את הקובץ .agents/skills/mcp-toolbox-postgres/SKILL.md בעורך. מחליפים את שורות התגובות TODO(codelab) בחלק העליון ב-frontmatter הזה:

---
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) בחלק העליון ב-frontmatter הזה:

---
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 נגמר באמצע המחקר או שהשיחה מופרעת, כל מה שהתגלה עד עכשיו כבר נשמר בקובץ. אם מפעילים מחדש את היכולת, היא ממשיכה מהמקום שבו היא הפסיקה, בלי לאבד את ההתקדמות.

אזהרה! ניתוח של מאגר גדול עלול לגרום לניצול מהיר של המכסה.

מוודאים שלשני הכישורים יש frontmatter תקין:

head -4 .agents/skills/mcp-toolbox-postgres/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

כל אחד מהם צריך להציג את התו --- כמפריד שמקיף את השדות name: ו-description:. אם התוחמים או השדות חסרים, Antigravity לא יזהה את המיומנות.

שתי המיומנויות נטענות לפי דרישה – Antigravity משווה את הבקשה שלכם לשדה description ושולף את ההוראות המלאות רק כשזה רלוונטי.

התקנת מיומנויות שזמינות לכולם

ADK Cheatsheet Skills

בעבר בדקנו מיומנויות שיצרנו בעצמנו ( המיומנויות repo-research ו-mcp-toolbox-postgres). עם זאת, יש הרבה מיומנויות אחרות שיכולות לתמוך בפיתוח התוכנה שלנו, ואפשר להתקין אותן בקלות בסוכן התכנות שלנו. לדוגמה, במדריך הזה נדרשת אינטראקציה עם ADK, ולכן נצטרך ידע מתאים לגבי אופן הפיתוח באמצעות ADK. נשתמש בפקודה הבאה כדי להתקין את מיומנות התיעוד של ADK

npx skills add google/adk-docs

לאחר מכן תתבקשו לאשר את ההתקנה כמו שמוצג בהמשך

לוחצים על y כדי להמשיך להנחיה הבאה ולבחור אילו מיומנויות להתקין, כמו שמוצג בהמשך. לעת עתה, נבחר רק באפשרות adk-cheatsheet (מקישים על מקש הרווח כדי לבחור, ואז על Enter כדי לאשר)

אחר כך פשוט לוחצים על Enter כדי לבחור באפשרות השנייה ולהפעיל את התקנת ברירת המאחד ואת התקנת המיומנות בפרויקט הנוכחי.

תראו שהמיומנות החדשה של ADK נוספה לספרייה .agents/skills, שהיא adk-cheatsheet

Caveman Skills

אחת מהמיומנויות השימושיות להפחתת השימוש בטוקנים היא מיומנות איש המערות . היכולת הזו יכולה לחתוך את טוקן הפלט מהסוכן,מה שהופך אותה לשילוב טוב כשמשתמשים בפיתוח מלא מבוסס מפרט כמו במדריך הזה

npx skills add JuliusBrussee/caveman

בדומה למה שעשינו קודם, נבחר כרגע את המיומנות caveman

אחר כך פשוט לוחצים על Enter כדי לבחור באפשרות השנייה ולהפעיל את התקנת ברירת המאחד ואת התקנת המיומנות בפרויקט הנוכחי.

עכשיו, אמורות להיות לנו כבר 4 מיומנויות מוגדרות ומוכנות להתחלת התהליך של SDD

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

יצירת ההקשר של הפרויקט

מוודאים שספריית הכללים קיימת:

mkdir -p .agents/rules

בתיבת הצ'אט או ב-Agent Manager של 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), מבנה הפרויקט, מודל הנתונים (טבלת menu_items עם pgvector) ושילובים חיצוניים.

טיפ: מסמך ההקשר של הפרויקט גדל ככל שהפרויקט מתפתח. אפשר להפעיל מחדש את המיומנות כדי לעדכן את ההקשר עם התוספות החדשות. כללי העדכון המצטבר מבטיחים שהתוכן הקיים יישמר – טכנולוגיות, ישויות ושילובים חדשים מצורפים ולא מחליפים את התוכן הקיים.

כדי לבצע עדכונים ממוקדים, משתמשים בהנחיות ספציפיות: "תחקור את סכימת מסד הנתונים ועדכן את ההקשר של הפרויקט" או "עדכן את ההקשר של הפרויקט עם ההגדרות החדשות של הכלי". כל הפעלה מוסיפה תוכן למסמך הקיים.

הגדרת חוקת הפרויקט

תהליכי העבודה של SDD מתייחסים למסמך הגדרת הפרויקט בכתובת .specify/memory/constitution.md במהלך התכנון והניתוח. תהליך העבודה /speckit.plan מריץ בדיקה של התקנון, ו/speckit.analyze מסמן הפרות כהפרות קריטיות. אם החוקה נשארת כתבנית ריקה עם אסימוני placeholder, אין לביקורות האלה שום דבר לאמת מולו – התוכניות והניתוחים מופעלים ללא אמצעי הגנה.

החוקה מגדירה עקרונות פרויקט שלא ניתן לנהל עליהם משא ומתן. זהו מאגר קטן שמתוחזק על ידי מפתח יחיד, ולכן החוקה צריכה לשקף את ההיקף הזה – כדאי לשמור על פשטות ועקביות, ולהימנע מתכנון מורכב מדי.

במנהל הסוכנים של Antigravity, מתחילים שיחה חדשה. מריצים את תהליך העבודה של החוקה:

/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. צריך לוודא ששלושת העקרונות מופיעים ומנוסחים בצורה ברורה.

הערה: החוקה מכילה בכוונה 3 עקרונות שמתאימים למפתחים עצמאיים. תהליך העבודה /speckit.constitution תומך בתיקונים מצטברים – מפעילים פתרונות חכמים שוב עם עקרונות נוספים והוא מטפל בניהול הגרסאות באופן אוטומטי. בפרויקט צוותי, כדאי להוסיף עקרונות לבדיקת קוד, לבדיקות, לניטור ולניהול גרסאות של API.

נקודת ביקורת: הקובץ .agents/rules/project-context.md קיים ומכיל מידע קונקרטי על המאגר. ‫.agents/skills/repo-research/SKILL.md מראה איך ליצור מיומנות באמצעות YAML frontmatter, הוראות ופתרון בעיות. ‫.specify/memory/constitution.md מכיל שלושה עקרונות פרויקט שתהליכי העבודה של התוכנית והניתוח מאמתים. אתם מבינים את היררכיית ההקשר בשלוש רמות: כללים (תמיד פעילים), מיומנויות (על פי דרישה), תהליכי עבודה (פקודות סלאש).

5. מחזור SDD – הוספת תכונת שמירת מקום

בשלב הזה נסביר איך להוסיף הזמנות במסעדה לסוכן הקונסיירז' של המסעדה באמצעות מחזור SDD מלא. אתם מפעילים את Antigravity בכל שלב – הגדרה, הבהרה, תכנון, משימות, ניתוח, הטמעה – ורואים איך כל ארטיפקט מתבסס על הקודם. זהו החלק המרכזי של שיעור ה-Codelab.

חשוב! ‫Antigravity הוא עוזר מבוסס-AI – יכול להיות שהארטיפקטים שהוא יוצר (מפרטים, תוכניות, משימות, קוד) יהיו שונים מאלה שמתוארים במדריך הזה. יכול להיות שיהיו הבדלים בשמות הקבצים, בסכימות ה-SQL המדויקות ובמבנה הקוד. זה צפוי וזה חלק מהעבודה עם פיתוח בעזרת AI. תהליך העבודה של SDD מבטיח שתבדקו כל ארטיפקט לפני שהוא הופך לקוד, לכן חשוב להפעיל שיקול דעת כדי לאשר, לשנות או ליצור מחדש כל פלט שלא תואם לציפיות שלכם.

ציון התכונה

במנהל הסוכנים של Antigravity, מתחילים שיחה חדשה. מקלידים את פקודת תהליך העבודה /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)

המפרט מתמקד בשאלות 'מה' ו'למה' – ולא בשאלה 'איך'. התיאור מתייחס לחוויית המשתמש ("אורחים יכולים להזמין מקום על ידי הזנת השם, מספר האורחים, התאריך והשעה") בלי להזכיר טבלאות SQL,‏ tools.yaml או ממשקי ADK API. פרטי ההטמעה מגיעים בשלב התכנון.

בודקים את המפרט שנוצר בכתובת 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. שלב המחקר – פותר בעיות לא ידועות ב-codebase הקיים, יוצר 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 מציג תוכנית הטמעה סופית וארטיפקט של משימה. כדי להמשיך, צריך לבדוק ולאשר את ההסכם

טיפ: אפשר להוסיף תגובה ישירות! אפשר לעשות את זה רק באמצעות Artifact מובנה של 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 יצרו סקריפט נפרד להעברה (למשל, scripts/create_reservations.py) במקום לעדכן את seed_db.py. בודקים אם יש סקריפטים חדשים ב-git diff --name-only ומריצים אותם במקום זאת.scripts/

אם הכול יתנהל כשורה עד לשלב הזה, נוכל לבדוק את התכונה בממשק המשתמש של ADK agent Dev. בואו נבצע את העברת מסד הנתונים כדי לשלב טבלה חדשה, ונפעיל מחדש את Toolbox כדי לאסוף את ההגדרות החדשות של הכלי ב-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:

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?

בדיקה: הסוכן צריך להציג את ההזמנה שביצעתם.

עכשיו, מפסיקים את ממשק המשתמש של ADK dev באמצעות הקשה על Ctrl+C פעמיים.

נקודת ביקורת: הסוכן מטפל בהזמנת מקומות ובחיפוש הזמנות. השלמתם מחזור מלא של SDD: הגדרה ← הבהרה ← תכנון ← משימות ← ניתוח ← הטמעה ← בדיקה. בכל שלב נוצר ארטיפקט עם מספר גרסה ב-specs/<branch-name>/.

7. אתגרים (אופציונלי)

עכשיו אתם מכירים את תהליך העבודה המלא של SDD. רוצים לנסות?

• מריצים מחזור שני של SDD כדי ליצור ממשק צ'אט באתר בשביל שירות הקונסיירז' של המסעדה – הפעם בלי הנחיות מפורטות.
• פריסת הסוכן ב-Cloud Run לתרחיש ייצור

רמזים

• לפרויקט אין מסגרת frontend. ‫Antigravity צריך להציע HTML/CSS/JS רגיל – אם הוא מציע 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.
• בשיעורי ה-Codelab לדוגמה כבר מוסבר איך לפרוס סוכן ADK ולשמור אותו. כדאי להפנות את המשתמשים לשיעורים האלה ב-Antigravity.

8. מעולה!

הרחבתם סוכן ADK של מסעדת קונסיירז' עם הזמנת מקומות – באופן מלא דרך תהליכי העבודה של SDD של Antigravity, בלי לכתוב קוד אפליקציה באופן ידני.

מה יצרתם

• סוכן ADK של קונסיירז' במסעדה עם חיפוש בתפריט, חיפוש סמנטי, מעקב אחרי העדפות תזונתיות והזמנת מקום
• מיומנות Antigravity למחקר במאגרים שיוצרת ושומרת על מסמך הקשר של הפרויקט
• מסמך עקרונות לפרויקט שמכתיב עקרונות שלא ניתן להתפשר עליהם במהלך התכנון והניתוח
• מחזור SDD מלא שמדגים את תהליך העבודה specify → clarify → plan → tasks → analyze → implement

מה למדתם

• איך משתמשים בתהליכי עבודה של פיתוח מונחה-מפרט ב-Antigravity כדי להוסיף תכונות באופן שיטתי לבסיס קוד קיים
• איך יוצרים יכולות Antigravity שמכילות ידע בתחום מסוים לשימוש חוזר בשיחות
• איך להוסיף הקשר לפרויקט כדי ש-Antigravity יקבל החלטות מושכלות לגבי ארכיטקטורה, דפוסים ובחירות טכנולוגיות
• איך מגדירים חוקה לפרויקט שתהליכי העבודה של SDD יאמתו
• איך מרחיבים סוכן ADK באמצעות כלים חדשים שמגובים במסד נתונים דרך 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}