AGENTS.md

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

سير عمل بدء التشغيل

قبل تغيير الكود:

1. تأكد من جذر المستودع باستخدام pwd.
2. اقرأ ARCHITECTURE.md للاطلاع على خريطة النظام الحالية وقواعد التبعيات الثابتة.
3. اقرأ docs/QUALITY_SCORE.md لمعرفة المجالات أو الطبقات الأضعف.
4. اقرأ docs/PLANS.md، ثم افتح الخطة النشطة التي تعمل وفقًا لها.
5. اقرأ مواصفات المنتج ذات الصلة في docs/product-specs/.
6. شغّل مسار الإعداد والتحقق القياسي لهذا المستودع.
7. إذا كان التحقق الأساسي يفشل، أصلح الأساس قبل إضافة نطاق جديد.

خريطة التوجيه

• ARCHITECTURE.md: خريطة المجالات، نموذج الطبقات، قواعد التبعيات
• docs/design-docs/index.md: قرارات التصميم والمعتقدات الأساسية
• docs/product-specs/index.md: سلوكيات المنتج الحالية وأهداف القبول
• docs/PLANS.md: دورة حياة الخطط وسياسة خطط التنفيذ
• docs/QUALITY_SCORE.md: صحة مجالات المنتج والطبقات
• docs/RELIABILITY.md: إشارات التشغيل، معايير الأداء، وتوقعات إعادة التشغيل
• docs/SECURITY.md: الأسرار، الحماية الرملية، البيانات، وقواعد الإجراءات الخارجية
• docs/FRONTEND.md: قيود واجهة المستخدم، قواعد نظام التصميم، وفحوصات إمكانية الوصول

عقد العمل

• اعمل وفق خطة محددة أو شريحة ميزة واحدة في كل مرة.
• لا تعتبر العمل منتهيًا من فحص الكود فقط؛ الأدلة القابلة للتنفيذ مطلوبة.
• إذا غيّرت سلوكًا، حدِّث وثائق المنتج أو الخطة أو الموثوقية المطابقة في نفس الجلسة.
• إذا لاحظت ملاحظات مراجعة متكررة،حوّلها إلى قاعدة آلية أو فحص أو أداة تنسيق بدلاً من إعادة شرحها في المحادثة.
• أبقِ المواد المُولَّدة في docs/generated/ والمراجع المصدرية في docs/references/.
• فضِّل إضافة وثائق صغيرة وحالية بدلاً من توسيع هذا الملف.

تعريف الإنجاز

التغيير يُعتبر منتهيًا فقط عندما يكون جميع ما يلي صحيحًا:

• السلوك المستهدف مُنفَّذ
• التحقق المطلوب تم تشغيله فعلًا
• الأدلة مرتبطة من الخطة أو وثيقة الجودة ذات الصلة
• الوثائق المتأثرة لا تزال محدثة
• المستودع يمكن إعادة تشغيله بنظافة من مسار بدء التشغيل القياسي

نهاية الجلسة

قبل إنهاء جلسة:

1. حدِّث خطة التنفيذ النشطة.
2. حدِّث docs/QUALITY_SCORE.md إذا تغيّر أي مجال أو طبقة بشكل ملحوظ.
3. سجّل الديون الجديدة في docs/exec-plans/tech-debt-tracker.md إذا أجلتها.
4. انقل الخطط المنتهية إلى docs/exec-plans/completed/ عند الاقتضاء.
5. اترك المستودع في حالة قابلة لإعادة التشغيل مع إجراء تالٍ واضح.