سير العمل من الموجه إلى PR مع Claude Code: تغييرات صغيرة

لماذا يتفوق "من الموجه إلى PR" على الموجه الكبير لمرة واحدة

الموجهات الكبيرة لمرة واحدة غالبًا ما تؤدي إلى تغييرات ضخمة وفوضوية: عشرات الملفات المُعدَّلة، إعادة هيكلة غير مترابطة، وشيفرة لم تمنحها وقتًا لفهمها. حتى لو كان الناتج صحيحًا تقنيًا، تبدو المراجعة محفوفة بالمخاطر لأن من الصعب معرفة ما تغيّر ولماذا.

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

نمط "من الموجه إلى PR" هو حلقة بسيطة:

• اطلب تغييرًا صغيرًا واحدًا بحدود واضحة.
• راجع الفارق وتأكد أنه يطابق النية.
• شغّل فحوصك المعتادة (اختبارات، lint، بناء).
• إذا فشل شيء، أعد الطلب بالمشكلة والسياق الدقيق.
• كرر حتى يصبح جاهزًا للدمج.

هذا الإيقاع يحوّل الفشل إلى ملاحظات سريعة بدلًا من مفاجأة في النهاية. إذا طلبت من Claude Code تعديل قاعدة تحقق، فاجعل التغيير مقتصرًا على تلك القاعدة فقط. إذا فشل اختبار، ألصق مخرجات الفشل واطلب أصغر إصلاح يجعل الاختبار يمر، وليس إعادة كتابة الوحدة بأكملها.

حقيقة واحدة لا تتغير: أنت ما زلت مسؤولًا عن الشيفرة النهائية. عامل النموذج كمبرمج شريك محلي يكتب بسرعة، لا كطيار آلي. أنت من يقرر ما يدخل وما يبقى ومتى آمن فتح PR.

جهِّز المستودع وإعداد الاقتران المحلي

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

إعداد "المبرمج الشريك المحلي" يعني أن Claude Code يعدّل ملفات في مستودعك بينما تحافظ أنت على هدفك والقيود وكل الفوارق. النموذج لا يعرف قاعدة شيفرتك ما لم تُظهرها، فكن صريحًا بشأن الملفات والقيود والسلوك المتوقع.

قبل أول موجه، قرر أين ستُشغَّل الفحوص. إذا كان بإمكانك تشغيل الاختبارات محليًا، ستحصل على ملاحظات خلال دقائق، وهذا يبقي التكرارات صغيرة. إذا كانت بعض الفحوص تعمل فقط في CI (قواعد lint معينة، مجموعات طويلة، خطوات بناء)، قرر متى ستعتمد على CI حتى لا تنتظر بعد كل تغيير بسيط.

فحص تحضيري بسيط:

• حدِّث فرعك وتأكد أن التطبيق يبنى أو يعمل.
• شغّل الفحوص السريعة محليًا (lint، اختبارات وحدة، فحص النوع).
• لاحظ أي فحوص خاصة بالـ CI ومدة تشغيلها المعتادة.
• أكد أنك تستطيع إعادة إنتاج المشكلة أو رؤية الميزة المفقودة بوضوح.
• تأكد أنك تستطيع التراجع عن التغييرات بسهولة (حالة نظيفة، التزامات صغيرة).

احتفظ بمفكرة صغيرة مفتوحة أثناء العمل. دوّن القيود مثل «لا تغيّر API»، «ابقَ السلوك متوافقًا للخلف»، «المس فقط وحدة X»، بالإضافة لأي قرارات تتخذها. عندما يفشل اختبار، ألصق رسالة الفشل هناك أيضًا. تلك المفكرة تصبح أفضل مدخل للموجه التالي وتمنع الانجراف في الجلسة.

اكتب موجهات تؤدي طبيعيًا إلى فروق صغيرة

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

موجة جيدة تسمي هدفًا واحدًا، ومساحة واحدة في قاعدة الشيفرة، ونتيجة متوقعة واحدة. إن لم تستطع الإشارة إلى مكان الهبوط (ملف، مجلد، أو وحدة)، سيخمن النموذج وسينتشر الفارق.

شكل موجه يبقي التغييرات ضيقة:

• الهدف: السلوك الواحد الذي تريد تغييره.
• المكان: الملف(ات) أو المكوّن الذي تريد لمسه.
• القيود: ما يجب ألا يتغير.
• القبول: ما الذي يعني "تم".
• حجم الفارق: اطلب صراحةً أصغر تغيير يعمل.

الحدود هي السلاح السري. بدلًا من "صحّح خطأ تسجيل الدخول"، اذكر ما يجب أن يبقى ثابتًا: «لا تغيّر شكل الـ API»، «لا تعيد تسمية دوال عامة»، «لا تعديلات تنسيقية فقط»، «تجنّب اعتماديات جديدة». هذا يوضح لمبرمجك الشريك أين لا يجب أن يكون ذكيًا.

عندما يظل التغيير غير واضح، اطلب خطة قبل الشيفرة. خطة قصيرة تُجبر العمل إلى خطوات وتمنحك فرصة للموافقة على خطوة أولى صغيرة.

Goal: Fix the null crash when rendering the profile header.
Location: src/components/ProfileHeader.tsx only.
Constraints: Do not change styling, props, or any exported types.
Expected outcome: If user.name is missing, show "Anonymous" and no crash.
Diff constraint: Minimal diff. No refactors. No unrelated formatting.
If unclear: First reply with a 3-step plan, then wait for approval.

إذا كنت تعمل في فريق، أضف قيودًا للمراجعة أيضًا: «اجعلها تحت ~30 سطرًا مُعدَّلاً» أو «ملف واحد فقط ما لم يكن ضروريًا». هذا يجعل الفارق أسهل للمسح ويجعل الموجهات اللاحقة أوضح عندما يفشل شيء.

اختر وحدة العمل المناسبة لكل تكرار

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

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

حدد وقتًا محدودًا لكل حلقة. عشر إلى عشرين دقيقة عادةً كافية لكتابة موجه واضح، تطبيق الفارق، وتشغيل فحص سريع. إن كنت لا تزال تستكشف بعد 20 دقيقة، صغ الوحدة أو انتقل إلى تحقيق فقط (ملاحظات، تسجيل، اختبار فاشل) وتوقف هناك.

عرّف "تم" قبل البدء:

• يبقى التغيير داخل الملفات والسلوك المقصود.
• فحص واحد يثبت أنه يعمل (اختبار، lint، أو خطوة تشغيل بسيطة).
• لا تحذيرات جديدة أو تغييرات تنسيقية مريبة.
• الفارق سهل الشرح في جملتين.

عندما يبدأ النطاق في التوسع، توقف مبكرًا. إذا وجدت نفسك تقول "بينما نحن هنا"، فأنت للتو وجدت التكرار التالي. سجّله كمتابعة، التزم بالفارق الصغير الحالي، واستمر.