موجهات دليل أسلوب Claude Code لمراجعات شفرة متسقة

لماذا تنتشر مخالفات دليل الأسلوب بسرعة\n\nنادرًا ما تظهر مخالفات دليل الأسلوب كخطأ واحد كبير. تبدأ كخيارات صغيرة "قريبة بما يكفي" تبدو بريئة في طلب السحب، ثم تتراكم حتى يصبح مستودع الشفرة غير متناسق وأصعب في القراءة.\n\nيبدو انحراف الأسلوب غالبًا هكذا: ملف واحد يستخدم ، وآخر يستخدم ، وثالث يستخدم . معالج واحد يُرجع ، وآخر يرمي استثناء، وآخر يسجل ويُرجع . كل تغيير صغير، لكن معًا يصنعون مستودعًا تتوقف فيه الأنماط عن أن تكون متوقعة.\n\nالتكرار السريع وتعدد المساهمين يجعل الأمر أسوأ. الناس ينسخون ما يرونه، خاصة تحت ضغط الوقت. إذا كان أحدث كود في المستودع استخدم اختصارًا، يصبح ذلك الاختصار القالب للتغيير التالي. بعد أسابيع قليلة، "نمط الافتراضي" ليس دليلك المكتوب. إنه ما حدث آخرًا.\n\nلذلك الهدف يجب أن يكون قواعد ثابتة، لا تفضيلات شخصية. السؤال ليس "هل يعجبني هذا الاسم؟" بل "هل يتطابق هذا مع القواعد المتفق عليها كي يتمكن القادم من اتباعه دون التفكير؟"\n\nالقبض على المخالفات مبكرًا يعني إيقاف الأنماط السيئة قبل أن تتحول إلى نسخ ولصق. ركز على الكود الجديد والمعدل، أصلح الظهور الأول لتباين جديد، وامنع الدمج الذي يقدم انحرافًا جديدًا. عندما تشير إلى مشكلة، أضف مثالًا قصيرًا مفضلًا يمكن للناس تقليده في المرة القادمة.\n\nمثال واقعي: مطور يضيف نقطة نهاية API جديدة ويسجل أجسام الطلب الخام "فقط للتصحيح". إذا دخل هذا، تنسخ النقطة التالية نفس التصرف، وسرعان ما تظهر بيانات حساسة في السجلات. القبض عليها في PR الأول رخيص؛ بعد انتشارها يكون المكلف والخطير.\n\n## حوّل دليل الأسلوب إلى قواعد واضحة وقابلة للاختبار\n\nدليل الأسلوب ينجح في المراجعات فقط إذا قرأ كقائمة تحقق، لا كمجموعة تفضيلات. أعد كتابة كل إرشاد كقاعدة يمكن فحصها على الفرق.\n\nنظم القواعد في أربع مجموعات لتكون صعبة التغاضي عنها: التسمية، الطبقات، التعامل مع الأخطاء، والتسجيل. لكل مجموعة اكتب شيئين: ما يجب أن يكون صحيحًا وما هو محظور.\n\nقرر قوة كل قاعدة مقدمًا:\n\n- : فشله يمنع الدمج.\n- : أصلحه إلا إذا كان هناك سبب واضح لعدم فعل ذلك.\n- : جيد وجوده، لا يمنع الدمج أبدًا.\n\nحدد النطاق حتى لا تتحول المراجعات إلى إعادة هيكلة لا تنتهي. قاعدة بسيطة تعمل جيدًا: “يجب أن يتوافق الكود الجديد والمعدل؛ لا يعاد كتابة الكود القديم غير المعد ما لم يمنع ذلك الإصلاح.” إذا أردت تنظيفًا عامًا، خصص له وقتًا كمهمة مستقلة.\n\nحدد أيضًا المخرجات التي تريدها من المراجعة لتكون سهلة التنفيذ: حكم اجتياز/فشل، قائمة مخالفات مع ملفات وأسطر، اقتراحات إصلاح مكتوبة كتحريرات محددة، وملاحظة مخاطر قصيرة عندما قد يسبب شيء أخطاء أو تسريبات.\n\nمثال: إذا سجّل PR رموز مستخدمين خامًا، يجب أن يفشل تحت "التسجيل: لا تسجل الأسرار" ويقترح تسجيل معرف الطلب بدلًا من ذلك.\n\n## بنية الموجه التي تفرض قواعد بدلًا من الآراء\n\nتفشل موجهات الأسلوب عندما تبدو كتفضيلات. موجه مراجعة جيدة تقرأ كعقد: غير قابلة للتفاوض بوضوح، استثناءات مسماة بوضوح، ومخرج متوقع.\n\nابدأ بمقطعين قصيرين: ما يجب أن يكون صحيحًا وما يمكن التنازل عنه. ثم أضف قاعدة قرار: "إذا لم يكن واضحًا، ضع علامة احتياج إلى توضيح. لا تخمن."\n\nألزم بالأدلة. عندما تشير الأداة إلى مخالفة، اشترط أن تقتبس المعرف الدقيق ومسار الملف، لا وصفًا غامضًا. هذا القيد الواحد يزيل الكثير من الجدل ذهابًا وإيابًا.\n\nحافظ على نطاق ضيق: علّق على الأسطر المعدلة ومسارات الكود المتأثرة مباشرة فقط. إذا سمحت بإصلاحات غير ذات صلة، يتحول تطبيق الأسلوب إلى "أعد كتابة الملف" ويتوقف الناس عن الوثوق في الملاحظات.\n\nها هي بنية يمكنك إعادة استخدامها:\n\n\n\nاطلب من التقرير أن يحتفظ بنفس الأقسام في كل مرة، حتى لو كانت بعض الأقسام "لم تُعثر على مشاكل": التسمية، الطبقات، التعامل مع الأخطاء، والتسجيل.\n\nإذا قال "تسرب تفاصيل قاعدة البيانات في طبقة الخدمة"، يجب أن يستشهد بشيء مثل والاستدعاء الدقيق (على سبيل المثال ) حتى تتمكن من إصلاح التسرب دون جدال حول المقصود.\n\n## خطوة بخطوة: بناء سير عمل لموجه فحص الأسلوب\n\nيلتصق دليل الأسلوب عندما يصبح العملية قابلة للتكرار. الهدف هو جعل النموذج يفحص القواعد، لا يناقش الذوق، وأن يفعل ذلك بنفس الطريقة كل مرة.\n\nاستخدم سير عمل بسيط من مرحلتين:\n\n1) ألصق معاييرك كقائمة قواعد مدمجة ومرقمة (10-25 سطرًا). اجعل كل قاعدة قابلة للاختبار.\n2) أضف سياقًا للتغيير: الفرق، الملفات التي لامستها، وجملة واحدة عن الهدف.\n3) اطلب تقرير مخالفات أولًا. اشترط ملف وسطر، سبب قصير، ورقم القاعدة بالضبط.\n4) فقط بعد التقرير، اطلب أصغر تصحيح ممكن للوصول إلى الامتثال.\n5) أعد تشغيل نفس الموجه على الكود المحدث للتأكيد أن لا شيء تبقى.\n\nمثال: يضيف PR نقطة نهاية جديدة. الجولة الأولى تحدد أن المعالج يتحدث إلى PostgreSQL مباشرة (طبقات)، يستخدم أسماء مختلطة لهياكل الطلب (تسمية)، ويسجل عناوين بريد كاملة (تسجيل). الجولة الثانية تقترح إصلاحات طفيفة: نقل استدعاء قاعدة البيانات إلى خدمة أو مستودع، إعادة تسمية الهيكل، وإخفاء البريد في السجلات. لا يتغير شيء آخر.\n\n## قواعد التسمية: موجهات تلتقط التفاصيل الصغيرة\n\nتبدو مشاكل التسمية طفيفة، لكنها تخلق تكلفة حقيقية: الناس يخطئون في فهم النية، البحث يصبح أصعب، و"أسماء شبه متطابقة" تتكاثر.\n\nحدد قواعد التسمية التي يجب على المراجع فرضها عبر التغيير كله: أسماء الملفات، الأنواع المصدّرة، الدوال، المتغيرات، الثوابت، والاختبارات. كن صريحًا بشأن الشكل (camelCase، PascalCase، snake_case) واختر قاعدة واحدة للاختصارات (مثال مقابل ). ثم أشترطها في كل مكان.\n\nوحد المصطلحات المشتركة: أنواع الأخطاء، حقول السجل، ومفاتيح التهيئة. إذا كانت السجلات تستخدم ، لا تسمح بـ في ملف واحد و في آخر.\n\nتعليمات مراجعة عملية:\n\n\n\nاطلب تقريرًا قصيرًا: أكثر ثلاثة أسماء مربكة، أي شبه-تكرارات وأي واحد يجب الاحتفاظ به، بالإضافة إلى أي أسماء سجلات/تهيئة/أخطاء لا تتطابق مع المعيار.\n\n## قواعد الطبقات: حافظ على فصل المسؤوليات\n\nتعمل قواعد الطبقات بأفضل شكل بلغة بسيطة: المعالجات تتعامل مع HTTP، الخدمات تحتفظ بقواعد العمل، والمستودعات تتعامل مع قاعدة البيانات.\n\nقفل اتجاه الاعتماد. يمكن للمعالجات استدعاء الخدمات. يمكن للخدمات استدعاء المستودعات. لا يجب على المستودعات استدعاء الخدمات أو المعالجات. لا تستورد المعالجات كود قاعدة البيانات، أو مساعدي SQL، أو نماذج ORM. إذا كنت تستخدم حزم مشتركة (config، time، IDs)، اجعلها خالية من منطق التطبيق.\n\nثبّت الأعمال العابرة في مكان واحد. عادةً ينتمي التحقق من الشكل في الحد الخارجي للطلب، وقواعد العمل في الخدمة. التفويض غالبًا يبدأ في المعالج (الهوية، الصلاحيات)، لكن يجب أن تفرض الخدمة القرار النهائي. التحويلات تنتمي إلى حواف الطبقات: المعالج يحول HTTP إلى مدخلات المجال، والمستودع يحول صفوف DB إلى أنواع المجال.\n\nاستخدم هذا المقطع في الموجه للحفاظ على المراجعات ملموسة:\n\n\n\nاجعل التقرير صريحًا: سمّ الملف، الطبقة التي ينتمي إليها، الاستيراد أو الاستدعاء الذي يكسر القاعدة، والتغيير الأدنى الذي يمنع انتشار النمط.\n\n## قواعد التعامل مع الأخطاء: الاتساق تحت الضغط\n\nتتصاعد معظم مناقشات الأسلوب عندما ينهار شيء في الإنتاج. سياسة واضحة للتعامل مع الأخطاء تحافظ على هدوء الإصلاحات لأن الجميع يعرف ما يبدو "جيدًا".\n\nاكتب الفلسفة واطبقها. مثال: "لف الأخطاء لإضافة سياق؛ أنشئ خطأً جديدًا فقط عند تغيير المعنى أو الربط برسالة للمستخدم. أعد الخطأ الخام فقط عند الحدود النظامية."句هذه الجملة الواحدة تمنع أنماطًا عشوائية من الانتشار.\n\nفصل نصوص الواجهة عن التفاصيل الداخلية. يجب أن تكون رسائل المستخدم قصيرة وآمنة. يمكن للأخطاء الداخلية أن تتضمن اسم العملية ومعرفات رئيسية، لكن ليس الأسرار.\n\nفي المراجعات، افحص بعض الأخطاء المتكررة: أخطاء موضوعية (مسجلة لكن غير مرجعة)، عائدات غامضة (قيمة nil مع خطأ nil بعد فشل)، ورسائل للمستخدم تكشف تراكيب المكدس أو نص الاستعلام أو رموز أو بيانات شخصية. إذا دعمت عمليات إعادة المحاولة أو الحدود الزمنية، اشترط أن تكون صريحة.\n\nمثال: عملية دفع تتوقف مؤقتًا. يرى المستخدم "خدمة الدفع تستغرق وقتًا طويلاً." داخليًا، لف الحدث وأضف ومعرف الطلب ليكون قابلاً للبحث والعمل.\n\n## قواعد التسجيل: واضح، قابل للبحث، وآمن\n\nتنفع السجلات فقط عندما يكتبها الجميع بنفس الطريقة. إذا اختار كل مطور صياغته، ومستواه، وحقوله، تتحول عمليات البحث إلى محاولة تخمين.\n\nاجعل مستويات السجل غير قابلة للتفاوض: debug لتفاصيل التطوير، info للمعالم العادية، warn للحالات غير المتوقعة لكن المعالجة، وerror عند فشل الإجراء الموجه للمستخدم أو الحاجة إلى انتباه. اجعل "fatal" أو "panic" نادرة ومرتبطة بسياسة واضحة للتعطل.\n\nالسجلات المهيكلة أهم من جمل مثالية. اشترط أسماء مفاتيح ثابتة حتى لا تنكسر اللوحات والتنبيهات. قرر مجموعة صغيرة أساسية (مثال: event، component، action، status، duration_ms) واحتفظ بها بثبات.\n\nعامل البيانات الحساسة كخط أحمر. كن صريحًا بما يجب ألا يُسجل أبدًا: كلمات المرور، رموز المصادقة، أرقام البطاقات الكاملة، الأسرار، والبيانات الشخصية الخام. نبه إلى أشياء تبدو غير ضارة لكنها ليست كذلك، مثل روابط إعادة تعيين كلمة المرور، معرفات الجلسة، وأجسام الطلب الكاملة.\n\nتجعل معرفات الارتباط (Correlation IDs) التصحيح ممكنًا عبر الطبقات. اشترط في كل سطر سجل ضمن الطلب. إذا سجّلت ، عرّف متى يُسمح وكيف تمثل المفقود أو المستخدم المجهول.\n\nمقطع موجه يمكنك إعادة استخدامه:\n\n\n\nقبل الدمج، قم بمرور "سلامة" سريع: أي سجل جديد يفتقد لعمل متعلق بالطلب، أي مفاتيح جديدة تغير أسماء موجودة ( مقابل )، أي سجلات أخطاء تفتقد ما فشل (العملية، المورد، الحالة)، أي سجلات عالية الحجم ستُفعل على كل طلب، وأي احتمال لظهور أسرار أو بيانات شخصية في الحقول أو الرسائل.\n\n## كيف تكتشف المخالفات قبل أن تنتشر\n\nعامل انحراف الأسلوب ككسر بناء، لا كاقتراح. أضف حاجزًا صارمًا يعمل قبل الدمج ويعطى نتيجة واضحة اجتياز أو فشل. إذا كُسرت قاعدة إلزامية (تسمية، حدود الطبقات، أمان السجلات، التعامل مع الأخطاء)، يفشل ويشير إلى ملفات وأسطر بالضبط.\n\nاجعل الحاجز قصيرًا. خدعة عملية هي طلب قائمة نعم/لا لكل قاعدة، ورفض الموافقة إذا كان أي عنصر لا.\n\nقائمة تحقق بحجم PR تلتقط معظم المشاكل:\n\n- التسمية: تطابق النمط المعتمد للملفات والأنواع والدوال\n- الطبقات: لا استدعاءات مباشرة تتخطى الطبقات (مثال: معالجات تستدعي قاعدة البيانات)\n- الأخطاء: تُرجع مع السياق، لا شيء يُتجاهل بصمت\n- السجلات: حقول متسقة، لا أسرار، والمستوى يتطابق مع الأثر\n- الاختبارات/الوثائق: تُحدّث عند تغيير السلوك أو واجهات عامة\n\nعندما تقترح الأداة إصلاحات، اشترط مقطعًا صغيرًا متوافقًا لكل قاعدة تمسها. هذا يمنع ملاحظات غامضة مثل "أعد التسمية للوضوح".\n\n## المصائد الشائعة عند استخدام الموجهات لتطبيق الأسلوب\n\nأسرع طريقة لفشل دليل الأسلوب هي ترك مجال للتفسير. إذا استطاع مراجعان قراءة نفس القاعدة والوصول إلى استنتاجات مختلفة، ستفرض الأداة الذوق، لا المعايير.\n\nالتسمية مثال شائع. "استخدم أسماء واضحة" غير قابلة للاختبار. شددها إلى شيء يمكنك التحقق منه: "الدوال أفعال (مثل )، البوالينات تبدأ بـ ، الأنواع المصدّرة PascalCase."\n\nمصيدة أخرى هي طلب كل شيء دفعة واحدة. عندما يحاول موجه واحد تغطية التسمية، والطبقات، والأخطاء، والسجلات، والاختبارات، والأداء، تصبح الملاحظات سطحية. قم بتقسيم المراجعات إلى تمريرات مركزة عند الحاجة إلى عمق، أو احتفظ بموجه الحاجز محدودًا بالقواعد الإلزامية.\n\nالمشاكل التي غالبًا ما تسبب انحراف التنفيذ:\n\n- : استبدل "نظيف" و"متسق" بلغة قابلة للقياس.\n- : لا تدع موجه الأسلوب يقترح بنية جديدة.\n- : اشترط أن يقتبس كل تعليق المعرف أو المقطع الدقيق.\n- : إذا سمحت باستثناء، اشترط ملاحظة قصيرة تشرح لماذا ومتى يجب إزالته.\n\nإذا عاملت الموجهات كاختبارات، ستحصل على تطبيق متوقع. إذا عاملتها كنصيحة، تنسل المخالفات وتتضاعف.\n\n## قائمة تحقق سريعة يمكنك تشغيلها على كل تغيير\n\nقم بتمرير سريع على الفرق (ليس المستودع كله) وتأكد:\n\n- المعرفات الجديدة تتبع نمطك (الحالة، البادئات، اللاحقات). مفهوم واحد اسمه بطريقة واحدة عبر الملفات.\n- الاعتمادات تذهب فقط في الاتجاه المسموح. الطبقات الأدنى لا تستورد الأعلى.\n- تُعاد الفشلات مع السياق. لا شيء مهمل بصمت.\n- المستوى صحيح، الحقول ثابتة، ولا أسرار أو بيانات شخصية.\n- يصرّ المراجع على عبارة بالضبط: "لم تُعثر على مخالفات إلزامية"، أو يورد المخالفات التي يجب إصلاحها قبل الدمج.\n\nاحتفظ بموجه صغير ألصقه مع كل تغيير:\n\n\n\nمثال: دالة جديدة في معالج تكتب إلى PostgreSQL مباشرة يجب أن تفشل في التسمية والطبقات حتى لو كانت الميزة تعمل. القبض عليها هنا يمنع نسخ-لصق الخطأ من الانتشار.\n\n## مثال: مراجعة واقعية تصلح المشاكل مبكرًا\n\nزميلك يضيف نقطة نهاية جديدة: . تمس معالجًا، خدمة، وتخزين.\n\nفي الجولة الأولى، تريد تقريرًا لا إعادة كتابة:\n\n\n\nالنتائج النموذجية: مقابل عدم تطابق في التسمية، المعالج يستدعي مباشرة، إرجاع الخام بدون سياق، وسجلات مزعجة مثل التي تطبع كائنات كاملة.\n\nالمرحلة الثانية تطلب اقتراحات إصلاح طفيفة وآمنة:\n\n\n\nإذا سُمح بكسر قاعدة، اذكره صراحة: "الاستثناءات مسموحة فقط إذا أضفت تعليقًا قصيرًا يشرح السبب، وأضفت مهمة متابعة لإزالة الاستثناء."\n\nبعد الإصلاح، يصبح المعالج مجرد محول رقيق، تملك الخدمة سير العمل، يملك التخزين الاستعلام، تصبح الأخطاء ، وتصبح السجلات سطرًا واحدًا نظيفًا مع حقول آمنة (معرف الفاتورة، لا الفاتورة الكاملة).\n\n## الخطوات التالية: اجعلها روتينًا بدون إبطاء\n\nاختر موجهًا واحدًا معتمدًا من الفريق وتعامل معه كأداة مشتركة. ابدأ بما يؤلمك أكثر في المراجعات (انحراف التسمية، تسرب الطبقات، أخطاء غير متسقة، سجلات غير آمنة). حدّث الموجه فقط عندما ترى مخالفة حقيقية في كود حقيقي.\n\nاحتفظ بكتلة قواعد صغيرة في أعلى الموجه وألصقها في كل مراجعة دون تغيير. إذا حرّك الجميع القواعد في كل مرة، لن يكون لديك معيار. سيكون لديك نقاش.\n\nإيقاع بسيط يساعد: يجمع شخص واحد أهم أخطاء الأسلوب من الأسبوع، وتضيف قاعدة أو مثالًا أوضح واحدًا بالضبط.\n\nإذا عملت في سريان عمل مدفوع بالدردشة مثل Koder.ai (koder.ai)، فمن المفيد تشغيل نفس فحوصات الحاجز أثناء التغييرات، لا فقط في النهاية. ميزات مثل التخطيط، اللقطات، والتراجع يمكن أن تساعدك على الحفاظ على إصلاحات الأسلوب صغيرة وقابلة للعكس قبل تصدير الشفرة المصدرية.