حافظ على تزامن التوثيق مع قاعدة الكود

السيناريو 1: التوثيق الأولي للمشروع

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

إعداد مساحة العمل

1. افتح المستودع في IBM Bob IDE.
2. افتح واجهة دردشة Bob: Option + Command + B (macOS) أو Ctrl + Alt + B (Windows).

إنشاء سياق قابل للقراءة من الذكاء الاصطناعي باستخدام /init

الخطوة الأولى هي تزويد Bob بمعرفة عن مشروعك. انتقل إلى وضع Agent ثم شغّل:

/init

يفحص Bob المستودع وينشئ:

• AGENTS.md في جذر المستودع (سياق المشروع الرئيسي)
• .bob/rules-code/AGENTS-code.md (سياق خاص بوضع Agent)
• .bob/rules-plan/AGENTS-plan.md (سياق خاص بوضع Plan)
• .bob/rules-ask/AGENTS-ask.md (سياق خاص بوضع Ask)

تحتوي هذه الملفات على:

• بنية الكود والأدلة الرئيسية
• الحزمة التقنية والاعتماديات
• أوامر البناء والاختبار والتحقق من التنسيق
• أنماط الكود واصطلاحاته

أهمية ذلك: تعمل ملفات AGENTS.md هذه كقواعد معرفة يرجع إليها Bob في كل محادثة. وبدلًا من إعادة تحليل قاعدة الكود كاملةً في كل مرة، يمتلك Bob سياقًا مستمرًا عن مشروعك.

مراجعة السياق المنشأ

افتح AGENTS.md وراجع ما اكتشفه Bob:

cat AGENTS.md

سترى ملخصًا منظّمًا لمشروعك. إذا أغفل Bob تفاصيل مهمة، مثل قواعد العمل أو اصطلاحات النشر أو ممارسات الفريق، فعدّل AGENTS.md لإضافتها. هذا الملف مصمم ليُخصّص.

إنشاء وضع Docs Architect

أنشئ الآن وضعًا مخصصًا ينتج توثيقًا موجّهًا للمستخدمين. يستخدم هذا الوضع سياق AGENTS.md لإنشاء توثيق للبشر، لا للذكاء الاصطناعي.

1. انقر أيقونة settings في لوحة Bob لفتح الإعدادات.
2. اختر علامة التبويب Modes.
3. انقر أيقونة + لإنشاء وضع جديد.
4. املأ القيم التالية:

في حقل Mode-specific Custom Instructions، انسخ النص التالي والصقه:

When documenting a project:
1. Review AGENTS.md files to understand project structure and technical details
2. Create user-facing documentation (READMEs, getting started guides, tutorials)
3. Avoid duplicating technical details from AGENTS.md (build commands, code patterns)
4. Focus on user workflows, conceptual overviews, and practical code examples
5. Include code blocks with clear explanations
6. Add docstrings and JSDoc comments to improve code quality

Generate:
- README.md explaining project purpose and navigation
- CONTRIBUTING.md with onboarding steps for new contributors
- Getting started guide with code snippets
- Conceptual documentation explaining architectural decisions

انقر Save.

ينشئ Bob ملف custom_modes.yaml في .bob يحتوي على إعداد وضع Docs Architect. يمكنك تعديل هذا الملف مباشرة لإجراء تغييرات مستقبلية.

إنشاء التوثيق الأولي

انتقل إلى وضع Docs Architect وأدخل الطلب التالي:

I've run /init to establish project context. Please create comprehensive documentation for this project:

1. Review AGENTS.md to understand the project structure
2. Create a README.md with:
   - Project overview and purpose
   - Quick start guide with code examples
   - Project structure explanation
   - Links to additional documentation
3. Create CONTRIBUTING.md with:
   - Development setup instructions
   - How to run tests
   - How to submit a pull request
   - Code style guidelines
4. Identify gaps in the codebase that need better documentation (missing docstrings, unclear functions)

Focus on making the technical details from AGENTS.md accessible to new developers.

ينشئ Bob ملفات التوثيق. راجعها للتأكد من دقتها، وأجرِ التعديلات، ثم أرسل التغييرات:

git add AGENTS.md .bob/ README.md CONTRIBUTING.md
git commit -m "docs: initial project documentation with AI assistance"

النتيجة: انتقلت من توثيق محدود إلى توثيق شامل خلال دقائق بدلًا من ساعات.

السيناريو 2: توثيق ميزة جديدة

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

إليك كيفية سد هذه الفجوة باستخدام Bob.

كتابة الميزة بمساعدة Bob

أثناء التطوير، انتقل إلى وضع Agent كي يساعدك Bob في التنفيذ. ولأن Bob لديه بالفعل سياق للمشروع من تشغيل /init في السيناريو 1، فإنه يفهم بنية الكود والاعتماديات والاصطلاحات، فتكون اقتراحاته أكثر صلة من البدء من الصفر.

اكتب الميزة كما تفعل عادةً، واستخدم Bob لإكمال الكود أو إعادة الهيكلة أو طرح أسئلة عن قاعدة الكود الحالية.

تشغيل /init مجددًا لتحديث سياق الذكاء الاصطناعي

بعد تنفيذ الميزة، يصبح سياق Bob قديمًا لأنه أُنشئ قبل وجود الكود الجديد. حدّثه:

/init

يعيد Bob فحص المستودع ويحدّث AGENTS.md ليعكس التغييرات، مثل الوحدات الجديدة والاعتماديات المحدّثة وأنماط الكود الجديدة التي يكتشفها.

تحقّق من أن التحديث التقط تغييراتك:

git diff AGENTS.md .bob/

إذا أظهر الفرق ميزتك الجديدة، فسيكون Bob جاهزًا لإنشاء توثيق دقيق. وإذا غاب شيء مهم، فعدّل AGENTS.md يدويًا قبل المتابعة.

إنشاء توثيق للميزة الجديدة

انتقل الآن إلى وضع Docs Architect. لأنك حدّثت AGENTS.md للتو، يمتلك Bob صورة دقيقة للميزة الجديدة ويمكنه إنشاء توثيق يعكس التنفيذ الفعلي لا تخمينًا.

أخبر Bob بما يحتاج إلى تحديث:

I've added a new feature to the project. Please update the documentation:

1. Add a section to README.md explaining:
   - What the feature does
   - How to configure and use it
   - A code snippet showing basic usage
2. Update CONTRIBUTING.md if the development workflow has changed
3. Create a dedicated docs page that covers:
   - How the feature works
   - Relevant API endpoints or interfaces
   - Code examples for common use cases
   - Code explanations for non-obvious logic
   - Troubleshooting tips

Include code blocks with clear explanations. Add docstrings to any functions that lack them.

راجع التوثيق المنشأ للتأكد من دقته، وتحقق تحديدًا من أن أمثلة الكود تطابق تنفيذك، ثم أرسل كل شيء معًا:

git add src/ AGENTS.md .bob/ README.md CONTRIBUTING.md docs/
git commit -m "feat: add [feature name] with documentation"

النتيجة: تُطوّر الميزتك وتوثيقها معًا ويُرسلان في طلب السحب نفسه.

السيناريو 3: مراجعة الكود مع فحوصات التوثيق

أرسل أحد أعضاء الفريق طلب سحب يضيف نقطة نهاية API جديدة. تحتاج إلى التأكد من تحديث التوثيق.

مراجعة تغييرات الكود

git diff main feature-branch

ترى نقاط نهاية API جديدة، لكن لا توجد تحديثات للتوثيق.

التحقق مما إذا كان /init قد شُغّل

git diff main feature-branch -- AGENTS.md .bob/

إذا لم توجد تغييرات في AGENTS.md، فهذا يعني أن المطوّر لم يشغّل /init. اطلب منه:

1. تشغيل /init لتحديث سياق الذكاء الاصطناعي
2. استخدام Docs Architect لتحديث التوثيق الموجّه للمستخدمين

إنشاء التوثيق الناقص

إذا كنت تراجع طلب السحب، يمكنك إنشاء التوثيق بنفسك:

git checkout feature-branch

في Bob، شغّل /init، ثم انتقل إلى وضع Docs Architect:

I'm reviewing a pull request that adds new API endpoints. Please update the documentation:

1. Review the new endpoints in src/api/
2. Update README.md with a brief mention of the new endpoints
3. Update docs/api.md with:
   - Endpoint descriptions
   - Request/response examples with code blocks
   - Authentication requirements
   - Error codes
4. Add JSDoc comments to the endpoint handlers if missing

Focus on making the API easy to understand for other developers.

أرسل تحديثات التوثيق:

git add AGENTS.md .bob/ README.md docs/api.md src/api/
git commit -m "docs: add documentation for new API endpoints"
git push

النتيجة: يصبح التوثيق جزءًا من عملية مراجعة الكود، لا خطوة لاحقة.

السيناريو 4: تأهيل عضو جديد في الفريق

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

اطلب منه تشغيل /init

يستنسخ المطوّر الجديد المستودع ويشغّل:

/init

ينشئ Bob ملفات AGENTS.md حديثة تعكس الحالة الحالية لقاعدة الكود. يمكن للمطوّر الجديد الآن:

1. قراءة AGENTS.md لفهم بنية المشروع
2. قراءة README.md للحصول على تعليمات البدء
3. قراءة CONTRIBUTING.md لفهم سير عمل التطوير

استخدام وضع Ask للاستكشاف

يمكن للمطوّر الجديد استخدام وضع Ask في Bob لاستكشاف قاعدة الكود:

@src/auth Explain how authentication works in this project

@src/api What API endpoints are available and what do they do?

@tests How do I run tests for a specific module?

يجيب Bob باستخدام السياق من AGENTS.md وكود المصدر الفعلي.

إنشاء توثيق تأهيل مخصص

إذا كان مشروعك يفتقر إلى توثيق التأهيل، فاستخدم Docs Architect:

Create an onboarding guide for new developers joining this project:

1. Prerequisites (tools, accounts, access)
2. Initial setup steps with code blocks
3. How to run the project locally
4. How to run tests
5. Overview of the codebase structure
6. Common development tasks with examples
7. Where to find help

Make it practical and include code snippets for each step.

النتيجة: يستطيع أعضاء الفريق الجدد بدء العمل خلال ساعات بدلًا من أيام.

السيناريو 5: صيانة التوثيق مع مرور الوقت

ظل مشروعك قيد التطوير لأشهر. تغيّر الكود بدرجة كبيرة، وبدأ التوثيق في الابتعاد عن الواقع.

اكتشاف انحراف التوثيق

شغّل /init لمعرفة ما تغيّر:

/init

راجع الفرق:

git diff AGENTS.md .bob/

تشير التغييرات الكبيرة إلى تطور مهم في الكود. وهذه إشارة إلى أن التوثيق الموجّه للمستخدمين يحتاج إلى تحديث.

تحديث التوثيق بصورة منهجية

استخدم Docs Architect لتحديث التوثيق:

I've run /init and noticed significant changes to the project structure. Please review and update the documentation:

1. Review AGENTS.md changes to understand what's different
2. Update README.md to reflect current project structure
3. Update CONTRIBUTING.md if development workflow has changed
4. Identify any new features that lack documentation
5. Remove documentation for deprecated features
6. Update code examples to match current API

Focus on accuracy—make sure documentation matches the current codebase.

وضع جدول للصيانة

أضف تحديثات التوثيق إلى سير عملك المعتاد:

• شهريًا: شغّل /init وراجع التغييرات
• قبل الإصدارات: حدّث جميع ملفات التوثيق
• بعد عمليات إعادة الهيكلة الكبرى: أعد إنشاء التوثيق المتأثر
• في مراجعات الكود: تحقّق من تشغيل /init وتحديث التوثيق

أتمتة اكتشاف الانحراف (متقدم)

بالنسبة إلى الفرق التي ترغب في فرض جودة التوثيق في CI، أضف فحصًا لطلبات السحب يتحقق من حداثة AGENTS.md و.bob/. يشغّل الفحص /init على الفرع، ثم يفشل إذا اختلف الناتج عما أُرسل، ما يدل على أن المطوّر نسي تحديث سياق الذكاء الاصطناعي قبل فتح طلب السحب. اقرن ذلك بقائمة التحقق في قالب طلب السحب ضمن قسم أفضل الممارسات لجعل تحديثات التوثيق جزءًا مطلوبًا من عملية المراجعة.

النتيجة: يبقى التوثيق متزامنًا مع الكود من خلال صيانة منتظمة.