كتابة ملف CLAUDE.md احترافي | دليل عملي مع قالب جاهز

[Ibn AliraQ]

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

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

ملف CLAUDE.md هو ملف Markdown للتعليمات المستمرة. يقرأه Claude Code عند بدء الجلسة وفق نطاقه وموقعه، لكنه يتعامل معه كسياق إرشادي لا كطبقة إنفاذ حتمية. لذلك يجب ألا تعتمد عليه وحده لمنع الأوامر الخطرة أو ضمان تشغيل فحص في كل مرة؛ هذه الحالات تحتاج إلى إعدادات صلاحيات أو Hooks أو أدوات تحقق فعلية.[1][4]​

ملاحظة تحديث: تعتمد التفاصيل التقنية في هذا الدليل على وثائق Claude Code المتاحة بتاريخ 11 يوليو 2026. راجع الوثائق الرسمية عند تغير سلوك الأداة أو بنية مجلد .claude.​

​

​

ما هو ملف CLAUDE.md وما وظيفته؟​

تبدأ كل جلسة جديدة في Claude Code بسياق جديد، من دون تحميل سجل المحادثات السابقة تلقائيًا. يستطيع Claude الاحتفاظ بمعلومات بين الجلسات بطريقتين مختلفتين: تعليمات يكتبها المستخدم في ملفات CLAUDE.md، وذاكرة تلقائية يدوّن فيها Claude ملاحظات وأنماطًا تعلمها أثناء العمل.[1]
وظيفة CLAUDE.md هي تعريف Claude بالمشروع وطريقة العمل فيه قبل أن يبدأ الاستكشاف والتنفيذ. حيث يمكن أن يحتوي على:​

• الغرض المختصر من المشروع.​
• الأوامر الصحيحة للتشغيل والبناء والاختبار.​
• خريطة المجلدات والمسؤوليات الأساسية.​
• القرارات المعمارية التي لا تظهر بوضوح من الكود.​
• قواعد العمل التي تنطبق على معظم المهام.​
• القيود التي يجب أن يعرفها الوكيل قبل تعديل الملفات.​
• تعريف واضح لما يعنيه اكتمال المهمة.​

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

CLAUDE.md ليس إعداد أمان ملزمًا​

محتوى الملف يساعد Claude على اتخاذ قرارات أفضل، لكنه لا يضمن الامتثال الصارم. إذا كتبت: «لا تعدل مجلد migrations»، فقد يلتزم Claude غالبًا، لكن هذه العبارة ليست حاجزًا تقنيًا. لمنع الكتابة فعليًا استخدم صلاحيات settings.json أو Hook يعترض العملية أو بيئة Sandbox مناسبة.[1][4]
هذه التفرقة تمنع خطأ شائعًا: تحويل ملف التعليمات إلى بديل عن نظام الأمان والاختبارات. التعليمات تشرح السلوك المطلوب، أما الأدوات الحتمية فتفرضه أو تتحقق منه.
​

الفرق بين CLAUDE.md والذاكرة التلقائية​

يكتب المستخدم CLAUDE.md ليحدد قواعد المشروع وسير العمل والمعمارية. أما Auto Memory فيكتبها Claude نفسه لحفظ ما اكتشفه من أوامر مفيدة، وأنماط تصحيح، وتفضيلات محلية. كلاهما يدخل في سياق الجلسة، لكن الذاكرة التلقائية محلية للجهاز وليست بديلًا موثوقًا عن تعليمات الفريق المحفوظة في Git.[1]
ضع قاعدة مثل «استخدم pnpm ولا تستخدم npm» في CLAUDE.md إذا كانت سياسة مشروع مشتركة. أما ملاحظة مثل «اختبارات التكامل المحلية تحتاج Redis يعمل على المنفذ المحدد» فقد تظهر أولًا في الذاكرة التلقائية، ثم تنقل إلى وثائق المشروع إذا أصبحت معرفة ثابتة يحتاجها الفريق.
​

الفرق بين CLAUDE.md و README.md​

ملف README.md موجه أساسًا للبشر: يشرح المنتج، وطريقة التثبيت، والاستخدام، والمساهمة. أما CLAUDE.md فيركز على المعلومات التشغيلية التي يحتاجها الوكيل لاتخاذ قرارات صحيحة أثناء العمل.
لا تنسخ README بالكامل إلى ملف Claude. اكتفِ بملخص قصير أو استورد الملف عند الحاجة، مع الانتباه إلى أن الاستيراد الكامل يضيف محتواه إلى السياق. يمكن أيضًا الإشارة إلى المسار بين علامات الكود من دون استيراده، ثم توجيه Claude إلى قراءته عندما تكون المهمة مرتبطة به.[1]
​

الفرق بين CLAUDE.md و AGENTS.md​

يقرأ Claude Code ملف CLAUDE.md مباشرة، ولا يقرأ AGENTS.md تلقائيًا. إذا كان المشروع يستخدم AGENTS.md مع وكلاء أخرين، يمكنك إنشاء ملف CLAUDE.md يحتوي على @AGENTS.md ثم إضافة تعليمات خاصة بـClaude تحته، أو استخدام رابط رمزي عندما يناسب نظام التشغيل.[1]
هذا أفضل من الاحتفاظ بنسختين متطابقتين قد تختلفان بمرور الوقت.
​

أين تضع ملف CLAUDE.md؟​

اختيار الموقع يحدد نطاق التعليمات. لا يوجد مكان واحد صحيح لكل الحالات؛ الصحيح هو وضع كل قاعدة في أضيق نطاق تحتاجه.
​

تعليمات المستخدم العامة​

المسار:

~/.claude/CLAUDE.md

يطبق هذا الملف تفضيلاتك الشخصية على جميع المشاريع، مثل طريقة عرض التقارير أو تفضيلك استخدام أداة CLI معينة. لا تضع فيه قواعد خاصة بمشروع واحد، لأن ذلك قد يسبب تعارضات أو سلوكًا غير مناسب في مشاريع أخرى.[1][3]

تعليمات المشروع المشتركة​

يمكن حفظ ملف المشروع في أحد الموقعين:

./CLAUDE.md
./.claude/CLAUDE.md

استخدمه للمعمارية، والأوامر، واتفاقيات الفريق، وحدود التعديل. توصي Anthropic بإضافته إلى Git حتى يراجعه الفريق ويتطور مع المشروع.[1][2]
​

التعليمات المحلية الخاصة بك​

المسار:

./CLAUDE.local.md

يُحمّل بجانب ملف المشروع، لكنه مخصص لتفضيلات محلية لا ينبغي مشاركتها، مثل عنوان بيئة Sandbox شخصية أو بيانات اختبار غير حساسة أو أمر محلي خاص بجهازك. أضفه إلى .gitignore ولا تضع فيه أسرارًا أو مفاتيح API.[1][3]
​

الملفات المتداخلة في المجلدات​

يبحث Claude Code صعودًا من مجلد العمل عن ملفات CLAUDE.md وCLAUDE.local.md، ويجمع الملفات التي يجدها بدل أن يلغي بعضها بعضًا. أما ملفات المجلدات الفرعية فتُحمّل عند قراءة Claude لملفات داخل تلك المجلدات.[1]

في مشروع Monorepo قد يكون لديك:

project/
├── CLAUDE.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md
│   └── api/
│       └── CLAUDE.md
└── packages/
    └── ui/
        └── CLAUDE.md

يحتوي الملف الجذري على القواعد المشتركة، بينما يشرح كل ملف فرعي ما يخص التطبيق أو الحزمة فقط. لا تكرر القواعد الجذرية داخل الملفات الفرعية، ولا تفترض أن الملف الأقرب يلغي ما سبقه؛ الملفات تُجمع في السياق وقد يختار Claude بصورة غير متوقعة عند وجود تعارض.[1]
​

​

ماذا تكتب داخل ملف CLAUDE.md الاحترافي؟​

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

1. ملخص المشروع والهدف​

اكتب فقرتين كحد أقصى توضحان:

• ما الذي يبنيه المشروع؟
• من المستخدم المستهدف؟​
• ما الوظائف الجوهرية؟​
• ما الحدود التي لا تدخل ضمن المنتج؟​

مثال جيد:

## Project Overview

Axvoid Hub is a marketplace for structured AI prompts and reusable skills.
The public site supports discovery and purchase; the admin area manages
products, editorial content, and downloadable assets.

Do not introduce social-network features or user-generated public posts
unless the task explicitly requires them.

هذا أفضل من وصف تسويقي طويل لا يساعد Claude على اختيار الملف أو الطبقة الصحيحة.
​

2. التقنية المستخدمة​

اذكر ما يؤثر في التنفيذ فقط:

## Stack

- Next.js App Router with TypeScript
- Supabase for authentication and PostgreSQL
- Tailwind CSS for styling
- pnpm is the only supported package manager

لا تسرد كل مكتبة موجودة في package.json. يستطيع Claude قراءتها. أضف الإصدار فقط عندما يغير طريقة الكتابة أو التوافق.
​

3. أوامر التشغيل والتحقق​

هذا من أعلى أقسام الملف قيمة، لأن الأمر الصحيح يوفر التخمين ويمنع تشغيل اختبارات واسعة بلا حاجة.

## Commands

- Install: `pnpm install`
- Development: `pnpm dev`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- Targeted tests: `pnpm test -- <test-file>`
- Full verification: `pnpm verify`

أضف ملاحظة عندما يكون الأمر الكامل مكلفًا أو يحتاج خدمة خارجية. لا تكتب «اختبر التغييرات» فقط؛ حدد الاختبار المناسب وكيف يعرف Claude أنه نجح. تشدد أفضل ممارسات Anthropic على إعطاء الوكيل وسيلة مباشرة للتحقق من عمله، مثل اختبار أو Build أو مقارنة مرئية.[2]
​

4. خريطة معمارية قصيرة​

الهدف ليس توثيق كل مجلد، بل تقليل وقت البحث ومنع وضع المنطق في طبقة خاطئة.

## Architecture

- `src/app/`: routing and page composition only
- `src/domains/`: business logic grouped by domain
- `src/components/ui/`: reusable presentational components
- `src/lib/`: shared infrastructure and integrations
- `supabase/migrations/`: database schema history; never rewrite applied files

أضف العلاقات غير الواضحة، مثل أن المصادقة تدار على الخادم أو أن الوصول إلى قاعدة البيانات يجب أن يمر عبر Repository محدد.
​

5. قواعد كتابة الكود​

اكتب فقط القواعد غير القياسية أو التي تتكرر فيها الأخطاء. استبدل العبارات الغامضة بتوجيهات قابلة للفحص:
ضعيف:

- Write clean code.
- Follow best practices.
- Handle errors properly.

أفضل:

- Keep database access inside domain repositories.
- Server actions return `{ success, data?, error? }` and never expose raw database errors.
- Reuse an existing UI component before creating a new variant.
- Add a focused regression test for every confirmed bug.

لا تجعل Claude يقوم بوظيفة Linter. ضع قواعد التنسيق في ESLint أو Prettier أو Biome، ثم اذكر أمر تشغيلها فقط. الأدوات الحتمية أسرع وأكثر اتساقًا من تعليمات لغوية طويلة.[2][6]
​

6. سير العمل المتوقع​

اكتب تسلسلًا يوجه طريقة التنفيذ من دون إجبار كل مهمة صغيرة على خطة ثقيلة:

## Workflow

1. Read the relevant implementation and tests before editing.
2. For changes spanning multiple domains, produce a plan first.
3. Implement the smallest correct change that preserves existing behavior.
4. Run targeted checks before broader verification.
5. Review `git diff` for unrelated changes.
6. Report what changed, what was tested, and any remaining risk.

توصي Anthropic بالفصل بين الاستكشاف والتخطيط والتنفيذ في المهام الكبيرة، مع تجاوز الخطة عندما يكون التغيير صغيرًا وواضحًا.[2]
​

7. القيود والمحظورات​

اكتب القيود التي يحتاج Claude إلى معرفتها قبل التعديل:

## Boundaries

- Do not modify generated files manually.
- Do not rewrite applied database migrations.
- Do not change public API contracts without explicit approval.
- Do not push, deploy, publish, or delete remote resources unless requested.
- Never add secrets, tokens, private keys, or production data to the repository.

لكن حوّل المحظورات الحرجة إلى صلاحيات أو Hooks أيضًا. لا تعتمد على النص وحده لمنع حذف الملفات أو تنفيذ أوامر إنتاجية.[1][4]
​

8. تعريف الاكتمال​

يمنع هذا القسم Claude من إعلان النجاح بعد تعديل الكود فقط:

## Definition of Done

A task is complete only when:
- the requested behavior is implemented;
- relevant tests pass;
- type checking and linting pass for affected code;
- no unrelated files changed;
- documentation is updated when public behavior changed;
- the final report lists verification performed and unresolved limitations.

​

خطوات كتابة ملف CLAUDE.md من الصفر​

الخطوة الأولى: افحص المشروع قبل كتابة التعليمات​

ابدأ بقراءة المصادر الحقيقية للحقيقة داخل المشروع:

• ملفات الحزم والبناء.
• أوامر CI/CD.​
• هيكل المجلدات.​
• إعدادات Lint وTypeScript.​
• الاختبارات القائمة.​
• وثائق المعمارية.​
• قواعد Git والمساهمة.​

يمكنك تشغيل /init للحصول على مسودة أولية؛ وفق الوثائق الرسمية يحلل الأمر المشروع ويستخرج أنظمة البناء والاختبارات والأنماط، وإذا كان الملف موجودًا يقترح تحسينات بدل استبداله.[1][2] لكن الناتج نقطة بداية وليس قرارًا نهائيًا. راجع كل سطر، واحذف ما هو قابل للاستنتاج أو غير دقيق.​

الخطوة الثانية: اجمع التصحيحات المتكررة​

راجع الجلسات ومراجعات الكود واسأل:​

• ما الخطأ الذي يكرره Claude؟​
• ما المعلومة التي أشرحها كل مرة؟​
• ما القرار الذي لا يظهر من أسماء الملفات؟​
• ما الأمر الذي يستخدمه Claude بصورة خاطئة؟​
• ما الذي يحتاجه مطور جديد قبل أول تعديل؟​

لا تضف قاعدة بسبب حادثة واحدة قبل فهم السبب. ربما يكون الحل إصلاح تسمية ملف، أو تحسين اختبار، أو إضافة Type، أو تحديث README بدل زيادة تعليمات الوكيل.​

الخطوة الثالثة: صنف كل معلومة حسب نطاقها​

استخدم هذا القرار:​

• مطلوبة في معظم جلسات المشروع: CLAUDE.md.​
• تخص نوع ملفات أو مجلدًا: .claude/rules/ مع paths.​
• إجراء متكرر متعدد الخطوات: Skill.​
• أمر يجب أن يعمل دائمًا: Hook.​
• تفضيل شخصي لكل المشاريع: ~/.claude/CLAUDE.md.​
• تفضيل محلي لمشروع واحد: CLAUDE.local.md.​
• ملاحظة اكتشفها Claude وقد تتغير: Auto Memory.​

هذا التصنيف أهم من الصياغة؛ لأنه يمنع تحميل تفاصيل غير مرتبطة بكل جلسة.​

الخطوة الرابعة: حوّل النوايا إلى قواعد قابلة للاختبار​

بدلًا من:

- Be careful with the database.

اكتب:

- Never edit an applied migration. Create a new migration and run the local schema test.

وبدلًا من:

- Keep changes minimal.

اكتب:

- Do not refactor unrelated modules while fixing a scoped bug. List any recommended refactor separately.

القواعد المحددة تقلل مساحة التفسير، وتساعدك على اختبار ما إذا كان الملف حسّن السلوك فعلًا.​

الخطوة الخامسة: احذف ما لا يحتاجه كل تشغيل​

اسأل عن كل سطر:​

1. هل يحتاجه Claude في معظم المهام؟​
2. هل يستطيع اكتشافه بسرعة من ملف موثوق؟​
3. هل يمكن فرضه بأداة؟​
4. هل أصبح قديمًا؟​
5. هل يتعارض مع قاعدة أخرى؟​

توصي الوثائق الحالية بإبقاء الملف أقل من نحو 200 سطر كقاعدة عملية، لأن الملفات الأكبر تستهلك سياقًا وقد تقلل الالتزام. كما أن تقسيم الملف إلى Imports يحسن التنظيم لكنه لا يخفض السياق؛ فالملفات المستوردة تُحمّل عند البداية.[1][3]​

قالب CLAUDE.md احترافي جاهز​

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

CLAUDE.md

## Project Overview

[Describe the product, its users, and its core purpose in 2–4 sentences.]

## Success Criteria

- [What must remain true after changes?]
- [What user-visible outcome defines success?]
- [Which compatibility or performance constraints matter?]

## Technology Stack

- Runtime: [example: Node.js 22]
- Framework: [example: Next.js App Router]
- Language: [example: TypeScript strict mode]
- Database: [example: PostgreSQL via Supabase]
- Package manager: [example: pnpm only]

## Repository Map

- `[path]`: [responsibility]
- `[path]`: [responsibility]
- `[path]`: [generated/read-only/critical notes]

## Architecture Rules

- [Where business logic belongs]
- [How data access is performed]
- [Allowed dependency direction]
- [Important boundary that must not be crossed]

## Commands

- Install: `[command]`
- Development: `[command]`
- Build: `[command]`
- Type check: `[command]`
- Lint: `[command]`
- Targeted test: `[command]`
- Full verification: `[command]`

## Coding Rules

- Follow existing patterns in `[reference path]`.
- [Specific error-handling rule]
- [Specific naming or API rule]
- [Specific UI or accessibility rule]
- Do not duplicate an existing abstraction without checking current usage.

## Workflow

1. Read the relevant code, tests, and documentation before editing.
2. Plan first when the change spans multiple modules or has unclear tradeoffs.
3. Implement the smallest complete change.
4. Run targeted tests, then broader checks when justified.
5. Review the diff for regressions and unrelated edits.
6. Report changes, verification, and remaining risks.

## Testing Requirements

- Add or update a regression test for confirmed bugs when practical.
- Prefer focused tests during iteration.
- Run `[full command]` before final delivery when the affected scope requires it.
- Never claim a test passed unless it was actually run successfully.

## Security and Data Rules

- Never expose secrets, credentials, private keys, or production data.
- Validate untrusted input at the server boundary.
- Do not weaken authentication, authorization, or row-level security to make a test pass.
- Ask before destructive, irreversible, production, billing, or publishing actions.

## Change Boundaries

- Do not edit generated files manually.
- Do not rewrite applied migrations.
- Do not change public contracts without explicit approval.
- Do not push, deploy, publish, or delete remote resources unless requested.
- Keep unrelated refactors outside the current change.

## Git Workflow

- Inspect `git status` before and after changes.
- Do not discard user changes.
- Use descriptive commits only when explicitly requested.
- Never force-push unless explicitly approved.

## Definition of Done

A task is complete only when:
- requested behavior is implemented;
- relevant verification passes;
- no unrelated changes remain;
- documentation is updated when needed;
- the final response accurately states what was and was not verified.

## Reference Documents

Read only when relevant:
- `[path]` — [when to read it]
- `[path]` — [when to read it]
- `[path]` — [when to read it]

نسخة مختصرة للمشاريع الصغيرة​

CLAUDE.md

## Project

[One-paragraph description of the project and its main boundary.]

## Commands

- Dev: `[command]`
- Test: `[command]`
- Verify: `[command]`

## Structure

- `[path]`: [purpose]
- `[path]`: [purpose]

## Rules

- [Most important project-specific rule]
- [Most common correction]
- [Critical change boundary]

## Done

Run `[verification command]`, inspect the diff, and report any unverified risk.

القالب المختصر أفضل من قالب شامل ممتلئ بعناوين فارغة. أضف قسمًا فقط عندما يمنع خطأ حقيقيًا أو يحسن قرارًا متكررًا.​

الاستيراد والملفات المرجعية دون تضخيم السياق​

يستطيع CLAUDE.md استيراد ملفات أخرى باستخدام الصيغة:

@docs/architecture.md

تُحل المسارات النسبية انطلاقًا من مكان ملف CLAUDE.md الذي يحتوي الاستيراد، ويمكن استخدام مسارات مطلقة. وتسمح الوثائق باستيراد متداخل حتى أربع طبقات.[1]
لكن الاستيراد ليس تحميلًا عند الحاجة؛ المحتوى المستورد يتوسع ويدخل السياق عند بدء الجلسة. لذلك لا تستورد دليلًا من مئات الأسطر لمجرد أنه مهم أحيانًا. استخدم أحد البدائل:​

• اذكر المسار بين backticks واطلب قراءته عند الحاجة.​
• انقل الإجراء المتخصص إلى Skill.​
• ضع قاعدة مرتبطة بمسار في .claude/rules/.​
• أبقِ الملخص الدائم في CLAUDE.md واترك التفاصيل في وثيقة مستقلة.​

مثال عملي:

## References

- Read `docs/database-migrations.md` before changing database schema.
- Read `docs/design-system.md` only for UI work.
- Read `docs/release-process.md` only when the user requests a release.

هذه صيغة توجيه للقراءة عند الحاجة، وليست Import تلقائيًا.​

متى تستخدم .claude/rules بدل CLAUDE.md؟​

ضع ملفات Markdown داخل:

.claude/rules/

القواعد التي لا تحتوي paths تُحمّل عند البداية مثل تعليمات المشروع. أما القواعد المشروطة فتطبق عندما يعمل Claude مع ملفات تطابق الأنماط المحددة.[1]
مثال لقواعد API:

---
paths:
  - "src/api/**/*.ts"
---

## API Rules

- Validate all external input at the handler boundary.
- Use the shared error-response helper.
- Add an authorization test for protected endpoints.

استخدم Path Rules عندما تكون القاعدة صحيحة في جزء واحد فقط. لا تضع قاعدة React في الملف الجذري إذا كان نصف المشروع Backend ولا يحتاجها.
​

CLAUDE.md أم Skills أم Hooks؟​

اختيار الآلية الصحيحة يمنع تحول CLAUDE.md إلى ملف ضخم.​

استخدم CLAUDE.md عندما​

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

استخدم Skill عندما​

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

توضح وثائق Claude Code أن Skills تحمل إجراءات أو معرفة تُستدعى عند الحاجة، بينما يحمل CLAUDE.md السياق الدائم.[3][5] ويمكنك الرجوع إلى دليل كتابة المهارات Skills باحتراف لبناء سير عمل مستقل بدل وضعه كاملًا داخل ملف المشروع.​

استخدم Hook عندما​

• يجب تشغيل Lint بعد كل تعديل.
• يجب منع الكتابة في مسار معين.
• يجب فحص أمر قبل تنفيذه.
• يجب تسجيل حدث أو تشغيل برنامج عند نقطة ثابتة.

الـHooks أوامر تعمل في مراحل محددة من دورة Claude Code، ولذلك توفر تحكمًا حتميًا لا يعتمد على قرار النموذج.[4]​

استخدم Settings أو Permissions عندما​

• تريد السماح أو المنع لأدوات وأوامر معينة.
• تحتاج Sandbox أو متغيرات بيئة أو إعدادات عميل.
• تريد سياسة مشتركة قابلة للتنفيذ بدل تذكير لغوي.

استخدم Auto Memory عندما​

• تريد أن يحتفظ Claude بملاحظات اكتشفها أثناء العمل.
• تكون المعلومة محلية أو تجريبية.
• لا تزال الملاحظة غير ناضجة لتصبح قاعدة مشروع رسمية.

أخطاء شائعة عند كتابة ملف CLAUDE.md​

نسخ README أو توثيق المشروع بالكامل​

المحتوى الطويل لا يصبح مفيدًا لمجرد أنه صحيح. دراسة حديثة على ملفات سياق الوكلاء وجدت أن توفير هذه الملفات لم يحسن النجاح عمومًا في إعدادات الاختبار المدروسة، وزاد كلفة الاستدلال بأكثر من 20% في المتوسط؛ وخلص الباحثون إلى أن المتطلبات غير الضرورية قد تجعل المهمة أصعب.[7]
هذا لا يعني حذف CLAUDE.md، بل استخدامه للمعرفة غير القياسية عالية القيمة، ثم قياس أثره بدل افتراض أن المزيد أفضل.​

تحويل الملف إلى Linter مكتوب بلغة طبيعية​

قواعد المسافات، وترتيب Imports، والاقتباسات، والتنسيق مكانها أدوات Format وLint. اذكر الأمر المطلوب، ولا تستهلك عشرات التعليمات في إعادة وصف ما تستطيع الأداة فرضه.
بحث آخر حلل 100 مستودع مفتوح المصدر يحتوي AGENTS.md أو CLAUDE.md، ووجد أن «تسرب قواعد Lint» ظهر في 62% من الملفات، وتضخم السياق في 42%، وتسرب الإجراءات المتخصصة في 35%.[8] هذه النتائج أولية وفي سياق بحثي محدد، لكنها تدعم فصل التنسيق والإجراءات عن السياق الدائم.​

التعليمات المتعارضة​

قد تكتب في الملف الجذري «استخدم Server Components دائمًا»، ثم يطلب ملف فرعي «اجعل كل مكونات هذا المجلد Client Components». إذا لم يكن النطاق واضحًا، فقد يختار Claude قاعدة بصورة غير متوقعة. راجع الملفات مجتمعة، واجعل الاستثناء محددًا بالمسار والسبب.[1]​

أوامر ومسارات قديمة​

يتغير المشروع لكن يبقى CLAUDE.md ثابتًا. عندها يتحول إلى مصدر تضليل. تصف أبحاث حديثة هذه الظاهرة باسم «تعفن السياق» (Context Rot)، أي بقاء تعليمات ووثائق تشير إلى بنية لم تعد مطابقة للكود.[9]​

كتابة عبارات عامة​

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

وضع الأسرار داخل الملف​

قد يُحفظ ملف المشروع في Git ويُقرأ في كل جلسة. لا تضع مفاتيح API أو كلمات مرور أو بيانات إنتاج أو معلومات شخصية. استخدم متغيرات البيئة ومديري الأسرار وإعدادات الوصول المناسبة.​

الاعتماد على الكلمات المشددة​

تكرار IMPORTANT وALWAYS لا يصلح قاعدة غامضة أو متعارضة. اجعل النطاق والشرط والإجراء والاختبار واضحًا، ثم استخدم Hook أو Permission عندما تحتاج ضمانًا حتميًا.​

قبول الملف المولّد آليًا دون مراجعة​

/init مفيد لاكتشاف نقطة البداية، لكنه قد يكرر ما هو موجود أو يخطئ في تفسير نمط المشروع. راجع الأوامر فعليًا، واحذف المعلومات العامة، وأضف القرارات التي لا يستطيع اكتشافها.[1][2]
​

​

كيف تختبر أن CLAUDE.md يعمل فعلًا؟​

1. تحقق من الملفات المحملة​

شغّل:

/memory

يعرض الأمر ملفات CLAUDE.md وCLAUDE.local.md والقواعد المحملة في الجلسة. إذا لم يظهر الملف، فلن يستطيع Claude استخدامه.[1]​

2. ابدأ جلسة جديدة واختبر الفهم​

اطلب من Claude:

لخّص بنية المشروع، أوامر التحقق، وأهم ثلاثة حدود يجب احترامها قبل أي تعديل.

قارن الإجابة بالملف. لا تختبر حقائق يستطيع استنتاجها من أسماء المجلدات فقط؛ اختبر قرارًا معماريًا أو أمرًا غير معتاد.​

3. نفذ مهمة صغيرة ذات نتيجة قابلة للقياس​

اختر إصلاحًا محدودًا، ثم راقب:​

• هل قرأ الملفات الصحيحة؟​
• هل استخدم مدير الحزم الصحيح؟​
• هل تجنب المسار المحظور؟​
• هل شغّل الاختبار المحدد؟​
• هل أبقى التغيير ضمن النطاق؟​

4. قارن قبل وبعد​

لا تنسب أي تحسن إلى الملف من تجربة واحدة. اختبر نوعين أو ثلاثة من المهام المتكررة، وسجل عدد التصحيحات، والملفات المقروءة، والاختبارات، والأخطاء. الأدلة البحثية الحالية ليست متفقة على أن ملفات السياق تحسن كل المهام، ولذلك القياس داخل مشروعك أهم من تقليد قالب شائع.[7]​

5. عالج سبب التجاهل الصحيح​

عندما يتجاهل Claude قاعدة:​

1. تحقق من تحميل الملف عبر /memory.​
2. افحص موقع الملف ونطاقه.​
3. اجعل القاعدة أكثر تحديدًا.​
4. ابحث عن تعليمات متعارضة.​
5. انقل الإجراء الحتمي إلى Hook.​
6. انقل التفاصيل المتخصصة إلى Rule أو Skill.​

لا تضف نسخة جديدة من القاعدة في ثلاثة أماكن؛ هذا يزيد التعارض بدل أن يحل المشكلة.​

صيانة ملف CLAUDE.md مع تطور المشروع​

عامل الملف ككود مشترك، لا كملاحظة شخصية منسية.​

• راجعه عند تغيير أوامر البناء أو الاختبار.​
• حدّثه عند نقل مجلد أو تغيير حدود المعمارية.​
• اجعل تعديل التعليمات جزءًا من Pull Request المرتبط بالتغيير.​
• احذف القواعد التي أصبحت مفروضة بأداة أو غير ضرورية.​
• افحص التعارض بين الملف الجذري والملفات الفرعية والقواعد.​
• راقب الحجم، وانقل الإجراءات المتخصصة إلى Skills.​
• اختبر المسارات والأوامر دوريًا في CI عندما يمكن ذلك.​
• استخدم تعليقات Markdown المخصصة للمشرفين عند الحاجة؛ وثائق Claude Code تشير إلى أن التعليقات الكتلية خارج كتل الكود تُزال قبل حقن المحتوى في السياق.[1]​

المراجعة الدورية ضرورية لأن المعلومة الصحيحة اليوم قد تصبح تعليمًا خاطئًا بعد إعادة هيكلة المشروع. وقد وجدت دراسة استكشافية إشارات قديمة إلى عناصر الكود في 23% من عينة مؤلفة من 356 مستودعًا عند تطبيق أداة اتساق وثائق موجودة، ما يوضح أن قدم السياق مشكلة قابلة للقياس وليست مجرد احتمال نظري.[9]​

الأسئلة الشائعة حول كتابة ملف CLAUDE.md احترافي​

هل يجب أن يكون CLAUDE.md في جذر المشروع؟​

لا. يمكن وضع ملف مشترك في الجذر أو داخل .claude/CLAUDE.md، كما يمكن إنشاء ملفات داخل المجلدات لتعليمات أكثر تخصصًا. اختيار الموقع يعتمد على نطاق القاعدة، لا على تفضيل شكلي.[1]​

ما الطول المناسب لملف CLAUDE.md؟​

توصي وثائق Claude Code الحالية بإبقاء الملف تحت نحو 200 سطر، لأن الملفات الأطول تستهلك سياقًا وقد تقلل الالتزام.[1][3] هذا هدف عملي لا رقم سحري؛ ملف من 80 سطرًا متناقض أسوأ من ملف من 210 أسطر دقيقة وضرورية، لكن زيادة الحجم يجب أن تكون مبررة.​

هل يمكن إنشاء الملف باستخدام /init؟​

نعم. ينشئ /init نقطة بداية بناءً على بنية المشروع وأوامره وأنماطه، ثم تحتاج إلى مراجعة الناتج وتحسينه. لا تعتمد على التوليد التلقائي بوصفه توثيقًا نهائيًا.[1][2]​

هل يجب رفع CLAUDE.md إلى GitHub؟​

ارفع ملف المشروع المشترك إلى مستودع Git حتى يراجعه الفريق ويستخدم الجميع التعليمات نفسها. لا ترفع CLAUDE.local.md أو ملفات تحتوي تفضيلات محلية أو بيانات حساسة.[1][2]​

هل يقرأ Claude Code ملف AGENTS.md؟​

ليس مباشرة. أنشئ CLAUDE.md يستورد @AGENTS.md أو استخدم رابطًا رمزيًا، ثم أضف تعليمات Claude الخاصة عند الحاجة.[1]​

هل الملف الفرعي يلغي تعليمات الملف الجذري؟​

لا. يجمع Claude الملفات المكتشفة في السياق، وتظهر التعليمات الأقرب إلى مجلد العمل لاحقًا، لكنها لا تحذف السابقة. لذلك يجب تجنب التعارض وتحديد النطاق بوضوح.[1]​

لماذا يتجاهل Claude بعض التعليمات؟​

قد يكون الملف غير محمل، أو القاعدة غامضة، أو هناك تعارض، أو التعليمات لا تبدو مرتبطة بالمهمة، أو السياق مزدحم. تحقق عبر /memory، ثم ضيق القاعدة أو انقلها إلى آلية أنسب.[1][6]​

هل يمكن وضع مفاتيح API في CLAUDE.md؟​

لا. استخدم متغيرات البيئة أو مدير أسرار. ملف المشروع قد يدخل Git ويُحمّل في جلسات متعددة، وليس مخزنًا آمنًا للأسرار.​

متى أنقل التعليمات إلى Skill أو Rule أو Hook؟​

انقلها إلى Skill إذا كانت إجراءً متعدد الخطوات أو معرفة تستخدم أحيانًا، وإلى Rule إذا كانت مرتبطة بمسارات، وإلى Hook إذا كان تنفيذها إلزاميًا عند حدث محدد.[1][3][4][5]
​

​

خلاصة القول​

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

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

لمتابعة بناء بيئة Claude Code منظمة، راجع دليل كتابة المهارات Skills باحتراف ثم تصفح قسم أدوات الذكاء الاصطناعي للمطورين للاطلاع على الأدلة العملية المرتبطة بوكلاء البرمجة.
دمتم بود!​

المصادر​

1. How Claude remembers your project — Anthropic, Claude Code Docs، تم الاطلاع في 11 يوليو 2026.
2. Best practices for Claude Code — Anthropic, Claude Code Docs، تم الاطلاع في 11 يوليو 2026.
3. Extend Claude Code — Anthropic, Claude Code Docs، تم الاطلاع في 11 يوليو 2026.
4. Automate actions with hooks — Anthropic, Claude Code Docs، تم الاطلاع في 11 يوليو 2026.
5. Extend Claude with skills — Anthropic, Claude Code Docs، تم الاطلاع في 11 يوليو 2026.
6. Writing a good CLAUDE.md — Kyle، HumanLayer، 25 نوفمبر 2025.
7. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? — Thibaud Gloaguen وآخرون، arXiv، النسخة المنقحة 23 يونيو 2026.​
8. Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents — Hélio Victor F. dos Santos وآخرون، arXiv، النسخة الرابعة 19 يونيو 2026.​
9. Context Rot in AI-Assisted Software Development: Repurposing Documentation Consistency for AI Configuration Artifacts — Christoph Treude وSebastian Baltes، arXiv، 8 يونيو 2026.​

 

تقليل استهلاك التوكنز في Claude Code وخفض التكلفة

[زهور]

الله يعطيك العافيه على الطرح الرائع 💫✨

 

[غزل..ᥫ᭡]

-

شرح وافي وكامل
وموضوع مميز ورائع
ان شاء الله يجدون فيه الافادة
وكل الشكر لك لـ طرحك الموضوع
ولترتيبك له واظهارة بهذه الحله الجميله
لروحك 🌷🍃