دليل استخدام CLAUDE.md: اكتب قواعد المشروع في ذاكرته
📚 التنقل في السلسلة: المقال السابق 17 الصور والوسائط المتعددة علمك كيفية تزويد Claude باللقطات وصور الأخطاء مباشرة. يغير this المقال الاتجاه — سنقوم بكتابة "قواعد" المشروع دفعة واحدة في ذاكرته، ليلتزم بها تلقائيًا عند بدء العمل في كل مرة، وتتجنب تكرارها يوميًا.
يقال إن كتابة CLAUDE.md بأكبر قدر من التفاصيل هو الأفضل، ولكن لنكن صادقين، إن ملف CLAUDE.md الأكثر عديم الفائدة هو بالضبط ذلك الذي تمت كتابته في 300 سطر ولم يلتزم Claude بأي منها.
تخيل ملف CLAUDE.md تركه لك زميل سابق في مشروع استلمته للتو، مليء بالتفاصيل: خلفية الشركة، ورؤية المنتج، ومقدمة الفريق، وتاريخ اختيار التقنيات... ولا تظهر لك جملة مفيدة إلا في الصفحة الثانية مثل "استخدم pnpm وتجنب npm". والنتيجة؟ يستمر Claude في تشغيل npm install بشكل متكرر دون اهتمام.
المشكلة ليست في عدم التزامه، بل في أن تلك القاعدة الهامة دفنت وسط 200 سطر من الكلام الحشو، وتشتت انتباهه قبل الوصول إليها.
ملف CLAUDE.md (ملف ذاكرة المشروع لـ Claude) هو أداة رائعة عند إعدادها بشكل صحيح، وعبء ثقيل إذا أسأت كتابتها — فهو يستهلك جزءًا من نافذة السياق الخاصة بك في كل جلسة، وكلما كان أضخم، قلّت المساحة المتاحة للعمل الفعلي. سنفصل هذا الأمر اليوم: مستويات الملف، ما الذي يجب كتابته وما يجب تجنبه، كيفية الإشارة لملفات أخرى، وكيفية صيانته وإبقائه مختصرًا.
بعد قراءة هذا المقال، ستحصل على:
- مستويات CLAUDE.md الثلاثة (المستخدم / المشروع / الدليل الفرعي)، وظيفة كل منها، وترتيب تحميلها
- قائمة بـ "ما يجب كتابته مقابل ما يجب تجنبه" لتتجنب الفخ الذي يقع فيه 90% من المبتدئين بحشو الملف ببيانات لا داعي لها
- الطريقة الصحيحة لاستخدام الرمز
@للإشارة لملفات أخرى، والتكلفة الحقيقية لذلك على حجم السياق - الطريقة الرسمية لإضافة ملاحظة سريعة للذاكرة أثناء الجلسة، مع جدول مقارنة بين "القواعد الجيدة والرديئة" كمرجع
ℹ️ 本篇只聚焦 CLAUDE.md 这一个文件怎么写好、怎么维护。
/init一键生成的玩法在 12「项目初始化」 讲过了，更广的自动记忆（auto-memory）机制留给 25「记忆系统」 专门聊。
01 先搞懂：CLAUDE.md 到底是什么
الخلاصة أولاً: يعد CLAUDE.md بمثابة "توجيهات دائمة" تكتبها لـ Claude، ليقوم بقراءتها في بداية كل جلسة، ويحفظها في ذاكرته كخلفية للمشروع.
为什么需要它？因为每个 Claude Code 会话都从一张白纸开始——上次你苦口婆心交代的「用 pnpm、别碰 legacy 目录、测试这么跑」，这次它一概不记得。没有 CLAUDE.md，你就得每次重新解释一遍，烦不烦？
تشبيه: دليل انضمام الموظف الجديد للعمل. عند انضمام موظف جديد، لن تقف بجانبه طوال اليوم لتلقينه القواعد شفهيًا. بل ستعطيه دليلاً يوضح: وظيفة المشروع، كيفية رفع الكود، والتحذيرات التي يجب تجنبها. ليقرأها ويبدأ العمل بمفرده. ملف CLAUDE.md هو دليل انضمام Claude — مع ميزة أنه يعيد قراءته بالكامل في بداية كل يوم عمل.
ولكن هناك مفهوم أساسي يجب توضيحه، وتذكره الوثائق الرسمية بوضوح:
CLAUDE.md 内容作为用户消息在系统提示之后传递，而不是系统提示本身的一部分。Claude 读取它并尝试遵循它，但没有严格遵守的保证。
وبعبارة أبسط: يعد CLAUDE.md بمثابة "توصيات قوية" وليس "قوانين صارمة". فهو يوجه سلوك Claude ولكنه ليس نظام حظر إجباري. لذلك، كلما كانت كتابتك محددة ومختصرة، زاد التزامه بها. هل تتوقع منه منع عملية خطيرة بنسبة 100% استنادًا إليه؟ هذا هو دور الخطافات (Hooks) وليس ملف CLAUDE.md — وسنشرح تقسيم المهام بينهما في مقالات لاحقة.
متى يجب إضافة بيانات جديدة للملف؟ تقدم الوثائق الرسمية مؤشرات عملية واضحة:
- عند تكرار خطأ معين من Claude للمرة الثانية — هذا يعني ضرورة تسجيل القاعدة وتثبيتها
- عندما تضطر لتكرار التوجيه التصحيحي الذي ذكرته في الجلسة السابقة مجددًا
- عند مراجعة الكود واكتشاف أنه كان ينبغي عليه معرفة اصطلاح أو قاعدة معينة للمشروع مسبقًا
- عندما يحتاج الزملاء الجدد لنفس الخلفية للبدء بالعمل سريعًا
💡 خلاصة في جملة واحدة: ملف CLAUDE.md هو دليل انضمام يعيد Claude قراءته في بداية كل جلسة عمل، وهو يمثل "توصيات قوية" وليس "قوانين صارمة"، وكلما كان محددًا زاد تأثيره.
02 المستويات الثلاثة: ما يطبق عالميًا وما يطبق على مشروع واحد
لا يقتصر ملف CLAUDE.md على نسخة واحدة، بل يمكن وضعه في عدة أماكن، بمستويات تأثير تتراوح من العام إلى الخاص. يسهل الخلط بينها على المبتدئين، وسنوضحها هنا دفعة واحدة.
وفقًا للوثائق الرسمية، تتوفر ثلاثة مستويات أساسية (بالإضافة لنسخة محلية متغيرة):
| المستوى | أين يوضع | نطاق التأثير | هل يدخل في git؟ |
|---|---|---|---|
| على مستوى المستخدم | ~/.claude/CLAUDE.md | جميع المشاريع على جهازك الحالي | لا، يمثل التفضيلات الشخصية فقط |
| على مستوى المشروع | ./CLAUDE.md أو ./.claude/CLAUDE.md | المشروع الحالي فقط | ✅ نعم، يُشارك مع الفريق |
| على مستوى الدليل الفرعي | أي دليل فرعي/CLAUDE.md | يتم تحميله فقط عندما يقرأ Claude ملفات من ذلك الدليل | ✅ نعم، مناسب للمستودعات متعددة الوحدات |
| على المستوى المحلي (متغير) | ./CLAUDE.local.md | المشروع الحالي，لك أنت فقط | ❌ لا، ويُضاف إلى .gitignore |
تتوفر أيضًا طبقة تسمى "مستوى السياسات المدارة (Managed Policy)"，يقوم مسؤولو تقنية المعلومات بنشرها في دليل النظام (على نظام macOS يكون المسار
/Library/Application Support/ClaudeCode/CLAUDE.md)，ويتم تحميلها قبل مستوى المستخدم ولا يمكن للمستخدم إلغاؤها. لا يحتاجها المستخدم الفردي عادة لذا سنتجاوزها في هذا المقال، ويمكن للمؤسسات الرجوع للوثائق الرسمية.
كيف نقسم المهام بينها؟ تذكر هذه القاعدة: العادات الشخصية توضع على مستوى المستخدم، وقواعد الفريق توضع على مستوى المشروع.
- على مستوى المستخدم (
~/.claude/CLAUDE.md): يضم التفضيلات الشخصية العامة عبر المشاريع المختلفة. مثل "الرد باللغة العربية"، "توضيح الأفكار قبل تعديل الكود وعدم البدء مباشرة"، "كتابة رسائل commit باللغة الإنجليزية". هذه الأمور لا ترتبط بمشروع محدد بل تمثل عاداتك "أنت شخصيًا"، لذا تطبق على جميع المشاريع ولا تدخل مستودعات git. - على مستوى المشروع (
./CLAUDE.md): يضم قواعد المشروع المحددة والتي يجب على الفريق بأكمله الالتزام بها. التقنيات المستخدمة، وأوامر البناء، والاتفاقيات الخاصة بالأدلة، وقائمة الملفات المحظور تعديلها. وهو يدخل نظام التحكم بالإصدارات مرافقة للكود، ويحصل عليها الزملاء الجدد مباشرة بمجرد سحب المشروع. - على مستوى الدليل الفرعي: يُستخدم في المستودعات الكبيرة فقط. على سبيل المثال، وضع نسخة مخصصة للواجهات الأمامية في دليل الواجهة الأمامية، ونسخة مخصصة للخلفية البرمجية في دليل الخلفية. ولا يتم تحميله في الأحوال العادية، بل يُحمل فقط عندما يقرأ Claude ملفًا من هذا الدليل — مما يوفر مساحة السياق.
العودة إلى تشبيه دليل الموظف: مستوى المستخدم = دفتر ملاحظات عاداتك الشخصية (تحتفظ به حتى لو غيرت الشركة)؛ مستوى المشروع = دليل الموظف الذي تصدره الشركة (تعيده عند المغادرة)؛ مستوى الدليل الفرعي = اللائحة الداخلية للقسم (تحصل عليها فقط عند الانتقال للعمل في هذا القسم).
على سبيل المثال، من التهيئات الشائعة على مستوى المستخدم: إضافة عبارة "عند توفر حلول متعددة، اعرض الخيارات لأختار منها وتجنب اتخاذ القرار بالنيابة عني تلقائيًا" في ملف ~/.claude/CLAUDE.md. هذه القاعدة تنطبق على جميع مشاريعك، لذا فإن وضعها على مستوى المستخدم هو الخيار الأسهل — وبمجرد إعدادها لمرة واحدة، لن تحتاج لتكرارها في أي مشروع جديد.
💡 خلاصة في جملة واحدة: اكتب العادات الشخصية على مستوى المستخدم (
~/.claude/CLAUDE.md)، وقواعد الفريق على مستوى المشروع (./CLAUDE.mdليدخل في git)، واستخدم مستوى الدليل الفرعي للتقسيم حسب الوحدات في المشاريع الكبيرة.
03 ترتيب التحميل: لماذا تكون لقواعد المشروع الكلمة الأخيرة
بعد أن استعرضنا المستويات الثلاثة، من تكون له الأولوية عند وجودها معًا؟ هذا فخ آخر نوضحه بدقة.
قاعدة التحميل الرسمية: يتم التحميل بالتدرج من النطاق الأعم إلى النطاق الأكثر تحديدًا، وكلما كان الملف أقرب للدليل الذي بدأت منه، تأخرت قراءته.
كيف يتم الترتيب بالتفصيل؟ يبدأ Claude Code من دليلك الحالي ويتجه للأعلى، ويقوم بجمع أي ملف CLAUDE.md يجده في الطريق، ليدمجها كلها في السياق. ويكون الترتيب كالتالي:
على مستوى المستخدم ~/.claude/CLAUDE.md
↓（先读）
ملف CLAUDE.md في الدليل الأب
↓
ملف ./CLAUDE.md في جذر المشروع
↓（后读，离你最近）
ملف CLAUDE.md في الدليل الفرعي（只有 Claude 读那个目录的文件时才加进来）انتبه لنقطتين هامتين مأخوذتين من الوثائق الرسمية:
أولاً، يتم "دمج وتوصيل" الملفات التي يتم العثور عليها وليست عملية "تجاوز وإلغاء". تدخل جميعها في السياق، ولا يقوم الملف اللاحق بإلغاء السابق. لذلك، يعمل مستوى المستخدم ومستوى المشروع معًا في نفس الوقت، ولا يؤدي تعيين مستوى المشروع إلى تعطيل مستوى المستخدم.
ثانياً، تتم قراءة التوجيهات الأقرب لدليل العمل "في النهاية". وعند حدوث تعارض بين قاعدتين — مثلاً يطلب مستوى المستخدم "استخدام علامات الاقتباس المفردة للنصوص"، بينما يطلب مستوى المشروع "استخدام علامات الاقتباس المزدوجة" — فإن مستوى المشروع الأقرب للدليل تكون له الكلمة الأخيرة لأنه قُرئ لاحقًا. وبعبارة أخرى، تتجاوز قواعد المشروع عاداتك الشخصية، وهو السلوك المطلوب للعمل الجماعي.
يعرض هذا الرسم التوضيحي المستويات الثلاثة متراكبة من الأعلى للأسفل: مستوى المستخدم (يتحكم بجميع المشاريع، ويُقرأ أولاً)، ومستوى المشروع (المشروع الحالي، يدخل في git)، ومستوى الدليل الفرعي (الأقرب للكود، وله الكلمة الأخيرة عند التعارض)؛ ويوضح السهم على اليمين اتجاه التحميل "من الأعلى للأسفل"، بينما تشير القاعدة في الأسفل إلى أن المستويات تدمج ولا تُلغي بعضها، وكلما كان الملف أقرب للكود تأخرت قراءته وأصبحت له الأولوية.
تجب الإشارة هنا لتصحيح مفهوم خاطئ شائع. تشير بعض الشروحات على الإنترنت إلى أن الأولويات تترتب كالتالي "المحلي للمشروع ← جذر المشروع ← الدليل الفرعي ← العالمي"، وهذا ترتيب معاكس لاتجاه التحميل الذي تصفه الوثائق الرسمية. من السهل الانجراف خلف هذا المفهوم الخاطئ، ولكن بمراجعة الوثائق الرسمية يتضح الأمر: تنص الوثائق صراحة على أن التحميل يتم "من النطاق الأعم إلى النطاق الأكثر تحديدًا"، وتظهر توجيهات المشروع بعد توجيهات المستخدم في الترتيب. اعتمد دائمًا على التوثيق الرسمي وتجنب الحفظ المعكوس.
تفصيل عملي مفيد: يتم تلقائيًا إعادة قراءة ملف CLAUDE.md الموجود في جذر المشروع من القرص بعد تشغيل الأمر /compact (لضغط المحادثة)، وبذلك لا يُفقد. بينما لا يتم إعادة قراءة ملفات CLAUDE.md الموجودة في الأدلة الفرعية تلقائيًا، بل يضطر للانتظار حتى يقرأ Claude ملفًا من ذلك الدليل مجددًا ليحملها. لذلك، ضع القواعد الهامة دائمًا في جذر المشروع وتجنب وضعها في أدلة عميقة.
💡 خلاصة في جملة واحدة: تدمج ملفات CLAUDE.md المتعددة ولا تُلغي بعضها، وكلما كان الملف أقرب لدليل العمل تأخرت قراءته وصارت له الأولوية عند التعارض، وبذلك تتجاوز قواعد المشروع التفضيلات الشخصية — وتجنب حفظ اتجاه التحميل بشكل معكوس.
04 ما يجب كتابته مقابل ما يجب تجنبه
هذا القسم هو الأهم في المقال. ففشل إعداد ملف CLAUDE.md يرجع في 90% من الحالات إلى التقصير في كتابة ما يجب وتكديس ما لا داعي له.
نبدأ بما يجب كتابته — تلخصه الوثائق الرسمية في جملة واحدة: اكتب "الحقائق والثوابت التي يجب على Claude تذكرها في كل جلسة عمل". وتتمثل في هذه الفئات الخمس:
| الفئة | تفاصيل الكتابة | مثال |
|---|---|---|
| ملخص المشروع | جملة واحدة توضح طبيعة المشروع | "خلفية برمجية لإدارة الطلبات معتمدة على FastAPI" |
| التقنيات المستخدمة | اللغات، وأطر العمل، وقواعد البيانات، والأدوات الأساسية | "Python 3.11 / PostgreSQL / pytest" |
| الأوامر الشائعة | كيفية تشغيل الفحص، والبناء، والاختبارات | uv run pytest、uv run ruff check . |
| اتفاقيات الكود | نمط كتابة الكود، التسميات، والقواعد الواجب الالتزام بها | "يجب كتابة تعليقات الأنواع (types) للدوال"، "استخدام علامات الاقتباس المزدوجة للنصوص" |
| قواعد "المنع" الصريحة | التحذيرات، الملفات المحظور تعديلها، والعمليات التي تتطلب استئذانًا | "يُمنع تعديل الملفات الحالية في دليل migrations/" |
وتعد الأوامر الشائعة هي الأكثر استخدامًا والرجوع إليها — حيث يفحص Claude هذا القسم قبل تشغيل الاختبارات أو البناء ليتجنب التخمين والخطأ. بينما تمثل قائمة المحظورات حواجز حماية تمنعه من التسبب في مشاكل؛ مثل تحديد الأدلة الموروثة (Legacy) كأدلة للقراءة فقط، أو الملفات التي تتطلب استئذانك قبل تعديلها، أو ملفات المفاتيح السرية التي يُحظر عرض محتوياتها.
أما ما يجب تجنبه، فهو المكان الأكثر إيقاعًا للمبتدئين في الأخطاء:
- ❌ الشروح الطويلة وغير المفيدة: مثل تاريخ الشركة، ورؤية المنتج، ومقدمة الفريق، وأسباب اختيار التقنيات سابقًا — لن يستفيد منها Claude عند كتابة الكود، وهي مجرد حشو يستهلك السياق.
- ❌ البيانات القديمة وغير المحدثة: مثل تغيير مدير الحزم دون تحديث ملف CLAUDE.md، وتركه يشير لـ npm، مما يؤدي لتضليله.
- ❌ الأشياء التي يمكن معرفتها بمجرد فحص الكود: تجنب شرح وظيفة كل ملف في هيكل المجلدات، أو نسخ قواعد التنسيق المحددة بالفعل في ملف تهيئة ESLint. يستطيع Claude قراءة وفهم الكود بمفرده، وتكرار هذه البيانات يستهلك المساحة بلا طائل.
توضح الوثائق الرسمية هذا الأمر بصرامة من خلال تحديد سقف واضح لعدد الأسطر:
每个 CLAUDE.md 文件目标在 200 行以下。较长的文件消耗更多上下文并降低遵守度。
لماذا يعد سقف 200 سطر بالغ الأهمية؟ لأن ملف CLAUDE.md يتشارك مع محادثتك في نفس مساحة نافذة السياق. فإذا حشوته بـ 300 سطر من الكلام غير المفيد، فإنك تبدأ الجلسة بإشغال مساحة كبيرة من طاولة العمل، وتقل المساحة المتاحة للمهمة الفعلية — بالإضافة إلى أن القواعد الهامة ستضيع وسط الحشو، مما يشتت انتباهه ويقلل من التزامه بالقواعد. هذا هو السبب الأساسي لمشكلة "كتابة 300 سطر دون التزام".
إليك نصيحة عملية ممتازة: قبل كتابة أي بند، اسأل نفسك "هل يستطيع Claude استنتاج هذه القاعدة بمفرده من خلال قراءة الكود؟ إذا كانت الإجابة بنعم، فاحذفها مباشرة". وباتباع هذا المبدأ، يمكنك تقليص ملف CLAUDE.md لمشروع استلمته من 300 سطر إلى 80 سطرًا فقط، لتقتصر محتوياته على القيود القوية التي يصعب عليه استنتاجها بمفرده — وستلاحظ بعد هذا التقليص انخفاض أخطائه في استخدام مدير الحزم بشكل كبير.
💡 一句话总结：写「每个会话都该记住的事实」（概述 / 技术栈 / 命令 / 约定 / 禁区），删一切 Claude 看代码能自己推出来的东西，全文压在 200 行以内。
05 الإشارة لملفات أخرى: استخدام الرمز @ والتكلفة الحقيقية له
في بعض الأحيان، تتوفر لديك وثائق معايير جاهزة في المشروع بالفعل — مثل دليل تصميم الـ API، أو اتفاقية قاعدة البيانات. لا توجد حاجة لنسخ محتواها داخل ملف CLAUDE.md، ويكفي الإشارة إليها باستخدام الرمز @.
طريقة الكتابة بسيطة للغاية، اكتب الرمز @ متبوعًا بالمسار في أي موضع داخل ملف CLAUDE.md:
有关项目概述，请参阅 @README，可用命令见 @package.json。
# 其他指令
- git 工作流 @docs/git-instructions.mdعندما يقرأ Claude ملف CLAUDE.md، سيقوم بـ توسيع محتوى الملفات المشار إليها وتحميلها معًا في السياق. إليك بعض التفاصيل الهامة المذكورة في الوثائق الرسمية لتجنب المشاكل:
- يتم تحليل المسار النسبي استنادًا للملف الذي يضم الإشارة نفسه، وليس استنادًا لدليل عملك الحالي. يسهل الخطأ في هذا البند.
- يتم قبول المسارات المطلقة أيضًا؛ ويمكن للملف المشار إليه الإشارة لملفات أخرى بدورها، بحد أقصى 4 مستويات متتالية (Recursion).
- عند مواجهة إشارة لملف خارج المشروع لأول مرة، سيظهر Claude Code صندوق استئذان يعرض قائمة بهذه الملفات لتأكيد موافقتك؛ وإذا رفضت، فسيتم تعطيل الإشارة ولن يظهر الصندوق مجددًا.
ولكن هناك مفهوم بالغ الأهمية تؤكد عليه الوثائق الرسمية مرارًا، وهو فخ يسهل الوقوع فيه:
导入的文件在启动时展开并加载到上下文中。分割到
@path导入有助于组织，但不会减少上下文，因为导入的文件在启动时加载。
وبعبارة أخرى: الإشارة بـ @ هي "تنظيم وترتيب" وليست "توفيرًا في التكلفة". يظن الكثيرون أن تقسيم المحتوى لملفات خارجية لتقليل طول ملف CLAUDE.md يوفر مساحة السياق — وهذا خطأ تمامًا. فالملفات المشار إليها تُحمل بالكامل في البداية وتستهلك نفس مساحة السياق دون أي توفير. تخيل تقسيم معيار يتكون من 500 سطر لملفات خارجية والإشارة إليها بـ @ لتظن أنك قمت بتقليصه، ولكن عند تشغيل الأمر /context لفحص السياق، ستجد أن الـ tokens المستهلكة هي نفسها دون تغيير.
لذلك، القاعدة هي: نستخدم الإشارة بـ @ لجعل الهيكل أكثر ترتيبًا وتسهيل صيانته على البشر، ولكن للتوفير في مساحة السياق، يجب الاعتماد على "تقليص واختصار المحتوى نفسه" أو "قواعد تحديد مسار النطاق"، وليس تقسيم الملفات. وتجنب الإشارة لملفات كبيرة جدًا لأنها تسبب بطء العمل أيضًا.
ملاحظة إضافية: إذا كان لديك تفضيلات شخصية بحتة لا تريد رفعها لـ git (مثل رابط البيئة التجريبية المحلية الخاصة بك، أو بيانات الاختبار التي تفضلها)، فلا تكتبها في ./CLAUDE.md بل اكتبها في ./CLAUDE.local.md وأضفه إلى .gitignore. ويتم تحميله ومعاملته تمامًا مثل ملف CLAUDE.md الأساسي، ولكنه لا يُرفع للمستودع ولا يؤثر على زملائك.
💡 خلاصة في جملة واحدة: استخدم
@pathللإشارة للوثائق الخارجية بهدف "ترتيب وتجميل الهيكل"، ولكن يتم تحميل محتوياتها بالكامل في السياق وتستهلك الـ tokens دون توفير؛ والتوفير الحقيقي يتطلب اختصار المحتوى نفسه؛ وأضف تفضيلاتك الشخصية فيCLAUDE.local.mdمع إضافته لـ gitignore.
06 الصيانات: الإضافة السريعة أثناء الجلسة والتقليص الدوري
لا يعد ملف CLAUDE.md وثيقة ثابتة تكتب لمرة واحدة وتترك، بل يجب أن ينمو مع نمو المشروع. نستعرض في هذا القسم عمليتين للصيانة: كيفية إضافة بند سريع، وكيفية تقليص حجم الملف دوريًا.
كيفية إضافة بند للذاكرة بشكل سريع أثناء الجلسة
يحدث هذا كثيرًا: أثناء المحادثة تقوم بتصحيح خطأ لـ Claude، وتفكر "يجب الالتزام بهذه القاعدة مستقبلاً، لذا يجب حفظها". الطريقة الرسمية الأسهل هي — إخباره بذلك مباشرة في المحادثة:
把「数据库操作必须走 Service 层，别在路由里直接写 SQL」这条加进 CLAUDE.mdسيقوم Claude بكتابة البند في ملف CLAUDE.md بالنيابة عنك. كما يمكنك تشغيل الأمر /memory في أي وقت لعرض جميع ملفات CLAUDE.md و CLAUDE.local.md وملفات القواعد المحملة للجلسة الحالية، والنقر فوقها لفتحها في المحرر والتعديل عليها يدويًا. استخدم الطريقة الأولى لتدع Claude يصيغ العبارة بنفسه، أو استخدم الأمر /memory وتعديل الملف بنفسك للتحكم الدقيق في الصياغة.
ℹ️ تنبيه بخصوص اختلاف الإصدارات: في الإصدارات الأولى من Claude Code، كان يمكن استخدام علامة المربع
#في بداية سطر الإدخال لإضافة ملاحظة سريعة للذاكرة. وقد تغيرت هذه الآلية في الإصدارات الأحدث — واعتمد دائمًا السلوك الرسمي الحالي: إما الطلب من Claude مباشرة "إضافة هذا لـ CLAUDE.md"، أو استخدام الأمر/memoryوتعديل الملف بنفسك. وإذا كتبت له "تذكر كذا"، فسيقوم Claude بحفظها افتراضيًا في نظام ذاكرته التلقائية (auto-memory، وهو موضوع سنفصله في المقال 25 "نظام الذاكرة")؛ ولضمان إضافتها لملف CLAUDE.md صراحة، اذكر العبارة "أضف هذا لـ CLAUDE.md" كاملة.
التقليص الدوري وحذف القواعد القديمة والمتعارضة
توضح الوثائق الرسمية خطرًا محتملاً: عند تعارض قاعدتين، قد يختار Claude الالتزام بأي منهما عشوائيًا. لذا يجب مراجعة الملف دوريًا لحذف القواعد القديمة أو المتعارضة. ويُنصح بالمراجعة في الأوقات التالية:
- عند تغيير مدير الحزم أو أدوات البناء (يجب حذف الأوامر القديمة لتجنب تضليله)
- عند إضافة أو حذف مكتبات برمجية أساسية وهامة
- عند اعتماد اتفاقيات برمجية جديدة (والتحقق من عدم تعارضها مع القواعد السابقة)
- عند ملاحظة زيادة طول ملف CLAUDE.md وتجاوزه سقف 200 سطر مجددًا
ولتقييم جودة البنود، تحقق من كونها تشبه "قوانين محددة وصارمة" وليست "نصوصًا إنشائية مبهمة". ويعرض الدليل الرسمي مقارنة عملية نوضحها في الجدول التالي:
| ❌ نص إنشائي مبهم (غير مفيد) | ✅ قاعدة محددة (فعالة) |
|---|---|
| 代码应该比较整洁 | 函数不超过 50 行，超了必须拆 |
| 尽量写测试 | 每个新增函数都必须有对应单元测试 |
| 注意安全 | 用户输入必须先过 sanitize() 再进数据库查询 |
| legacy 目录不太重要 | 禁止修改 legacy/ 目录下任何文件 |
| 用 pnpm 比较好 | 依赖管理只用 pnpm，禁用 npm 和 yarn |
وبعد كتابة كل بند، تحقق بنفسك "هل يمكن التحقق من مخالفتها بنظرة واحدة وبشكل قاطع؟". وإذا صعب ذلك، فهذا يعني أن القاعدة عامة ومبهمة، ويجب إعادة صياغتها لتصبح محددة.
💡 خلاصة في جملة واحدة: أضف بندًا سريعًا عبر الطلب من Claude "كتابة البند في CLAUDE.md" أو تشغيل الأمر
/memoryلتعديله يدويًا؛ واحذف القواعد القديمة والمتعارضة دوريًا؛ فالقواعد الفعالة تكون محددة وقابلة للتحقق القاطع، وليست نصوصًا إنشائية مبهمة مثل "مرتب، حاول قدر الإمكان".
07 عملي: إعداد ملف CLAUDE.md مناسب لمشروع تجريبي
التطبيق العملي يثبت المعلومات. سنستخدم مشروعًا بسيطًا لتجربة دورة العمل الكاملة "إنشاء الملف ← كتابة القواعد ← تأكيد نجاح التحميل". اتبع الخطوات التالية ولن يستغرق الأمر سوى خمس دقائق.
الخطوة الأولى: إنشاء مشروع تجريبي وتهيئته كمستودع git (Mac / Linux)
mkdir claude-md-demo
cd claude-md-demo
git init
echo 'def add(a, b):
return a + b' > main.pyالنتيجة المتوقعة: يحتوي مجلد claude-md-demo على ملف main.py ومجلد .git. وتهيئة git أساسية لضمان إدخال ملف CLAUDE.md في نظام التحكم بالإصدارات ومشاركته مع الفريق.
الخطوة الثانية: كتابة ملف CLAUDE.md مبسط ومحدد للمشروع
باستخدام محرر النصوص المفضل لديك، أنشئ ملفًا جديدًا باسم CLAUDE.md في جذر المشروع، والصق المحتوى التالي (انتبه لطول الملف المكون من بضعة أسطر فقط — هذا هو النمط المثالي لملف CLAUDE.md الفعال):
# add-demo — 一个演示用的最小 Python 项目
只有一个 `add` 函数，用来演示 CLAUDE.md 怎么写。
## 常用命令
- `python -m pytest` —— 运行测试
## 编程约定
- 所有函数必须有类型注解
- 字符串一律用双引号
## 注意事项
- 不要修改 `main.py` 里 `add` 的函数签名，只能在内部加逻辑النتيجة المتوقعة: يظهر ملف CLAUDE.md في جذر المشروع بمحتويات مشابهة للمثال المذكور. طول الملف أقل من 15 سطرًا — تذكر دائمًا هذا الحجم التقريبي، وتجنب تضخيم الملف في مشاريعك الحقيقية.
الخطوة الثالثة: تشغيل Claude وتأكيد نجاح القراءة
شغل الأداة في دليل المشروع:
claudeبعد التشغيل، اكتب هذا الأمر لتأكيد حالة التحميل:
/memoryالنتيجة المتوقعة: ستظهر لك مسار الملف ./CLAUDE.md في القائمة. وجود الملف في القائمة يؤكد قيام Claude بتحميله ليكون جزءًا من سياق الجلسة الحالية. هذه هي الخطوة الموصى بها رسميًا لفحص المشاكل — فإذا لاحظت عدم التزامه بقاعدة معينة، استخدم أولاً الأمر /memory للتحقق من تحميل الملف بنجاح.
الخطوة الرابعة: اطلب منه تنفيذ عمل يتعارض مع القواعد واختبر التزامه
اخرج من واجهة /memory وعد إلى سطر الإدخال واكتب:
给 add 函数加上类型注解النتيجة المتوقعة: في الـ diff الذي سيعرضه Claude، ستجده استخدم نمط كتابة تعليقات الأنواع المعتمد في قواعد المشروع، ولم يقم بتعديل توقيع الدالة الذي تم حظر تعديله. والتزامه الكامل بقاعدة "يجب كتابة تعليقات الأنواع لجميع الدوال" المحددة في ملف CLAUDE.md يعني نجاح إعداد واستخدام دليل الموظف، تهانينا!
⚠️ إذا لاحظت عدم التزامه بالملف: استخدم أولاً الأمر
/memoryلتأكيد تحميل الملف؛ ثم فحص ما إذا كانت القاعدة مبهمة (مثل عبارة "مرتب")؛ وأخيرًا فحص ما إذا كان هناك تعارض بين قاعدتين. هذه هي الخطوات الثلاث القياسية الموصى بها رسميًا لتحديد وحل المشكلة.
💡 خلاصة في جملة واحدة: اتبع خطوات العمل: إنشاء الملف ← كتابة قواعد مبسطة وقصيرة ← فحص نجاح التحميل عبر
/memory← وتكليفه بعمل لاختبار مدى التزامه، وفي حال عدم عمله اتبع ترتيب الفحص الرسمي: تحقق من التحميل ← فحص الإبهام ← فحص التعارض.
08 ملخص
استعرضنا في هذا المقال ملف CLAUDE.md الذي يمثل "ذاكرة المشروع لـ Claude" بالتفصيل:
| البعد الجوهري | النقاط الأساسية |
|---|---|
| تعريفه | دليل انضمام يعيد قراءته في بداية كل جلسة، ويمثل "توصيات قوية" وليس قوانين صارمة |
| مستوياته | مستوى المستخدم (شخصي) / مستوى المشروع (للفريق في git) / مستوى الدليل الفرعي (عند الحاجة) |
| ترتيب التحميل | تُدمج الملفات ولا تُلغي بعضها، وكلما كان الملف أقرب للدليل تأخرت قراءته وصارت له الأولوية عند التعارض |
| ماذا تكتب | الملخص، التقنيات، الأوامر، الاتفاقيات، والمحظورات؛ واحذف أي شيء يمكن استنتاجه بمجرد فحص الكود |
الإشارة بـ @ | تستخدم لترتيب وتنسيق الهيكل، ولا توفر في مساحة السياق (حيث يتم تحميل محتوياتها بالكامل) |
| صيانته | اطلب من Claude "كتابة البند في CLAUDE.md" أو استخدم /memory للتعديل يدويًا؛ واحذف القواعد القديمة؛ واجعل البنود قواعد محددة وليست نصوصًا إنشائية |
من المفترض الآن أن تكون قادرًا على: تقييم مدى ملاءمة إدخال قاعدة معينة لملف CLAUDE.md واختيار المستوى المناسب لها؛ وصياغة قواعد محددة وقابلة للتحقق وتجنب الكلمات العامة؛ واستخدام الإشارة بـ @ للوثائق الخارجية مع فهم تكلفتها على السياق؛ ومعرفة كيفية صيانة وتقليص الملف دوريًا مع تطور المشروع. باختصار — يمكنك الآن كتابة ملف CLAUDE.md يلتزم به Claude بدقة، بدلاً من تكديس 300 سطر دون أي التزام.
المقال التالي 19 "إدارة السياق" — أشرنا في هذا المقال مرارًا إلى أن "ملف CLAUDE.md يستهلك مساحة نافذة السياق" وأن "الملفات المشار إليها بـ @ تُحمل بالكامل في السياق"، فما هي نافذة السياق بالتفصيل، وماذا يحدث عند امتلائها، وكيف نستخدم الأمرين /context و /compact؟ سنفصل الحديث عن طاولة العمل هذه في المقال القادم. فكر في هذا السؤال البسيط: أيهما يستهلك tokens أكثر، ملف CLAUDE.md أم المحادثة بأكملها؟