Skills: مهارات مراجعة الكود
آخر تحديث: 2026-08-31
مراجعة الكود هي خط الدفاع الأول عن الجودة — مهارة مراجعة ممتازة كوجود مراجع أول لا يكل في الفريق.
1. تصميم أبعاد المراجعة
(1) أبعاد المراجعة الأساسية
| البُعد | عناصر الفحص | الخطورة |
|---|---|---|
| الأمان | حقن SQL، XSS، مفاتيح مشفرة بشكل ثابت، تبعيات غير آمنة | 🔴 حرج |
| الأداء | استعلامات N+1، تسريبات الذاكرة، حلقات غير ضرورية | 🟡 مهم |
| القراءة | اصطلاحات التسمية، طول الدوال، كفاية التعليقات | 🟢 اقتراح |
| أفضل الممارسات | معالجة الأخطاء، مبادئ SOLID، DRY | 🟡 مهم |
| تغطية الاختبارات | اختبارات الوحدة، الشروط الحدية، مسارات الاستثناء | 🟡 مهم |
(2) أبعاد خاصة باللغة
MARKDOWN
## فحوصات إضافية لـ Python
- اكتمال تلميحات الأنواع
- تنسيق Docstring (أسلوب Google/NumPy)
- f-string مقابل format/concat
- نطاق التقاط الاستثناءات (تجنب except العاري)
## فحوصات إضافية لـ TypeScript
- استخدام نوع any
- معقولية تأكيدات الأنواع
- اكتمال تعريفات الواجهات
- تعليقات توضيحية للخصائص الاختيارية
2. تصميم عملية المراجعة
(1) العملية القياسية
TEXT
📖 للعرض فقط
عملية مراجعة الكود
├── 1. جمع التغييرات
│ ├── اقرأ git diff (قائمة الملفات المتغيرة)
│ └── حدد نطاق المراجعة
├── 2. مراجعة ملف بملف
│ ├── اقرأ محتويات الملف
│ ├── Grep للسياق ذي الصلة
│ └── فحص عبر الأبعاد
├── 3. إخراج التقرير
│ ├── رتب حسب الخطورة
│ ├── قدّم اقتراحات إصلاح محددة
│ └── أدرج أمثلة كود
└── 4. التقييم الختامي
├── الدرجة الإجمالية
└── توصية الدمج
(2) المراجعة التزايدية مقابل الكاملة
| النوع | النطاق | حالة الاستخدام |
|---|---|---|
| مراجعة تزايدية | مراجعة الأجزاء المتغيرة فقط | مراجعة PR/MR |
| مراجعة كاملة | مراجعة الوحدة بالكامل | مراجعة كود مطور جديد، تحقق بعد إعادة الهيكلة |
3. تنسيق تقرير المراجعة
(1) قالب المخرجات القياسي
MARKDOWN
## تقرير مراجعة الكود
### 📊 نظرة عامة
- الملفات المراجعة: 3
- المشاكل المكتشفة: 5 (🔴 1 / 🟡 2 / 🟢 2)
- الدرجة الإجمالية: 7/10
- التوصية: ⚠️ دمج بعد إصلاح المشاكل الحرجة
### 🔴 المشاكل الحرجة
**[SEC-001] خطر حقن SQL**
📍 الموقع: src/auth/login.py:42
📝 استخدام ربط النصوص لبناء استعلام SQL
✅ الاقتراح:
```python
query = "SELECT * FROM users WHERE name = ?"
cursor.execute(query, (username,))
🟡 المشاكل المهمة
...
🟢 اقتراحات التحسين
...
### (2) نظام التسجيل
```text
قواعد التسجيل:
- 🔴 مشكلة حرجة: -3 نقاط لكل منها
- 🟡 مشكلة مهمة: -1 نقطة لكل منها
- 🟢 اقتراح: -0.5 نقطة لكل منها
- الدرجة الأساسية: 10 نقاط
- الحد الأدنى: 0 نقطة
توصية الدمج:
- ≥ 8 نقاط: ✅ يُوصى بالدمج
- 5-7 نقاط: ⚠️ دمج بعد الإصلاحات
- < 5 نقاط: ❌ لا يُوصى بالدمج
4. ممارسة مهارة المراجعة
▶ مثال: مهارة مراجعة كاملة الأبعاد
أنشأت Alice مهارة مراجعة موحدة للفريق:
YAML
---
name: full-review
description: "مراجعة كود كاملة الأبعاد"
triggers:
- keyword: "full-review"
tools:
- Read
- Grep
- Glob
- Bash
---
MARKDOWN
## عملية المراجعة
1. Glob لتحديد نطاق الملفات للمراجعة
2. لكل ملف، فحص حسب البُعد:
- الأمان: Grep للأنماط الخطيرة
- الأداء: Read لتحليل تعقيد الخوارزمية
- القراءة: تحقق من التسمية والهيكل
- الاختبارات: تأكد من تغطية الاختبارات
3. تجميع وإخراج تقرير المراجعة
علّق Bob: "التقارير الموحدة تجعل نتائج المراجعة واضحة بنظرة — الأحمر يجب إصلاحه، الأصفر يعتمد، الأخضر لطيف وجوده."
❓ الأسئلة الشائعة
س هل المراجعات الصارمة جدًا تبطئ التطوير؟
ج نعم. نوصي بمستويين — مراجعات PR تفحص الأمان والمنطق الحرج فقط؛ المراجعات الدورية الكاملة تغطي جميع الأبعاد.
س هل يمكن للمراجعة بالذكاء الاصطناعي أن تحل محل المراجعة اليدوية؟
ج ليس بالكامل. الذكاء الاصطناعي يتفوق في مطابقة الأنماط والمسح الأمني؛ البشر يتفوقون في مراجعة البنية والحكم على المنطق التجاري. الاثنان يكملان بعضهما بشكل أفضل.
س كيف أتجنب تقارير المراجعة الطويلة جدًا؟
ج اضبط تصفية الخطورة؛ المخرجات الافتراضية فقط المشاكل 🟡 وما فوق. اقتراحات 🟢 مخرجات اختيارية.
📖 ملخص
- خمسة أبعاد للمراجعة: الأمان، الأداء، القراءة، أفضل الممارسات، تغطية الاختبارات
- العملية القياسية: جمع التغييرات → مراجعة ملف بملف → إخراج التقرير → التقييم الختامي
- تنسيق التقرير: نظرة عامة + مشاكل مصنفة + درجة + توصية دمج
- نظام التسجيل: مقياس 10 نقاط، خصومات حسب خطورة المشكلة
📝 تمارين
- أساسي (⭐): أنشئ مهارة مراجعة أمنية تفحص حقن SQL وXSS والمفاتيح المشفرة بشكل ثابت فقط.
- متوسط (⭐⭐): أنشئ مهارة مراجعة كاملة الأبعاد تُخرج تقرير مراجعة قياسي مع تسجيل وتوصية دمج.
- متقدم (⭐⭐⭐): أنشئ مهارة مراجعة تزايدية تراجع فقط التغييرات في git diff، وتُعدّل أبعاد المراجعة تلقائيًا حسب اللغة.