تطوير وكيل "حزمة تطوير الوكلاء" المستند إلى المواصفات باستخدام Antigravity وSpec-kit

1. مقدمة

إنّ إضافة ميزات إلى وكيل حالي، أي إمكانية جديدة مستندة إلى قاعدة بيانات، تعني عادةً كتابة نص نموذجي وإعداد عمليات الدمج والحفاظ على اتساق كل شيء مع الأنماط المتوفّرة في قاعدة الرموز. تسرّع Antigravity كل مرحلة من هذه العملية: فهي تحلّل قاعدة الرموز البرمجية لإنشاء السياق الذي تحتاجه، وتنتج مواصفات منظَّمة وخطط تنفيذ لتراجعها، وتنفّذ تغييرات الرموز البرمجية، وكل ذلك بإرشاد من المعرفة بالمجال التي تساعدك في تسجيلها كمهارات قابلة لإعادة الاستخدام ودستور مشروع يفرض مبادئ غير قابلة للتفاوض. يقدّم هذا الدرس التطبيقي حول الترميز طريقة لتحسين نموذج "التطوير المستند إلى المواصفات" في Antigravity من خلال تقديم دورة جديدة لتحسين مستندات المواصفات التي تشير بشكل كبير إلى spec-kit.

ما ستنشئه

تطبيق خدمة كونسيرج للمطاعم يعمل على الجهاز المحلي مع إمكانية حجز المطاعم من خلال دورة تطوير برامج كاملة:

حجز المطاعم: يمكن للضيوف حجز طاولات والاطّلاع على الحجوزات، وذلك باستخدام أدوات قاعدة بيانات MCP Toolbox الجديدة وجدول reservations في Cloud SQL.
(تحدّي) – تطوير واجهة مستخدم خاصة بك للوكيل
(تحدّي) – النشر على Google Cloud بمساعدة وكيل Antigravity

يوفّر الرمز الأولي وكيل ADK يعمل مع البحث في القائمة (الكلمة الرئيسية + الدلالة من خلال MCP Toolbox) وتتبُّع التفضيلات الغذائية (من خلال ToolContext). يمكنك توسيع نطاقها بدون كتابة الرمز البرمجي للتطبيق يدويًا، إذ تتولّى Antigravity عملية التنفيذ استنادًا إلى مواصفاتك.

أهداف الدورة التعليمية

كيفية إعداد سياق المشروع لكي يفهم Antigravity قاعدة رموز برمجية حالية
كيفية إنشاء مهارات Antigravity التي تحزم معرفة المجال (مثل أنماط دروس ADK التطبيقية حول الترميز) لإعادة استخدامها
كيفية إعداد دستور مشروع تتحقّق منه عمليات سير عمل SDD أثناء التخطيط والتحليل
كيفية استخدام سير عمل Spec-Driven Development (SDD) في Antigravity لإضافة ميزات بشكل منهجي
كيفية توسيع نطاق وكيل ADK باستخدام أدوات جديدة مستندة إلى قاعدة بيانات من خلال MCP Toolbox

المتطلبات الأساسية

تثبيت Google Antigravity وgit على جهازك
حساب على Google Cloud تم تفعيل حساب فوترة نشط فيه
سيكون من المفيد إكمال أربع دورات تدريبية مسبقة حول "حزمة تطوير التطبيقات" (أو معرفة مكافئة) لفهم سياق حالة الاستخدام:
إنشاء وكلاء الذكاء الاصطناعي باستخدام حزمة ADK: الأساسيات
إنشاء وكلاء الذكاء الاصطناعي باستخدام حزمة ADK: تزويد الوكلاء بالأدوات
إنشاء وكلاء ذكاء اصطناعي دائمين باستخدام ADK وCloudSQL
نشر وكيل ADK وإدارته ومراقبته على Cloud Run
استخدام قاعدة البيانات كأداة: التوليد المعزّز بالاسترجاع (RAG) المستنِد إلى الذكاء الاصطناعي الوكيل باستخدام ADK وMCP Toolbox وCloud SQL

2. إعداد البيئة

تؤدي هذه الخطوة إلى استنساخ مستودع الرموز البرمجية الأساسي، والمصادقة باستخدام Google Cloud، وتوفير قاعدة بيانات Cloud SQL، وإعداد بيئة Antigravity المحلية.

تثبيت المتطلبات الأساسية

تأكَّد من أنّ نظامك يتضمّن ملف CLI التنفيذي التالي:

تختلف تعليمات التثبيت حسب نظام التشغيل على جهازك.

إنشاء نسخة طبق الأصل من مستودع التطبيق النموذجي

افتح وحدة طرفية في Antigravity (أو وحدة طرفية في نظامك). أنشئ نسخة طبق الأصل من مستودع الرمز المصاحب وأدخِل الدليل:

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

افتح المستودع المستنسخ في Antigravity. ملف->فتح مجلد->اختَر الدليل المستنسخ sdd-adk-agents-agy

أزِل جهاز التحكّم عن بُعد المصدر. تنشئ سير عمل SDD فروع git لمواصفات الميزات، وتؤدي إزالة المستودع البعيد إلى منع إرسال البيانات عن طريق الخطأ إلى مستودع التطبيق الأوّلي:

git remote remove origin

المصادقة باستخدام Google Cloud

نفِّذ أمرَي مصادقة. يفتح كلاهما متصفّحًا لبروتوكول OAuth:

gcloud auth login
gcloud auth application-default login

بما أنّك تعمل على Antigravity بشكل محلي، عليك إثبات ملكية حسابك يدويًا. تتم مصادقة واجهة سطر الأوامر gcloud من خلال auth login. تُصادق application-default login على حِزم تطوير البرامج (SDK) من Google Cloud التي يستخدمها تطبيقك، إذ تعتمد كلّ من طلبات Vertex AI في "حزمة تطوير التطبيقات" وCloud SQL Python Connector على "بيانات الاعتماد التلقائية للتطبيق".

إعداد مشروعك على 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 وبنية Google Cloud Platform الأساسية الأخرى

ملاحظة مهمة: يتم توفير الخطوة أدناه للمساعدة في إعداد مشروع على السحابة الإلكترونية من Google Cloud المرتبط بحساب فوترة تجريبي (محدود)، وإذا كنت تفضّل استخدام مشروعك السابق، يمكنك تخطّي الخطوة التالية وتنفيذ الخطوة التالية بدلاً منها:

أضِف اسم مشروعك كمتغيّر GOOGLE_CLOUD_PROJECT في ملف ‎.env

فعِّل مشروعك في الجهاز الطرفي باستخدام الأمر 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

بعد ذلك، عدِّل ملف .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

بعد ذلك، شغِّل النص البرمجي scripts/setup_database.sh لإعداد جميع البنية الأساسية اللازمة. سيؤدي ذلك إلى ما يلي:

إنشاء مثيل Cloud SQL
التحقّق مما إذا كانت الآلة الافتراضية جاهزة
منح أذونات Vertex AI
إنشاء قاعدة بيانات
قاعدة بيانات المحتوى الأساسي
تشغيل خدمة "أدوات MCP" في الخلفية

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

سيؤدي هذا الأمر إلى تشغيل عملية الإعداد في الخلفية، ويمكنك التحقّق من الناتج بشكل دوري في ملف database_setup.log.

الآن، يجب أن يتوفّر لدينا كل مستودع وكيل ADK المطلوب للبدء. سنتحدث الآن أكثر عن Antigravity والتطوير المستند إلى المواصفات في القسم التالي أثناء انتظار اكتمال كل شيء.

3- استكشاف الرمز الأولي وفهم نهج Spec-Driven Development

تتضمّن هذه الخطوة شرحًا لبنية الرمز الأولي، وعرضًا لمنهجية التطوير المستند إلى المواصفات، وتعبئة قاعدة البيانات، والتأكّد من أنّ الوكيل الأساسي يعمل قبل البدء في توسيعه.

بنية المشروع

افتح مشروع مستودع الرموز البرمجية المستنسخ في محرِّر 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 Toolbox تم تحديد ثلاث أدوات بحث في القائمة: البحث عن الكلمات الرئيسية (search_menu) والبحث الدلالي من خلال pgvector (semantic_search_menu) وفلتر الفئات (get_menu_by_category). لا تتوفّر أدوات الحجز بعد، وسيتمّ إضافتها لاحقًا
server.py: خادم FastAPI بسيط يعرض كيفية الوصول إلى حزمة تطوير التطبيقات ككائن FastAPI. توفر حزمة تطوير التطبيقات (ADK) get_fast_api_app() نقاط نهاية مدمجة، بما في ذلك /run_sse لبث SSE وواجهات برمجة تطبيقات لإدارة الجلسات.

Antigravity Files

.agents/skills/mcp-toolbox-postgres/SKILL.md: مهارة توجّه Antigravity بشأن كيفية إنشاء إعدادات صحيحة لملف tools.yaml في MCP Toolbox. ستعلّمك هذه المهارة كيفية ضبط إعدادات sources وtools وembeddingModels المطلوبة لإنشاء مسار توليد معزّز بالاسترجاع مناسب. لن يتم تفعيل هذه المهارة إلى أن تضيف YAML frontmatter المناسب ليتم التعرّف عليه من خلال Antigravity
.agents/skills/repo-research/SKILL.md: هي مهارة تعلّم Antigravity كيفية تحليل مستودع بشكل تدريجي وإنشاء مستند منظَّم لسياق المشروع. تتّبع هذه الأداة نهجًا من 4 مراحل: الفحص السطحي (شجرة الدليل فقط)، وملفات الإعداد والبيانات الوصفية، ونقاط الدخول ونماذج البيانات، ثم عمليات التدقيق المتعمّق المستهدَفة. تتوقف كل مرحلة وتكتب النتائج قبل الانتقال إلى المرحلة التالية. تظل هذه الميزة غير نشطة إلى أن تضيفوا YAML frontmatter لاحقًا. بعد التفعيل، يمكنك استدعاء هذه الأداة لإنشاء .agents/rules/project-context.md، وهو مستند شامل لإعداد التطبيق يتضمّن البنية والتبعيات في وقت التشغيل وواجهة برمجة التطبيقات ومسرد المصطلحات الخاصة بالمجال.

تطوير مستند إلى المواصفات: من التخطيط المضمّن في Antigravity إلى التطوير المنظَّم المستند إلى المواصفات

تسهّل أدوات المساعدة في الترميز المستندة إلى الذكاء الاصطناعي إنشاء الرموز البرمجية من طلب. المخاطرة: تصف ميزة في جملة واحدة، ويكتب لك المساعد مئات الأسطر، ثم تقبلها لأنّها تبدو صحيحة. يُطلق على هذه العملية أحيانًا اسم "البرمجة الوصفية"، وهي تعني التوجيه حسب الإحساس، أي قبول أو رفض الناتج بناءً على ما إذا كان يبدو مناسبًا. وهي سريعة لإنشاء النماذج الأولية والنصوص البرمجية التي يمكن التخلص منها. ويحدث ذلك عندما يزداد حجم قاعدة الرموز البرمجية، أو عندما تتفاعل الميزات، أو عندما تعيد النظر في الرمز البرمجي بعد أسابيع ولا يمكنك إعادة بناء سبب اتخاذ قرار معيّن.

تضيف عملية التطوير المستند إلى المواصفات (SDD) بنية إلى هذه الحلقة. قبل إنشاء أي رمز، عليك كتابة مواصفات: ما هي وظيفة الميزة، ومن يستفيد منها، وما هي معايير النجاح. يعمل المساعد المستند إلى الذكاء الاصطناعي وفقًا لهذه المواصفات، وكذلك أنت عند مراجعة النتائج التي يعرضها. يصبح المستند المواصفات المصدر الوحيد للحقيقة بشأن النية. إذا كان الرمز البرمجي يختلف عن المواصفات، يمكنك رصد ذلك أثناء المراجعة. في حال تغيّرت المتطلبات، عليك تعديل المواصفات أولاً، ثم إعادة الإنشاء. يتم توثيق القرارات، وليس اتخاذها بشكل مرتجل.

المفاضلة حقيقية: تكون سرعة SDD أقل لكل ميزة من سرعة البرمجة الوصفية. كتابة المستندات قبل كتابة الرمز البرمجي لكنّ الفائدة تتضاعف، فكل تغيير مستقبلي في قاعدة الرموز البرمجية يتضمّن سياقًا، وكل عملية تنفيذ من إنشاء الذكاء الاصطناعي تتضمّن عقدًا قابلاً للمراجعة، ويمكنك إعداد المتعاونين (بشريين أو من الذكاء الاصطناعي) من خلال توجيههم إلى المواصفات بدلاً من شرح القرارات من الذاكرة.

تتّبع Antigravity حاليًا مبادئ التطوير المستند إلى المواصفات. عند ضبط الوكيل على وضع التخطيط، ينتج عنصرَين قبل كتابة أي رمز:

خطة التنفيذ: نظرة عامة على النهج الفني المقترَح والتغييرات في الملفات وقرارات البنية
قائمة المهام: هي تقسيم منظَّم لعناصر العمل

يطلب منك Antigravity مراجعة هذه العناصر والموافقة عليها قبل تنفيذها. تشكّل حلقة التخطيط ثم التنفيذ هذه جوهر عملية التطوير المستندة إلى المواصفات، إذ إنّ المواصفات هي التي توجّه الرمز البرمجي، وليس العكس.

يستند هذا الدرس التطبيقي حول الترميز إلى هذا الأساس، ويقدّم سير عمل محدّدًا ومتحكّمًا في الإصدارات استنادًا إلى spec-kit، وهو إطار عمل لتطوير البرامج يستند إلى المواصفات من GitHub. تخضع كل ميزة لمسار مدروس، حيث يكون كل عنصر عبارة عن مستند مستقل يمكنك مراجعته وتعديله وتتبُّعه في git. تتضمّن عملية التطوير مرحلتَين اختياريتَين لبوابة الجودة (التوضيح والتحليل) لرصد المشاكل قبل أن تصبح مشاكل في التنفيذ:

المرحلة	القطع الأثرية	Purpose
`/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، ويمكن إعادة استخدامه. إذا تمت مقاطعة محادثة أو أردت إعادة النظر في القرارات لاحقًا، ستكون مستندات المواصفات متاحة دائمًا، ولن يتم إخفاؤها في سجلّ المحادثات.

يتضمّن مستودع الرموز البرمجية الأوّلي عمليات سير عمل SDD هذه في .agents/workflows/ ونماذج في .specify/templates/. ستستخدمها لاحقًا لإضافة ميزات إلى الوكيل.

4. بدء مشروع باستخدام Antigravity

الآن، لنحاكي الأمور بشرط "أقرب" إلى عملنا اليومي:

مستودع غير مُدار بشكل جيد
ملف README قديم
عدم تعديل المستندات بشكل متكرّر

أول ما نريد فعله في هذا النوع من المواقف هو عادةً إنشاء خريطة أو سياق حول المشروع الذي نريد أن تعمل عليه Antigravity. تعرض هذه الخطوة مثالاً واحدًا على كيفية منح Antigravity فهمًا عميقًا لقاعدة رموز برمجية حالية من خلال إنشاء مهارة تحلّل المستودع وتنشئ مستندًا لسياق المشروع.

ويتم أيضًا إعداد دستور المشروع، أي المبادئ غير القابلة للتفاوض التي تتحقّق منها عمليات سير عمل SDD. توفّر هذه العناصر معًا السياق والقيود التي تحتاج إليها Antigravity لدورات SDD لاحقًا

التدرّج الهرمي للسياق في Antigravity

تستخدم Antigravity ثلاثة مستويات من السياق، ولكل منها نطاق مختلف:

القواعد (.agents/rules/): تعليمات نشطة دائمًا. يمكن لكل محادثة في مساحة العمل هذه الاطّلاع عليها ( إذا فعّلتها). استخدِم القواعد للحصول على سياق على مستوى المشروع، مثل قرارات التصميم أو معايير الترميز أو معلومات حزمة التكنولوجيا.
المهارات (.agents/skills/): معلومات عند الطلب لا تحمّل Antigravity مهارة إلا عندما تتطابق المهمة الحالية مع حقل description الخاص بالمهارة. استخدام المهارات للحصول على مواد مرجعية خاصة بمجال معيّن
مهام سير العمل (.agents/workflows/): طلبات محفوظة يتم تشغيلها باستخدام أوامر /. استخدِم سير العمل للعمليات المتكررة المتعدّدة الخطوات، مثل مسار SDD.

تفعيل المهارات

يتضمّن مستودع الرموز البرمجية الأولي مهارتَين مكتوبتَين مسبقًا في .agents/skills/. تحتوي هذه الملفات على تعليمات مفصّلة، ولكنها تبدأ بتعليقات TODO(codelab) بدلاً من YAML frontmatter المطلوب. بدون frontmatter، لا يمكن لـ Antigravity اكتشافها.

تتطلّب مهارات Antigravity كتلة frontmatter بتنسيق 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
---

افتح الملف ‎ .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.
---

تأكَّد من أنّ كلتا المهارتين تتضمّنان بيانات أولية صالحة:

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). ومع ذلك، هناك العديد من المهارات الأخرى المفيدة لدعم تطوير البرامج ويمكن تثبيتها بسهولة في وكيل الترميز. على سبيل المثال، في هذا البرنامج التعليمي، يجب التفاعل مع "حزمة تطوير التطبيقات على Android"، وبالتالي سنحتاج إلى معرفة مناسبة حول كيفية إنشاء التطبيقات باستخدام هذه الحزمة. لنثبّت مهارة مستندات 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/Chat في 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 علامة على الانتهاكات باعتبارها "خطيرة". إذا تم ترك الدستور كنموذج فارغ مع رموز مميّزة للقيم النائبة، لن يكون هناك أي شيء يمكن التحقّق منه، وسيتم تنفيذ الخطط والتحليلات بدون ضوابط.

يحدد الدستور مبادئ المشروع غير القابلة للتفاوض. هذا المستودع صغير ويديره مطوّر واحد، لذا يجب أن يعكس الدستور هذا النطاق، أي يجب أن تكون الأمور بسيطة ومتسقة، ويجب تجنُّب التعقيد المفرط.

في "إدارة الوكلاء" (Agent Manager) من 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. تأكَّد من توفّر المبادئ الثلاثة وذكرها بوضوح.

5- دورة تطوير البرامج (SDD) - ميزة إضافة الحجز

توضّح هذه الخطوة دورة كاملة من SDD لإضافة حجز إلى وكيل خدمة العملاء في المطعم. يمكنك استخدام Antigravity خلال كل مرحلة من المراحل التالية: التحديد والتوضيح والتخطيط والمهام والتحليل والتنفيذ، مع مراقبة كيفية استناد كل عنصر إلى العنصر السابق. هذه هي تجربة التعلّم الأساسية في الدرس التطبيقي حول الترميز.

ملاحظة مهمة: ‫Antigravity هو مساعد مستند إلى الذكاء الاصطناعي، وقد تختلف العناصر التي ينشئها (المواصفات والخطط والمهام والرموز البرمجية) عن تلك الموضّحة في هذا البرنامج التعليمي. قد تختلف أسماء الملفات ومخططات SQL الدقيقة وبنية الرموز. هذا أمر متوقّع وهو جزء من عملية التطوير بمساعدة الذكاء الاصطناعي. تضمن سير عمل SDD مراجعة كل عنصر قبل تحويله إلى رمز برمجي، لذا استنِد إلى تقديرك الخاص لقبول أي ناتج لا يتوافق مع توقعاتك أو تعديله أو إعادة إنشائه.

تحديد الميزة

في "إدارة الوكلاء" (Agent Manager) من 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 أسئلة توضيحية، أجب عنها استنادًا إلى وصف الميزة أعلاه.

تركز المواصفات على ماذا ولماذا، وليس على كيف. تصف هذه السمة تجربة المستخدم ("يمكن للضيوف حجز طاولة من خلال تقديم الاسم وعدد الأشخاص والتاريخ والوقت") بدون الإشارة إلى جداول SQL أو 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 خطة فنية من خلال مرحلتَين:

مرحلة البحث: تحلّ المشاكل غير المعروفة في قاعدة الرموز البرمجية الحالية، وتنشئ research.md
مرحلة التصميم: يتم فيها إنشاء 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 المهام، وتضع علامة بجانب كل مهمة عند إكمالها. عند الانتهاء، سيتم عرض الجولة الإرشادية الكاملة.

اختبار تغييرات الرمز

بعد اكتمال عملية التنفيذ، تحقَّق من إجراء التغييرات الرئيسية. قد تختلف أسماء الملفات ومحتواها الدقيق، ولكن يجب أن تكون هذه الأنماط متوفرة كما في 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,
...

من المفترض أن تؤثر التغييرات في نص قاعدة البيانات الأولية. يجب أن ينشئ النص البرمجي المعدَّل الجدول reservations إذا لم يكن موجودًا من قبل. من المفترض أن يظهر لك ناتج يؤكّد أنّه تم إنشاء الجدول الجديد (مع الاحتفاظ ببيانات menu_items الحالية).

إذا سارت الأمور على ما يرام حتى هذه المرحلة، يمكننا اختبار الميزة على واجهة المستخدم المخصّصة للمطوّرين في وكيل ADK. لننفّذ عملية نقل قاعدة البيانات لدمج الجدول الجديد وإعادة تشغيل "مجموعة الأدوات" لاستخدام تعريفات الأداة الجديدة في 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:

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) مرتين باستخدام Ctrl+C.

7. التحديات (اختياري)

أصبحت الآن على دراية بسير عمل SDD الكامل. اختبِر معلوماتك:

نفِّذ دورة ثانية من عملية التصميم والتطوير السريعَين لإنشاء واجهة محادثة على الويب لخدمة الكونسيرج في المطعم، ولكن بدون إرشادات تفصيلية هذه المرة.
نشر الوكيل على Cloud Run في سيناريو الإنتاج

تلميحات

لا يتضمّن المشروع أي إطار عمل للواجهة الأمامية. يجب أن تقترح 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
توضّح دروس الترميز المرجعية كيفية نشر وكيل ADK والحفاظ عليه، لذا يمكنك تقديم مراجع Antigravity إلى هذا.

8. تهانينا!

لقد وسّعت نطاق عمل وكيل ADK الخاص بخدمة الاستقبال في المطعم ليشمل حجز الطاولات، وذلك من خلال سير عمل SDD في Antigravity بالكامل، بدون كتابة الرمز البرمجي للتطبيق يدويًا.

ما أنشأته

وكيل ADK لخدمة الاستقبال في المطاعم يتيح البحث عن قوائم الطعام والبحث الدلالي وتتبُّع الخيارات الغذائية المفضّلة وحجز الطاولات
مهارة Antigravity للبحث في المستودع والتي تنشئ مستندًا لسياق المشروع وتحافظ عليه
دستور مشروع يفرض مبادئ غير قابلة للتفاوض أثناء التخطيط والتحليل
دورة كاملة لتطوير البرامج المستند إلى المواصفات (SDD) توضّح سير العمل "تحديد المواصفات → التوضيح → التخطيط → المهام → التحليل → التنفيذ"

ما تعلّمته

كيفية استخدام سير عمل Spec-Driven Development في Antigravity لإضافة ميزات بشكل منهجي إلى قاعدة رموز برمجية حالية
كيفية إنشاء مهارات Antigravity التي تحزم معرفة المجال لإعادة استخدامها في المحادثات
كيفية إعداد سياق المشروع لكي يتخذ Antigravity قرارات مدروسة بشأن البنية والأنماط وخيارات التكنولوجيا
كيفية ضبط دستور مشروع تتحقّق منه مسارات عمل SDD
كيفية توسيع نطاق وكيل ADK باستخدام أدوات جديدة مستندة إلى قاعدة بيانات من خلال MCP Toolbox

تَنظيم

أوقِف أي عمليات محلية قيد التشغيل (Toolbox):

pkill -f toolbox 2>/dev/null

احذف مثيل Cloud SQL لتجنُّب الرسوم المستمرة:

gcloud sql instances delete restaurant-db --quiet

يمكنك اختياريًا حذف المشروع بأكمله:

gcloud projects delete $GOOGLE_CLOUD_PROJECT