تطوير وكيل "حزمة تطوير الوكلاء" المستند إلى المواصفات باستخدام 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: تزويد الوكلاء بالأدوات
إنشاء وكلاء ذكاء اصطناعي دائمين باستخدام ADK وCloudSQL
نشر وكيل ADK وإدارته ومراقبته على Cloud Run
استخدام قاعدة البيانات كأداة: التوليد المعزّز بالاسترجاع (RAG) المستنِد إلى الذكاء الاصطناعي الوكيل باستخدام ADK وMCP Toolbox وCloud SQL

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

ملاحظات مهمة:

يتطلّب هذا البرنامج التعليمي مشروعًا على Google Cloud مع حساب فوترة نشط. إذا لم يكن لديك حساب بعد، يُرجى اتّباع الخطوات التالية للحصول على حساب فوترة تجريبي يمكن استخدامه في هذا البرنامج التعليمي:

فتح نافذة التصفُّح المتخفي
إذا كنت ستنضم إلى جلسة ورشة عمل، سيتم عادةً تقديم عنوان URL لبوابة الاسترداد في الجلسة، وإلا يمكنك الانتقال إلى بوابة استرداد حساب الفوترة التجريبي.
سجِّل الدخول باستخدام حسابك الشخصي على Gmail ( لن تعمل حسابات Google Workspace أو عناوين البريد الإلكتروني الأخرى). )
اتّبِع تعليمات تحصيل القيمة المفصّلة.

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

استنساخ مستودع التطبيق النموذجي

افتح وحدة طرفية في 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

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

شغِّل النص البرمجي للمتطلبات الأساسية. يبحث عن git وcurl وgcloud وuv وPython 3.12 وMCP Toolbox (ويثبّتها إذا لم تكن متوفّرة):

bash scripts/setup_prerequisites.sh

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

توفير Cloud SQL

اضبط كلمة مرور قاعدة البيانات وأضِفها إلى .env:

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

أنشئ مثيل Cloud SQL:

gcloud sql instances create restaurant-db \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --region=${REGION} \
  --availability-type=ZONAL \
  --tier=db-custom-1-3840 \
  --root-password=${DB_PASSWORD} \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on &

إنّ مستوى db-custom-1-3840 هو الحدّ الأدنى المطلوب لدمج تعلُّم الآلة في Vertex AI. تتيح العلامة --enable-google-ml-integration لخدمة Cloud SQL استدعاء نماذج التضمين من Gemini مباشرةً من SQL، ما يتيح استخدام ميزة البحث الدلالي.

تثبيت الحِزم التابعة

افتح علامة تبويب جديدة في الوحدة الطرفية. تأكَّد من أنّك لا تزال في دليل مشروع مستودع الرموز البرمجية المستنسخ وأعِد تحميل متغيرات البيئة:

source .env

سنستخدم 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

الآن، يجب أن يتوفّر لدينا كل مستودع وكيل 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)
│   │   ├── adk-agent-development/
│   │   │   ├── SKILL.md     # ADK patterns
│   │   │   └── examples/
│   │   │       ├── basic_agent.py
│   │   │       ├── Dockerfile
│   │   │       ├── server.py
│   │   │       ├── stateful_agent.py
│   │   │       ├── toolbox_agent.py
│   │   │       ├── tools_agent.py
│   │   │       └── tools.yaml
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis 
│   └── 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/adk-agent-development/SKILL.md: مهارة تم ضبطها مسبقًا ( تم إنشاؤها باستخدام Antigravity) تحتوي على أنماط مرجعية مكثّفة من جميع دروس ADK البرمجية الأربعة. وهي غير نشطة حاليًا (لا تتضمّن YAML frontmatter)، لذا عليك تعديلها لاحقًا. تحمّل Antigravity هذه المهارة تلقائيًا عندما ترصد عملًا مرتبطًا بميزات وكيل ADK وأمثلتها، وهي المعرفة التي ترشد Antigravity عند التخطيط لميزة الحجز لاحقًا.
.agents/skills/repo-research/SKILL.md: هي مهارة تعلّم Antigravity كيفية تحليل مستودع بشكل تدريجي وإنشاء مستند منظَّم لسياق المشروع. تستخدِم هذه الأداة نهجًا من 4 مراحل: الفحص السطحي (شجرة الدليل فقط)، وملفات الإعداد والبيانات الوصفية، ونقاط الدخول ونماذج البيانات، ثم عمليات التدقيق المستهدَفة. تتوقف كل مرحلة وتكتب النتائج قبل الانتقال إلى المرحلة التالية. وكما هو الحال مع مهارة ADK، تظل هذه الميزة غير نشطة إلى أن تضيف 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. إكمال عملية إعداد Cloud SQL والتأكّد من أنّ الوكيل الأساسي يعمل بشكل سليم

ارجع إلى علامة تبويب الوحدة الطرفية التي يتم فيها تنفيذ أمر إنشاء Cloud SQL. بعد اكتمالها، تحقَّق من أنّ الجهاز الظاهري جاهز:

gcloud sql instances describe restaurant-db --format="value(state)"

إذا كانت المخرجات تعرض RUNNABLE، يمكنك المتابعة. إذا ظهرت PENDING_CREATE، انتظِر لحظة وأعِد تنفيذ الأمر.

امنح حساب خدمة Cloud SQL إذن الوصول إلى Vertex AI (مطلوب لوظيفة التضمين داخل قاعدة البيانات):

SERVICE_ACCOUNT=$(gcloud sql instances describe restaurant-db --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

أنشئ قاعدة البيانات:

gcloud sql databases create restaurant_db --instance=restaurant-db

من المفترض أن تظهر لك النتيجة على النحو التالي

Creating Cloud SQL database...done.
Created database [restaurant_db].
instance: restaurant-db
name: restaurant_db
project: <your-project-id>

تعبئة قاعدة البيانات

حمِّل متغيرات البيئة وشغِّل نص برمجي لإنشاء قاعدة البيانات من أجل إنشاء المخطط وإدراج 16 عنصرًا من عناصر القائمة:

source .env
uv run python scripts/seed_db.py

الناتج المتوقّع:

Creating extensions...
Creating menu_items table...
Inserting 16 menu items...
Seeded 16 menu items.
Done.

إنشاء تضمينات متجهة للبحث الدلالي:

uv run python scripts/generate_embeddings.py

الناتج المتوقّع:

Generating embeddings for 16 menu items...
Generated embeddings for 16 menu items.

يستخدم هذا الإجراء الدالة embedding() المضمّنة في Cloud SQL (من خلال الإضافة google_ml_integration) لاستدعاء gemini-embedding-001 مباشرةً من SQL. يتم تخزين المتجهات ذات 3072 بُعدًا في العمود embedding من menu_items، بدون الحاجة إلى رمز التضمين من جهة التطبيق.

اختبار الوكيل الأساسي

ابدأ تشغيل MCP Toolbox كعملية في الخلفية:

set -a; source .env; set +a # Export env variables to child process
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

تعرض "مجموعة الأدوات" أدوات قواعد البيانات عبر HTTP. يتواصل موظّف الدعم مع الجهاز عند الساعة http://127.0.0.1:5000.

ابدأ واجهة مستخدم مطوّر ADK:

uv run adk web .

افتح واجهة مستخدم أدوات المطوّرين في المتصفّح. بعد ذلك، اختبِر الوكيل باستخدام الطلبات التالية:

What appetizers do you have?

I'm vegetarian

Can I make a reservation for tomorrow?

أوقِف واجهة مستخدم مطوّر ADK بالضغط على Ctrl+C مرّتين. اترك "صندوق الأدوات" يعمل في الخلفية، فستحتاج إليه لاحقًا

5- تهيئة سياق المشروع باستخدام 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/adk-agent-development/SKILL.md

في المحرِّر استبدِل سطرَي التعليق TODO(codelab) في الأعلى بما يلي:

---
name: adk-agent-development
description: Comprehensive guide for building, developing, and deploying AI agents using Google's Agent Development Kit (ADK) with Gemini models, covering agent creation, tools, state management, persistence, deployment, and database integration via MCP Toolbox.
---

افتح

.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/adk-agent-development/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

يجب أن يعرض كلّ منها محدّدات --- تحيط بالحقلَين name: وdescription:. في حال عدم توفّر المحددات أو الحقول، لن يتعرّف Antigravity على المهارة.

يتم تحميل كلتا المهارتين عند الطلب، إذ تطابق Antigravity طلبك مع الحقل description وتجلب التعليمات الكاملة فقط عندما تكون ذات صلة.

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

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

mkdir -p .agents/rules

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

Research this repository and create a project context document

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

بعد اكتمال العملية، افتح .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. تأكَّد من توفّر المبادئ الثلاثة وذكرها بوضوح.

6. دورة تطوير البرامج (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

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

7. التنفيذ

نفِّذ سير عمل التنفيذ:

/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,
...

يجب أن تؤثّر التغييرات في نص قاعدة البيانات الأولية، فلنحاول تنفيذه

source .env
uv run python scripts/seed_db.py

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

إذا سارت الأمور على ما يرام حتى هذه النقطة، يمكننا اختبار الميزة على واجهة المستخدم المخصّصة للمطوّرين في وكيل ADK. أعِد تشغيل "صندوق الأدوات" لاختيار تعريفات الأدوات الجديدة باللغة tools.yaml. أوقِف أي عملية حالية في Toolbox، ثم ابدأ عملية جديدة:

pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &