CLAUDE.md: اجعل الذكاء الاصطناعي يفهم حقًا مشروعك
ملف واحد لتخزين مواصفات مشروعك وقرارات البنية وأعراف الفريق بشكل دائم — يقرأه Claude في بداية كل جلسة
آخر تحديث 2026-11-14
ما هو CLAUDE.md؟
CLAUDE.md هو ملف خاص في جذر مشروعك يقرأه Claude Code تلقائيًا عند بدء التشغيل. وهو «إحاطة مشروع» موجهة إلى الذكاء الاصطناعي — تتضمن التقنيات المستخدمة وأعراف البرمجة وبنية المجلدات والأوامر الأساسية، حتى يفهم Claude سياقك من دون شرح متكرر. اعتبارًا من 2026-10-07: إذا كان المستودع يحتوي على AGENTS.md لكنه لا يحتوي على CLAUDE.md، فإن Claude Code 2.1.277 وما بعده يقرأ AGENTS.md بدلًا منه.
تعرّفه الوثائق الرسمية بأنه المكان الذي تكتب فيه ما كنت ستظل تعيد شرحه: لا تنتمي إليه إلا الحقائق التي تحتاجها كل جلسة، أما تفاصيل المهمة لمرة واحدة فتبقى في المحادثة (تم التحقق في 2026-09-21).
ملف نصي عادي
إنه ملف markdown عادي في المستودع: تكتبه وتودعه (commit) وتقرؤه وتقارن تغييراته (diff) مثل أي ملف آخر. وفقًا للوثائق، تكتبه أنت ويقرأه Claude Code في بداية كل جلسة (تم التحقق في 2026-09-21).
يُحمّل عند التشغيل
يُحمّل CLAUDE.md في دليل العمل وكل مستوى أعلى منه عند التشغيل؛ وتُحمّل ملفات الدلائل الفرعية بمجرد أن يقرأ Claude ملفات هناك (تم التحقق في 2026-09-21).
سياق، لا إعدادات
يُحمّل في نافذة السياق عند كل جلسة ويستهلك tokens إلى جانب محادثتك، دون أي ضمان للالتزام الصارم به — تسميه الوثائق سياقًا، لا إعدادات مفروضة (تم التحقق في 2026-09-21).
لماذا CLAUDE.md؟
العائد ثلاثي: لا مزيد من كتابة الخلفية في بداية كل جلسة، والشكل نفسه للإخراج أيًا كان من يسأل، وتأهيل لا يعتمد على التقاليد الشفهية.
إلغاء التكرار
لا حاجة بعد الآن إلى شرح «نستخدم TypeScript» أو «تُشغَّل الاختبارات باستخدام Jest» في كل جلسة — اكتب مرة واحدة، لتبقى فعّالة إلى الأبد
إخراج متسق
حدّد أسلوب البرمجة وأعراف التسمية وقيود البنية لضمان أن يتوافق إخراج Claude دائمًا مع معايير المشروع
مشاركة معرفة الفريق
عند انضمام أعضاء جدد، يعمل CLAUDE.md كإعداد للذكاء الاصطناعي ودليل تأهيل للمشروع مقروء للبشر في آن واحد
القالب الموصى به
يتضمن CLAUDE.md الجيد عادةً هذه الأقسام
# نظرة عامة على المشروع
- الواجهة الخلفية لمركز الطلبات، وREST API لتطبيق الويب والبرنامج المصغر
- يقرأ المنضمون الجدد هذا الملف، ثم دليل التأهيل
- قبل أي تغيير في API، تحقق مما إذا كان العملاء بحاجة إلى مزامنة
## المكدس التقني
- اللغة TypeScript على Node.js، وpnpm للحزم
- PostgreSQL للبيانات، وتُخدَم القراءات الساخنة من Redis
- Vitest للاختبارات، وتُفرض تغطية الاختبارات في CI
## هيكل الدلائل
- src/api: نقطة دخول HTTP وفحوص الوسائط، بلا قواعد أعمال
- src/domain: قواعد الأعمال، بلا استيرادات من أطر العمل
- tests: يحاكي شجرة src، ما يسرّع تحديد موضع الإخفاقات
## اصطلاحات الشيفرة
- مسافة بادئة بمقدار مسافتين، وعلامات اقتباس مفردة، والإبقاء على الفواصل المنقوطة
- أسماء مكتوبة كاملة، بلا اختصارات
- لا أنواع أُطُر في طبقة النطاق، فذلك عيب
## الأوامر الشائعة
- npm run dev: التشغيل محليًا
- npm test: مجموعة اختبارات الوحدة الكاملة، ويجب أن تنجح قبل أن تتوقف
- npm run lint: مرة واحدة قبل الالتزام
## ملاحظات مهمة
- لا أسرار أو عناوين URL داخلية هنا، استخدم متغيرات البيئة
- شغّل ترحيلات قاعدة البيانات على قاعدة بيانات ظل أولًا
- حالة حدّية غير واضحة: اسأل، ولا تخترع قيمة افتراضيةنصائح متقدمة
هذه النقاط الخمس تحدد ما إذا كان الملف سيُتبع أم سيصبح ضجيجًا لا يعيد أحد قراءته؛ وكل نقطة تقدم اختبارًا يمكنك تطبيقه على ملفك.
الحقائق المتكررة فقط
الاختبار مباشر: هل ما زال هذا السطر مفيدًا في الجلسة التالية؟ أوامر البناء وقواعد التسمية والمزالق السابقة تستوفي المعيار؛ أما قوائم الدلائل وقوائم التبعيات فلا — يستخلصها Claude من الشيفرة (تم التحقق في 2026-09-21).
ابقَ تحت 200 سطر
الإرشاد في الوثائق هو أقل من 200 سطر لكل ملف؛ وما يتجاوز ذلك يستهلك سياقًا أكبر ويُتبع بدرجة أقل (تم التحقق في 2026-09-21). إذا لم يتناسب، فقسّمه إلى قواعد محددة النطاق حسب المسار تُحمّل فقط عندما يتعامل Claude مع ملفات مطابقة.
اجعله قابلًا للتحقق
«نسّق الشيفرة بشكل جميل» لا يحمل أي معلومات؛ أما «مسافة بادئة بمسافتين، وعلامات اقتباس مفردة، وشغّل npm test قبل الإيداع» فيمكن الالتزام به. جمّع الأسطر ضمن عناوين فرعية ونقاط — يستعرض Claude البنية كما يفعل القارئ (تم التحقق في 2026-09-21).
ولّد ثم قلّم
لا تبدأ من صفحة فارغة: يحلل /init قاعدة الشيفرة ويصوغ مسودة أوامر البناء وإعداد الاختبار والاصطلاحات التي يجدها؛ ثم احذف الحشو بالطريقة نفسها التي يفعلها /doctor، مع الإبقاء على المزالق والمبررات؛ واختم بـ /context للتأكد من تحميل الملف (تم التحقق في 2026-09-21).
لا أسرار بالداخل
يُحفظ هذا الملف في Git ويقرأه الجميع في كل جلسة. احتفظ بالأسرار وعناوين URL الداخلية وحسابات الاختبار في متغيرات البيئة؛ ضع التفضيلات الشخصية في CLAUDE.local.md وأضفه إلى gitignore حتى تبقى نسخة الفريق نظيفة (تم التحقق في 2026-09-21).
معايير تعاون الفريق
أفضل الممارسات لصيانة CLAUDE.md في المشاريع متعددة الأشخاص
راجعها كما تراجع الشيفرة
نسخة المشروع أصل من أصول الفريق وليست ملاحظات خاصة: غيّرها في PR نفسه الذي يحمل الشيفرة، واشرح السبب، واطلب من مالك ذلك الدليل مراجعتها. وتقول الوثائق: تُشارَك تعليمات المشروع عبر نظام التحكم بالإصدارات (تم التحقق في 2026-09-21).
الترتيب والتعارضات
تُحمّل الملفات أعلاه في السياق أولًا، وملفات الدلائل الفرعية عند الحاجة — يُدمج المحتوى بالتسلسل، ولا يلغي أي منها الآخر. إذا صاغ ملفان السلوك نفسه بصيغتين مختلفتين، فقد يختار Claude أيّهما عشوائيًا، لذا وحّد الصياغة أو احذف أحدهما (تم التحقق في 2026-09-21).
قسّم حسب الوحدة
في مستودع كبير لا تحشُ الملف الجذري: توضع الملاحظات الخاصة بكل وحدة في CLAUDE.md داخل دليل فرعي أو في قاعدة محددة النطاق حسب المسار، وهي لا تدخل السياق إلا عندما يعمل Claude هناك — أرخص وأدق من ملف جذري ضخم واحد (تم التحقق في 2026-09-21).
أتمتة التحقق
اجعل أمرين روتينًا: أن تتحقق CI من وجود CLAUDE.md في الجذر ومن بقائه ضمن الحجم المتفق عليه، وأن يعيد كل PR للبنية المعمارية قراءة المدخلات القائمة. وتطلب الوثائق بالمثل إزالة دورية للتعليمات القديمة والمتعارضة (تم التحقق في 2026-09-21).
الأخطاء الشائعة
كل هذه الأربعة تحوّل الملف من رافعة إلى ضجيج، ولا يحتاج أي منها إلى إعادة كتابة لإصلاحه.
ملاحظات مهام وليست قواعد
لصق خطوات إعادة إنتاج خلل واحد أو ملاحظات مؤقتة لإعادة هيكلة واحدة يعني أنها ستظل تشغل السياق في الجلسة التالية بينما لم تُكتب قاعدة عامة. مكان ذلك هو issue أو وصف PR (تم التحقق في 2026-09-21).
إنه ينمو فقط
تضع الوثائق الحد عند 200 سطر: بعد ذلك يصبح الملف أكبر كلفة على السياق وأقل التزامًا (تم التحقق في 2026-09-21). لا يجدي علاج التضخم بإضافة قاعدة أخرى — انقل منه ما يهم في بعض الدلائل فقط.
القواعد تتناقض
ملف الجذر يقول pnpm، وملف في دليل فرعي يقول npm — وقد يتبع Claude أيّهما استقر عليه (تم التحقق في 2026-09-21). احتفظ ببيان مرجعي واحد لكل موضوع وارجع إليه من مواضع أخرى بدل نسخ نسخة ثانية.
لا أحد يتولى صيانته
تغيّرت حزمة التقنيات، وأُعيدت هيكلة التخطيط، لكن الأوامر في الملف ما زالت القديمة. تطلب الوثائق مراجعة دورية لكل مستوى، مع حذف المدخلات القديمة والمتعارضة (تم التحقق في 2026-09-21) — وأسهل إطلاق ذلك من PR البنية المعمارية.
الأسئلة الشائعة
هل يجب تغذية CLAUDE.md في كل جلسة؟
لا. يُحمّل CLAUDE.md الموجود في دليل العمل لديك أو في أي دليل أعلى منه تلقائيًا عند بداية الجلسة؛ وتنضم ملفات الأدلة الفرعية عندما يقرأ Claude الكود هناك. شغّل /context وافحص قائمة ملفات الذاكرة لترى ما حُمّل فعليًا (تم التحقق في 2026-09-21).
ما الحجم الكبير جدًا؟
المرجع الموثّق أقل من 200 سطر لكل ملف؛ وبعد ذلك ترتفع كلفة السياق وينخفض الالتزام (تم التحقق في 2026-09-21). انقل محتوى كل وحدة إلى ملفات قواعد محددة النطاق حسب المسار بحيث لا يُحمّل إلا عندما يتعامل Claude مع الملفات المطابقة.
ماذا عن AGENTS.md؟
الوضع الافتراضي هو «إما/أو»: أي CLAUDE.md في دليل العمل لديك أو أعلى منه يمنع تحميل AGENTS.md. للحصول على كليهما، اضبط Project instructions في لوحة /config على تحميل كليهما، أو استورد الملف من CLAUDE.md عبر @AGENTS.md (تم التحقق في 2026-09-21). أُضيف في 2026-10-07: وصل هذا السلوك في Claude Code 2.1.277 (صدر في 2026-09-18)، ويقول سجل تغييراته «أُضيف دعم AGENTS.md: في مشروع بلا CLAUDE.md، يقرأ Claude Code ملف AGENTS.md بدلًا منه»؛ ومنذ 2.1.281 (2026-09-23) يعمل أيضًا في جلسات LLM gateway.
من يتولى صيانته؟
سير العمل نفسه المتبع مع الشيفرة: توجد نسخة المشروع في نظام التحكم بالإصدارات وتُراجَع مع التغيير الذي حفّزها، ومن يمسّ البنية المعمارية يحدّثها. تُوضع التفضيلات الشخصية في ملف محلي منفصل يستبعده gitignore، وتطلب الوثائق تنظيفًا دوريًا للمدخلات القديمة (تم التحقق في 2026-09-21).
ممارسات الفريق مع QCode.cc
مفتاح API واحد من QCode.cc + CLAUDE.md موحّد = برمجة بالذكاء الاصطناعي متسقة وفعّالة لفريقك بأكمله
مفتاح واحد للفريق
يشارك الفريق مفتاح QCode.cc واحدًا ويُسجّل الاستخدام تحت حساب واحد، بدلًا من مفتاح لكل شخص (تم التحقق في 2026-09-21).
بدّل النماذج واحتفظ بالملف
يقرأ العميل ملف CLAUDE.md داخل المشروع، وهو لا يعتمد على النموذج الذي يجيب، لذا لا يتطلب تبديل النماذج إعادة كتابة.
نقطة بداية واحدة
يبدأ الجميع من النقطة نفسها: الوافد الجديد والمهندس الخبير يسألان بمسلمات المشروع نفسها في السياق، لذا يتوقف الإخراج عن الاعتماد على من كتبه.
أشكال المشاريع الثلاثة
لا ينبغي أن يُنتج القالب نفسه الملف نفسه. تحتاج أشكال المستودعات الثلاثة هذه إلى أمور مختلفة يجب توضيحها؛ واحذف كل ما تبقى.
الواجهة الخلفية للفريق
وضّح بالتفصيل أوامر البناء والترحيل، وقواعد التوافق الصارمة مع API، والمجلدات المحظورة؛ هنا الجزء المكلف هو ما يكرره الجميع.
مكتبة مفتوحة المصدر
تدفق المساهمات ومتطلبات الاختبار وما يُعد تغييرًا كاسرًا: يعمل المساهمون الخارجيون والمشرفون من النص نفسه، لذا يجب أن يكون كل سطر قابلًا للتحقق.
أدوات فردية
تخطَّ قائمة الأقسام الكاملة. أبقِ طريقة تشغيله وسياسة إصدارات التبعيات والقيود الصارمة مثل «لا تُعد تنسيق الملف بأكمله» — لا أكثر.
اكتب CLAUDE.md أفضل، وبرمج بذكاء أكبر
ذاكرة المشروع + خطة QCode.cc = أفضل ممارسات البرمجة بالذكاء الاصطناعي للفريق