AGENTS.md و CLAUDE.md: اترك دليل مشروع للذكاء الاصطناعي
قراءة مسبقة: الدليل المتقدم: اجعل الذكاء الاصطناعي يفهم مشروعك أكثر
AGENTS.md هو دليل مشروع يوضع في جذر المشروع: يقرؤه Claude Code وCodex وOpenCode تلقائيًا قبل بدء العمل، فلا تحتاج إلى شرح حزمة التقنيات والقواعد شفهيًا في كل مرة.
ملف الذاكرة لدى Claude Code يسمى CLAUDE.md، بنفس الآلية لكن باسم ملف مختلف. ستُهيئ هذه الصفحة الملفين معًا، لتقرأ الأدوات الثلاث المحتوى نفسه.
ماذا ستستطيع أن تفعل بعد التعلم
- كتابة
AGENTS.mdيوضع في جذر المشروع ويقرأه تلقائيًا وكلاء الترميز الثلاثة بالذكاء الاصطناعي - توضيح الأقسام الأربعة التي يجب كتابتها في AGENTS.md، ولماذا لا ينبغي كتابته كنص طويل
- تهيئة
CLAUDE.mdلـ Claude Code، مع ضمان ألا يتعارض الملفان أبدًا - فتح جلسة جديدة للتحقق: يجيب الذكاء الاصطناعي دون شرح منك عن كيفية تشغيل المشروع والاتفاقيات المتبعة
معضلتك الحالية
- في كل مرة تفتح جلسة جديدة، عليك أن تعيد شرح «نستخدم pnpm لا npm» و«تشغيل الاختبارات بـ
pnpm test». - القواعد المتفق عليها في الجلسة السابقة ينساها الذكاء الاصطناعي في هذه الجلسة تمامًا، ثم يبدأ بتثبيت
npm installبشكل عشوائي. - اتفاقيات المشروع موجودة فقط في رأسك: تغيير الجلسة، أو تغيير الأداة، أو تعاون زميل جديد — كل ذلك يستلزم إعادة الشرح من جديد.
متى تستخدم هذه الحيلة
عندما تحتاج إلى:
- أن يعرف الذكاء الاصطناعي في كل جلسة جديدة تلقائيًا حزمة تقنيات المشروع وأوامره الشائعة واتفاقيات الكود
- إرسال القواعد إلى git، ليشاركها كل فرد في الفريق وكل ذكاء اصطناعي في نسخة واحدة
- اليوم تستخدم Claude Code، وغدًا تنتقل إلى Codex أو OpenCode، ويظل الدليل ساريًا
ولا تريد:
- لصق فقرة طويلة من «خلفية المشروع» في مربع الحوار قبل بدء العمل في كل مرة
- تهيئة القواعد نفسها في الأدوات الثلاث بشكل منفصل، وبشكل غير متطابق
🎒 الاستعدادات قبل البدء
- قراءة الدرس التمهيدي الدليل المتقدم: اجعل الذكاء الاصطناعي يفهم مشروعك أكثر
- امتلاك مجلد مشروع، حتى لو كان مشروعًا فارغًا في بدايته
- تثبيت أي وكيل ترميز بالذكاء الاصطناعي: Claude Code أو Codex أو OpenCode. لم تثبّته بعد؟ اطّلع أولًا على تثبيت Claude Code: جاهز خلال 10 دقائق
- تخصيص 10 دقائق
الفكرة الأساسية
«آلية الدليل» لدى الأدوات الثلاث متشابهة جدًا، والاختلاف في اسم الملف وطريقة البحث:
| الأداة | أي ملف يقرأ | أين يوضع على مستوى المشروع | الملف العام (التفضيلات الشخصية) |
|---|---|---|---|
| Claude Code | CLAUDE.md؛ وعند عدم وجوده يمكنه قراءة AGENTS.md مباشرة (يتطلب v2.1.277+) | جذر المشروع ./CLAUDE.md أو ./.claude/CLAUDE.md | ~/.claude/CLAUDE.md |
| Codex | AGENTS.md، ويقرأه قبل بدء العمل | جذر المشروع | ~/.codex/AGENTS.md |
| OpenCode | AGENTS.md؛ بدءًا من الإصدار v2.3.1، عندما لا يوجد AGENTS.md في الدليل، يتم بدلًا من ذلك قراءة CLAUDE.md | من الدليل الجذر للمشروع | ~/.config/opencode/AGENTS.md (وعند غيابه يتم الرجوع إلى قراءة ~/.claude/CLAUDE.md) |
الفكرة في جملة واحدة: اعتبار AGENTS.md مصدر الحقيقة الوحيد. يقرؤه Codex وOpenCode مباشرة؛ أما Claude Code فيستخدم CLAUDE.md للإشارة إلى محتواه، ثم يضيف الإرشادات الخاصة بـ Claude. عند تعديل القواعد تعدّلها في مكان واحد، فتسري التغييرات على الأدوات الثلاث معًا.
ينقسم CLAUDE.md نفسه أيضًا حسب نطاق التأثير: مستوى المؤسسة (إدارة موحدة للمنظمة)، مستوى المستخدم (~/.claude/CLAUDE.md، يوضع فيه التفضيلات الشخصية، ويسري على جميع مشاريعك)، ومستوى المشروع (يدخل في نظام إدارة الإصدارات، وتتشاركه الفريق). تُهيئ هذه الصفحة بشكل أساسي مستوى المشروع.
اتبع خطواتي
الخطوة 1: أنشئ AGENTS.md في جذر المشروع
لماذا: كلما كان الدليل أكثر تحديدًا، قلّ تخمين الذكاء الاصطناعي. المثال في الدليل الرسمي لـ Codex هو أيضًا تعليمات قابلة للتنفيذ مباشرة، واحدة في كل سطر، وليس عبارة عامة مثل «يجب أن يكون الكود منظمًا».
أنشئ AGENTS.md في جذر المشروع (بنفس مستوى README)، واكتب فيه أربعة أقسام:
# وصف المشروع
- جملة واحدة: ماذا يفعل هذا المشروع (مثال: موقع لحجز الدورات)
- حزمة التقنيات: Next.js + TypeScript، وإدارة الحزم بـ pnpm
- الأوامر الشائعة: pnpm install / pnpm dev / pnpm test / pnpm build
- اتفاقيات الكود: المكونات في src/components، وتشغيل pnpm test قبل الإرسال، وعدم تعديل الملفات الناتجة عن البناء مباشرةاكتب كل قاعدة كتعليمة قابلة للتحقق: «استخدم مسافة بادئة بمقدار 2 مسافات» أفضل من «يجب أن يكون التنسيق منظمًا»، و«شغّل pnpm test قبل الإرسال» أفضل من «لا تنسَ الاختبارات».
ينبغي أن ترى: الملف موجود في جذر المشروع، في حدود عشرات الأسطر، وكل قاعدة في سطر واحد.
- تحقق سريع: اطلب من شخص لا يعرف مشروعك النظر لمدة 30 ثانية، ويجب أن يستطيع تحديد حزمة التقنيات التي يستخدمها المشروع وكيفية تشغيله
الخطوة 2: ضع الدليل في المكان الصحيح
لماذا: الأدوات الثلاث تبحث عن دليل الاستخدام بطرق مختلفة، لكنها جميعًا تتعرف على جذر المشروع — Codex يبحث من جذر المشروع حتى الدليل الفرعي الذي تقف فيه؛ OpenCode يقرأ الملف العام أولًا ثم يجمع من الدليل الحالي صعودًا مستوى بمستوى؛ Claude Code يقرأ CLAUDE.md في الدليل الحالي والمستويات الأعلى. بوضعه في الجذر، تُصيب طرق البحث الثلاث جميعًا.
الخطوات:
- تأكد من أن
AGENTS.mdموجود في جذر المشروع، ولا تضعه في دليل فرعي مثلsrc/، ولا تضعه على سطح المكتب. - ارفعه إلى git. توصي وثائق OpenCode صراحةً برفع ملف إرشادات المشروع إلى المستودع، ليحصل كل متعاون على النسخة نفسها من الإرشادات.
- لا تكتب التفضيلات الشخصية (مثل «الرد بالصينية») في دليل المشروع، بل ضعها في ملف المطالبات العام لكل أداة: Codex يستخدم
~/.codex/AGENTS.md، وOpenCode يستخدم~/.config/opencode/AGENTS.md، وClaude Code يستخدم~/.claude/CLAUDE.md.
ينبغي أن ترى: يُظهر git status أن AGENTS.md أصبح مُتتبَّعًا؛ وls في الجذر يُظهره بجانب README. وبعد ذلك، سواء أطلقت الوكيل من الجذر أو من دليل فرعي، سيجد هذا الدليل.
الخطوة 3: جهّز لـ Claude Code ملف CLAUDE.md
لماذا: يقرأ Claude Code افتراضيًا CLAUDE.md. وطالما يوجد ملف CLAUDE.md على مستوى المشروع في دليل العمل أو مستوى أعلى، فلن يقرأ AGENTS.md — وإذا لم تربط الملفين، س«يكون Claude Code غير قادر على رؤية» دليلك.
الطريقة A (موصى بها): يستورد CLAUDE.md ملف AGENTS.md
أنشئ CLAUDE.md في الجذر:
@AGENTS.md
## خاص بـ Claude Code
- (اختياري) إرشادات إضافية موجهة إلى Claude فقط@AGENTS.md هو صيغة الاستيراد في Claude Code: يُحمَّل محتوى AGENTS.md موسّعًا، وتُكتب الإرشادات الخاصة بـ Claude أسفل سطر الاستيراد. تُصان القواعد في مكان واحد فقط.
الطريقة B: رابط رمزي
ln -s AGENTS.md CLAUDE.mdأمر واحد، ويلتزم الملفان بالتزامن دائمًا، ولا يظهر أي ناتج عند النجاح. لكن إنشاء روابط رمزية على Windows يتطلب صلاحيات مسؤول أو وضع المطوّر، وقد يفحصه Git كنص عادي — إن كان في فريقك من يستخدم Windows، فاختر الطريقة A.
الطريقة C: نسخ المحتوى كما هو
انسخ محتوى AGENTS.md إلى CLAUDE.md. الأكثر بساطةً، لكن الثمن أن تعديل القواعد يتطلب تعديل موضعين؛ وإذا اختلف نص الموضعين، قد يختار الذكاء الاصطناعي أحدهما عشوائيًا ويصدّقه.
ينبغي أن ترى: شغّل claude في دليل المشروع، وأدخل /context، فيظهر CLAUDE.md في قائمة Memory files، ويُحمَّل معه محتوى AGENTS.md المستورد.
- تحقق سريع: يظهر CLAUDE.md في Memory files لدى
/context
💡 ماذا يحدث إذا لم تُنشئ CLAUDE.md؟
الإصدارات الجديدة من Claude Code (بدءًا من v2.1.277) تقرأ AGENTS.md مباشرةً عند غياب CLAUDE.md، وتعرض في بداية الجلسة سطرًا مثل no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. لكن بعض الجلسات لا تدعم ذلك (مثل أول جلسة بعد الترقية من إصدار قديم)، لذا فإعداد CLAUDE.md هو الخيار الأكثر أمانًا.
الخطوة 4: افتح جلسة جديدة للتحقق من سريان دليل الاستخدام
لماذا: الأدوات الثلاث تقرأ الدليل عند بدء الجلسة — Claude Code يحمّل ملفات الذاكرة عند بداية كل جلسة، وCodex يبني سلسلة التعليمات مرة واحدة عند كل تشغيل، وOpenCode لا تسري تغييرات ملفات الإرشادات المتداخلة إلا بجلسة جديدة. إذا اختبرت في جلسة قديمة، فأنت تختبر القواعد القديمة.
الخطوات:
- افتح جلسة جديدة تمامًا: شغّل Claude Code في دليل المشروع لـ
claude، وشغّلcodexلـ Codex. - اسأل مباشرةً: «كيف يُشغَّل هذا المشروع؟ وما هي اصطلاحات الكود؟»
- يمكن لمستخدمي Codex تشغيل أمر التحقق الوارد في الدليل الرسمي:
codex --ask-for-approval never "Summarize the current instructions."ينبغي أن ترى: يجيب الذكاء الاصطناعي بأوامر التشغيل والاصطلاحات المكتوبة في الملف دون أي شرح إضافي منك؛ ويعيد Codex سرد الإرشادات من الملفات العامة وملفات المشروع بترتيب التحميل.
- تحقق سريع: انتقل إلى دليل فرعي آخر وأعد التشغيل، ويظل الذكاء الاصطناعي يجد الدليل
نقطة تحقق ✅
- يقع
AGENTS.mdفي جذر المشروع، ويتضمن أربعة أقسام: نبذة عن المشروع، وحزمة التقنيات، والأوامر الشائعة، واصطلاحات الكود - رُفع الملف إلى git، وأي شخص يستنسخ المستودع يحصل على الإرشادات نفسها
- شغّل
/contextفي جلسة Claude Code، وقائمة Memory files تعرض CLAUDE.md - افتح جلسة جديدة واسأل «كيف يُشغَّل المشروع»، فيجيب الذكاء الاصطناعي إجابة صحيحة دون شرح منك
- محتوى AGENTS.md و CLAUDE.md متطابق (استيراد أو مزامنة)، دون قواعد متناقضة بينهما
تنبيهات للمزالق
❌ كتابته كمقال طويل
كلما طال الدليل، قلّت قدرة الذكاء الاصطناعي على إدراك النقاط المهمة. توصي وثائق Claude Code الرسمية بالحفاظ على كل CLAUDE.md في حدود 200 سطرًا: الطول المفرط يستهلك السياق ويخفض درجة الالتزام. ولدى Codex حد إجمالي أيضًا، إذ يتوقف التحميل عند بلوغ مجموع ملفات الإرشادات 32 KiB (القيمة الافتراضية).
الطريقة الصحيحة: اكتب فقط الحقائق التي لا يستطيع الذكاء الاصطناعي تخمينها (أوامر، اصطلاحات، محظورات)، سطرًا واحدًا لكل بند، في حدود عشرات الأسطر.
❌ كتابة مبادئ فقط دون أوامر
«يجب أن يكون الكود منظمًا» كلام فارغ لا يستطيع الذكاء الاصطناعي تنفيذه.
الطريقة الصحيحة: اكتب تعليمات قابلة للتحقق — «التشغيل بـ pnpm dev والاختبار بـ pnpm test»، «معالجات API توضع في src/api/handlers/».
❌ Claude Code لا يرى AGENTS.md
السبب الشائع: وجود ملف CLAUDE.md على مستوى المشروع (أو CLAUDE.local.md) في دليل العمل أو مستوى أعلى، فيقرأ Claude Code CLAUDE.md فقط، ولا يُحتسب ~/.claude/CLAUDE.md على مستوى المستخدم؛ أو أن الإصدار أقدم من v2.1.277.
الطريقة الصحيحة: claude --version للتأكد من الإصدار؛ /context لمعرفة الملفات التي تم تحميلها فعليًا، و/memory لسرد مواقع ملفات الذاكرة في كل مكان؛ ثم اتبع الخطوة رقم 3 واستخدم @AGENTS.md لإتمام الربط عبر الاستيراد. ملاحظة إضافية: OpenCode بدءًا من الإصدار v2.3.1 (2026-11-18) أصبح يقرأ CLAUDE.md أيضًا، لكن فقط كخيار احتياطي عندما لا يوجد AGENTS.md في الدليل؛ وإذا قمت بتعيين متغير البيئة OPENCODE_DISABLE_CLAUDE_CODE أو OPENCODE_DISABLE_CLAUDE_CODE_PROMPT فسيتم تخطي جميع CLAUDE.md. لذلك يظل AGENTS.md هو المرجع، وتكوين الملفين معًا هو الخيار الأكثر أمانًا.
❌ التحقق في جلسة قديمة
بعد تعديل الدليل، إذا سألت الذكاء الاصطناعي فورًا في الجلسة الحالية، فسيجيب بالقواعد القديمة.
الطريقة الصحيحة: بعد تعديل الملف، افتح جلسة جديدة ثم اختبر؛ ويمكن أيضًا في Claude Code تشغيل /context مباشرةً للتأكد من تحميل الملف.
حيل متقدمة
- دع الذكاء الاصطناعي يكتب المسودة نيابةً عنك: شغّل
/initفي Claude Code، فيحلل قاعدة الكود ويولّد تلقائيًا ملف CLAUDE.md مبدئيًا يتضمن أوامر البناء وتعليمات الاختبار واصطلاحات المشروع؛ وإذا كان الملف موجودًا فسيقدم اقتراحات للتحسين دون الكتابة فوقه. - افحص صحة القواعد: اعتبارًا من Claude Code v2.1.283 أصبح
/doctor prompt-auditمتاحًا، ليجعل Claude يفحص ملف التعليمات بحثًا عن محتوى قديم أو متناقض أو يشير إلى ملفات غير موجودة. - تجاوز على مستوى الدليل (Codex): ضع
AGENTS.override.mdفي دليل فرعي، فيقرأه Codex بأولوية؛ وإذا كان المستودع يحتوي ملفات مثلTEAM_GUIDE.md، يمكنك تسجيلها كأسماء ملفات احتياطية فيproject_doc_fallback_filenamesضمن~/.codex/config.toml. - علّق مزيدًا من الإرشادات (OpenCode): أضف ملفات أو أنماط glob أو عناوين ويب إلى مصفوفة
instructionsفيopencode.jsonc، لتُحمَّل مع AGENTS.md. - تفضيلات مشروعك الخاصة فقط:Claude Code يدعم
CLAUDE.local.md، حيث تضع تفضيلات مشروعك الشخصية، ولا تنسَ إضافته إلى.gitignore.
خلاصة هذا الدرس
✅ في هذه المرحلة أنت قد:
- كتبت ملف
AGENTS.md: أربعة أقسام من المحتوى، سطر واحد لكل عنصر، موضوع في جذر المشروع ومُدرج في git - ضبطت لـ Claude Code ملف
CLAUDE.mdالذي يشير إليه، فتقرأ الأدوات الثلاث نفس مجموعة القواعد - تحققت باستخدام جلسة جديدة: الذكاء الاصطناعي يعرف كيف يبدأ المشروع وما القواعد التي يلتزم بها دون أن تخبره
مراجعة الملفات الأساسية:
| الملف | الموقع الموصى به | الدور |
|---|---|---|
AGENTS.md | جذر المشروع | مصدر الحقيقة الوحيد، يقرؤه Codex وOpenCode مباشرة |
CLAUDE.md | جذر المشروع | ملف الذاكرة الخاص بـ Claude Code، استخدم @AGENTS.md لاستيراد المحتوى المشترك |
~/.claude/CLAUDE.md | المجلد الرئيسي للمستخدم | تفضيلات شخصية تسري على جميع مشاريعك |
~/.codex/AGENTS.md | Codex المجلد الرئيسي | Codex إرشادات عامة ترثها جميع المستودعات |
~/.config/opencode/AGENTS.md | OpenCode مجلد الإعدادات | OpenCode إرشادات عامة، ضع هنا القواعد المنطبقة في كل مكان |
تذكّرها بجملة واحدة: AGENTS.md هو دليل المشروع الموجّه للذكاء الاصطناعي — اكتبه بتفصيل محدد، ضعه في جذر المشروع، وأبقه المصدر الوحيد.
استعراض الدرس التالي
جعلَ الدليلُ الذكاءَ الاصطناعي يفهم مشروعك، وفي الدرس التالي سيكتسب قدرات أكثر: Vercel × وكلاء البرمجة بالذكاء الاصطناعي: ثلاثية Plugin وSkills وMCP.
ستتعلم:
- ما هي ثلاثية Plugin وSkills وMCP التي أعدّتها Vercel لوكلاء البرمجة بالذكاء الاصطناعي
- كيف تربطها بوكيلك باستخدام الأوامر الرسمية
- بعد الربط، ما الأمور التي يمكن ربطها بين الذكاء الاصطناعي ومشروعك على Vercel
إذا أردت أن توضّح أولاً «ماذا تكتب»، راجع خطّط أولاً ثم نفّذ: حوّل فكرة من جملة واحدة إلى قائمة متطلبات؛ وللعمليات الأساسية في Claude Code انظر Claude Code الاستخدام: وكيل برمجة بالذكاء الاصطناعي في الطرفية.