فحص قاعدة كود غير مألوفة
استخدم IBM Bob لفهم تطبيق غير مألوف بسرعة، مثل غرضه وهيكل المشروع والمعمارية ومكدس التقنيات والمكونات الرئيسية وتغطية الاختبارات ونموذج النشر. يمكنك فعل ذلك دون الاعتماد على توثيق قديم أو انتظار الزملاء.
الإنتاجية في قاعدة كود غير مألوفة عادةً تعني ساعات من قراءة الكود والبحث عن التوثيق وسؤال الزملاء عن السياق. في هذا الدرس، ستستخدم Bob في وضع Ask لاستجواب قاعدة كود Galaxium Travels بشكل منهجي واستخلاص صورة كاملة عن التطبيق: غرضه ومعماريته، ومكدس التقنيات، والمكونات الرئيسية، وتغطية الاختبارات الوحدوية والتكاملية، ونموذج النشر. ثم تبدّل إلى وضع Agent لحفظ كل ما اكتشفه Bob في مرجع Markdown دائم يمكن لفريقك بأكمله استخدامه.
Galaxium Travels هو تطبيق معقد عمداً يشبه التطبيقات الواقعية، مع واجهة React أمامية وخلفية Python FastAPI وخدمة جرد Java Spring Boot. هذا يجعله مرشحاً قوياً لهذا سير العمل.
مخرجات Bob تتفاوت اعتماداً على الحالة الراهنة لقاعدة الكود. عامل الأمثلة في هذا الدرس كنقاط انطلاق تمثيلية وليست نصوصاً حرفية. استخدمها لضبط طلباتك الخاصة وتحسين النتائج.
الميزات الرئيسية التي ستتعلمها
- وضع Ask: استكشاف وتحليل الكود دون أن يُعدِّل Bob أي ملفات.
- وضع Agent: السماح لـ Bob بكتابة الملفات بشكل مستقل لحفظ النتائج المُولَّدة في مشروعك.
- Context mentions: الإشارة إلى ملفات ومجلدات محددة بـ
@لمنح Bob نطاقاً دقيقاً للتحليل. /init: تهيئة سياق المشروع حتى يفهم Bob اصطلاحات قاعدة الكود قبل البدء في طرح الأسئلة.
المتطلبات الأساسية
لإكمال هذا الدرس، تحتاج إلى:
- Bob IDE مثبت.
- Git مثبت محلياً.
- إلمام بأساسيات استخدام Bob. إذا كنت جديداً على Bob، أكمل درس البدء السريع أولاً.
إعداد مساحة عملك
استنساخ مستودع Galaxium Travels
في الـ terminal، استنسخ المستودع النموذجي:
git clone https://github.com/IBM/galaxium-travels.gitفتح المشروع النموذجي
في Bob IDE، افتح مجلد galaxium-travels الذي استنسخته للتو. إذا سأل Bob "Do you trust the authors of the files in the folder?"، انقر على Yes, I trust the authors.
فتح واجهة دردشة Bob
إذا لم تكن واجهة الدردشة مفتوحة بالفعل، انقر على أيقونة Bob في شريط التنقل أو استخدم الاختصار Option + Command + B (Mac) أو Ctrl + Alt + B (Windows).
تهيئة سياق المشروع
Bob يبدأ في وضع Agent افتراضياً. قبل تبديل الأوضاع، نفّذ الأمر /init حتى يقرأ Bob المشروع ويُولِّد ملفات سياق AGENTS.md التي يستخدمها في التفاعلات اللاحقة.
/initإذا كانت الموافقة التلقائية معطلة، يطلب Bob إذناً لقراءة الملفات وكتابة ملفات AGENTS.md. وافق على كل طلب. ينشئ Bob ملف AGENTS.md على مستوى الجذر ومجلد .bob/ بتكوين خاص بكل وضع.
راجع AGENTS.md المُولَّد للتأكد من أن Bob حدد بشكل صحيح الهيكل متعدد الخدمات للمستودع.
التبديل إلى وضع Ask
اختر Ask في محدد الوضع أسفل حقل إدخال الدردشة، أو اكتب /ask للتبديل بين الأوضاع. وضع Ask للقراءة الصارمة فقط. يُحلِّل Bob الملفات لكنه لا يستطيع إنشاء أو تعديل أي شيء، مما يجعله الوضع الصحيح لجميع أعمال الاستكشاف في هذا الدرس.
فهم غرض التطبيق وهيكل المشروع
ابدأ بالسؤال الأشمل: ما الذي يفعله هذا التطبيق، وكيف تنظم قاعدة الكود؟ يقرأ Bob هيكل المشروع والملفات الرئيسية مثل README.md وpackage.json وrequirements.txt وملفات البناء والتكوين الأخرى. يُجمع Bob ملخصاً موجزاً دون الحاجة إلى تتبع كل مجلد يدوياً.
في وضع Ask، أدخل الطلب التالي:
What is the purpose of this application? Describe the project structure,
the high-level architecture, and the main responsibilities of each top-level
directory.يقرأ Bob شجرة الملفات ونقاط الدخول الرئيسية، ثم ينتج مخرجات تتضمن:
- غرض التطبيق
- مسؤوليات المجلدات على المستوى الأعلى
- ملخص محتويات كل مجلد على المستوى الأعلى
- مخطط معمارية على مستوى عال
تحليل مكدس التقنيات
مع توضح الهيكل على مستوى عال، تعمق في التقنيات المستخدمة بالضبط. هذا الطلب مفيد عندما تحتاج إلى فهم أدوات البناء، أو تقييم خيارات التبعيات، أو تقييم نطاق الترقية.
في وضع Ask، أدخل الطلب التالي:
Analyze the tech stack for the entire application. For each service, list the
programming language, runtime version requirements, framework, key libraries,
database, and build/test tooling.يفحص Bob التبعيات وملفات التكوين لكل خدمة وينتج مخرجات تتضمن:
- تحليل مفصّل لمكدس التقنيات لكل خدمة
- تحديد إطار اختبارات النهاية إلى النهاية
- أدوات إضافية من مكدس CI/CD ونصوص النشر
- مخطط "مكدس التقنيات في لمحة" الذي يُلخِّص مكدس التقنيات بصرياً عبر جميع الخدمات والطبقات
تحديد المكونات الرئيسية
فهم مكدس التقنيات يُخبرك بما تستخدمه قاعدة الكود؛ فهم المكونات الرئيسية يُخبرك بكيفية عملها. يطلب هذا الطلب من Bob تتبع حدود المكونات وتدفقات البيانات عبر الخدمات الثلاث، وهو مفيد بشكل خاص قبل إجراء تغييرات تمتد عبر حدود الخدمات.
في وضع Ask، أدخل الطلب التالي مع mentions السياق لتوجيه Bob نحو الملفات الأكثر صلة:
Identify the key components of this application and explain how they interact.
Reference @booking_system_frontend/src/services,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/models.py,
and @booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.
Describe the component responsibilities, the data flow for the booking
lifecycle, and any cross-service contracts I need to know before modifying
the codebase.يتتبع Bob سلسلة التفاعل وينتج مخرجات تحتوي على:
- مسؤوليات تفصيلية للواجهة الأمامية وطبقة API الخلفية وطبقة قاعدة البيانات وخدمة الجرد Java
- تفصيل مخطط لتدفقَي دورة حياة الحجز مع تعليقات توضيحية على تفاعلات المكونات
- ملخص للعقود الخمسة بين الخدمات التي يجب معرفتها قبل إجراء التغييرات
- خريطة تفاعل المكونات
تقييم تغطية الاختبارات الوحدوية
قبل إضافة الميزات أو إعادة الهيكلة، تحتاج إلى معرفة ما تغطيه مجموعة الاختبارات الموجودة وأين توجد الفجوات. يطلب هذا الطلب من Bob قراءة ملفات الاختبار وإنتاج تقييم التغطية دون تشغيل الاختبارات.
في وضع Ask، أدخل الطلب التالي:
Analyze the unit test suites across all three services. Reference
@booking_system_backend/tests,
@booking_system_inventory_hold_service/src/test,
and @booking_system_frontend/src.
For each service, describe what is tested, which testing framework is used,
what the test structure looks like, and identify any obvious gaps where
critical logic appears to be untested.يقرأ Bob ملفات الاختبار وينتج تحليلاً مفصّلاً لمجموعة الاختبارات يتضمن:
- إطار الاختبار والفئات الخاضعة للاختبار وعدد الاختبارات لكل فئة وما يتم التحقق منه لكل فئة
- فجوات حرجة في الاختبار
- تغطية اختبار مفقودة للمنطق التجاري الحرج
تقييم تغطية الاختبارات التكاملية والشاملة
الاختبارات الوحدوية تُخبرك بما إذا كانت المكونات الفردية تعمل بمعزل؛ الاختبارات التكاملية والشاملة تُخبرك بما إذا كانت الخدمات تعمل بشكل صحيح معاً. هذا مهم بشكل خاص لـ Galaxium Travels لأن تدفق تأكيد الحجز يمتد عبر الخدمات الثلاث.
في وضع Ask، أدخل الطلب التالي:
Analyze the end-to-end and integration test coverage. Reference
@tests_e2e and any cross-service test fixtures you can identify.
Describe which cross-service flows are covered, which are not, what test
infrastructure is required to run the suite, and what the tests assert
at the boundary level.يقرأ Bob مجموعة اختبارات النهاية إلى النهاية ويُولِّد تحليلاً مفصّلاً يتضمن:
- البنية التحتية للاختبار ومتطلبات تشغيل المجموعة
- اختبارات الدخان
- قرارات البنية التحتية الرئيسية
- التدفقات بين الخدمات المُغطَّاة وغير المُغطَّاة
- تأكيدات الاختبار على مستوى الحدود
مراجعة نموذج النشر
فهم كيفية نشر التطبيق (منصاته المستهدفة واستراتيجية الحاويات وأتمتة البنية التحتية) ضروري قبل الانضمام كمساهم أو قبل تشغيل التطبيق في أي مكان بعيداً عن حاسوبك الشخصي.
في وضع Ask، أدخل الطلب التالي:
Analyze the deployment model for this application. Reference
@docker-compose.yml, @deployment_scripts, @terraform, @.github/workflows,
and the deployment documentation in @docs.
Describe the supported deployment targets, how each service is containerized,
what infrastructure is provisioned, and how CI/CD is configured.يقرأ Bob نتائج النشر وينتج تحليلاً لنموذج النشر يتضمن:
- أهداف النشر المدعومة
- استراتيجية الحاويات لكل خدمة
- تفاصيل توفير البنية التحتية
- سير عمل CI/CD
- قيود النشر الرئيسية والفجوات
حفظ النتائج في المستودع
التحليل الذي أجريته في وضع Ask يعيش فقط في جلسة الدردشة. بدّل إلى وضع Agent لطلب Bob كتابة وثيقة مرجعية للتأهيل الدائمة في المستودع، حتى يستفيد المساهمون المستقبليون من هذا العمل.
التبديل إلى وضع Agent
اختر Agent في محدد الوضع، أو اكتب /agent في حقل إدخال الدردشة.
إنشاء مرجع التأهيل
اطلب من Bob دمج كل ما اكتشفه في ملف Markdown واحد. لدى Bob السياق الكامل للمحادثة ويُجمّع النتائج دون إعادة قراءة جميع الملفات.
Create a file called docs/ONBOARDING.md.
Create one section for each of these topics:
1. Application overview: purpose, project structure, high-level architecture, and the main responsibilities of each top-level directory.
2. Tech stack analysis, including a "Stack at a Glance" diagram.
3. Key components and their interactions, including a component interaction map.
4. Unit test coverage analysis.
5. End-to-end test coverage analysis.
6. Deployment model analysis.
Populate each section with everything you discovered in this session.
Use clear headings, Mermaid diagrams, and tables where appropriate. Keep the tone concise and technical.يكتب Bob الملف. إذا كانت الموافقة التلقائية معطلة، انقر على Approve عندما يطلب Bob إذناً لكتابة docs/ONBOARDING.md.
التحقق من المخرجات
افتح docs/ONBOARDING.md في المحرر للتأكد من احتواء الوثيقة على كل المحتوى المتوقع. يمكنك أيضاً طلب من Bob معاينته:
Show me a preview of docs/ONBOARDING.mdيُرنِّد Bob ملف Markdown في واجهة الدردشة. راجع المحتوى للتأكد من دقته واكتماله قبل الـ commit.
عمل commit للملف
استخدم سير عمل Git المفضل لديك لعمل commit لـ docs/ONBOARDING.md في مستودعك. الوثيقة متاحة الآن لكل مساهم وللـ Bob نفسه في الجلسات المستقبلية.
استكشاف الأخطاء وإصلاحها
تحليل Bob ضحل أو يفتقر إلى خدمات
بشكل افتراضي، يقرأ Bob هيكل المشروع ومجموعة من الملفات الرئيسية. إذا كانت المخرجات تفتقر إلى خدمة أو أقل تفصيلاً مما هو متوقع، أضف mentions سياق صريحة لتضييق تركيز Bob.
مثلاً، إذا لم تنعكس خدمة Java في تحليل مكدس التقنيات، أضف @booking_system_inventory_hold_service/pom.xml إلى الطلب.
Bob لا يمكنه إيجاد ملفات الاختبار
إذا أبلغ Bob عن عدم قدرته على إيجاد ملفات الاختبار، استخدم mention سياق للإشارة مباشرةً إلى مجلدات الاختبار.
تحليل نشر Bob يغفل هدفاً
نتائج النشر لـ AWS وIBM Cloud والنشر المحلي موزعة عبر عدة مجلدات على المستوى الأعلى. إذا كان ملخص النشر من Bob غير مكتمل، وجّهه بالمجلدات المحددة.
/init يُولِّد AGENTS.md فارغاً أو غير صحيح
في جذر مساحة العمل، يبني أمر /init سياق المشروع من خلال قراءة الملفات المرساة مثل README.md وpackage.json وrequirements.txt وpom.xml وMakefile والبيانات التعريفية المشابهة. إذا لم يوجد أي من هذه الملفات في الجذر، أو إذا كانت جذر مساحة العمل مُعيَّناً على مجلد فرعي، فسيرى Bob جزءاً فقط من المشروع ويُولِّد AGENTS.md متفرقاً أو غير صحيح.
تحقق من التالي:
- جذر مساحة العمل: تأكد من أن
galaxium-travels/وليس مجلد فرعي مفتوح كجذر لمساحة العمل. - الملفات المرساة المفقودة: إذا كان الجذر يفتقر إلى
README.mdأو بيانات تعريفية أخرى، أضف ملفREADME.mdعلى مستوى الجذر مع وصف موجز للمشروع، ثم أعد تشغيل/init.
تقييس سلوك Bob
قيّس سلوك Bob عبر فريقك باستخدام ملفات قواعد على مستوى المشروع تُوجِّه Bob لتوثيق كوده وتذكر إجراءاته السابقة.
توليد مخططات المعمارية
استخدم IBM Bob لتحليل قاعدة كود Galaxium Travels وتوليد مخططات UML للفئات، ومخططات التسلسل، ومخططات حالة الاستخدام باستخدام Mermaid. تعلم كيفية استخدام mentions السياق في وضع Ask لاستكشاف الكود ووضع Agent لحفظ النتائج في مستودعك.