ما الذي يدخل في CLAUDE.md مقابل الـ README؟

الـ README لبني البشر الذين يتصفّحون المشروع؛ والـ CLAUDE.md هو الـ context العملي الذي يقرأه Claude في كل مهمة. هناك تداخل، لكن الـ CLAUDE.md يميل إلى التشغيلي — أوامر test/lint/build الدقيقة، والأعراف التي تُتّبع، والـ guardrails على ما لا يُلمَس — مصاغًا كتعليمات إلى agent يؤدّي العمل، لا مقدّمة لقارئ جديد. قاعدة جيدة: إن كان يغيّر كيف تُنجَز المهمة (شغّل هذا الأمر، اتّبع هذا النمط، لا تلمس هذا)، فمكانه الـ CLAUDE.md.

هل يقرأ Claude الـ CLAUDE.md تلقائيًّا، أم عليّ توجيهه إليه؟

تلقائيًّا — حين يكون الـ repo مفتوحًا في Claude Desktop (أو شغّلت claude في المجلد الجذر للمشروع)، يقرأ Claude الـ CLAUDE.md كجزء من context المشروع لكل مهمة، دون أي prompt. هذه هي الغاية كلّها: تكتبه مرّة واحدة، فتبدأ كل محادثة لاحقة راسخةً فيه بدل أن تعيد أنت شرح الأساسيات.

بمَ يختلف هذا عن playbook الـ map-the-codebase؟

الـ map-the-codebase هو القراءة — جولة لمرّة واحدة تمنحك أنت، الإنسان، نموذجًا ذهنيًّا عن repo غير مألوف. وهذا الـ playbook يحوّل تلك القراءة إلى أصل دائم: ملف مُدرَج يرسّخ كل مهمة وزميل في المستقبل تلقائيًّا. الخريطة تجيب عن «ما هذا الكود؟» مرّة واحدة؛ والـ CLAUDE.md يجيب عن «كيف نعمل في هذا الـ repo؟» إلى الأبد. شغّل الخريطة أولًا، ثم قطّرها في الملف.

نحن monorepo بـ packages كثيرة — هل CLAUDE.md واحد أم عدّة؟

كلاهما. أبقِ CLAUDE.md جذريًّا لما هو صحيح عبر الـ repo كلّه (الأعراف المشتركة، البنية المعمارية العليا)، وأضِف CLAUDE.md لكل package يحوي أوامره وأنماطه المحلية. يقرأ Claude الأقرب إلى الكود الذي يعمل عليه، فتحصل مهمة في package ما على تفاصيل ذلك الـ package دون ضوضاء البقية.

اكتب الـ CLAUDE.md الذي يرسّخ كل مهمة

متى تلجأ إلى هذا

كل محادثة جديدة تعيد شرح الأشياء نفسها: كيف تشغّل الـ tests، والأعراف التي تتّبعها، وما هو أساسيّ وممنوع المساس به. كلٌّ يعيد صياغتها بشكل مختلف قليلًا، فتعني «أعرافنا» ما طبع آخر مهندس أن يكتبه. الـ CLAUDE.md المُدرَج في الـ repo هو العلاج — إنه ذاكرة المشروع التي يقرأها Claude تلقائيًّا، فتشير «طريقتنا» أخيرًا إلى مستند حقيقي واحد بدل تخمين كل شخص. ابنِه مبكرًا. إنه الأصل الذي يجعل بقية المسار حادًّا: كل playbook لاحق (debug، test، refactor، ship، migrate) يبدأ من الحقيقة نفسها بدل إعادة الجدل حول الأساسيات، وأول محادثة لزميل جديد تكون راسخة منذ اليوم الأول.

جهّز هذا أولًا

الـ repo مفتوحًا في Claude Desktop — افتح المجلد الجذر للمشروع كي يقرأ Claude ملفاتك الحقيقية ويصوغ المسوّدة ممّا هو موجود فعلًا. (مسار Power Track: تشغيل claude في المجلد الجذر من الـ Terminal يفعل الشيء نفسه.)
حلقة التطوير الحقيقية لديك: الأوامر الدقيقة التي تشغّلها للـ tests، والـ lint، والـ type-check، والـ build — تلك التي في رأسك أو في سجلّ shell، لا ما يدّعيه الـ README المتقادم.
الأعراف وقواعد «دائمًا / أبدًا» التي تعيش في رؤوس الناس فقط: أنماط التسمية، والأجزاء الأساسية، وأين تعيش الـ secrets، وما لا يُلمَس.

الـ workflow

اجعل Claude يصوغ مسوّدة الـ CLAUDE.md ممّا قرأه فعلًا

افتح المجلد في Claude Desktop واسأل في المحادثة — دون حاجة إلى Terminal. لا تكتب الملف من الصفر؛ دع Claude يقرأ الـ repo ويصوغ نسخة أولى ممّا هو موجود فعلًا، ثم تصحّحها أنت. المسوّدة المرسّخة في شجرتك الفعلية أسرع في الإصلاح من صفحة بيضاء في الملء.

أنت تطلب

اقرأ هذا الـ repo وصُغ له `CLAUDE.md`: خريطة معمارية قصيرة (الـ modules العليا، والمجلدات الرئيسية، وكيف يتدفّق request نموذجي من نقطة الدخول إلى البيانات)، بناءً فقط على ما وجدته فعلًا في الملفات — لا نسخة عامة من هذا الـ framework. أبقِه محكمًا؛ وسمِّ ملفات حقيقية.

ما تحصل عليه مسوّدة أولى من CLAUDE.md تصف الـ repo الخاص بك — أسماء مجلدات حقيقية، ومسار الـ request الفعلي — لا وصفًا من كتاب لـ stack الخاص بك. إن قُرئت عامةً، فهو لم يقرأ الملفات؛ أعِد توجيهه إلى المجلد الجذر للمشروع.

هذا يبني مباشرةً على playbook الـ map-the-codebase — تلك القراءة هي المادة الخام، وهذا يحوّلها إلى أصل دائم مُدرَج في الـ repo. صحّح كل ادّعاء قبل أن تُبقيه؛ أنت صاحب القرار على هذا الملف كما على أي diff.
التقِط حلقة التطوير الحقيقية

أعلى شيء قيمةً في الـ CLAUDE.md هو الأوامر الدقيقة لتشغيل الـ tests، والـ linter، والـ type-checker، والـ build. بوجودها في الملف، يستطيع الـ agent تشغيل حلقتك وتصحيح نفسه مقابل الأخطاء بدل تخمين ما إذا كان تغييره يعمل.

أنت تطلب

أضِف قسم "Commands" إلى الـ `CLAUDE.md` يحوي الأوامر الدقيقة لتشغيل الـ test suite، والـ linter، والـ type-checker، والـ build. وهذه الأوامر الحقيقية التي نستخدمها: <ألصِق أوامرك الفعلية>. ووضّح أيّها للفحص السريع مقابل التمريرة الكاملة.

ما تحصل عليه كتلة Commands بأوامرك الحقيقية، كي تستطيع أي مهمة لاحقة تشغيل الـ test suite والوثوق بالأحمر — يرى الـ agent إخفاقاته ويصلحها بدل إعلان النصر بلا أساس.

أعطِه الأوامر الحقيقية، لا إعادة صياغة. أمر test خاطئ في الـ CLAUDE.md أسوأ من غيابه — سيشغّله الـ agent، ويحصل على خطأ مربك، ويلتفّ حول شبكة أمانك.
اكتب الأعراف والـ guardrails

الآن رسّخ القواعد التي تعيش في رؤوس الناس فقط: الأنماط التي تُتّبع، وما هو أساسيّ، والخطوط التي لا تُتجاوز. هذا ما يجعل «افعلها بطريقتنا» يعني شيئًا محدّدًا.

أنت تطلب

أضِف قسم "Conventions" وقسم "Guardrails". Conventions: تسميتنا، والأنماط التي تُتّبع، وكيف نبني module نموذجيًّا — استنتج مسوّدة من الكود، وسأصحّحها. Guardrails: الأجزاء الأساسية الممنوع تغييرها باستهتار، وأين تعيش الـ secrets والـ credentials كي تبقى خارج الـ context. ضع علامة على أي شيء لست متيقّنًا منه بدل اختراع قاعدة.

ما تحصل عليه أعراف وguardrails مذكورة بوضوح كافٍ كي تتّبعها مهمة لاحقة — أو زميل جديد — دون أن يُقال لها ذلك. سطر الـ secrets يُبقي الـ credentials وبيانات العملاء خارج الـ context window: المجلد المفتوح هو الحدّ، والملف يقول ذلك.

راجِع هذا كأي diff: لا تدعه يرسّخ عرفًا لا تتّبعه فعلًا. القاعدة الطموحة التي لا يلتزم بها أحد تدرّب الـ agent على كتابة كود سيرفضه فريقك في المراجعة.
أدرِجه وأثبِت أنه يعمل

أدرِج الملف كالكود، ثم تحقّق أنه فعلًا يرسّخ محادثة جديدة — فالغاية كلّها أن تبدأ المحادثة التالية وهي تعرف كل هذا دون أن تعيد شرحه.

أنت تطلب

أدرِج الـ `CLAUDE.md` في الـ staging واعمل له commit برسالة تشرح ما يغطّيه ولماذا. ثم، في محادثة جديدة: دون أن أشرح أي شيء، أخبرني كيف ستشغّل الـ tests لهذا المشروع، والعُرفين الرئيسيين اللذين ستتّبعهما — مستخدمًا الـ `CLAUDE.md` فقط.

ما تحصل عليه ملف CLAUDE.md مُدرَج، ومحادثة جديدة تعرف مسبقًا أمر الـ test وأعرافك دون أي إعادة شرح. هذا الترسيخ الصامت — بدء كل مهمة من الحقيقة نفسها — هو كامل عائد العشرين دقيقة.

اقرأ الـ diff قبل أن توافق على الـ commit. من هنا فصاعدًا، كل محادثة في هذا الـ repo ترث هذا الملف تلقائيًّا — وهذا تحديدًا سبب وجوب أن يكون صحيحًا.

اجعله ملكك

monorepo: أضِف CLAUDE.md لكل package بجوار الملف الجذر — يحصل كل package على أوامره وأعرافه الخاصة، ويقرأ Claude الأقرب منها. الملف الجذر يحوي ما هو صحيح في كل مكان؛ وملفات الـ packages تحوي الحقيقة المحلية.
رقِّ الـ prompts التي تكرّرها (Power Track): الـ prompts التي تجد نفسك تعيد كتابتها كل أسبوع مرشّحة لتكون slash commands أو skills — حوّلها إلى commands قابلة لإعادة الاستخدام كي يشغّل الفريق كلّه التدفّق نفسه، لا تقريبًا مكتوبًا باليد (انظر تبويب Features).
أنشئ منه نسخًا كالكود: أبقِ الـ CLAUDE.md تحت المراجعة — تنزل التغييرات على شكل commits مراجَعة بـ لماذا واضح، تمامًا كـ ADR، كي يبقى الملف جديرًا بالثقة بدل أن ينحرف.

انتبه إلى

راجِع الملف المُصاغ كأي diff. يستنتج Claude الأعراف من الكود، والكود ليس دائمًا العُرف الذي تريده — لا تدعه يكرّس نمطًا تحاول الابتعاد عنه. أنت صاحب القرار على هذا الملف أيضًا.
أبقِ الـ secrets خارج الملف نفسه. وثّق أين تعيش الـ credentials وأنها تبقى خارج الـ context — لا تلصق أبدًا key أو token أو connection string فعليًّا في الـ CLAUDE.md. إنه مُدرَج في الـ repo؛ عامِله كأنه مكشوف لكل من لديه وصول إلى الـ repo.
الـ `CLAUDE.md` الذي لا يحدّثه أحد يتعفّن. الملف المتقادم أسوأ من غيابه — يرسّخ كل مهمة بثقة في حقيقة الربع الماضي. أعطِه مالكًا وحدّثه حين تتغيّر الأعراف أو الأوامر تغيّرًا حقيقيًّا، كما تصون ADR.

ستحصل في النهاية على ملف `CLAUDE.md` مُدرَج — خريطة معمارية، وأوامر تطوير حقيقية، وأعراف، وguardrails — يقرأه Claude تلقائيًّا في كل مهمة. محادثات الفريق كلّها تبدأ من الحقيقة نفسها، فيبدأ كل playbook لاحق في المسار راسخًا بدل التخمين، ويصير الزميل الجديد منتجًا منذ اليوم الأول.

أسئلة يطرحها الناس

ما الذي يدخل في CLAUDE.md مقابل الـ README؟: الـ README لبني البشر الذين يتصفّحون المشروع؛ والـ `CLAUDE.md` هو الـ context العملي الذي يقرأه Claude في كل مهمة. هناك تداخل، لكن الـ `CLAUDE.md` يميل إلى التشغيلي — أوامر test/lint/build الدقيقة، والأعراف التي تُتّبع، والـ guardrails على ما لا يُلمَس — مصاغًا كتعليمات إلى agent يؤدّي العمل، لا مقدّمة لقارئ جديد. قاعدة جيدة: إن كان يغيّر *كيف* تُنجَز المهمة (شغّل هذا الأمر، اتّبع هذا النمط، لا تلمس هذا)، فمكانه الـ `CLAUDE.md`.
هل يقرأ Claude الـ CLAUDE.md تلقائيًّا، أم عليّ توجيهه إليه؟: تلقائيًّا — حين يكون الـ repo مفتوحًا في Claude Desktop (أو شغّلت `claude` في المجلد الجذر للمشروع)، يقرأ Claude الـ `CLAUDE.md` كجزء من context المشروع لكل مهمة، دون أي prompt. هذه هي الغاية كلّها: تكتبه مرّة واحدة، فتبدأ كل محادثة لاحقة راسخةً فيه بدل أن تعيد أنت شرح الأساسيات.
بمَ يختلف هذا عن playbook الـ map-the-codebase؟: الـ map-the-codebase هو *القراءة* — جولة لمرّة واحدة تمنحك أنت، الإنسان، نموذجًا ذهنيًّا عن repo غير مألوف. وهذا الـ playbook يحوّل تلك القراءة إلى *أصل دائم*: ملف مُدرَج يرسّخ كل مهمة وزميل في المستقبل تلقائيًّا. الخريطة تجيب عن «ما هذا الكود؟» مرّة واحدة؛ والـ `CLAUDE.md` يجيب عن «كيف نعمل في هذا الـ repo؟» إلى الأبد. شغّل الخريطة أولًا، ثم قطّرها في الملف.
نحن monorepo بـ packages كثيرة — هل CLAUDE.md واحد أم عدّة؟: كلاهما. أبقِ `CLAUDE.md` جذريًّا لما هو صحيح عبر الـ repo كلّه (الأعراف المشتركة، البنية المعمارية العليا)، وأضِف `CLAUDE.md` لكل package يحوي أوامره وأنماطه المحلية. يقرأ Claude الأقرب إلى الكود الذي يعمل عليه، فتحصل مهمة في package ما على تفاصيل ذلك الـ package دون ضوضاء البقية.