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

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

قام مؤلف هذا المقال باختبار 30 مكتبة كود خلال 6 أسابيع، وأضاف 8 قواعد جديدة على أساس القواعد الأصلية الأربع لكارباتي، محاولاً تغطية المشكلات الجديدة الناشئة مع انتقال البرمجة بالذكاء الاصطناعي من التكملة الفردية إلى التعاون القائم على الوكلاء.

Below is the original text:

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

رأى فورست تشانغ سلسلة التغريدات هذه، وقام بتنظيم الشكاوى إلى 4 قواعد سلوكية، وكتبها في ملف منفصل باسم CLAUDE.md، ثم نشره على GitHub. وحصل المشروع على 5,828 نجمة في يومه الأول، وتم حفظه 60,000 مرة خلال أسبوعين، ووصل الآن إلى 120,000 نجمة، ليصبح أسرع مستودع كود مكون من ملف واحد نموًا في عام 2026.

ثم قمت باختباره على 30 مخزنًا كوديًا خلال 6 أسابيع.

هذه القواعد الأربعة فعالة بالفعل. انخفضت الأخطاء التي كانت تحدث سابقًا بحوالي 40% من الاحتمالات، إلى أقل من 3% في المهام المناسبة لتطبيق هذه القواعد. لكن المشكلة أن هذا القالب وُضع في الأصل لحل الأخطاء التي ظهرت عند كتابة كود Claude في يناير.

بحلول مايو 2026، كانت المشكلات التي تواجهها بيئة Claude Code قد تغيرت: تعارضات بين الوكلاء، تفعيل مترابط للـ hook، تعارضات في تحميل المهارات، وانقطاع سير العمل متعدد الخطوات عبر الجلسات.

لذلك، أضفت 8 قواعد إضافية. إليك النسخة الكاملة المكونة من 12 قاعدة من CLAUDE.md: لماذا تستحق كل قاعدة أن تُضاف، وأين ستفشل النسخة الأصلية من قالب Karpathy في 4 أماكن.

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

لماذا هذا مهم؟

ملف CLAUDE.md الخاص بـ Claude Code هو أكثر الملفات تقليلًا في كامل بنية تقنية البرمجة بالذكاء الاصطناعي. عادةً ما يرتكب المطورون ثلاثة أنواع من الأخطاء:

أولاً، اعتبره سلة مهملات تفضيلات، وأدخل فيه جميع عاداتك، حتى ينتهي بك الأمر إلى انتفاخه إلى أكثر من 4000 رمز، فينخفض معدل الالتزام بالقواعد إلى 30%.

ثانيًا، تجنب استخدامه تمامًا وأعد إدخال الأمر في كل مرة. هذا سيؤدي إلى هدر خمسة أضعاف الرموز، كما أنه يفتقر إلى الاتساق بين الجلسات المختلفة.

ثالثًا، بعد نسخ قالب، لا تعتني به مرة أخرى. قد يعمل لمدة أسبوعين، لكنه سيصبح غير فعال دون أن تلاحظ مع تغيرات قاعدة الكود.

تقول الوثائق الرسمية لـ Anthropic بوضوح: إن ملف CLAUDE.md هو مجرد توصية. سيتبع Claude حوالي 80% من الوقت، ولكن بمجرد تجاوز 200 سطر، تنخفض نسبة الالتزام بشكل ملحوظ لأن القواعد المهمة تُطمس بواسطة الضوضاء.

حلّ قوالب كارباتي المشكلة: ملف واحد، 65 سطرًا، 4 قواعد. هذا هو الحد الأدنى الأساسي.

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

القواعد الأصلية الأربع

إذا لم تشاهد مخزن Forrest Chang بعد، فابدأ بهذا الإصدار الأساسي:

القاعدة 1: فكّر قبل الترميز.

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

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

القاعدة 3: تعديلات جراحية.
غيّر فقط الأجزاء الضرورية. لا تُحسّن تلقائيًا الشيفرة أو الملاحظات أو التنسيق المجاورة. لا تُعيد هيكلة الأشياء التي لا توجد بها مشكلة. احتفظ بالنمط الحالي.

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

هذه القواعد الأربعة يمكنها حل حوالي 40٪ من أنماط الفشل التي أراها في جلسات Claude Code غير الخاضعة للإشراف. تكمن الـ 60٪ المتبقية من المشكلات في هذه الفراغات أدناه.

القواعد الثمانية التي أضفتها، والسبب

كل قاعدة تأتي من لحظة حقيقية: لم تعد القواعد الأصلية الأربعة لكارباتي كافية. سأشرح أولاً السيناريو، ثم أقدم القاعدة المقابلة.

قواعد كارباتي لم تغطي هذه النقطة. لذا بدأ النموذج في اتخاذ قرارات حول أمور كان ينبغي التعامل معها بواسطة كود محدد: ما إذا كان ينبغي إعادة محاولة استدعاء واجهة برمجة التطبيقات، أو كيفية توجيه رسالة، أو متى يجب الترقية في المعالجة. والنتيجة كانت أن الأحكام الأسبوعية كانت مختلفة. لقد حصلت على نوع من if-else غير مستقر يُدفع مقابل كل رمز بقيمة 0.003 دولار.

كان الوضع كالتالي: كان هناك كود يُستدعي به Claude لـ"تحديد ما إذا كان ينبغي إعادة المحاولة عند مواجهة خطأ 503". عمل الكود بشكل جيد في البداية واستمر لفترة أسبوعين، ثم أصبح غير مستقر فجأة لأن النموذج بدأ يأخذ جسم الطلب كجزء من سياق التقييم. أصبحت استراتيجية إعادة المحاولة عشوائية لأن المُحفّز نفسه كان عشوائيًا.

بدون قيود ميزانية لـ CLAUDE.md، فهي تشبه شيكًا بيضاء. كل دورة قد تخرج عن السيطرة وتصبح تدفقًا لـ 50,000 رمزًا. النموذج لن يتوقف بنفسه.

كان الوقت كالتالي: استمرت جلسة تصحيح الأخطاء لمدة 90 دقيقة. كان النموذج يعيد التكرار باستمرار حول نفس رسالة الخطأ التي حجمها 8 كيلوبايت، وينسى تدريجيًا ما هي الحلول التي جربها بالفعل. في النهاية، بدأ يقترح حلولًا كانت قد رفضتها منذ 40 رسالة. لو كان هناك ميزان من الرموز، كان ينبغي إيقاف هذه العملية في الدقيقة 12.

عندما يكون هناك تناقض بين جزأين في قاعدة الكود، يحاول كلاود تهدئة الطرفين، مما يؤدي إلى كتابة كود غير متماسك.

كان الوضع كالتالي: كان هناك نمطان معالجة أخطاء في مستودع الكود، أحدهما يعتمد على async/await مع try/catch صريح، والآخر على حدود أخطاء عالمية. استخدم كلاود النموذجين معًا في الكود الجديد الذي كتبه. ونتيجة لذلك، تم معالجة الأخطاء مرتين. استغرقني 30 دقيقة لفهم سبب ابتلاع الأخطاء مرتين.

التعديلات "الجراحية" لكارباتي تخبر كلاود بعدم تغيير الكود المجاور. لكنها لم تخبر كلاود: فهم الكود المجاور أولاً. بدون هذا، سيكتب كلاود كوداً جديداً يتعارض مع الكود القائم على بعد 30 سطراً.

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

يشير "التنفيذ الموجه بالهدف" لكارباتي إلى أن الاختبارات يمكن أن تكون معيارًا للنجاح. لكن في الممارسة العملية، يصبح "تمرير الاختبارات" الهدف الوحيد لـ Claude، فيكتب كودًا يمرر الاختبارات السطحية لكنه يُتلف أشياء أخرى.

كان الوضع كالتالي: كتب كلاود 12 اختبارًا لوظيفة المصادقة، ونجحت جميعها. لكن منطق المصادقة في بيئة الإنتاج كان معطوبًا. كانت تلك الاختبارات تتحقق فقط من أن الوظيفة "أعادت شيئًا ما"، وليس من أنها أعادت الشيء الصحيح. نجحت الوظيفة في الاختبارات لأنها كانت تعيد قيمة ثابتة.

قالب كارباتري يفترض تفاعلاً لمرة واحدة. لكن العمل الحقيقي مع Claude Code غالبًا ما يكون متعدد الخطوات: إعادة هيكلة عبر 20 ملفًا، وبناء ميزة داخل جلسة واحدة، وتصحيح الأخطاء عبر عدة commits. بدون نقاط تفتيش، يمكن أن يُفقد كل التقدم المحرز إذا ارتكبت خطوة واحدة خاطئة.

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

في قاعدة كود بها نمط ناضج بالفعل، يحب كلاود أن يُدخل أسلوبه الخاص. حتى لو كان أسلوبه "أفضل"، فإن إدخال نمط ثانٍ بنفسه أسوأ من أي نمط واحد فقط.

كان الوضع كالتالي: أدخل Claude الـ hooks في قاعدة كود React القائمة على مكونات الفئة. لقد عملت بالفعل، لكنها دمرت نمط الاختبار الأصلي للقاعدة، لأن تلك الاختبارات كانت تعتمد على componentDidMount. واستغرق حذفها وإعادة كتابتها نصف يوم كامل.

أغلى فشل لـ Claude هو غالبًا ذلك الذي يبدو وكأنه نجاح. دالة "تعمل" لكنها تُرجع بيانات خاطئة؛ عملية هجرة "أُكملت" لكنها تخطت 30 سجلاً؛ اختبار "نجح" لكنه فقط لأن التأكيد نفسه كان خاطئًا.

كان الوقت كالتالي: قال كلاود إن نقل قاعدة البيانات "تم إكماله بنجاح". لكنه في الواقع تجاهل بصمت 14% من السجلات التي تسببت في تعارض القيود. تم تسجيل سلوك التجاهل في السجلات، لكنه لم يُكشف صراحةً. بعد 11 يومًا، عندما بدأت بيانات التقارير في التصرف بشكل غير طبيعي، اكتشفنا المشكلة.

على مدار 6 أسابيع، تتبعت نفس مجموعة من 50 مهمة تمثيلية تغطي 30 مستودعًا كوديًا، وقمت باختبار ثلاث تكوينات.

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

يُشير معدل الامتثال إلى احتمالية تطبيق Claude صراحةً للقاعدة عندما تكون قابلة للتطبيق.

النتيجة الحقيقية المثيرة ليست فقط انخفاض معدل الخطأ من 41% إلى 3%. الأهم هو أن التوسع من 4 قواعد إلى 12 قاعدة لم يُضف تقريبًا أي عبء على الامتثال، حيث ظل معدل الامتثال عند 78% ثم انخفض فقط إلى 76%، بينما انخفض معدل الخطأ بمقدار 8 نقاط مئوية إضافية. القواعد الجديدة تغطي أنماط فشل لم تُعالجها القواعد الأربعة الأصلية، ولم تتنافس على نفس ميزانية الانتباه.

أين ستفشل قوالب كارباتي بصمت

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

أولاً، مهام العميل التي تعمل لفترة طويلة.
قواعد كارباتي موجهة بشكل أساسي للحظة التي يكتب فيها كلاود الكود. لكن ماذا يحدث عندما يُشغّل كلاود عملية متعددة الخطوات؟ لم تتضمن القالب الأصلي قواعد الميزانية، ولا قواعد نقاط التفتيش، ولا قاعدة "الفشل بصوت عالٍ". وبالتالي، ستبدأ العملية في الانحراف تدريجيًا.

ثانيًا، الاتساق عبر مستودعات الكود المتعددة.
يُفترض أن "التطابق مع النمط الحالي" يحتوي على نمط واحد فقط. لكن في مونوريبو يحتوي على 12 خدمة، يجب على كلاود أن يختار أي نمط يجب التوافق معه. القاعدة الأصلية لم تُخبره بكيفية الاختيار. لذلك فإما أنه يختار عشوائيًا، أو يمزج عدة أنماط بشكل متساوٍ.

ثالثًا، جودة الاختبار.
"التنفيذ الموجه بالهدف" يُعتبر "اجتياز الاختبار" نجاحًا، لكنه لا يوضح أن الاختبار نفسه يجب أن يكون ذا معنى. والنتيجة هي أن كلاود يكتب اختبارات لا تتحقق تقريبًا من أي شيء، لكنها تجعله يعتقد أنه واثق جدًا.

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

هذه القواعد الثمانية الجديدة ليست مخصصة لاستبدال القواعد الأصلية الأربعة لكارباتي، بل لسد الفراغات فيها: فالقالب الأصلي كان مصممًا لسيناريو كتابة الكود المدعوم بالتكملة التلقائية في يناير 2026؛ بينما بحلول مايو 2026، دخل Claude Code بيئة مدعومة بالوكيل، متعددة الخطوات، ومتعددة مكتبات الكود، حيث تختلف المشكلات التي تواجهها كلا البيئتين.

ما هي الطرق التي لم تنجح؟

قبل تثبيت هذه القواعد الـ12، جربت أيضًا بعض الحلول الأخرى.

انضم إلى القواعد التي رأيتها على Reddit / X.
معظمها إما تكرر قواعد كارباتي الأصلية الأربع بعبارات مختلفة، أو كانت قواعد متخصصة لا يمكن تعميمها، مثل "استخدم دائمًا فئات Tailwind". في النهاية، تم حذفها جميعًا.

أكثر من 12 قاعدة.
لقد اختبرت ما يصل إلى 18 بندًا. بعد تجاوز 14 بندًا، انخفضت نسبة الامتثال من 76% إلى 52%. الحد الأقصى البالغ 200 سطر هو حد حقيقي. بعد تجاوز هذا الطول، يبدأ Claude في إجراء مطابقة نمطية على أنه "هناك قواعد"، بدلاً من قراءة القواعد فعليًا واحدًا تلو الآخر.

Rules that depend on the existence of certain tools.
على سبيل المثال، "استخدم دائمًا eslint"، إذا لم يتم تثبيت eslint في المشروع، فستصبح هذه القاعدة غير فعالة، وتفشل بصمت. لاحقًا، قمت بتعديلها إلى تعبير لا يعتمد على أداة محددة، مثل تغيير "استخدم eslint" إلى "اتبع النمط المُطبَّق بالفعل في مستودع الكود".

أضف الأمثلة في CLAUDE.md، وليس القواعد.
المثال يحتل سياقًا أكثر من القواعد. ثلاثة أمثلة تستهلك من السياق ما يعادل تقريبًا 10 قواعد، كما أن كلاود يُصاب بسهولة بالتكيف المفرط مع الأمثلة. القواعد مجردة، بينما الأمثلة محددة. لذلك، يجب استخدام القواعد.

كن حذرًا، فكّر بعناية، ركّز قليلاً.
كل هذه ضوضاء. انخفض معدل الامتثال لهذه التعليمات إلى حوالي 30% لأنها لا يمكن التحقق منها. لاحقًا، استبدلتُها بقواعد إجرائية أكثر تحديدًا، مثل "وضح الافتراضات".

أخبر Claude أن يتصرف كـ "مهندس خبير".
هذا لا يفيد. كلاود يشعر بالفعل أنه مهندس خبير. المشكلة الحقيقية ليست في ما إذا كان يشعر بذلك، بل في ما إذا كان ينفذ ذلك. القواعد الإجرائية يمكنها تقليل هذه الفجوة، لكن التلميحات الهوية لا يمكنها.

النسخة الكاملة من 12 قاعدة CLAUDE.md

إليك النسخة الكاملة القابلة للنسخ واللصق مباشرة.

لا يمكن عرض هذا المحتوى خارج مستندات Feishu مؤقتًا

احفظه كملف CLAUDE.md في الجذر الرئيسي للمستودع. أسفل هذه القواعد الـ12، أضف قواعد خاصة بالمشروع، مثل تقنيات التكنولوجيا، أو أوامر الاختبار، أو أنماط الأخطاء. لا يتجاوز المجموع 200 سطر، فبعد ذلك تنخفض معدلات الالتزام بالقواعد بوضوح.

كيفية التثبيت

بخطوتين فقط:

أضف القواعد الأربع الأساسية لكارباتي إلى ملف CLAUDE.md الخاص بك
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. الصق القواعد 5–12 من هذا النص أدناه

احفظ الملف في الجذر الرئيسي للمستودع. إن الرمز >> مهم جدًا، فهو يُستخدم لإضافة المحتوى إلى ملف CLAUDE.md الموجود مسبقًا، وليس لاستبدال القواعد الخاصة بالمشروع التي كتبتها بالفعل.

CLAUDE.md ليس قائمة أمنيات، بل هو عقد سلوكي مصمم لإغلاق أنماط الفشل المحددة التي لاحظتها.

كل قاعدة يجب أن تجيب على سؤال: ما الخطأ الذي تمنعه؟

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

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

بالطبع، تختلف النتائج من شخص لآخر. إذا لم تستخدم أنبوب عمل متعدد الخطوات، فإن القاعدة 10 ليست ذات أهمية كبيرة بالنسبة لك. إذا كان مخزن كودك يعتمد على نمط موحد واحد فقط، ويتم تطبيقه تلقائيًا بواسطة أداة التحقق، فإن القاعدة 11 غير ضرورية. بعد قراءة هذه القواعد الـ12، احتفظ بالقواعد التي تتوافق حقًا مع الأخطاء التي ارتكبتها سابقًا، واحذف الباقي.

نسخة مخصصة من CLAUDE.md بست قواعد مصممة خصيصًا لحالات الفشل الحقيقية، أفضل من نسخة تحتوي على 12 قاعدة، ستكون 6 منها غير مستخدمة أبدًا.

خاتمة

التغريدة التي نشرها كارباتي في يناير 2026 كانت في جوهرها شكوى. حوّل فورست تشانغ ذلك إلى 4 قواعد. في النهاية، منح 120 ألف مطور هذا الناتج علامة نجمة. ومع ذلك، لا يزال معظم هؤلاء الأشخاص اليوم يستخدمون فقط تلك القواعد الأربع.

لقد تقدم النموذج، وتغيرت البيئة. الوكلاء متعدد الخطوات، تفعيل السلسلة عبر الـ hook، تحميل المهارات، التعاون بين مكتبات كود متعددة—جميعها لم تكن موجودة عندما كتب كارباتي تلك التغريدة. القواعد الأصلية الأربع لم تحل هذه المشكلات. ليست خاطئة، بل غير كاملة.

تم إضافة 8 قواعد جديدة. 6 أسابيع، تغطي اختبارات 30 مستودعًا كوديًا. انخفض معدل الأخطاء من 41% إلى 3%.

احفظ هذه المقالة الليلة، وانسخ هذه القواعد الـ12 إلى ملف CLAUDE.md الخاص بك. إذا وفرت عليك أسبوعًا من تجربة Claude، فشاركها.