محرّك جودة الكود: مراجعة تصطاد الخطأ الحقيقي، وcommits تشرح اللماذا

بين يدي فريقك playbook الـ code-review والـ git-workflow — الوصفتان المجرّبتان لمراجعة منظّمة بالأبعاد، ولتجهيز كل همّ والتزامه وحده. هذه الوحدة طبقة أعلى من الوصفة: هنا تُتقن الحركتين اللتين تُبقيان الـ codebase مقروءًا وقابلًا للمراجعة — المراجعة بعين الخصم التي تصطاد الخطأ الحقيقي وتُسقط النتائج الزائفة، وانضباط الـ commit الذي يجعل مهندس المستقبل يبني فعلًا على git blame — وتثبت، أمام معايير حقيقية، أنك تجيد الاثنتين.

الفشل السهل في مراجعة الكود هو الختم الأعمى: تصفّحٌ سريع، وتشغيل الاختبارات، والاعتماد. أما الفشل الأصعب — الذي يجعلك أقل نفعًا من الصمت — فهو نشر «خطأ» واثق الصياغة وهو ليس خطأً، لأنك لم تتحقق من النتيجة على الكود الفعلي قبل إرسالها إلى الكاتب. Claude مُراجِع خصم سريع. وهو أيضًا مُراجِع مخطئ سريع. والحسّ الذي تعلّمه هذه الوحدة هو الفرق بين الوضعين.

المراجعة بعين الخصم — لماذا التأطير هو اللعبة كلها

الـ playbook يعلّمك أن تطلب مراجعة بالأبعاد: الصحة، والحالات الحدّية، والأمن، والتشغيل. الإتقان هو الحسّ وراء لماذا يهمّ هذا التأطير وما العمل حين لا يكفي.

• المُراجِع الذي يريد الاعتماد لا يجد شيئًا. الموقف الافتراضي للمراجعة المهذبة — «هل يبدو هذا صحيحًا؟» — ينتج «يبدو جيدًا» على diffs غير تافهة. التأطير بعين الخصم يقلب هذا: «افترض أن فيه خطأ حقيقيًا واحدًا على الأقل وجِد أسوأه.» تلك التعليمة الواحدة هي ما يفصل مراجعةً تجد خطأ الثالثة فجرًا عن أخرى تعتمده. ليست عدوانية؛ إنها منهج.
• الأبعاد تمنع النظرة العامة الغائمة. طلب مراجعة «منظَّمة بالصحة والحالات الحدّية والأمن والتشغيل» يفرض تغطية لا يفرضها «راجع هذا الـ diff». خطأ التشغيل الذي يوقظ أحدهم الثالثة فجرًا — الذي يعمل بلا مشكلة في التطوير ويصرخ حين يتضاعف الحمل عشر مرات — لا يظهر إلا إذا سأل أحد صراحةً كيف يتصرف الكود تحت الحمل، أو الفشل الجزئي، أو حالة سباق.
• إن عادت نظيفة على diff غير تافه، فاضغط أكثر. «لم أجد شيئًا خطيرًا» على diff من 200 سطر يعبر حدود المصادقة يكاد لا يكون الجواب الصحيح أبدًا. إن عادت الجولة الأولى نظيفة، فمُر بعين الخصم: «افترض أن فيه خطأً. الآن جِده.» تلك التعليمة وحدها تُخرج نتائج مرّ عليها الوضع المهذب مرور الكرام.
• التأطير لا يحلّ محلّ حُكمك. Claude جولة خصم أولى سريعة. وليس هو المعتمِد. إنسان يملك التوقيع لأن إنسانًا هو صاحب الاسم. وكلما أسرعت الجولة الأولى، ازدادت أهمية أن يبقى القرار الأخير قرارك.

خطوة التحقق — الضابط الذي يجعل الباقي آمنًا

الـ playbook يذكر التحقق من النتائج؛ وهذه الوحدة تجعله واجبًا. هذه هي الخطوة التي تفصل مراجعة نافعة عن أخرى محرجة.

• سيجزم Claude بلا-خطأ بثقة كاملة. يخطئ أحيانًا قراءة مسار التحكم — يؤشّر على حارس موجود أصلًا، أو تفوته فحصة تقع دالّتين أعلى في سلسلة الاستدعاء، أو يجزم بعدم تطابق نوع يمنعه المترجم أصلًا. النتيجة الواثقة الصياغة ليست نتيجة متحقَّقًا منها. وخطوة التحقق ليست صقلًا اختياريًا؛ إنها ما يجعل المراجعة جديرة بالإرسال أصلًا.
• «أرني الأسطر» هو الاختبار. لكل نتيجة جوهرية، اطلب من Claude الأسطر بعينها التي تثبت أنها حقيقية — الكود الذي يصنع المشكلة، لا وصفها. إن لم يستطع أن يريك الأسطر المحددة، تسقط النتيجة ولا تُنشر تعليقًا. «أعتقد أن هذا قد يكون خطأ» ليس تعليق مراجعة؛ أما «هذه src/webhooks/stripe.ts:84-92 حيث يجري فحص نوع الحدث بعد أن عولجت الحمولة أصلًا» فهو كذلك.
• اقتل النتائج الزائفة قبل أن تبلغ الكاتب. نشر نتيجة غير متحقَّق منها يهدر وقت الكاتب ويحرق صدقيّتك مُراجِعًا. معدل النتائج الزائفة في جولة بلا تحقق مرتفع بما يجعلك تفترض أن كل نتيجة خاطئة حتى تثبت الأسطر أنها صائبة. وهذا ليس سوء ظن بـ Claude — إنه المعيار المهني لأي أداة مراجعة.
• اختبار واحد لكل خطأ مؤكَّد. لكل نتيجة تنجو من التحقق، اطلب الاختبار الواحد الذي يفشل على الكود الحالي وينجح متى أُصلح. ذلك الاختبار يحوّل «أظن هذا مكسورًا» إلى «هذا هو الاختبار الأحمر الذي يثبته» — وذلك تعليق مراجعة أقوى بكثير من النثر، وخطوة ملموسة تالية للكاتب بدل مجرد شكوى.

انضباط الـ commit — الحسّ الذي لا تعلّمه الوصفة

الـ playbook يريك خطوات تجهيز كل همّ والتزامه وحده وصياغة رسالة تشرح اللماذا. الإتقان هو الحسّ الذي يفصل تاريخ commits يستحق أن يُورَّث عن آخر هو تنقيب أثري.

• «اللماذا» لا تُستنتج من «الماذا». «Update session TTL» يصف ما تغيّر. أما «Fix session expiry: كانت الـ TTL تُقرأ من الإعدادات بالمللي ثانية وتُقارَن بالثواني في session.ts:142، فتنتهي الجلسات أسرع بألف مرة. لم يغطِّ أي اختبار المقارنة — أضفت واحدًا» فتلك هي اللماذا — القيد الذي كان الكود يدور حوله، ومنطق الاختيار، والشيء الذي لا يستطيع القارئ إعادة بنائه من الـ diff وحده. متن رسالة الـ commit ليس وصفًا للتعديل؛ إنه السياق الغائب الذي لا يحمله الـ diff.
• همّ واحد لكل commit هو غير القابل للتفاوض. الـ commit الذي يصلح خطأ ويحدّث اعتمادية ويعيد تسمية ثلاث دوال commit لا يستطيع أحد عمل bisect عليه. حين يظهر انحدار ويهبط الـ bisect على ذلك الـ commit، على المهندس أن يقرأ 300 سطر ليجد أي الأشياء الثلاثة هو المعني. همّ واحد لكل commit دقيقتا انضباط توفّران أمسية في كل مرة يتتبع فيها أحدٌ خطأً إليه.
• الرسالة وثيقة تكتبها وأنت تتحرك. الـ CLAUDE.md الذي كتبته في الوحدة الأولى يخبر Claude بعرفكم في الـ commit. بعدها يصوغ Claude رسائل على صيغتكم وأنت تعتمدها. الانضباط أن تشترط المتن حين يحتاجه التعديل — لا يحتاج كل commit ثلاث فقرات لماذا، لكن كل commit قد يسأل عنه مهندس المستقبل يحتاجها.
• شرح حالة الـ working tree هو الحركة الأولى غير القابلة للتفاوض. قبل أن يجهّز Claude أو يلتزم شيئًا، يشرح الحالة: ما المجهَّز، وما غير المجهَّز، وأي الملفات يمتد عبر همّين. تقرأ أنت ذلك الشرح وتطابقه على رؤيتك للشجرة قبل أن يجري أمر واحد. الفهم قبل الفعل هو قاعدة playbook الـ git-workflow كلها، وهي حاملة في سير عمل المراجعة أيضًا.

بُعد المنطقة — المراجعة والتاريخ لفريق هندسي ثنائي اللغة

مراجعة الكود وتاريخ الـ commits إنجليزيان عند معظم الفرق الهندسية، وهذه الوحدة لا تغيّر ذلك. المعيار الثنائي هنا أضيق وأدقّ.

• أوصاف الـ PR لمُراجِع ثنائي اللغة. الـ PR الذي يمسّ نصوصًا عربية مواجهة للعملاء — قوالب الفواتير، وبريد التهيئة، ورسائل الأخطاء — ينبغي أن يضم وصفه ملاحظة عمّا يفعله التعديل العربي ومن راجعه. ليست تلك ترجمة؛ إنها السياق الذي يحتاجه مدير هندسي أو قائد تقني ثنائي اللغة ليراجع التعديل عن بيّنة.
• نتائج المراجعة على ملفات النصوص العربية تُقيَّم بالسجلّ. إن مسّت نتيجةٌ محتوى عربيًا — نصًّا وُلّد ولم يُؤلَّف، أو مصطلحًا يخالف مسرد CLAUDE.md، أو عبارة خليجية تُقرأ مترجمة — سمّت النتيجة النص بعينه والمشكلة والصيغة الصحيحة. «هذه الترجمة تُقرأ آلية؛ والمكافئ الخليجي هو [كذا]» تعليق مراجعة له بنية نتيجة جودة الكود نفسها.
• متن الـ commit يبقى إنجليزيًا. ليس هذا سياق ترجمة. الـ commit الذي يغيّر نصًّا عربيًا يشرح بالإنجليزية ما يفعله التعديل العربي: «fix(invoice-ar): correct Arabic amount formatting for VAT line. The فاتورة ضريبة القيمة المضافة label was using MSA register instead of Gulf Arabic — replaced with the standard used in the rest of the invoice template.»

تكليفك

أكمِل حلقة جودة الكود لـPR حقيقي واحد أو تعديل ملتزَم واحد — الخاص بك (وهذا ما ننصح به) أو ربط Stripe webhook في «ميزان» المعروض في هذه الوحدة. افتح الفرع أو الـ diff في Claude Desktop واعمل داخل المحادثة — لا حاجة إلى terminal للقراءة والمراجعة؛ وتشغيل الحزمة هو خطوة مسار الـ Power Track.

ناتج الوحدة الثانية — محرّك جودة الكود

1. مراجعة منظّمة (صفحة واحدة)
   - منظَّمة بالأبعاد: الصحة، والحالات الحدّية، والأمن، والتشغيل
   - كل نتيجة بالملف والسطر، والمشكلة، ودرجة الخطورة
   - كل نتيجة جوهرية متحقَّق منها: الأسطر التي تثبت أنها حقيقية،
     أو إسقاطها صراحةً نتيجةً زائفة
   - اختبار فاشل واحد مصوغ لكل خطأ مؤكَّد

2. تاريخ commits نظيف (ظاهر في git log)
   - كل همّ في commit خاص به
   - رسائل بعنوان (بصيغة الأمر، ≤50 حرفًا) ومتن يشرح لماذا لزم
     التعديل — لا ماذا يفعل
   - حالة الـ working tree شُرحت قبل تجهيز أي شيء

كيف يجري التقييم — المعايير

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

1. التأطير بعين الخصم استُعمل
   المراجعة افترضت خطأً وبحثت عن الأسوأ — لا «هل يبدو صحيحًا؟»
   فقط. ونتيجة واحدة على الأقل جاءت من جولة الخصم، لا من التصفح
   المهذب الأول.
2. النتائج متحقَّق منها
   كل نتيجة جوهرية راسية على أسطر بعينها تثبت أنها حقيقية.
   والنتائج الزائفة أُسقطت صراحةً، لا نُشرت تعليقات مترددة.
3. اختبار واحد لكل خطأ مؤكَّد
   لكل خطأ مؤكَّد: اختبار يفشل على الكود الحالي وينجح بعد
   الإصلاح. الاختبار يثبّت السلوك المكسور بعينه.
4. الـ commits همّ واحد + متن لماذا
   همّ واحد لكل commit. ولكل رسالة متن يجيب «لماذا لزم هذا» —
   لا «ماذا فعلت». والتاريخ قابل للملاحة عند من لم يحضر.
5. الـ working tree شُرح أولًا
   شرح Claude الحالة قبل تجهيز أي شيء. والأوامر الهدّامة (reset،
   force-push) شُرحت واعتُمدت قبل تشغيلها.

المستوى المطلوب، معروضًا — نموذج إجابة («ميزان»)

(لاحظ النمط الثنائي المقصود: تحليل المراجعة بالعربية — فالنقاش يتبع قارئه — والكود والمسارات والاختبارات ورسائل الـ commit بالإنجليزية، فالكود إنجليزي دائمًا.)

«ميزان» — مراجعة PR ربط Stripe webhook (مقتطف)

الـ diff:‏ src/webhooks/stripe.ts (‏190 سطرًا مضافًا)،
tests/unit/webhooks/stripe.test.ts (‏47 سطرًا)

نتيجة صحة (متحقَّق منها):
  stripe.ts:84-92 — الـ webhook يعالج الحمولة قبل التحقق من توقيع
  Stripe. إن فشل التحقق (السطر 94) تكون الحمولة قد عولجت أصلًا.
  المسار الحالي يتيح replay attack: أي مستدعٍ يعرف شكل الحدث يستطيع
  تشغيل معالج payment_intent.succeeded دون توقيع Stripe صالح.

  الأسطر التي تثبتها: processingEvent(payload) يُستدعى عند :84؛
  stripe.webhooks.constructEvent() يُستدعى عند :94. والإصلاح هو
  إعادة الترتيب.

  الاختبار الفاشل:
    it('rejects payload processed before signature verification', async () => {
      const invalidSig = 'invalid'
      // send well-formed payload with bad sig — handler should reject before
      // any processing, not after
      const res = await handler(mockPayload, invalidSig)
      expect(res.status).toBe(400)
      expect(mockProcessingFn).not.toHaveBeenCalled()  // currently fails
    })

نتيجة زائفة أُسقطت:
  النتيجة الأولية: «نوع الحدث لا يُتحقق منه على allowlist.»
  التحقق: stripe.ts:31-35 يعرّف HANDLED_EVENTS =
  ['payment_intent.succeeded', 'invoice.payment_failed']؛ والمعالج
  يعيد 200 مبكرًا لأي نوع آخر. أُسقطت النتيجة — الـ allowlist موجودة.

تاريخ الـ commits — «ميزان»، Stripe webhook (مقتطف)

fix(webhooks): verify Stripe signature before processing payload

Processing the event before calling constructEvent() allowed replay
attacks on the webhook handler. Reordered to verify first; added a
test for the rejection path. Closes #201.

test(webhooks): add missing coverage for payment_failed handler

The invoice.payment_failed path had no test. Added three cases:
successful retry scheduling, idempotency on duplicate events, and
the error path when the customer is not found.

chore(webhooks): extract HANDLED_EVENTS to a shared constant

The allowlist was duplicated between the handler and the tests.
Extracted to src/webhooks/constants.ts so both import from one place.

ما الذي أثبتّه — وما التالي

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

الوحدة 3 — شحن الميزات هي التالية: حلقة «الـ spec أولًا، والخطة قبل الـ diff» التي تشحن ميزة خلف حزمة خضراء. انضباط الـ commit من هذه الوحدة وسياق المشروع من الأولى يمضيان معك — فـ commits الميزة على العرف نفسه، وprompt الـ plan mode يستعمل CLAUDE.md ليأتيك بنصيحة تخص مشروعك.