كيفية إعداد CLAUDE.md في 2026: قالب و6 قواعد

مواد عن البرمجة بأسلوب vibe coding: أدوات، ودراسات حالة، وأخطاء. أدلة Ailoot.

لماذا تحتاج إلى CLAUDE.md، ولماذا ينسى Claude المشروع من دونه؟#

تفتح Claude Code يوم الثلاثاء وتشرح: «أعمل على هذا المشروع، وهذه هي الأدوات، ولا تفعل هذا». فينجح الأمر.

يوم الخميس، تكون المحادثة نفسها قد انتهت، فتكرر كل شيء. ويوم السبت، مرة أخرى؛ ويوم الاثنين، مرة إضافية.

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

مع ملف CLAUDE.md متجدد، تختفي التهيئة. كل القواعد التي كنت تكررها في كل محادثة موجودة في ملف واحد وتظهر تلقائيًا في بداية كل جلسة. يصبح الطلب قصيرًا: «نفّذ X»، بدلًا من «أعمل على المشروع Y، والأدوات هي Z، لا تفعل A أو B، وبالمناسبة، تذكر C أيضًا».

ثم تختفي الأخطاء المتكررة.

كل خطأ يرتكبه الوكيل سبب لإضافة سطر إلى CLAUDE.md. وبعد شهر، يصبح لديك «دستور مشروع» حي، ويتوقف Claude عن الوقوع في الفخاخ المألوفة نفسها.

وهناك طبقة ثالثة: يتوقف الوكيل عن الكتابة في فراغ. فمن خلال CLAUDE.md، أوجّه Claude إلى مجلدات تحتوي على سياق: أين يبحث عن معلومات الجمهور والأسعار والعلامة التجارية. ومن دون هذا التوجيه، يكتب الوكيل «حلولًا عالية الجودة» من دون معرفة اقتصادياتي، فتكون النتيجة مجردة ونمطية و«مثلما يكتب الجميع».

ما هو CLAUDE.md، وبأي ترتيب يقرأه Claude؟#

تصف Anthropic ملف CLAUDE.md بهذه الطريقة في توثيقها الرسمي:

المواضع الأربعة التي يبحث فيها Claude Code عن CLAUDE.md، مرتبة تصاعديًا حسب الأولوية:

تُحمَّل الملفات الأربعة كلها إلى السياق في الوقت نفسه. وإذا تعارضت القواعد، تقول Anthropic مباشرةً في توثيقها إنه من غير المعروف أيها ستكون له الأولوية؛ وقد يختار Claude أحدها عشوائيًا. لذلك، من الأسهل إبقاء كل ما هو مهم في ملف CLAUDE.md الخاص بالمشروع وتجنب إنشاء نسخ مكررة.

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

بعبارة أخرى، لا يُعدّ CLAUDE.md «موجه نظام» بالمعنى الدقيق. إنه أول رسالة مستخدم يراها Claude. لذا فإن قواعده اقتراحات قوية، وليست قوانين. إذا احتاجت قاعدة إلى إنفاذ، فاستخدم hook مختبرًا للحدث الذي يغطيه، وأذونات أو عزل بيئة لحدود الوصول الأوسع. تشغيل hook تلقائيًا لا يجعل فحوصه شاملة. سأشرح أدناه الحد الفاصل بين hooks وCLAUDE.md.

كيف تكتب CLAUDE.md بالحد الأدنى في 5 دقائق (قالب جاهز للاستخدام)؟#

فيما يلي قالب اختبرته عبر عشرات مشاريعي. يبقي الملف في حدود 80-120 سطرًا، أي ضمن توصية Anthropic باستهداف أقل من 200 سطر. يقدّم الوكيل مع هذا القالب أكثر النتائج منطقية.

# [PROJECT NAME] - project navigation

This document is the project map. Read it at the start of every session
to understand where things are and how to work with them.

## What this project is

**[NAME]** - [one sentence: what it is and who it’s for].
[1-2 sentences: what problem it solves and how].

Details are in `business/INDEX.md`.

## Reading order at the start of every session

1. `about-me/INDEX.md` - who I am and how I think
2. `business/INDEX.md` - what we do (product, audience, economics)
3. `CLAUDE.md` (this file) - repo rules, tools, navigation
4. Task area: the relevant file from `business/`, `plans/<current plan>`,
   `mastery/<area>` or the feature folder in the code

Principle: layer 1 (about me) comes before layer 2 (business) for a reason.
First, **who** is thinking, then **about what**.

## Repository structure

[NAME]/
├── CLAUDE.md            ← this file, navigation
├── about-me/            ← digital projection of you (how you think, what you value)
│   └── INDEX.md
├── business/            ← the business’s second brain
│   ├── INDEX.md
│   ├── audience/        ← customer profile
│   ├── products/        ← products, prices
│   ├── goals/           ← goals, metrics
│   └── economics/       ← unit economics, revenue
├── plans/               ← technical plans (one plan = one feature)
├── retrospectives/      ← reflections after each session
└── (project code)

### Where to find things

| What you need | Where to look |
|---|---|
| Why we’re building the project, and for whom | `business/INDEX.md` |
| Target customer, pains, desires | `business/audience/` |
| Product, plans, prices | `business/products/` |
| Goals and metrics | `business/goals/` |
| Economics | `business/economics/` |
| Technical plans | `plans/` |

## Tools

[INSERT TOOLS - for example: Next.js 14, TypeScript, Tailwind CSS, Prisma + PostgreSQL].

## Repo rules

1. Never hardcode dynamic data (prices, dates, figures) -
   get everything from files in `business/` and the LIVE marker.
2. Don’t publish without my explicit command.
3. Before `git push`, run `npm run build` and check that it
   builds without errors or warnings.
4. Add files by name with `git add`. Never use `git add .` or `git add -A`.
5. Don’t read `.env` in full. To check a variable, use
   `grep "^VAR=" .env`.

## Big features = a plan in `plans/`

Any task lasting more than an hour must be written up as a plan in the `plans/` folder:
1. Filename: `YYYY-MM-DD-feature-name.md`.
2. Divide the plan into phases. Mark each phase `[ ]` or `[x]`.
3. At the end of the plan, add a summary: whether it was fully implemented and what remains.

## End-of-feature cycle

After each feature is complete, go through these 5 steps:
1. Find errors → prove them with an example → fix them.
2. What was missed (edge cases, input validation, error handling).
3. Is this a real problem in our project? Check `business/` and `plans/`.
4. Take a fresh look: reread the diff as if you’re seeing it for the first time.
5. Security review. Especially: personal data and third-party materials.

## End-of-session reflection

In `retrospectives/YYYY-MM-DD_short-name.md`, record:
1. What the task was.
2. How it was solved.
3. Whether it was solved - yes / no / partially.
4. What could have been done better.
5. What was learned about the user or project.

## Language

Always respond in the user’s preferred language. Use hyphens only, not em dashes.

لكي تجعل Claude يملأ هذا القالب تلقائيًا لمشروعك، أعطه هذا الطلب. سيقرأ السياق ويملأ الحقول بين الأقواس المربعة:

Create a CLAUDE.md file at the project root using this template:

[INSERT THE ENTIRE TEMPLATE FROM ABOVE]

Proceed as follows:

Read about-me/INDEX.md and business/INDEX.md to understand the project context and me as the author.

Fill in all the square-bracketed fields in the template based on what you find in those folders.

If some information is missing, ask me clarifying questions one at a time, with 3-4 answer options.

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

Show me the final file and ask what should be revised.

Always respond in the user’s preferred language.

إذا لم يكن لديك مجلدا about-me/ وbusiness/ بعد، فلا بأس. سيطرح Claude أسئلة توضيحية ويعد CLAUDE.md بالحد الأدنى استنادًا إلى المعلومات المتاحة. ويمكنك إنشاء المجلدين لاحقًا، حين تعرف ما الذي تريد وضعه فيهما.

ما القواعد الست التي تجعل CLAUDE.md وثيقة حية؟#

القاعدة 1. أبقه دون 200 سطر

تقول Anthropic ذلك بإيجاز في توثيقها الرسمي:

يعمل ملف CLAUDE.md طويل ضد نفسه بطريقتين. أولًا، يستهلك الرموز. يُحمَّل ملف تعليمات من 800 سطر في كل نافذة، ويستهلك عدة آلاف من الرموز من ميزانيتك في كل جلسة. ومع اشتراك Pro ذي الحد اليومي، يقلل ذلك عدد الجلسات المتاحة بشكل ملحوظ. ثانيًا، يبدأ النموذج بتجاهل القواعد.

توصي الوثائق باستهداف أقل من 200 سطر لتقليل استهلاك السياق وتحسين الالتزام. ولا تثبت حد فشل حادًا عند السطر 201. راجع الصلة والتناقضات وحجم الرموز المحمل ونتائج المهام الفعلية قبل تقرير ما تنقله خارج الملف.

القاعدة 2. اختم كل جلسة بتأمل

اكتب في CLAUDE.md: «في نهاية كل جلسة، سجّل ما أنجزته وما تعلمته في retrospectives/YYYY-MM-DD_*.md». بعد إضافة هذا السطر، يبدأ Claude تلقائيًا بإنهاء كل جلسة بتأمل؛ ولن تحتاج إلى طلب ذلك.

لماذا نتأمل:

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

القاعدة 3. أنشئ commit بعد كل مهمة مكتملة

يقول ملف CLAUDE.md الخاص بي: «بعد كل مهمة مكتملة، أنشئ commit في git برسالة ذات معنى». ويبدأ Claude من تلقاء نفسه بتقسيم العمل إلى commits ذرية.

وهذا يمنحك أمرين. أولًا، إذا حدث عطل، يمكنك التراجع عن عملية واحدة، لا عن «كل ما فعلته اليوم». ثانيًا، يصبح سجل commits سجلًا للعمل يبيّن ما الذي تغير وبأي ترتيب.

القاعدة 4. راجع مجلد business/ دائمًا

في أي مهمة تتعلق بالعملاء أو المنتجات أو النصوص، ينبغي للوكيل أولًا فتح business/INDEX.md والملف المناسب المشار إليه فيه. ويقول ملف CLAUDE.md الخاص بي صراحةً: «عند العمل على واجهة المستخدم أو النصوص، راجع أولًا business/audience/avatar.md وbusiness/assets/brand-guidelines.md».

من دون هذه القاعدة، يكتب Claude نصوصًا «بالأسلوب العام لموقع إلكتروني جيد». ومعها، يكتب بأسلوبك ولعميلك، ويتجنب كلماتك الممنوعة.

القاعدة 5. أضف قاعدة بعد كل خطأ يرتكبه الوكيل

هذه هي القاعدة الأساسية التي تبقي CLAUDE.md حيًا.

أمثلة من ملف CLAUDE.md الخاص بي أُضيفت بعد أخطاء محددة:

• «لا تدرج ملفات عمل مؤقتة لشخص آخر في commit باستخدام git add .؛ أضف الملفات إلى منطقة التجهيز بالاسم».
• «قبل الدفع إلى main، افحص git log origin/main..main --oneline؛ إذا لم يكن الناتج فارغًا، فلا تدفع».
• «لا تختلق القيم؛ خذها من .env أو من الشفرة. وخصوصًا عناوين URL وأسماء المستخدمين والرموز المميزة».

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

القاعدة 6. ضع قواعد الأمان في .claude/settings.json، لا في CLAUDE.md

يمكنك أن تكتب في CLAUDE.md «لا تلمس .env»، لكن ذلك مجرد طلب؛ وقد يخالفه Claude لأن CLAUDE.md يُحمَّل كرسالة مستخدم، لا كقانون. للأمان الحرج، استخدم .claude/settings.json، حيث يمكنك حظر أوامر بعينها حظرًا صارمًا.

قائمة الحظر التي أضيفها إلى كل مشروع جديد:

• rm -rf (الحذف التكراري لأي ملفات).
• قراءة .env كاملًا (Read .env).
• export وcurl في الأمر نفسه (نمط لتسريب الأسرار خارجيًا).
• git push --force من دون موافقة صريحة.

اعثر على أدلة أخرى لدى Ailoot.

كيف تكون بنية CLAUDE.md في نشاط تجاري قائم (تشريح ملف من 280 سطرًا)؟#

معظم أمثلة CLAUDE.md المتاحة على الإنترنت قوالب تقنية للمطورين: «استخدم TypeScript»، و«لا تكتب اختبارات أطول من 50 سطرًا». هذا النوع من CLAUDE.md عديم الفائدة لرائد الأعمال، إذ لا يغطي الجانب التجاري.

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

1. وصف موجز للمشروع (15 سطرًا). ما الذي نفعله، ومن الجمهور، وما المنتجات التي نقدمها. ليس ملخصًا لموقع تسويقي، بل موجزًا للوكيل لكي يفهم «إلى أين نتجه».

2. نبذة عني (10 أسطر). إشارة إلى مجلد about-me/، وهو إسقاط رقمي لكيفية تفكيري. النبرة والقيم والمبادئ والكلمات الممنوعة. عندما يكتب Claude نصًا «بصفتي»، يقرأ هذا المجلد أولًا كي يطابق صوتي.

3. بنية المستودع (20 سطرًا). شجرة مع تعليقات: أين توجد الشفرة، وأين يوجد سياق الأعمال، وأين توجد الخطط والتأملات. من دون هذه الخريطة، يبحث Claude عن الملفات عشوائيًا في كل مرة.

4. جدول «أين تجد الأشياء» (25 سطرًا). توجيه من «السؤال ← الملف». مثلًا، قد يقول الجدول لوكالة عقارات: «تحتاج إلى شروط الرهن العقاري ← business/products/mortgage.md»، أو «تحتاج إلى نبرة المنشورات ← business/assets/voice.md». استبدل ذلك بملفاتك. هذا الجدول هو جوهر CLAUDE.md. من دونه، يخمّن الوكيل أي ملف يحتوي على الإجابة. ومعه، يصل مباشرةً إلى المصدر.

5. مبادئ المشروع الرئيسية (40 سطرًا، 10-15 بندًا). يتراكم هذا القسم ببطء ويتطلب أكبر جهد. كل بند أثر لخطأ محدد. على سبيل المثال، قد تكون قواعد متجر إلكتروني: «لا تضع الأسعار ومواعيد التسليم ضمن الشفرة أبدًا»، و«لا تنشر منتجًا من دون أمر صريح»، و«تحقق من توافق أسلوب وصف المنتج مع مسرد العلامة التجارية قبل نشره». هذا القسم هو «دستور المشروع».

6. التخطيط التشغيلي (20 سطرًا). جدول محفزات يربط «عبارة المستخدم ← الإجراء». مثلًا: «عندما أقول: خطط للأسبوع، افتح ops/monthly.md وأنشئ ملف الأسبوع». وهذا يحوّل Claude إلى مساعد عمليات يفهم سياق الأوامر.

7. الأدوات (5 أسطر). التقنيات. باختصار ومن دون حشو.

8. النشر (15 سطرًا). عملية خطوة بخطوة لنشر التغييرات في بيئة الإنتاج: الأوامر المطلوب تشغيلها، وترتيبها، وما ينبغي التحقق منه. كنت أشرح ذلك في كل مرة. أما الآن فيعرفه Claude.

9-12. الأمان (35 سطرًا). أربعة أقسام فرعية منفصلة: قواعد التعامل مع .env، والوصول إلى قاعدة بيانات الإنتاج، والأوامر الآمنة للعروض التوضيحية (تسجيلات الشاشة والبث ولقطات الشاشة، لتجنب كشف الرموز المميزة عن طريق الخطأ)، وقواعد تدوير الأسرار.

13. مجلد plans/ (10 أسطر). معيار الخطة: اسم الملف، وبنية المراحل، وما ينبغي وضعه في كتلة الملخص.

14. مجلد retrospectives/ (5 أسطر). معيار التأمل: القالب، واسم الملف، ومحتواه.

15. بيانات قاعدة البيانات الحية (15 سطرًا). قاعدة لتمييز «البيانات الحديثة»: عندما يشير ملف إلى وجوب تحديث الأرقام، يجلب الوكيل الأرقام من المصدر بدلًا من استخدام الأرقام القديمة. وهذا يزيل خطر استخدام Claude لأرقام الأمس.

16. اللغة (3 أسطر). «أجب دائمًا باللغة التي يفضلها المستخدم. استخدم الشرطات فقط، لا الشرطات الطويلة».

يبلغ المجموع نحو 280 سطرًا. يتجاوز ذلك هدف الاختصار لكنه لا يجعل الملف غير صالح. ظل مفيدًا في هذا المثال؛ وينبغي أن يعتمد إبقاؤه على استخدام السياق المقاس وفحوص مهام تمثيلية. ليست الجداول أقل تكلفة بالرموز من النثر تلقائيًا.

ماذا يفعل الأمر /init، ولماذا لا يكفي؟#

تصف Anthropic الأمر بهذه الطريقة في توثيقها:

ما الذي يفعله /init جيدًا:

• يتعرف على الأدوات من package.json وCargo.toml وpyproject.toml.
• يسرد أوامر البناء والاختبار.
• يلتقط الأعراف من الملفات الموجودة (.eslintrc و.prettierrc).
• يلاحظ قواعد Cursor الموجودة (.cursorrules و.cursor/rules/) وقواعد Copilot، ويدمج الأجزاء ذات الصلة. كما يلتقط AGENTS.md في وضع CLAUDE_CODE_NEW_INIT=1.

ما الذي لن يفعله /init:

• لن يعرف من هو عميلك.
• لن يضيف كلماتك الممنوعة للنصوص.
• لن يضيف قواعد تتعلق بأخطاء الوكيل (إذ لم تحدث أخطاء بعد).
• لن ينشئ جدول «أين تجد الأشياء» لبنية أعمالك.

إذًا، سير العمل الصحيح هو:

1. شغّل /init في Claude Code

   ستحصل على ملف CLAUDE.md أولي من 30-50 سطرًا، يتضمن الأدوات والأوامر. وهذا هو الأساس التقني.

2. أضف قالب هذه المقالة إليه

   استخدم قسم «CLAUDE.md بالحد الأدنى في 5 دقائق». أضف أقسام التنقل والتوجيه والمبادئ.

3. املأ الحقول بين الأقواس المربعة

   أعط Claude الطلب: «اقرأ مشروعي واملأ القالب». وإذا لم يكن مجلدا business/ وabout-me/ موجودين بعد، فسيطرح Claude أسئلة توضيحية.

4. أجرِ اختبار ضغط

   قل لـ Claude: «اقرأ CLAUDE.md وابحث عن 10 نقاط غامضة قد تجعلك، بصفتك وكيلًا، تسيء فهمه». ستحصل على قائمة بالإصلاحات.

5. ثم عايش الملف

   أضف سطرًا بعد كل خطأ يرتكبه الوكيل. وبعد شهر، سيكون لديك ملف CLAUDE.md حي مصمم خصيصًا لنشاطك التجاري.

نص الطلب للخطوة الرابعة:

I have a CLAUDE.md. Tomorrow I’ll be building a feature based on it.

Your task is to stress-test it. Find 10 reasons we could potentially fail:

where CLAUDE.md is ambiguous and you, as an agent, might misunderstand it

where there are gaps that would force you to make things up

where rules contradict one another

where I overestimate how much can be done in one day

where I underestimate things (this is even worse)

Don’t hold back. Criticize it harshly. I want to find these issues now, not in production.
At the end, give me a list of specific changes: what to change and how, so these problems don’t happen.

CLAUDE.md مقابل AGENTS.md مقابل MEMORY.md: من يقرأ ماذا في 2026؟#

السؤال الرئيسي الذي يربك المبتدئين هو: هل يقرأ Claude Code ملف AGENTS.md؟ قبل سبتمبر 2026، كانت الإجابة «لا»: نصح توثيق Anthropic بإنشاء CLAUDE.md يستورد AGENTS.md. ومنذ الإصدار 2.1.277 (الصادر في 18 سبتمبر 2026)، يقرأ Claude Code ملف AGENTS.md بنفسه، لكن فقط إذا لم يوجد ملف CLAUDE.md أو .claude/CLAUDE.md أو CLAUDE.local.md في مجلد العمل أو في أحد المجلدات الأعلى منه.

إذا كان للمشروع ملف CLAUDE.md، فلن يقرأ Claude Code افتراضيًا إلا ذلك الملف، ويتجاوز AGENTS.md. يمكنك تغيير هذا في /config، ضمن تعليمات المشروع: مثلًا، يجعل الإعداد claude-md-and-agents-md Claude يقرأ الملفين. وثمة طريقة أخرى تعمل في كل الإصدارات: أضف استيرادًا إلى CLAUDE.md:

@AGENTS.md

## Claude Code

Additional rules for Claude Code that other agents don’t need.

تستورد الصيغة @filename ملفًا آخر. يقرأه Claude ويحمّله إلى السياق مع CLAUDE.md. ولا يؤدي الاستيراد إلى قراءة الملف مرتين، حتى إذا كان Claude Code يستطيع قراءة AGENTS.md بمفرده.

متى تحتاج إلى AGENTS.md. إذا كنت تعمل بالتوازي باستخدام Claude Code وCodex CLI أو Cursor أو Copilot، فأنشئ AGENTS.md بوصفه المصدر الوحيد للحقيقة، وضع @AGENTS.md في CLAUDE.md، وأضف فوقه أي قواعد خاصة بـ Claude. وإذا لم توجد قواعد كهذه، فلا حاجة إلى إنشاء CLAUDE.md: فمنذ الإصدار 2.1.277، يقرأ Claude Code ملف AGENTS.md بنفسه. وإذا كنت تعمل باستخدام Claude Code وحده، فلا تحتاج إلى AGENTS.md؛ استخدم ملف CLAUDE.md واحدًا فقط. للاطلاع على الخيارات خطوة بخطوة، راجع دليل استخدام AGENTS.md وCLAUDE.md معًا في مشروع واحد.

ما هو MEMORY.md؟ منذ تحديث حديث، يحتفظ Claude Code تلقائيًا بملاحظات عنك في ~/.claude/projects/<project-name>/memory/MEMORY.md. وتتضمن هذه الملاحظات عادات المحادثة («يفضل المستخدم الإجابات القصيرة»)، والعبارات المتكررة («منع الرموز التعبيرية في الشفرة»)، والملاحظات السلوكية («يعمل على macOS ويستخدم zsh»).

هذا نظام ذاكرة منفصل، وليس CLAUDE.md. لا تكتبه يدويًا؛ بل يكتبه Claude استنادًا إلى محادثاتك. إذا احتوى MEMORY.md على معلومة ينبغي أن تصبح قاعدة، فانقلها إلى CLAUDE.md. وإذا احتوى على شيء غير ضروري أو غير صحيح، فيمكنك حذفه يدويًا؛ فهو ملف نصي.

ما حجم CLAUDE.md المفيد، وكيف تراجع ملفًا طويلًا؟#

تُحمَّل في سياق كل نافذة من Claude Code عدة طبقات: موجه النظام من Anthropic (يُقدَّر بعشرات الآلاف من الرموز)، وملف CLAUDE.md، والملفات المستوردة باستخدام @، وملف MEMORY.md، وسجل المحادثة الحالي، ومحتوى الملفات التي يفتحها Claude. ويجب أن يتسع كل ذلك في سياق النموذج (200K رمز لـ Sonnet، و1M لـ Opus).

كلما كبر ملف CLAUDE.md، قلّت المساحة المتاحة للعمل الحالي. يعادل ملف من 1,000 سطر نحو 8,000 رمز، ويتكرر في كل جلسة. وفي اشتراك Pro (بحسب تجربتي، نحو 10-12 طلبًا «ثقيلًا» يوميًا)، يخفض ذلك قدرتك بربعها.

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

إذًا، هذه قاعدة تقريبية للحجم:

• 80-120 سطرًا - بداية مناسبة لخريطة مشروع موجزة، وليست درجة التزام مضمونة.
• 150-200 سطر - تذكير مفيد بمراجعة الصلة ونقل الإجراءات التفصيلية إلى ملفات مرتبطة.
• 200-300 سطر - افحص حجم الرموز والتكرار ونتائج المهام؛ فقد يظل مثال النشاط التجاري ذي 280 سطرًا أعلاه مفيدًا.
• 400+ سطر - سبب قوي لمراجعة مركزة، وليس دليلًا على عدم صلاحية الملف. أبق القيود الأساسية وانقل التفاصيل بعد التحقق من استمرار عمل الروابط والقواعد.

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

تقدم Anthropic اختبارًا مباشرًا في توثيقها:

طبّق ذلك على كل سطر. إذا كانت الإجابة «سيظل يؤدي المهمة على نحو صحيح»، فاحذف السطر. ليس CLAUDE.md مكانًا للتوثيق أو سجل القرارات أو الفلسفة. إنه للقواعد التي يحتاج إليها الوكيل كي يتجنب الأخطاء فحسب.

ما الأخطاء السبعة التي تجعل CLAUDE.md عديم الفائدة؟#

الخطأ 1. «كن مهندسًا جيدًا»

هذا هو الخطأ الأكثر شيوعًا. يكتب الناس أمنيات عامة في CLAUDE.md: «اكتب شفرة نظيفة»، و«اتبع أفضل الممارسات»، و«فكر كمهندس خبير».

هذه الكلمات لا تعني شيئًا. يكتب Claude أصلًا «شفرة نظيفة» بالمعنى العام. تشغل هذه الأسطر مساحة من السياق من دون أن تؤثر في أي قرار.

استبدل «اكتب شفرة نظيفة» بعبارات مثل «استخدم مسافة بادئة من مسافتين»، أو «لا تستخدم any في TypeScript»، أو «يجب ألا يزيد طول الدوال على 30 سطرًا». عبارات محددة وقابلة للتحقق.

الخطأ 2. تكرار ما يعرفه Claude مسبقًا

أوصاف أعراف اللغات القياسية («في JavaScript، الدوال مواطنون من الدرجة الأولى»، و«لدى TypeScript أنواع ثابتة»). وشروحات طريقة عمل npm أو git أو docker.

تعلم Claude كل ذلك خلال التدريب. وتكراره في CLAUDE.md لا يضيف شيئًا؛ بل يستهلك جزءًا من سياقك فحسب.

الخطأ 3. تعليمات طويلة خطوة بخطوة داخل CLAUDE.md

تعليمات طويلة حول «كيفية نشر المشروع» أو «كتابة ترحيل لقاعدة البيانات» أو «إعداد مكوّن جديد». عشرات الأسطر التي تشرح الخطوات.

هذا ليس مكانًا للتعليمات الطويلة خطوة بخطوة، بل للقواعد ذات السطر الواحد. ضع التعليمات الطويلة في skills/ (آلية منفصلة في Claude Code تُحمَّل عند الحاجة) أو في docs/. واستخدم في CLAUDE.md رابطًا من سطر واحد: «عند إنشاء ترحيل جديد، افتح docs/migrations.md».

الخطأ 4. قواعد يتحقق منها محلل الشفرة تلقائيًا أصلًا

«استخدم الفواصل المنقوطة»، و«لا تترك استيرادات غير مستخدمة»، و«لا تستخدم var». تكشف ESLint وPrettier وBiome كل هذه الحالات؛ فهي أدوات lint (أدوات تلقائية للتحقق من الشفرة).

أداة lint حتمية: تعمل، وتجد الخطأ، وتصلحه. أما قاعدة CLAUDE.md فاحتمالية؛ إذ قد ينساها الوكيل. لا حاجة إلى تكرارها؛ فمن الأسهل إعداد أداة lint.

الخطأ 5. أسرار في CLAUDE.md

رأيت كلمات مرور لحسابات اختبار، ورموز API مميزة لبيئة الاختبار، وروابط إلى لوحات إدارة تتطلب تسجيل الدخول. وكان كل ذلك في ملف مودع في git ومحمّل إلى سياق نموذج Anthropic.

إياك. مكان الأسرار هو .env، الموجود في .gitignore. وفي أقصى الأحوال، ينبغي أن يقول CLAUDE.md: «لا تقرأ .env كاملًا؛ استخدم grep لمتغير محدد».

الخطأ 6. ملف تفريغ من 500+ سطر لم يُنظف منذ ستة أشهر

نما ملف CLAUDE.md، وصار يكرر نصف محتوى docs/، ويتناقض مع نفسه في مواضع متعددة، ولم يعد أحد يتذكر ما يحتويه. فيبدأ الوكيل بتجاهل معظمه. ويشتكي الفريق من أن «Claude لا يتبع التعليمات»، فيضيف مزيدًا من القواعد، فتزداد الأمور سوءًا.

من علامات إهمال CLAUDE.md: أكثر من 300 سطر، وقواعد مكررة في أقسام مختلفة، وروابط قديمة إلى ملفات لم تعد موجودة، وملاحظات «تاريخية» مثل «قررنا هذا في 2024، ثم غيرنا رأينا».

الحل: اطلب من Claude كل أسبوعين مراجعته باستخدام اختبار Anthropic: «لو حُذف هذا السطر، هل سيرتكب الوكيل خطأً؟». احذف كل ما كانت إجابته «لا».

الخطأ 7. إنشاء CLAUDE.md ونسيانه

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

علامة واضحة: تكرر التعليمات نفسها في كل جلسة. «لا تفعل X»، و«لا تلمس Y»، و«تذكر Z». إذا كررت ذلك أكثر من مرتين، فمكان القاعدة هو CLAUDE.md، لا ذاكرتك.

كيف تجعل CLAUDE.md يتعلم ذاتيًا بقاعدة «التحديث في نهاية الجلسة»؟#

يحتوي ملف CLAUDE.md الخاص بي على قسم قصير:

## Self-learning

At the end of every session, check:
- Have I learned anything new about the user or how to work with them?
- Did I break any rule that should now be recorded?

If so, create or update a file in `about-me/feedback/` in this format:
Rule (one-line rule) → Why (why it was added)
→ How to apply (when it applies).

I don’t write the rules by hand - I say, “not like that, because this is how,”
and you put it into a file.

بعد إضافة هذا القسم إلى CLAUDE.md، بدأ Claude يسأل في نهاية كل جلسة: «هل كان هناك شيء جديد يستحق التسجيل؟». وإذا وُجد، اقترح مسودة قاعدة، ووضحتها له، ثم أُنشئ ملف.

بعد شهرين من العمل بهذه الطريقة، صار لدي أكثر من اثني عشرين ملفًا في about-me/feedback/، وهي قواعد تعلمتها من أخطاء محددة. يمثل كل ملف صفحة واحدة بتنسيق القاعدة ← السبب ← كيفية التطبيق. وصار المجلد «ذاكرة ثانية» تسجل تفضيلاتي ومحظوراتي الشخصية.

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

كيف تضيف القواعد القانونية والتسويق والعمليات إلى CLAUDE.md؟#

بالنسبة إلى معظم الفرق، CLAUDE.md وثيقة تقنية بحتة: الأدوات، وأوامر البناء، وأعراف البرمجة. وهذا مفيد، لكنه لا يمثل إلا ثلث القيمة.

عندما يحافظ رائد الأعمال على CLAUDE.md، فمن المنطقي إضافة أقسام خاصة بالأعمال. هناك ثلاثة أقسام هي الأهم:

القواعد القانونية (للأسواق الخاضعة للتنظيم)

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

مثال لمشروع في مجال التقنية المالية من دون ترخيص مصرفي:

ملاحظة تحريرية: يوضح ما يلي تنسيق قاعدة داخلية لمشروع بعينه. ولا يُعد إذنًا عامًا لاستخدام المصطلحات المذكورة؛ فمدى قبول العبارة يعتمد على القانون المعمول به ووضع الشركة.

🚨 حرج - يُحظر استخدام ألفاظ مالية. في المواد الموجهة للعملاء، لا تستخدم: «وديعة» أو «عائد مضمون» أو «منتج استثماري». استخدم: «حساب ادخار» و«عائد متوقع» و«منتج بسعر متغير». والسبب هو المتطلبات القانونية المنطبقة على الإعلان عن الخدمات المالية لهذا المشروع.

هذا الجزء في CLAUDE.md يؤدي أمرًا بسيطًا: كلما طلبت من Claude كتابة نص موجه للعملاء، يتحقق الوكيل من مطابقته لهذه المحظورات. ومن دون القاعدة، تظهر الكلمات المحظورة في كل حملة ثالثة. ومعها، تنساها من الأساس.

ينجح النهج نفسه في:

• المشاريع الطبية (لا تدّعِ أن شيئًا ما «يعالج» أو «يشفي»).
• الإعلان عن الأدوية (لا تدّعِ أنها «الأكثر فاعلية»؛ وأدرج التحذيرات المطلوبة).
• أي قطاع خاضع للتنظيم وله قواعده الإعلانية الخاصة.

أسلوب التسويق وتنسيق النصوص

إذا كنت تنشر النصوص بانتظام (في وسائل التواصل الاجتماعي، أو النشرات الإخبارية، أو المواقع الإلكترونية)، فمن المفيد توثيق التنسيق في فقرة واحدة في CLAUDE.md. إليك مثالًا لما قد يكتبه مؤثر أو وكالة تدير قناة مراسلة:

عند كتابة منشورات القناة، راجع style/posts.md. استخدم علامات التنسيق المسموح بها في القناة، وتجنب المحارف الخاصة «الخطرة». واختم بدعوة إلى اتخاذ إجراء تحمل وسم UTM وفق هذا الاصطلاح: utm_source=<channel>&utm_medium=<type>&utm_campaign=<slug>.

كان Claude يكتب المنشورات «بالأسلوب العام لموقع تسويقي». أما الآن فيتبع التنسيق الخاص بك، ويستخدم وسوم UTM الخاصة بك، ولا يكشف أن النص مكتوب بالذكاء الاصطناعي.

العادات التشغيلية

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

«خطط للأسبوع» ← افتح ops/monthly.md، وأنشئ YYYY-WNN.md في المجلد نفسه، وانقل المهام من ops/backlog.md إلى الأيام المناسبة. «ما الموجود في قائمة الأعمال المتراكمة؟» ← اقرأ ops/backlog.md واعرض محتواه في قائمة. «اختتم الأسبوع» ← املأ قسم «ملخص الأسبوع» في ملف الأسبوع الحالي.

باستخدام جداول كهذه، ينتقل Claude من «مساعد يكتب الشفرة» إلى «مشغّل» يعرف روتين عملك. كل يوم اثنين، أقول: «لنخطط للأسبوع»، فيفتح Claude الملفات المناسبة، ويقرأ الأهداف الشهرية، ويقترح طريقة لتقسيم العمل.

كيف تدقق CLAUDE.md باستخدام قائمة من 12 نقطة في 5 دقائق؟#

1. الحجم. هل هو موجز، مع نحو 200 سطر كهدف للمراجعة وليس سقف نجاح أو فشل؟
2. الاسم. هل اسمه بالضبط CLAUDE.md بأحرف كبيرة، وليس claude.md؟
3. الموقع. هل يوجد في جذر المشروع أو في ./.claude/CLAUDE.md؟
4. وصف المشروع. هل توضح الأسطر الخمسة الأولى ما هو المشروع ولمن؟
5. الأدوات. هل التقنيات مذكورة بوضوح ومن دون حشو؟
6. البنية. هل يوجد مخطط للمستودع مع شروح؟
7. التوجيه. هل يوجد جدول «السؤال ← الملف» يوضح أين تجد الإجابات؟
8. المبادئ. هل يوجد قسم للقواعد يبدأ بـ«لا تفعل أبدًا» و«افعل دائمًا»؟
9. التحديد. هل كل قاعدة قابلة للتحقق؟ («استخدم مسافتين»، لا «اكتب بأسلوب جميل».)
10. التحديث الذاتي. هل توجد قاعدة تنص على «التحقق مما يجب إضافته في نهاية الجلسة»؟
11. التأمل. هل توجد قاعدة تنص على «تسجيل ملخص الجلسة في retrospectives/»؟
12. الأمان. هل أُدرجت المحظورات الحرجة (.env وrm -rf) أيضًا في .claude/settings.json؟

إذا كانت لديك أكثر من خمس إجابات بـ«لا»، فافتح Claude وأعطه هذا الطلب:

Read my CLAUDE.md and compare it with the checklist below. For each item, say: yes / no / partly, and what specifically to fix.

Checklist:

موجز بما يكفي للمهمة؛ راجعه قرب 200 سطر دون اعتبارها سقفًا صارمًا

وصف المشروع in the first 5 lines

Tools listed explicitly

Repository structure diagram included

“Question → file” table included

Principles section with rules included

Every rule is specific and verifiable

“Update at the end of the session” rule included

“Reflect at the end of the session” rule included

Critical prohibitions included in .claude/settings.json

No duplicates of the same rule in different sections

No dangling links to files that no longer exist

After the audit, give me a list of specific changes that will make the file living.

ماذا تستخدم بعد CLAUDE.md: Plan Mode أم Skills أم الوكلاء الفرعيون؟#

CLAUDE.md هو الأساس. وحين يعمل، يمكنك إضافة ثلاث آليات إلى Claude Code يعزز بعضها بعضًا.

Plan Mode. وضع ينشئ فيه Claude خطة للتغيير أولًا، وينتظر موافقتك، ثم يبدأ العمل. فعّله باستخدام Shift+Tab أو الأمر /plan. ويعالج نقطة الألم الأساسية في البرمجة بأسلوب vibe coding: «طلبت من Claude إصلاح شيء واحد، فأعاد كتابة نصف المشروع». لن يحدث ذلك في Plan Mode، إذ ترى الخطة قبل أن يلمس الوكيل أي ملف.

Skills. ملفات .md منفصلة في مجلد .claude/skills/، تتضمن معرفة بنوع محدد من المهام. مثلًا، تحتوي مهارة «كيفية كتابة ترحيل لقاعدة بيانات» على إجراء محدد وقالب وأمثلة. لا توضع هذه المعرفة في CLAUDE.md لأنها مطولة جدًا. لكن عندما يواجه Claude مهمة مثل «اكتب ترحيلًا»، يحمّل المهارة المناسبة ويتبعها.

الوكلاء الفرعيون. عندما تتطلب المهمة قدرًا كبيرًا من السياق (مثل مراجعة ميزة كبيرة)، يستطيع Claude تشغيل وكيل فرعي منفصل في سياقه النظيف الخاص. وينفذ الوكيل الفرعي المهمة ثم يعيد النتيجة من دون إثقال سياق محادثتك الأساسية.

تستخدم الآليات الثلاث CLAUDE.md نقطة انطلاق: تقرأه في بداية عملها لفهم سياق المشروع. ولهذا تعمل هذه الميزات أيضًا على نحو سيئ من دون ملف CLAUDE.md متجدد. ابدأ بالأساس، ثم أضف الطبقات فوقه.

الخطوة التالية. أنشئ ملف CLAUDE.md في جذر المشروع، وانسخ القالب من بداية هذه المقالة، واملأ الحقول بين الأقواس المربعة باستخدام طلب المساعدة. ثم عايش الملف: حوّل كل خطأ يرتكبه الوكيل إلى سطر جديد. بعد أسبوعين أو ثلاثة، يتوقف CLAUDE.md عن كونه «وثيقة كتبناها ونسيناها»، ويصبح شيئًا يرجع إليه Claude فعلًا في كل جلسة.

إذا أردت بناء إطار كامل حول CLAUDE.md، يتضمن مجلد business/ للدماغ الثاني، ومجلد about-me/ لإسقاط رقمي لك، ومهارات أساسية، وPlan Mode مضبوطًا، فاستخدم الخطوات والأمثلة في هذه المقالة. أدلة Ailoot.

تابع قراءة أدلة Ailoot.