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

1. مقدمة

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

ما ستنشئه

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

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

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

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

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

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

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

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

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

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

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

• git
• gcloud
• uv
• npm

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

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

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

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

افتح المستودع المستنسخ في Antigravity. ملف->فتح مجلد->اختَر الدليل المستنسخ 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. تتم مصادقة حِزم تطوير البرامج (SDK) في Google Cloud التي يستخدمها تطبيقك، إذ تعتمد كلّ من طلبات Vertex AI في ADK وCloud SQL Python connector على "بيانات الاعتماد التلقائية للتطبيق".application-default login

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

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

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

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

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 بسيط يعرض كيفية الوصول إلى ADK ككائن FastAPI. توفّر get_fast_api_app() من "حزمة تطوير التطبيقات" نقاط نهاية مدمجة، بما في ذلك /run_sse لبث SSE وواجهات برمجة التطبيقات لإدارة الجلسات.

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، وهو مستند شامل لإعداد التطبيق يتضمّن البنية والتبعيات في وقت التشغيل وواجهة برمجة التطبيقات ومسرد المصطلحات الخاصة بالمجال.

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

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

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

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

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

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

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

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

يتم الاحتفاظ بكل عنصر كملف في 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 كتلة بيانات وصفية تمهيدية بتنسيق 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 وتجلب التعليمات الكاملة فقط عندما تكون ذات صلة.

إعداد MCP في مستندات ADK

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

أولاً، من محرر Antigravity، ابحث عن رمز "علامة الحذف" في أعلى يسار نافذة الوكيل وانقر عليه، وستظهر لك خيارات الإعداد الخاصة بـ MCP والتخصيص على النحو التالي. انقر على MCP.

\

بعد ذلك، انقر على الزر Manage MCP servers

سيتم فتح علامة التبويب الخاصة بإعدادات خوادم MCP، ثم انقر على الزر View Raw Config

سيتم فتح ملف mcp_config.json. الآن، انسخ هذا الإعداد والصقه في الملف

{
    "mcpServers": {
        "adk-docs-mcp": {
            "command": "uvx",
            "args": [
                "--from",
                "mcpdoc",
                "mcpdoc",
                "--urls",
                "AgentDevelopmentKit:https://adk.dev/llms.txt",
                "--transport",
                "stdio"
            ]
        }
    }
}

سيسمح هذا الإعداد لوكيل الترميز بالبحث عن مستندات ADK وقراءتها باستخدام خادم MCP

تثبيت مهارات متاحة للجميع

لقد فحصنا سابقًا المهارات التي أنشأناها بأنفسنا ( المهارتان repo-research وmcp-toolbox-postgres). ومع ذلك، هناك العديد من المهارات الأخرى المفيدة لدعم تطوير البرامج ويمكن تثبيتها بسهولة في وكيل الترميز.

Caveman Skills

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

npx skills add JuliusBrussee/caveman

كما فعلنا سابقًا، لنحدّد مهارة caveman هنا في الوقت الحالي.

بعد ذلك، ما عليك سوى النقر على Enter للانتقال إلى الخيار الآخر لتفعيل التثبيت التلقائي وتثبيت المهارة في مشروعك الحالي.

الآن، من المفترض أن يكون لدينا 4 مهارات تم إعدادها وجاهزة لبدء رحلة SDD

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

إنشاء سياق المشروع

تأكَّد من توفّر دليل القواعد:

mkdir -p .agents/rules

في مربّع "إدارة الوكلاء"/"المحادثة" في Antigravity (في وضع التعديل، اضغط على ctrl + L)، ابدأ محادثة جديدة. النوع:

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

تطابق Antigravity طلبك مع مهارة repo-research وcaveman ( أمر للتواصل بكفاءة)، وتبدأ في تحليل قاعدة الرموز البرمجية بشكل منهجي. يقرأ ملفات الإعدادات ورمز المصدر والمستندات، ثم يملأ نموذج سياق المشروع بالنتائج التي يتوصّل إليها.

بعد اكتمال العملية، افتح .agents/rules/project-context.md في المحرِّر. يتضمّن معلومات ملموسة حول المشروع: مجموعة التكنولوجيات (Python 3.12 وADK وMCP Toolbox وCloud SQL) وبنية المشروع ونموذج البيانات (جدول 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 Cycle — Add Reservation Feature

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

تحديد الميزة

في "إدارة الوكلاء" (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. Utilize your access to ADK Docs tools and MCP toolbox skill to implement it properly

تُنشئ Antigravity خطة فنية من خلال مرحلتَين:

1. مرحلة البحث: يتم فيها حلّ المشاكل غير المعروفة في قاعدة الرموز البرمجية الحالية، وإنشاء research.md
2. مرحلة التصميم: يتم فيها إنشاء data-model.md (تعريف عنصر الحجوزات) وتعديل project-context.md

يجب أن تستخدم Antigravity أدوات MCP في مستندات ADK ومهارة مستندات MCP Toolbox أثناء التخطيط. راجِع البيانات الرئيسية:

• 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 الكامل. اختبار الميزة:

• نفِّذ دورة ثانية من عملية التصميم المستند إلى البيانات (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 للبحث في المستودع، والتي تنشئ مستندًا لسياق المشروع وتحافظ عليه
• دستور مشروع يفرض مبادئ غير قابلة للتفاوض أثناء التخطيط والتحليل
• دورة كاملة لتطوير البرامج المستندة إلى البيانات توضّح سير العمل "تحديد → توضيح → تخطيط → مهام → تحليل → تنفيذ"

ما تعلّمته

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

تَنظيم

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

lsof -ti:5000 | xargs kill -9 2>/dev/null

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

gcloud sql instances delete restaurant-db --quiet

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT