مراجعة PR من Claude Code: معاينات الاختلافات أسرع وأكثر أمانًا

لماذا تستغرق مراجعات PR وقتًا أطول\n\nنادرًا ما تستغرق مراجعات PR وقتًا طويلاً لأن الشيفرة "صعبة" فقط. السبب في التأخر هو أن المراجع يجب أن يعيد بناء النية والمخاطر والأثر من diff يعرض التغييرات، وليس القصة كاملة.\n\nتعديل بسيط قد يلمس تبعيات خفية: إعادة تسمية حقل وكسر تقرير، تغيير قيمة افتراضية وتحول السلوك، تعديل شرط وتغير التعامل مع الأخطاء. يزداد وقت المراجعة عندما يضطر المراجع للتنقل للحصول على السياق، تشغيل التطبيق محليًا، وطرح أسئلة متابعة فقط لفهم ما المقصود من PR.\n\nهناك أيضاً مشكلة نمط بشري. الناس يمرّون على diffs بطرق متوقعة: نركز على "التغيير الرئيسي" ونفوت السطور المملة التي تختبئ فيها الأخطاء (فحوصات الحدود، التعامل مع null، التسجيل، التنظيف). كما نميل إلى قراءة ما نتوقع رؤيته، لذا قد تمرّ أخطاء النسخ واللصق أو الشروط المقلوبة دون ملاحظة.\n\nالمراجعة المسبقة الجيدة ليست حكما. إنها مجموعة سريعة ومنظمة من العيون تشير إلى الأماكن التي يجب أن يبطئ عندها المراجع البشري. أفضل ناتج هو:\n\n- ملخّص باللغة البسيطة عما تغيّر\n- نقاط مخاطرة محددة (ملفات، دوال، فروض)\n- ملاحظات عن قابلية القراءة (التسمية، تدفق التحكم المربك)\n- مخاوف صحيحة (المنطق، التعامل مع الأخطاء، اتساق البيانات)\n- حالات طرفية تستحق الاختبار (المدخلات، الوقت، الأذونات، الحالات الفارغة)\n\nما يجب ألا تفعله: "الموافقة" على PR، اختراع متطلبات، أو التخمين عن سلوك وقت التشغيل دون دليل. إذا لم يتضمن الـ diff سياقًا كافياً (المدخلات المتوقعة، القيود، عقود المستدعين)، يجب أن تقول المراجعة المسبقة ذلك وتدرج بالضبط ما الناقص.\n\nمساعدة الذكاء الاصطناعي أقوى في PRs متوسطة الحجم التي تمس منطق الأعمال أو إعادة التهيئة حيث يمكن أن يضيع المعنى. إنها أضعف عندما يعتمد الجواب الصحيح على معرفة عميقة خاصة بالمنظمة (سلوك قديم، خصائص أداء الإنتاج، قواعد أمان داخلية).\n\nمثال: PR يقول "فقط يحدث ترقية في الترقيم (pagination)" غالبًا ما يخفي أخطاء صفحة بواحد، نتائج فارغة، وعدم تطابق الترتيب بين API والواجهة. يجب أن ترفع المراجعة المسبقة هذه الأسئلة قبل أن يقضي إنسان 30 دقيقة في إعادة اكتشافها.\n\n## ماذا تطلب من Claude أن يفعل في المراجعة المسبقة\n\nعامل Claude كمراجع أولي سريع ومتطلب، وليس الشخص الذي يقرر ما إذا كان PR ينشر. الهدف هو كشف المشاكل مبكرًا: الشيفرة المربكة، تغيّرات السلوك الخفية، الاختبارات المفقودة، والحالات الطرفية التي تنساها وأنت قريب من التغيير.\n\nزودها بما يحتاجه مراجع بشري عادل:\n\n- هدف الـ PR (1 إلى 3 جمل)\n- ما يجب ألا ينكسر (شكل الـ API، التوافق العكسي، ميزانية الأداء، قواعد الأمان)\n- أي قيود أو مقايضات خاصة (مواعيد نهائية، نشر جزئي)\n- قطع diff ذات الصلة، مع كفاية من الشيفرة المحيطة لفهم النية\n\nإذا لمس PR منطقة معروفة عالية المخاطر، اذكر ذلك مقدمًا (المصادقة، الفوترة، الهجرات، التزامن).\n\nثم اطلب مخرجات قابلة للفعل. طلب قوي يبدو كالتالي:\n\n- لخّص ما تغيّر بلغة بسيطة.\n- اشر إلى مشاكل القابلية للقراءة (التسميات، البنية، المفاجآت، أنماط غير متسقة).\n- حدّد مخاطر الصواب (التعامل مع null، مسارات الخطأ، off-by-one، عدم تطابق شكل البيانات).\n- ادرج حالات طرفية أو أوضاع فشل للاختبار (المهلات، المحاولات، المدخلات الفارغة، التحديثات الجزئية).\n- اقترح اختبارات مفقودة وما يبرهن عنه كل اختبار.\n- قدم قائمة تحقق قصيرة للمراجع و5 إلى 10 "أسئلة لطرحها" قبل الدمج.\n\nحافظ على بقاء الإنسان مسؤولاً عبر إجبار الوضوح عند عدم اليقين. اطلب من Claude وسم النتائج كـ "مؤكد من diff" مقابل "يحتاج تأكيدًا"، وأن يقتبس السطور الدقيقة التي أثارت كل قلق.\n\n## حضّر الـ diff والسياق قبل أن ترسل الطلب\n\nClaude جيد بقدر ما تعرضه عليه. إذا لصقت diff ضخمًا بلا هدف أو قيود، ستحصل على نصائح عامة وتفوت المخاطر الحقيقية.\n\nابدأ بهدف ملموس ومعايير نجاح. على سبيل المثال: "يضيف هذا PR تحديد معدل لواجهة تسجيل الدخول للحد من الإساءة. لا يجب أن يغير شكل الاستجابة. يجب أن يحافظ متوسط الكمون تحت 50 ملّي ثانية."\n\nبعدها، تضمّن فقط ما يهم. إذا تغيّرت 20 ملفًا لكن 3 فقط تحتوي على المنطق، ركّز على تلك. أدرج سياقًا محيطًا عندما يكون المقتطف مضللًا، مثل تواقيع الدوال، الأنواع الرئيسية، أو الإعداد الذي يغيّر السلوك.\n\nوأخيرًا، كن صريحًا بشأن توقعات الاختبارات. إذا كنت تريد اختبارات وحدة لحالات الطرف، اختبار تكاملي لمسار حرج، أو تشغيل يدوي للواجهة، اذكر ذلك. إذا كانت الاختبارات مفقودة عمدًا، فسِّب السبب.\n\nحزمة سياق بسيطة تعمل جيدًا:\n\n- هدف PR: ما تغيّر، ماذا يرى المستخدم، وما الذي سيتحسن\n- قطع diff ذات الصلة: الملفات الرئيسية فقط، مع كفاية شيفرة محيطة\n- قيود صارمة: ميزانيات الأداء، متطلبات التوافق، قواعد الأمان/الخصوصية\n- توقعات الاختبار: ما يجب تغطيته، ما أضيف، كيف تشغله\n- عناصر "يجب ألا تتغير": عقود API العامة، مخطط قاعدة البيانات، سلوك UX، تنسيق التسجيل/التدقيق\n\n## خطوة بخطوة: سير مراجعة مسبقة يمكن تكراره\n\nمراجعة Claude Code PR جيدة تعمل كحلقة ضيقة: زودها بسياق كافٍ، احصل على ملاحظات منظمة، ثم حوّلها إلى إجراءات. لا تحل محل البشر. تمسك الأخطاء السهلة قبل أن يقضي زميل وقتًا طويلاً في القراءة.\n\n### تدفق من 5 مرورَات\n\nاستخدم نفس المرات كل مرة حتى تبقى النتائج متوقعة:\n\n1. اشرح التغيير بلغة بسيطة. اطلب من Claude تلخيص ما يفعله PR، الملفات التي تغيّرت، والسبب المحتمل للتغيير. إذا لم يستطع شرحه ببساطة، فربما يحتاج PR لوصف أو نطاق أوضح.\n2. افحص الصواب أولاً. ابحث عن أخطاء منطقية، فروض مكسورة، وتغيّرات سلوكية صامتة (القيم الافتراضية، تعامل الأخطاء، الأذونات، المناطق الزمنية، off-by-one).\n3. امسح بحثًا عن الحالات المفقودة. فكر كمستخدم وكبيئة إنتاج: مدخلات فارغة، nulls، المحاولات المتكررة، الفشل الجزئي، التزامن، التوافق الخلفي.\n4. راجع القابلية للقراءة والصيانة. حدد التسميات المربكة، الدوال الطويلة، تكرار المنطق، التعليقات غير الواضحة، وإصلاحات صغيرة تقلّل وقت المراجعة في المستقبل.\n5. صغ تعليقات مراجعة مع مؤشرات. جمّع التعليقات حسب الملف واذكر اسم الدالة أو مقتطف مقتبس لكي يعثر المراجع البشري على المكان بسرعة.\n\nبعد أن تحصل على الملاحظات، حوّلها إلى بوابة دمج قصيرة:\n\nقائمة دمج (اجعلها قصيرة):\n- الاختبارات تغطي السلوك الجديد وعلى الأقل حالة طرفية واحدة\n- الأخطاء تُعالج باستمرار (وتُسجل إذا اقتضى الأمر)\n- لا تغيير كاسح دون مسار هجرة واضح\n- التسمية والبنية تواكب الشيفرة القريبة\n- للأجزاء الخطرة خطة تراجع\n\nاختم بطلب 3 إلى 5 أسئلة تجبر على الوضوح، مثل: "ماذا يحدث إذا أعاد API قائمة فارغة؟" أو "هل هذا آمن تحت طلبات متزامنة؟"\n\n## استخدم معيارًا بسيطًا (قابلية القراءة، الصواب، الحالات الطرفية)\n\nClaude أكثر فائدة عندما تعطيه عدسة ثابتة. بدون معيار، يميل إلى التعليق على ما يقفز أولًا (غالبًا ملاحظات أسلوبية) وقد يفوت حالة حدود خطيرة واحدة.\n\nمعيار عملي:\n\n- قابلية القراءة: أسماء واضحة، تدفق بسيط، دوال قصيرة، تعليقات تشرح لماذا، لا شيفرة ميتة أو مخرجات تصحيح متبقية.\n- الصواب: الضمانات الرئيسية محفوظة، الأخطاء تُعالج باستمرار، القيم null/الفارغة آمنة، الحدود صحيحة (off-by-one، التقريب).\n- الحالات الطرفية: مدخلات فارغة/ضخمة، حقول اختيارية مفقودة، المناطق الزمنية والصيف/شتاء، محاولات قد تسبب كتابة مزدوجة، سباقات التزامن.\n- الأمان والخصوصية: فحوصات المصادقة في المكان الصحيح، لا أسرار في الشيفرة/السجلات، السجلات لا تكشف رموزًا أو حمولات حساسة.\n- التوافق وسلامة النشر: العملاء الأقدمون والبيانات المخزنة لن تنكسر، الهجرات آمنة، وخطة التراجع موجودة.\n\nعند الطلب، اطلب فقرة قصيرة لكل فئة واطلب "أعلى مشكلة مخاطرة أولًا." ذلك الترتيب يحافظ على تركيز البشر.\n\n## قوالب طلبات تعطي ملاحظات مراجعة مفيدة\n\nاستخدم قالب طلب قابل لإعادة الاستخدام حتى تبدو النتائج متشابهة عبر PRs. ألصق وصف PR ثم الـ diff. إذا كان السلوك موجهًا للمستخدم، أضف سلوكًا متوقعًا في 1 إلى 2 جملة.\n\ntext\nYou are doing a pre-review of a pull request.\n\nContext\n- Repo/service: <name>\n- Goal of change: <1-2 sentences>\n- Constraints: <perf, security, backward compatibility, etc>\n\nInput\n- PR description:\n<...>\n- Diff (unified diff):\n<...>\n\nOutput format\n1) Summary (max 4 bullets)\n2) Readability notes (nits + suggested rewrites)\n3) Correctness risks (what could break, and why)\n4) Edge cases to test (specific scenarios)\n5) Reviewer checklist (5-10 checkboxes)\n6) Questions to ask the author before merge (3-7)\n\nRules\n- Cite evidence by quoting the relevant diff lines and naming file + function/class.\n- If unsure, say what info you need.\n\n\nللتغييرات عالية المخاطر (المصادقة، المدفوعات، الأذونات، الهجرات)، أضف تفكيرًا صريحًا بالفشل وخطة التراجع:\n\ntext\nExtra focus for this review:\n- Security/privacy risks, permission bypass, data leaks\n- Money/credits/accounting correctness (double-charge, idempotency)\n- Migration safety (locks, backfill, down path, runtime compatibility)\n- Monitoring/alerts and rollback plan\nReturn a “stop-ship” section listing issues that should block merge.\n\n\nفي عمليات إعادة الهيكلة، اجعل "عدم تغيير السلوك" قاعدة صارمة:\n\ntext\nThis PR is a refactor. Assume behavior must be identical.\n- Flag any behavior change, even if minor.\n- List invariants that must remain true.\n- Point to the exact diff hunks that could change behavior.\n- Suggest a minimal test plan to confirm equivalence.\n\n\nإذا أردت مسحًا سريعًا، أضف حدًا مثل "أجب ضمن 200 كلمة". إذا أردت عمقًا، اطلب "حتى 10 نتائج مع السبب."\n\n## حوّل النواتج إلى قائمة تحقق للمراجع\n\nتصبح ملاحظات Claude مفيدة عندما تحولها إلى قائمة تحقق قصيرة يمكن للبشر إغلاقها. لا تعيد صياغة الـ diff. التقط المخاطر والقرارات.\n\nاقسم البنود إلى فئتين حتى لا يتحول النقاش إلى جدالات تفضيلية:\n\nيجب الإصلاح (حظر الدمج)\n- [ ] الصواب: النتيجة المتوقعة مكتوبة في جملة واحدة وتطابق التذكرة\n- [ ] الحالات الطرفية: المدخلات الفارغة/null ومسارات الخطأ معالجَة أو رُفضَت بوضوح\n- [ ] سلامة البيانات: الكتابات والهجرات آمنة للبيانات الحالية والشيفرة القديمة\n- [ ] الاختبارات: اختبار واحد على الأقل يغطي السلوك الرئيسي واختبار واحد يغطي أخطر فشل\n- [ ] القابلية للمراقبة: سجلات/مقاييس كافية لتصحيح سريع (معرف الطلب، معرف المستخدم، معرف المهمة)\n\nمن الجيد أن تتوفر (متابعات)\n- [ ] قابلية القراءة: أعد تسمية أكثر معرف مربك أو أضف تعليقًا قصيرًا يشرح "لماذا"\n- [ ] الاتساق: طابق الأنماط الموجودة للأخطاء، التسمية، وتخطيط الملفات\n- [ ] الأداء: لاحظ تغييرات المسارات الساخنة وهل تؤثر على المقياس الحالي\n- [ ] التوثيق: حدّث الوثائق المضمنة إذا أضيف خيار/علم جديد\n\nسجّل أيضًا جاهزية النشر: ترتيب النشر الأكثر أمانًا، ما يجب مراقبته بعد النشر، وكيف تلغي التغيير.\n\n## أسئلة لطرحها قبل الدمج\n\nالمراجعة المسبقة تفيد فقط إذا انتهت بمجموعة صغيرة من الأسئلة التي تجبر على الوضوح.\n\n### السلوك والصواب\n\n- أي سلوك مرئي للمستخدم يتغير، وما الذي يجب أن يبقى كما هو؟\n- إذا كان هذا "بدون تغيير سلوكي"، ما الدليل أن المخرجات متطابقة؟\n- ما أسوأ فشل محتمل في الإنتاج، وأين سيظهر (الواجهة، الـ API، البيانات)؟\n- ما الافتراضات التي تضعها الشيفرة عن المدخلات، الترتيب، الوقت، أو استدعاءات الشبكة؟\n- هل تُبتلع أخطاء أو تُحوّل إلى قيم افتراضية صامتة؟\n\n### الحالات الطرفية، الاختبارات، والعمليات\n\n- ما أسوأ المدخلات الحقيقية (فارغة، ضخمة، تالفة، مكررة)، وماذا يجب أن يحدث؟\n- أي تدفق شائع قد يفعّل هذا مرتين (محاولات، نقرة مزدوجة، مهام خلفية)، وهل هذا آمن؟\n- أي اختبار يثبت السلوك الرئيسي، وأي اختبار يغطي أخطر حالة طرفية؟\n- إذا كان اختبار مفقودًا، هل صعب كتابته أم أن الشيفرة صعبة للاختبار؟\n- ماذا ستحتاج العمليات: سجلات ومقاييس وتنبيهات افادة وخطوات تراجع؟\n\nإذا لم تستطع الإجابة بعبارات بسيطة، أوقف الدمج وشدّد النطاق أو أضف دليلًا.\n\n## المصائد الشائعة (وكيف تتجنبها)\n\nمعظم الإخفاقات مشكلات عملية، لا نموذجية.\n\n- إلصاق diffs ضخمة بلا تركيز. اطلب مراجعة على 1 إلى 3 مناطق خطرة وألصق فقط القطع ذات الصلة مع التواقيع التي تعتمد عليها.\n- تخطي النية والسلوك المتوقع. بدون هدف، تتيه المراجعة. أضف سطرين: ماذا تغير، وما الذي يجب ألا يتغير.\n- الثقة بالتخمينات الواثقة. اطلب اقتباسات إلى الـ diff. إذا لم يستطع الاقتباس، عاملها كفرضية يجب اختبارها.\n- الانشغال بخلاف الجوهر (bikeshedding). اطلب "يجب الإصلاح" مقابل "جيد أن يتوفر"، وقيّد ملاحظات الأسلوب.\n- تجاهل معايير الفريق. إذا لدى فريقك توافقات (إرجاع مبكر، أنواع أخطاء، تنسيق التسجيل)، أدرجها.\n\nإذا أضاف PR نقطة إنهاء الدفع (checkout) جديدة، لا تلصق الخدمة كلها. ألصق المعالج، التحقق، كتابة قاعدة البيانات، وأي تغيّر في المخطط. ثم اذكر: "الهدف: منع الشحن المزدوج. غير الأهداف: إعادة تسمية." ستحصل على تعليقات أقل، وأسهل في التحقق.\n\n## مثال واقعي: مراجعة مسبقة لPR صغير\n\nPR صغير حقيقي: إضافة حقل "اسم العرض" إلى شاشة الإعدادات. يمس التحقق (الخادم) ونص الواجهة (العميل). صغير بما يكفي للتفكير، لكنه يحتوي أماكن يختبئ فيها خطأ.\n\nإليك أمثلة لقطع diff تلصقها (بالإضافة إلى 2-3 جمل سياق مثل السلوك المتوقع وأي تذاكر ذات صلة):\n\ndiff\n- if len(name) == 0 { return error("name required") }\n+ if len(displayName) < 3 { return error("display name too short") }\n+ if len(displayName) > 30 { return error("display name too long") }\n\n\ndiff\n- <TextInput label="Name" value={name} />\n+ <TextInput label="Display name" value={displayName} helperText="Shown on your profile" />\n\n\nأمثلة على النتائج التي تريدها:\n\n- قابلية القراءة: يُستعمل "displayName" مقابل "name" بشكل مختلط عبر الملفات. اختر مصطلحًا واحدًا حتى لا تحتاج التغييرات المستقبلية للترجمة الذهنية.\n- الصواب: الخادم يتحقق من الطول، لكن العميل لا. يمكن للمستخدمين كتابة 1 أو 2 حرفًا ولن يروا الخطأ إلا بعد الإرسال.\n- حالة طرفية: السلاسل المكوّنة من مسافات فقط تمرّ len(displayName) لكنها تبدو فارغة. قصّ الفراغات قبل التحقق.\n\nحوّل ذلك إلى قائمة تحقق:\n\n- التسمية متسقة عبر API، حقول قاعدة البيانات، وتسميات الواجهة.\n- الفحوصات على جهة العميل تطابق قواعد الخادم (الحد الأدنى/الحد الأقصى، إلزامي).\n- يتم قص المدخل (وسلوك Unicode/الرموز التعبيرية مقبول).\n- رسائل الخطأ واضحة ومتطابقة بين الخادم والواجهة.\n\n## فحوصات سريعة، قياس، والخطوات التالية\n\nتنجح مراجعة Claude Code PR عندما تنتهي بعدد قليل من الفحوصات السريعة:\n\n- السلوك: ما الذي يتغير للمستخدم، وما يجب ألا يتغير\n- الاختبارات: ما المغطى، ما المفقود، وما قد يترنح\n- السجلات والأخطاء: الفشل واضح ورسائل مفيدة\n- الأداء: حلقات جديدة، استعلامات N+1، أحجام حمولة كبيرة، استدعاءات شبكة إضافية\n- الأمان: التحقق، فحوصات المصادقة، الأسرار، القيم الافتراضية الخطرة\n\nلتعرف ما إذا كان الأسلوب يؤتي ثماره، راقب مقياسين بسيطين لمدة 2 إلى 4 أسابيع: وقت المراجعة (من الفتح إلى أول مراجعة ذات مغزى، ومن الفتح إلى الدمج) وإعادة العمل (التزامات متابعة بعد المراجعة، أو عدد التعليقات التي تطلب تغييرات فعليًا).\n\nالتوحيد يفوق القوالب المثالية. اختر قالبًا واحدًا، اشترط حزمة سياق قصيرة (ما تغيّر، لماذا، كيف تختبر)، واتفق على معنى "تم".\n\nإذا كان فريقك يبني ميزات عبر التطوير القائم على الدردشة، يمكنك تطبيق نفس السريان داخل Koder.ai: ولّد التغييرات، صدّر الشيفرة المصدرية، ثم أرفق قائمة المراجعة المسبقة إلى PR ليبقى تركيز المراجعة البشرية على الأجزاء الأعلى مخاطرة.