# ما هو AGENTS.md وكيف تكتب ملفك الخاص في 30 دقيقة > تنسيق AGENTS.md، ودعمه في أدوات الذكاء الاصطناعي، وقالب جاهز للاستخدام، والقواعد والأخطاء. كيفية تنسيق AGENTS.md مع CLAUDE.md وملفات التعليمات الأخرى. Source: https://ailoot.ai/blog/ar/agents-md-guide-template/ Canonical: https://ailoot.ai/blog/ar/agents-md-guide-template/ Language: ar Publisher: Ailoot (https://ailoot.ai/) Translation: guide-034 Revision: sha256-ebe406bf181f3f5429ab39e7349f81c4175c4f20b57fe639f0fc54c94453dc05 مواد عملية حول البرمجة بأسلوب vibe coding والعمل مع الوكلاء: [وثائق Ailoot](https://ailoot.ai/docs/). ## AGENTS.md في فقرة واحدة
أهم ما في القسم AGENTS.md ملف Markdown عادي في جذر مشروعك، يحتوي على تعليمات لوكيل ذكاء اصطناعي: كيفية تثبيت التبعيات، وتشغيل الاختبارات، وأسلوب كتابة الشفرة الذي يجب اتباعه، وما يجب عدم المساس به. التنسيق مفتوح، أنشأته OpenAI في أغسطس 2025، وانضم إلى Linux Foundation في ديسمبر من العام نفسه. يمكن لأدوات برمجة عديدة استخدامه، لكن طريقة اكتشافه تختلف باختلاف العميل والإصدار: يحمّل بعضها AGENTS.md تلقائيًا، بينما يحتاج بعضها الآخر إلى ضبط اسم الملف أو إعداد لقراءته صراحةً. منذ الإصدار 2.1.277 (سبتمبر 2026)، يقرأ Claude Code أيضًا AGENTS.md إذا لم يتضمن المشروع ملف CLAUDE.md. وإذا كان CLAUDE.md موجودًا، فإن Claude Code يقرأ هذا الملف وحده افتراضيًا، ويمكن تضمين AGENTS.md باستخدام السطر `@AGENTS.md` أو عبر رابط رمزي.
نستعرض أدناه التنسيق بالاستناد إلى [agents.md](https://agents.md)، ووثائق [OpenAI Codex](https://github.com/openai/codex)، و[JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html)، و[وثائق Cursor Rules](https://cursor.com/docs/rules)، و[سجل تغييرات GitHub Copilot Coding Agent](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)، و[البيان الصحفي لـ Linux Foundation عن Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation). جميع الأرقام والميزات محدثة حتى 30 مايو 2026، ووُصف دعم AGENTS.md في Claude Code وفقًا لـ[وثائق Anthropic](https://code.claude.com/docs/en/memory#agents-md)، مع تحديث بتاريخ 24 سبتمبر 2026. إذا لم تكن لديك فكرة عن ماهية حديقة الأدوات هذه في السوق أو عن سبب حاجتها إلى ملف مشترك، فاقرأ أولًا دليل [«بماذا تبرمج في 2026: 8 أدوات ذكاء اصطناعي من Claude Code إلى Antigravity»](https://ailoot.ai/blog/ar/ai-coding-tools/). يركز هذا المقال تحديدًا على تنسيق AGENTS.md وكيفية كتابة ملفك الخاص في 30 دقيقة. ## ما هو AGENTS.md ومن أين أتى؟
أهم ما في القسم AGENTS.md تنسيق مفتوح لملفات Markdown تكتب فيه بنفسك تعليمات لوكلاء الذكاء الاصطناعي. أطلقته OpenAI في أغسطس 2025 مع Codex CLI، ودعت فورًا شركاء للمشاركة في تأليفه: Cursor وSourcegraph Amp وGoogle Jules وFactory. الفكرة بسيطة: «لنتفق على ملف واحد بدلًا من إنشاء ملف مملوك لكل أداة». في 9 ديسمبر 2025، انضم AGENTS.md، إلى جانب MCP من Anthropic وgoose من Block، إلى Linux Foundation بوصفه واحدًا من ثلاثة مشاريع مؤسسة لـAgentic AI Foundation الجديدة. وبحلول ديسمبر من العام نفسه، كانت أكثر من 60,000 مستودع على GitHub تحتوي بالفعل على AGENTS.md في جذرها.
كان لكل أداة ذكاء اصطناعي سابقًا ملف قواعد خاص بها: لدى Anthropic ملف `CLAUDE.md`، ولدى Cursor ملف `.cursorrules`، ولدى GitHub ملف `.github/copilot-instructions.md`، ولدى Aider ملف `.aider.conf.yml`، ولدى JetBrains ملف `.junie/guidelines.md`. إذا كان لدى فريقك ثلاثة وكلاء مختلفين، فهذا يعني وجود ثلاثة ملفات متوازية بالمحتوى نفسه، سرعان ما تتباين خلال أسبوع. كانت OpenAI أول من سئم هذا الوضع. ففي أغسطس 2025، أطلقت Codex CLI وأطلقت بالتزامن [agents.md](https://agents.md) بوصفه تنسيقًا مفتوحًا. ويقول الموقع: > «اعتبر AGENTS.md بمثابة README للوكلاء.» > > ([agents.md](https://agents.md)، مترجم عن الإنجليزية) الفكرة الأساسية هي أن AGENTS.md يكمل README. يُكتب README للبشر: «ما المشروع، وكيفية تشغيله محليًا، وكيفية المساهمة فيه». أما AGENTS.md فيُكتب للوكيل: أوامر shell دقيقة، ومعايير إنجاز قابلة للتحقق، وحدود مثل «لا تلمس هذا مطلقًا». ويقول الموقع: > «يكمل AGENTS.md ملف README: فهو يحتوي على سياق إضافي، مفصل أحيانًا، يحتاج إليه الوكيل، مثل خطوات البناء والاختبارات والأعراف التي قد تجعل README مزدحمًا أو لا يحتاج إليها المساهمون البشر ببساطة.» > > ([agents.md](https://agents.md)، مترجم عن الإنجليزية) بحلول سبتمبر 2025، كان GitHub Copilot Coding Agent يدعم التنسيق ([سجل التغييرات، 28.08.2025](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)). وبحلول ديسمبر، انضمت Cursor وJunie وGemini CLI وAider ونحو اثنتي عشرة أداة أخرى. في 9 ديسمبر 2025، أنشأت Linux Foundation [Agentic AI Foundation (AAIF)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation): وكانت مشاريعها المؤسسة الثلاثة AGENTS.md من OpenAI، وMCP من Anthropic، وgoose من Block. وكان الأعضاء المؤسسون AWS وAnthropic وBlock وBloomberg وCloudflare وGoogle وMicrosoft وOpenAI. وبحلول 24 فبراير 2026، كانت المؤسسة تضم بالفعل [146 منظمة](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members)، منها Red Hat وServiceNow وAkamai وLenovo وJPMorgan Chase وHuawei وUiPath وHitachi. ومنذ تلك اللحظة، توقف AGENTS.md عن كونه «شيئًا آخر من OpenAI» وأصبح معيارًا بحكم الواقع. ## أي وكلاء الذكاء الاصطناعي يقرأون AGENTS.md وأيهم لا يفعل ذلك؟
أهم ما في القسم يُستخدم AGENTS.md في أدوات برمجة عديدة، منها العملاء المدرجون أدناه. اقرأ الجدول بوصفه خريطة لمسارات التحميل، لا وعدًا بدعم أصلي متطابق: فقد يختلف الاكتشاف التلقائي والإعداد الصريح وأولوية أسماء الملفات والتعامل مع الملفات المتداخلة. وكان Claude Code من Anthropic استثناءً طويل الأمد: ظلت المسألة \#6235، التي تطالب بالدعم، مفتوحة من أغسطس 2025 إلى أغسطس 2026. منذ الإصدار 2.1.277 (18 سبتمبر 2026)، يقرأ Claude Code ملف AGENTS.md بنفسه إذا لم يتضمن المشروع ملف CLAUDE.md. وإذا كان CLAUDE.md موجودًا، فلا يُقرأ افتراضيًا سوى هذا الملف، ويُضمَّن AGENTS.md باستخدام السطر `@AGENTS.md` داخل CLAUDE.md أو عبر رابط رمزي.
جدول الدعم كما في 30 مايو 2026؛ حُدّث صف Claude Code في 24 سبتمبر 2026: | الأداة | تقرأ AGENTS.md | التاريخ / المصدر | |----|----|----| | OpenAI Codex CLI | نعم (تنسيق أصلي) | أغسطس 2025، [agents.md](https://agents.md) | | GitHub Copilot Coding Agent | نعم | 28.08.2025، [GitHub Changelog](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) | | Cursor | نعم، الجذر + الملفات المتداخلة | [وثائق Cursor Rules](https://cursor.com/docs/rules) | | JetBrains Junie | نعم، المشروع + العام `~/.junie/AGENTS.md` | [وثائق Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html) | | Gemini CLI (Google) | نعم، عبر `.gemini/settings.json` مع `fileName: AGENTS.md` | [agents.md](https://agents.md) | | Jules (Google) | نعم، شارك في تأليف المعيار | أغسطس 2025 | | Sourcegraph Amp | نعم، شارك في تأليف المعيار | أغسطس 2025 | | Aider | نعم، عبر `read: AGENTS.md` في `.aider.conf.yml` | [agents.md](https://agents.md) | | Factory | نعم، شارك في تأليف المعيار | أغسطس 2025 | | OpenCode | نعم | — | | Zed | نعم | [agents.md](https://agents.md) | | Warp | نعم | [agents.md](https://agents.md) | | VS Code | نعم | [agents.md](https://agents.md) | | Windsurf | نعم | — | | Devin (Cognition) | نعم، عبر Spec Kit Skills | أبريل 2026 | | RooCode، Kilo Code، Augment Code | نعم | [agents.md](https://agents.md) | | **Claude Code (Anthropic)** | **نعم، إذا لم يتضمن المشروع ملف CLAUDE.md** | منذ الإصدار 2.1.277 (18.09.2026)، [وثائق Claude Code](https://code.claude.com/docs/en/memory#agents-md) | كانت Anthropic آخر اللاعبين الكبار انضمامًا. في أغسطس 2025، فُتحت المسألة \#6235 في المستودع الرسمي `anthropics/claude-code` للمطالبة بدعم AGENTS.md. ظلت المسألة مفتوحة قرابة عام وأُغلقت في 17 أغسطس 2026؛ ثم صدر الإصدار 2.1.277 الداعم لـAGENTS.md في 18 سبتمبر. منطق Anthropic كالتالي: له الأولوية لملف CLAUDE.md، ويُقرأ AGENTS.md عندما لا يوجد CLAUDE.md في مجلد العمل أو أي مجلد أب. ووفقًا لـ[الوثائق](https://code.claude.com/docs/en/memory#agents-md)، يعمل الأمر كما يلي: | الملفات الموجودة في المشروع | ما يقرأه Claude Code | |----|----| | AGENTS.md فقط | AGENTS.md | | AGENTS.md وCLAUDE.md (أو CLAUDE.local.md) | CLAUDE.md فقط | | CLAUDE.md مع السطر `@AGENTS.md` | CLAUDE.md الذي يضم AGENTS.md | المهم أن ملف `CLAUDE.local.md` الشخصي يُحتسب أيضًا، وبوجوده يتوقف Claude Code عن قراءة AGENTS.md. يمكنك تغيير هذا السلوك في `/config`، ضمن Project instructions، مثلًا لجعل Claude Code يقرأ الملفين معًا. في الإصدارات الأقدم من 2.1.277، لن يُلتقط AGENTS.md تلقائيًا؛ ويظل السطر `@AGENTS.md` في CLAUDE.md حلًا بديلًا. ## ما الفرق بين AGENTS.md وCLAUDE.md و`.cursorrules`؟
أهم ما في القسم من الناحية التقنية، لا شيء مميزًا فيها: التنسيقات الأربعة كلها (AGENTS.md وCLAUDE.md و`.cursorrules` و`.github/copilot-instructions.md`) ملفات Markdown عادية تتضمن تعليمات لوكيل. والفرق هو من يقرأها وأين توجد. يمكن أن يجمع AGENTS.md التعليمات المشتركة لعدة عملاء، مع إبقاء طريقة اكتشاف الملف أو إعداده الخاصة بكل عميل منفصلة. أما CLAUDE.md فهو خاص بـClaude Code، لكنه يتيح ميزات متقدمة: قواعد مرتبطة بمسارات محددة، و`CLAUDE.local.md` للتخصيصات الشخصية، و`@import` لتضمين ملفات أخرى، وتسلسل هرمي للمشروع والمستخدم والإعدادات المحلية. أصبح `.cursorrules` قديمًا في Cursor؛ ويستخدم النظام الجديد `.cursor/rules/*.mdc` مع إرفاق تلقائي بحسب نوع الملف. أما `.github/copilot-instructions.md` فلا يلزم إلا لـCopilot على الويب.
مقارنة التنسيقات الأربعة كما في 30 مايو 2026: | التنسيق | من يقرأه | مكانه | نقطة القوة | نقطة الضعف | |----|----|----|----|----| | **AGENTS.md** | عدة عملاء، بحسب الإصدار وطريقة التحميل | الجذر أو المسار المضبوط؛ التداخل بحسب العميل | تعليمات مشتركة مع ضبط التحميل لكل عميل | يتطلب التحقق من قواعد الاكتشاف والأولوية في كل عميل | | **CLAUDE.md** | Claude Code فقط | الجذر + `~/.claude/CLAUDE.md` + `CLAUDE.local.md` | تسلسل هرمي، وقواعد مرتبطة بمسارات، و`@import`، وskills، وhooks | خاص بـClaude. لا يعمل في Cursor / Codex / Copilot | | **`.cursor/rules/*.mdc`** | Cursor فقط | `.cursor/rules/.mdc` | إرفاق تلقائي بحسب نوع الملف (TS وPython ومسارات محددة) | خاص بـCursor، وبصياغة `.mdc` غير القياسية | | **`.github/copilot-instructions.md`** | GitHub Copilot (الويب + التقليدي) | `.github/` | يعمل مباشرةً في المتصفح على GitHub.com | خاص بـCopilot ويكرر محتوى AGENTS.md | الفكرة الأساسية هي أن AGENTS.md يحل مشكلة «ملف واحد لجميع الوكلاء»، لكنه لا يحل مشكلة «الإعدادات الشخصية التي لا أضمّنها في commit». لدى Claude Code ملف `CLAUDE.local.md` لهذا الغرض، ولدى Cursor ملفات `.mdc` محلية ضمن إعدادات المستخدم. لا يوفر AGENTS.md وحده ذلك؛ لذا تحتاج إما إلى دمجه مع ملفات أخرى أو الاتفاق كفريق على كتابة القواعد الشخصية في أقسام مستثناة من git. ومن التفاصيل المهمة الأخرى المستودعات أحادية البنية. يطبق Codex وCursor قاعدة «الأقرب يفوز» بالنسبة إلى AGENTS.md: > «في المستودع أحادي البنية، ضع ملف AGENTS.md منفصلًا داخل كل حزمة. تقرأ الوكلاء تلقائيًا أقرب ملف في شجرة المجلدات، والملف الأقرب هو المعتمد.» > > ([agents.md](https://agents.md)، مترجم عن الإنجليزية) يشير موقع [agents.md](https://agents.md) إلى أن المستودع أحادي البنية الرئيسي لدى OpenAI يحتوي على 88 ملف AGENTS.md لحزم فرعية مختلفة. إذا كنت تعمل في مستودع أحادي البنية، وزّع القواعد على مستويات: القواعد العامة في الجذر، والقواعد الخاصة في المجلدات الفرعية. ## ماذا ينبغي أن يتضمن ملف AGENTS.md جيد؟
أهم ما في القسم يتكون مخطط AGENTS.md الجيد من 8 أقسام موجودة في معظم الملفات الشائعة: نظرة عامة على المشروع، وأوامر الإعداد، وأسلوب الشفرة، ونصائح بيئة التطوير، وتعليمات الاختبار، وإرشادات PR، واعتبارات الأمان، والحدود (ما يجب عدم فعله). كل ما عدا ذلك اختياري. القاعدة الأساسية: يجب أن يكون كل بند أمرًا دقيقًا أو مثالًا ملموسًا، لا فكرة عامة مثل «اكتب شفرة نظيفة».
يعرض موقع [agents.md](https://agents.md) تنسيقًا مرنًا: «أي Markdown». لكن 80% من الملفات الجيدة المتداولة تتضمن الأقسام الثمانية نفسها. والقاعدة الأساسية أن يكون كل بند أمرًا دقيقًا أو مثالًا ملموسًا. أما الفكرة المجردة مثل «اكتب شفرة نظيفة» فسيتجاهلها الوكيل. 1. **نظرة عامة على المشروع** — سطران أو ثلاثة. ما المشروع، ولمن هو، وما هدفه الأساسي. دون تسويق. مثال: «بوت Telegram للتهيئة الأولية في ورشة مدفوعة. حزمة التقنية: Next.js 14 وPrisma وPostgreSQL. يعمل عند إضافة سجل جديد إلى `purchases`.» 2. **أوامر الإعداد** — أوامر shell دقيقة للتشغيل محليًا. `npm install` و`npm run dev` و`npm run build`. لا تكتب «هذه طريقتنا المعتادة». 3. **أسلوب الشفرة / الأعراف** — قواعد محددة مع مثال، لا عبارة «اكتب بأسلوب نظيف». مثلًا: «استخدم TypeScript strict، وعلامات اقتباس مفردة، ولا تستخدم التصدير الافتراضي، وسمِّ المكونات بـPascalCase، واجعل أسماء hooks تبدأ بـ`use`.» 4. **نصائح بيئة التطوير** — أين توجد الأشياء المهمة. ما المتغيرات المطلوبة في `.env`، وأين تُخزن الأسرار، وما المنافذ المستخدمة، وكيفية العمل مع قاعدة البيانات المحلية. 5. **تعليمات الاختبار** — كيفية تشغيل اختبار محدد وما الذي يُعد «نجاحًا». مثلًا: `npm test -- --testPathPattern=user-auth`؛ والمتوقع نجاح 100% من الاختبارات. 6. **إرشادات PR / commit** — تنسيق رسالة commit، وقائمة التحقق قبل PR (الاختبارات وlinter والتوثيق)، ومن يوافق. 7. **اعتبارات الأمان** — ما الذي يجب ألا يحدث مطلقًا. «لا تضمّن `.env` في commit. يجب أن تكون الأسرار في Vault فقط. لا تعرض البيانات الشخصية للمستخدمين في السجلات.» 8. **الحدود / لا تفعل هذا مطلقًا** — محظورات مع بديل. «لا تستخدم `git push --force` على main. إذا احتجت إلى التراجع، فاستخدم `git revert` أو `git reset` على feature branch.» طبّق مبدأ «الأمر بدلًا من الفكرة» في كل قسم. سيتجاهل الوكيل «توخَّ الحذر عند إجراء migrations». لكنه سيتبع «قبل `alembic upgrade head`، نفّذ `alembic check`. إذا أظهر خطأً، فلا تطبّق migration؛ واسألني». ## قالب AGENTS.md جاهز للاستخدام (انسخه وعدّله)
أهم ما في القسم فيما يلي قالب أولي لملف AGENTS.md يناسب مشروع ويب نموذجيًا. انسخه إلى جذر المستودع، واستبدل `` و`` والأوامر الدقيقة، واحذف الأقسام التي لا تحتاج إليها. يستغرق تعديله 20–30 دقيقة، وقد يستغرق أكثر إذا كانت هذه تجربتك الأولى.
````markdown # AGENTS.md ## Project overview - . Stack: . Main entities: . Details for people are in README.md. ## Setup commands ```bash # first install npm install cp .env.example .env # then fill in manually; see list below # run npm run dev # dev server on :3000 npm run build # production build npm run start # run production build ``` ## Dev environment - Node 20+ (via nvm: `nvm use 20`) - PostgreSQL 16 locally on :5432 (`docker-compose up postgres`) - Redis is optional, needed only for queues (`docker-compose up redis`) - `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET` - Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env` ## Code style - TypeScript strict mode - Single quotes, no semicolons (unless ESLint requires them) - Imports: external first, then internal via `@/`, then relative - Components in PascalCase; hooks start with `use` - No `any` without an explicit comment explaining “why it can’t be typed” Example of a good module: ```ts import { z } from 'zod' const UserSchema = z.object({ email: z.string().email(), name: z.string().min(2), }) export function parseUser(raw: unknown) { return UserSchema.parse(raw) } ``` ## Testing ```bash npm test # all tests npm test -- --testPathPattern=auth # auth only npm test -- --watch # watch mode ``` All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do. ## Pull request guidelines - Commit format: `(): ` (`feat(auth): add magic-link`) - Before PR: `npm run build && npm test && npm run lint` - PR description = what changes, why, and how to test - Don’t approve your own PR—always wait for human review ## Security - Secrets only in `.env` and Vault, never in code - Don’t log personal data (email, phone, name) - When working with the production DB, use read-only queries only unless explicitly authorized - Don’t hardcode external service API keys (Stripe, OpenAI) in tests ## Never do this - Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR - Don’t run DB migrations without `alembic check` (or the equivalent in your ORM) - Don’t use `npm install -g` or `sudo` for project dependencies - Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM) ```` يبلغ طول القالب 80–120 سطرًا في المتوسط. إذا تجاوز الملف 150 سطرًا، فهذه إشارة إلى الحاجة لإعادة تنظيمه: انقل بعض المحتوى إلى `docs/`، أو أضف رابطًا، أو اختصره في سطر واحد. عمليًا، تحقق الملفات التي تتراوح بين 100 و150 سطرًا أفضل أداء؛ وبعد هذا الحد تبدأ مكاسب الجودة في التراجع. ## ما القواعد الخمس التي تجعل AGENTS.md مفيدًا فعلًا؟
أهم ما في القسم يتبع AGENTS.md الجيد خمس قواعد: أوامر بدل الأفكار، ومحظورات مصحوبة ببدائل، ومصدر حقيقة واحد، ومعايير إنجاز قابلة للتحقق، وملف أقصر من 150 سطرًا.
1. **أوامر بدل الأفكار.** لا يفهم الوكيل عبارة «توخَّ الحذر عند إجراء migrations». لكنه سيتبع `alembic check` قبل `alembic upgrade head`. تعمل الوكلاء بالأوامر والشروط لا بالمزاج. صغ جميع القواعد الأساسية على نمط «نفّذ X، وإلا فنفّذ Y». 2. **محظورات مصحوبة ببديل.** يتجاهل الوكيل بهدوء عبارة «لا تستخدم force push» بعد مطالبتين أو ثلاث. أما صيغة «لا تفعل X؛ افعل Y بدلًا منه» فتنجح. مثال: «لا تستخدم `git push --force` على main؛ إذا احتجت إلى التراجع، فاستخدم `git revert` أو افتح PR جديدًا». 3. **مصدر حقيقة واحد فقط.** ملف AGENTS.md في الجذر هو مصدر الحقيقة للمشروع بأكمله. إذا كان لديك مستودع أحادي البنية، فاستخدم ملفات AGENTS.md متداخلة في المجلدات الفرعية وفق قاعدة «الأقرب يفوز». لا تنشئ ملفات متوازية بتعليمات متضاربة. 4. **معايير إنجاز قابلة للتحقق.** عبارة «يجب أن تنجح الاختبارات» لا تفيد. المعيار الدقيق هو أن يعيد `npm test` رمز خروج 0 وألا يطبع `FAIL` إلى stdout. وعبارة «ينبغي أن تكون الشفرة نظيفة» لا تفيد أيضًا. المعيار الدقيق هو أن يجتاز `npm run lint` من دون تحذيرات. لا يفهم الوكيل معنى «تم» إلا إذا وصفت الشرط صراحةً. 5. **ملف أقصر من 150 سطرًا.** بعد 150 سطرًا تبدأ المقاييس في التراجع: يقضي الوكيل وقتًا أطول في قراءة السياق ويفوّت قواعد مهمة. إذا لم يتسع الملف، فانقل التفاصيل إلى `docs/architecture.md` واربطه من AGENTS.md، مع إبقاء الأوامر والحدود فقط في الملف. ## ما الأخطاء العشرة التي تحول AGENTS.md إلى فوضى؟
أهم ما في القسم السبب الرئيسي لفشل AGENTS.md هو الصياغة المبهمة. في دراسة شملت أكثر من 2,500 مستودع، أوضح GitHub Blog أن معظم الملفات تفشل لأنها مكتوبة بعمومية مفرطة. فعلى سبيل المثال، لا تمنح عبارة «أنت مساعد برمجة مفيد» الوكيل أي معلومة مفيدة على الإطلاق. فيما يلي 10 أخطاء شائعة وكيف تظهر في الملفات السيئة: تكرار README، والنثر غير المنظم، وأكثر من 30 محظورًا بلا بدائل، وتضارب الأولويات، والأسرار المكتوبة مباشرةً في الشفرة، والتوثيق القديم، والإفراط المعماري في المهام البسيطة.
1. **قواعد مبهمة بلا أوامر.** سيتجاهل الوكيل عبارة «توخَّ الحذر عند إجراء migrations»، فهي جملة فارغة بالنسبة إليه. لا تنجح إلا أوامر محددة مرتبطة بشرط: «شغّل `alembic check` قبل `alembic upgrade head`. إذا ظهر خطأ، فلا تطبّق migration؛ واسألني». 2. **«شفرة نظيفة».** عبارة لا فائدة منها. استبدلها بنمط محدد: «استخدم مكونات وظيفية مع hooks. مثال: `function LoginForm() { const [email, setEmail] = useState(''); ... }`» 3. **نثر غير منظم.** إذا كان AGENTS.md يتكون من 300 سطر من النثر بلا عناوين، فسيستهلك الوكيل 80K من رموز السياق في مقاطع غير مهمة ويفوّت ما يهم. استخدم عناوين H2/H3 وأقسامًا قصيرة وقوائم نقطية. 4. **ملف يزيد على 150 سطرًا.** تتدهور مقاييس الجودة بعد هذا الحد. قسّمه إلى ملف رئيسي وروابط للتفاصيل في `docs/`. 5. **أكثر من 30 محظورًا بلا بدائل.** إذا احتوى الملف على قائمة طويلة من «لا تفعل X، ولا تفعل Y» من دون شرح «افعل Z بدلًا من ذلك»، فسيترنح الوكيل بلا اتجاه. 6. **تكرار README.md.** إذا كنت قد كتبت بالفعل «كيفية التثبيت والتشغيل» في README، فلا تنسخ ذلك إلى AGENTS.md. أشر إلى README بسطر واحد، واشرح في AGENTS.md ما يحتاج إليه الوكيل ولا يحتاج إليه المساهمون البشر. 7. **تضمين الأسرار مباشرةً.** قد يكون AGENTS.md عامًا لأنه موجود في git. لا تضع فيه مفاتيح API أو رموز وصول أو كلمات مرور حقيقية. أدرج مراجع إلى مخازن الأسرار فقط: «راجع Vault: `secret/staging/db`». 8. **أولويات متضاربة بلا ترتيب.** تترك عبارتا «تحرك بسرعة» و«حافظ على تغطية اختبارات بنسبة 90%» الوكيل في حيرة بشأن ما يختار. رتّبها صراحةً: «تغطية الاختبارات ≥80% أولًا، ثم السرعة. إذا تعارضتا، تكون الأولوية للاختبارات». 9. **توثيق قديم.** وصف معماري يتحدث عن REST + polling بينما الواقع أصبح WebSockets. يتبع الوكيل الوصف القديم ويضر بالمعمارية. القاعدة: حدّث AGENTS.md في PR نفسه الذي يتضمن الشفرة كلما تغيرت المعمارية. 10. **إفراط معماري لمهمة بسيطة.** إذا طُلب تغيير سطرين في ملف إعدادات، فلا ينبغي أن يضطر الوكيل إلى قراءة طوبولوجيا 14 خدمة مصغرة كاملة. انقل المعمارية «المتعمقة» إلى `docs/architecture.md`، واكتفِ في AGENTS.md بعبارة «إذا كانت المهمة معمارية، فاقرأ `docs/architecture.md`». تذكر [دراسة GitHub Blog لأكثر من 2,500 مستودع AGENTS.md](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) الاستنتاج الرئيسي: > «تفشل معظم ملفات الوكلاء لأنها عامة أكثر مما ينبغي. عبارة “أنت مساعد برمجة مفيد” لا تنجح.» > > ([GitHub Blog](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)، مترجم عن الإنجليزية) ## كيف تحتفظ بملفي AGENTS.md وCLAUDE.md في مستودع واحد؟
أهم ما في القسم ثلاثة سيناريوهات: (1) Claude Code وحده — احتفظ بـCLAUDE.md؛ ولا حاجة إلى AGENTS.md. (2) أدوات غير Claude فقط (Codex وCursor وCopilot وJunie) — استخدم AGENTS.md بوصفه مصدر الحقيقة الوحيد. (3) فريق مختلط يستخدم Claude Code وأدوات أخرى — اجعل AGENTS.md الملف الأساسي. إذا لم تكن لديك قواعد منفصلة لـClaude، يمكنك الاستغناء عن CLAUDE.md: فمنذ الإصدار 2.1.277، يقرأ Claude Code AGENTS.md بنفسه. وإذا كانت لديك قواعد منفصلة، فاربط AGENTS.md بـCLAUDE.md عبر رابط رمزي أو استيراد `@AGENTS.md`. في macOS وLinux، أعد التسمية فقط إذا لم يوجد AGENTS.md. إذا وجد الملفان، فاحفظ قواعدهما وادمجها أولًا، ثم استخدم CLAUDE.md قصيرًا يستورد `@AGENTS.md`؛ ولا تستبدل AGENTS.md القائم أبدًا. أما في Windows، فتتطلب الروابط الرمزية تفعيل Developer Mode، لذا يكون الاستيراد أسهل.
السؤال العملي الأساسي هو كيفية استخدام الملفين معًا من دون تكرار المحتوى. هناك ثلاثة سيناريوهات: **السيناريو 1: Claude Code فقط.** احتفظ بـCLAUDE.md واستخدم جميع ميزات Claude Code: `~/.claude/CLAUDE.md` للتعليمات على مستوى المستخدم، و`CLAUDE.md` للمشروع، و`CLAUDE.local.md` للتخصيصات الشخصية، و`@import` لتضمين ملفات أخرى، و`.claude/skills/` للمهارات المتخصصة. لا حاجة إلى AGENTS.md. **السيناريو 2: عدة عملاء للبرمجة.** احتفظ بالقواعد المشتركة في AGENTS.md، ثم اربط كل عميل وتحقق منه على حدة. يدعم Gemini CLI ضبط اسم ملف السياق، ويمكن لـAider تحميل ملف عبر إعداد القراءة. هذان مساران صريحان للتحميل، وليسا اكتشافًا تلقائيًا متطابقًا. | مسار التحميل | ما يجب التحقق منه | |----|----| | اكتشاف AGENTS.md تلقائيًا | قواعد الجذر والملفات المتداخلة والأولوية الموثقة للعميل المثبّت | | إعداد صريح، كما في Gemini CLI أو Aider | اسم الملف أو مسار القراءة المضبوط وعرض السياق المحمّل في العميل | | تحميل Claude Code المشروط أو الاستيراد | الإصدار المثبّت والملفات ذات الأولوية؛ راجع [دليل AGENTS.md الخاص بـClaude Code](https://ailoot.ai/blog/ar/claude-code-agents-md-support/) | ابدأ جلسة جديدة في مستودع اختبار غير حساس، وأضف تعليمة مميزة غير ضارة مثل «ضمّن العلامة instructions-loaded في رد الاختبار». افحص عرض الملفات المحمّلة أو السجلات الموثقة للعميل إلى جانب رده. كرر ذلك لكل عميل وإصدار تستخدمه فعليًا. ادعاء النموذج أنه قرأ الملف ليس دليلًا مستقلًا على التحميل؛ ولا تعمم نجاح اختبار واحد على بقية الأدوات. **السيناريو 3: فريق مختلط (Claude Code وأدوات أخرى).** هذا الإعداد هو الأكثر شيوعًا في 2026. والحل هو جعل AGENTS.md الملف الأساسي. إذا لم تكن لديك قواعد خاصة بـClaude Code، فلا تنشئ CLAUDE.md أصلًا: فمنذ الإصدار 2.1.277، يقرأ Claude Code AGENTS.md عندما لا يوجد CLAUDE.md في المشروع. وإذا كانت لديك مثل هذه القواعد، فاجعل CLAUDE.md إما رابطًا رمزيًا أو ملفًا قصيرًا يستورد AGENTS.md باستخدام `@AGENTS.md`. قبل تغيير أي من الملفين، افحصهما وانسخهما احتياطيًا. إذا وُجدا معًا، فادمج التعليمات المشتركة غير المتعارضة في AGENTS.md، وأبق تعليمات Claude الخاصة في CLAUDE.md مع استيراد `@AGENTS.md`. احتفظ بالروابط الرمزية القائمة بدل استبدالها. لملف CLAUDE.md عادي **فقط عند غياب AGENTS.md**، يرفض حارس macOS/Linux التالي استبدال هدف قائم أو رابط رمزي قائم: ```bash if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2 elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md else printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2 fi ``` بعد نجاح إعادة التسمية، يصبح CLAUDE.md رابطًا رمزيًا إلى AGENTS.md. وترى جميع الوكلاء الذين يقرأون AGENTS.md المحتوى نفسه. أما Claude Code، الذي يقرأ CLAUDE.md، فيرى المحتوى نفسه عبر الرابط الرمزي. في Windows، يتطلب إنشاء رابط رمزي تفعيل Developer Mode (أو صلاحيات المسؤول)، وقد لا يكون ذلك مناسبًا للفريق كله. والبديل هو إنشاء CLAUDE.md قصير يستورد AGENTS.md: ```markdown # CLAUDE.md @AGENTS.md ## Claude Code specific - Use .claude/skills/ for specialized prompts - When working with Skills, consult .claude/skills/INDEX.md - Use Plan Mode before major changes (Shift+Tab) ``` في Claude Code، تستورد هذه الصياغة AGENTS.md بسطر واحد وتضيف أسفله تعليمات خاصة بـClaude Code. إذا أردت لاحقًا إزالة AGENTS.md، فما عليك إلا حذف سطر الاستيراد. ولا يؤدي هذا السطر إلى قراءة الملف مرتين: فوفقًا لوثائق Claude Code، لا يحمّل ملف AGENTS.md نفسه مرتين حتى لو كان يستطيع قراءته تلقائيًا. التنظيم المعتمد لفريق متعدد الأدوات في 2026: ``` repo-root/ ├── AGENTS.md # مصدر الحقيقة، ≤150 سطرًا ├── CLAUDE.md # للقواعد الخاصة بـClaude فقط: رابط رمزي إلى AGENTS.md أو @AGENTS.md مع إضافات ├── .cursor/rules/ # استثناءات موجهة لـCursor فقط ├── .github/copilot-instructions.md # «راجع AGENTS.md»، إن استُخدم └── docs/architecture.md # معمارية مفصلة يشير إليها AGENTS.md ``` يمكنك معرفة المزيد عن CLAUDE.md في دليل [«كيفية إعداد CLAUDE.md بطريقة صحيحة»](https://ailoot.ai/blog/ar/claude-md-template/). ولمعرفة سبب حاجة الوكيل إلى ملف تعليمات كبير، اقرأ [«ما هي هندسة السياق»](https://ailoot.ai/blog/ar/context-engineering/). ## ما الذي تغير في 2026: لماذا وضعت AAIF AGENTS.md تحت مظلة Linux Foundation؟
أهم ما في القسم في 9 ديسمبر 2025، أنشأت Linux Foundation مؤسسة Agentic AI Foundation (AAIF) بثلاثة مشاريع مؤسسة: AGENTS.md من OpenAI، وMCP من Anthropic، وgoose من Block. وكان الأعضاء المؤسسون AWS وAnthropic وBlock وBloomberg وCloudflare وGoogle وMicrosoft وOpenAI. وبحلول 24 فبراير 2026، ضمت المؤسسة 146 منظمة. وهذا يعني أن AGENTS.md لم يعد «شيئًا من OpenAI»، بل أصبح معيارًا في المجال إلى جانب MCP. ومن الناحية العملية، إذا كنت تبني منتجًا ينبغي أن يعمل مع وكلاء من مورّدين مختلفين، فإن وضع AGENTS.md في الجذر من أساسيات العمل. وبدونه ستصون ثلاثة أو أربعة ملفات متوازية ستتباعد خلال شهر.
لم تكن القصة السياسية الأهم في برمجة الذكاء الاصطناعي خلال مايو 2026 إصدار نموذج جديد، بل توحيد التنسيقات. كان لكل مورّد في السابق ملف قواعد خاص به، وهو أمر مريح للمورّدين لكنه مرهق للفرق التي تستخدم أدوات متعددة. في [بيان صحفي بتاريخ 9 ديسمبر 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)، أعلنت Linux Foundation عن Agentic AI Foundation بوصفها مظلة لثلاثة تنسيقات: - **AGENTS.md** من OpenAI — تنسيق ملفات تعليمات للوكلاء - **Model Context Protocol (MCP)** من Anthropic — بروتوكول لربط الأدوات الخارجية بالوكلاء - **goose** من Block — إطار عمل مفتوح المصدر للوكلاء من البيان الصحفي لـLinux Foundation: > «إن جمع هذه المشاريع تحت مظلة AAIF يضمن تطورها بالشفافية والاستقرار اللذين لا توفرهما إلا الحوكمة المفتوحة.» > > ([البيان الصحفي لـLinux Foundation، 9 ديسمبر 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)، مترجم عن الإنجليزية) بحلول 24 فبراير 2026، [كانت 146 منظمة عضوًا في AAIF](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members) (97 عضوًا جديدًا خلال شهرين). وشمل الأعضاء الجدد من الفئة الذهبية Red Hat وServiceNow وAkamai وLenovo وJPMorgan Chase وHuawei وHitachi وUiPath وAmerican Express وAutodesk. Anthropic عضو من الفئة البلاتينية وتدعم MCP. وOpenAI عضو من الفئة البلاتينية وتدعم AGENTS.md. أما Block فهي عضو من الفئة البلاتينية مع goose. يغير هذا مكانة AGENTS.md: من «تنسيق OpenAI» إلى معيار في المجال. في ربيع 2026، ظل Claude Code على الهامش، لكنه تعلم في سبتمبر، مع الإصدار 2.1.277، قراءة AGENTS.md بنفسه. ولم يختفِ CLAUDE.md، وما زال له الأولوية افتراضيًا إذا كان موجودًا في المشروع. نقطة البداية العملية هي قواعد المشروع المشتركة في AGENTS.md، مع الاستيراد أو الملف الوسيط أو إعداد القراءة الصريح الذي يحتاج إليه كل عميل تستخدمه. في Claude Code افحص الإصدار المثبّت وأولوية ملفات التعليمات قبل تحديد الحاجة إلى استيراد داخل CLAUDE.md أو رابط رمزي. تحقق من التحميل في كل عميل؛ لا يثبت هذا الدليل نسبة تغطية عامة. ## ما الخطوة التالية؟ AGENTS.md هو المكوّن الأول في «كيفية الاتفاق مع وكيل كي يعمل على نحو متوقع». يليه المكوّن الثاني، وهو مجلد معرفة المشروع الذي يحتوي على سياق العمل والجمهور والمنتجات والأسعار. أما المكوّن الثالث فهو [هندسة السياق](https://ailoot.ai/blog/ar/context-engineering/)، التي تجمع كل شيء: ما الملفات التي يراها الوكيل في كل خطوة، وكيفية حفظ الحالة بين الجلسات، وكيفية التبديل بين النماذج المختلفة. مواد عملية: [وثائق Ailoot](https://ailoot.ai/docs/).
### المصادر - [agents.md — الموقع الرسمي للمعيار](https://agents.md) - [Linux Foundation: تأسيس Agentic AI Foundation (9 ديسمبر 2025)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) - [AAIF ترحب بانضمام 97 عضوًا جديدًا (24 فبراير 2026)](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members) - [OpenAI تشارك في تأسيس Agentic AI Foundation](https://openai.com/index/agentic-ai-foundation/) - [GitHub Changelog: وكيل البرمجة Copilot يدعم AGENTS.md (28 أغسطس 2025)](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) - [GitHub Blog: دروس مستفادة من أكثر من 2500 مستودع AGENTS.md](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) - [وثائق Claude Code: كيفية قراءة Claude لملف AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) - [وثائق إرشادات JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html) - [وثائق Cursor Rules](https://cursor.com/docs/rules)
مواد وأدوات أخرى: [Ailoot](https://ailoot.ai/). ## أسئلة شائعة ### ماذا لو وُجد AGENTS.md وCLAUDE.md معًا بالفعل؟ انسخ الملفين احتياطيًا وقارنهما قبل التعديل. ادمج القواعد المشتركة في AGENTS.md، وأبق قواعد Claude الخاصة في CLAUDE.md، وأضف استيراد @AGENTS.md؛ ولا تعِد تسمية أحدهما فوق الآخر. ### كيف أجعل التعليمات قابلة للتحقق؟ اكتب أوامر الإعداد والاختبار الدقيقة، وحدد النتيجة المتوقعة وما يجب على الوكيل ألا يغيره. انقل تفاصيل البنية إلى وثائق مرتبطة لتظل التعليمات الأساسية سهلة القراءة. ## Ailoot · الشركة ومحفظة مشاريعها تستند Ailoot إلى خبرة تشغيلية متراكمة وقاعدة عملاء واسعة وخدمة مستقرة ومراقبة مستمرة لمؤشرات الأداء KPI. الشركة ومحفظة مشاريعها: ملايين العملاء؛ مبيعات بالمليارات شهريًا. توظف Ailoot هذه الخبرة التشغيلية لإتاحة الوصول عبر API إلى قدرات الذكاء الاصطناعي في منتجات العملاء ووكلائهم وتطبيقاتهم وعمليات الأتمتة.