دليل ملف AGENTS.md: كيف توجه وكلاء البرمجة بذكاء؟

ما هو ملف AGENTS.md

ملف AGENTS.md هو ملف Markdown بسيط يقع في المجلد الجذري للمستودع، ويُستخدم لتوجيه وكيل البرمجة (coding agent) حول كيفية العمل على هذا المشروع. يصفه الموقع الرسمي بأنّه "ملف README مخصص للوكلاء: مكان محدد ومتوقع لتوفير السياق والتعليمات التي تساعد وكلاء البرمجة المعتمدين على الذكاء الاصطناعي في العمل على مشروعك". يخضع هذا التنسيق لإشراف مؤسسة Agentic AI Foundation التابعة لمؤسسة Linux Foundation، ويقرأه أكثر من عشرين وكيلاً، بما في ذلك Codex وCursor وJules وDevin وGitHub Copilot (حتى يوليو 2026).

سبب وجود هذه الاتفاقية عملي بحت. عندما ينضم شخص جديد إلى فريقك، فإنه يقرأ ملف README، ويخمن أمر البناء، ثم يسأل شخصاً ما عندما يكون تخمينه خاطئاً. أما الوكيل فلا يمكنه السؤال. إنه يخمن، ويشغل npm test على مشروع يستخدم pnpm test، ثم يقرأ رسالة الفشل، ويحاول شيئاً آخر. أنت تدفع مقابل كل رمز (token) من هذه الرموز. كتابة الأمر الصحيح مرة واحدة تلغي هذا النوع بالكامل من الإخفاقات.

لا توجد حقول مطلوبة. الموقع صريح بشأن ذلك: "AGENTS.md هو مجرد ملف Markdown قياسي. استخدم أي عناوين تفضلها؛ يقوم الوكيل ببساطة بتحليل النص الذي توفره". هذه هي المواصفات بالكامل. القيمة لا تكمن في التنسيق، بل في وجود الملف في مسار تبحث فيه جميع الأدوات بالفعل.

موقع الملف والأولوية

ضع الملف الأول في المجلد الجذري للمستودع. في المستودعات المتعددة (monorepo)، يمكنك إضافة المزيد داخل كل مشروع فرعي، والقاعدة بسيطة: "تقرأ الوكلاء تلقائياً أقرب ملف في شجرة المجلدات، لذا فإن الملف الأقرب هو الذي يمتلك الأولوية". يُحل التعارض بين ملفين لصالح الملف الذي يجري تحريره، وأي شيء تكتبه في المحادثة يتجاوز كليهما.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

يستحق التداخل (nesting) الاستخدام، لأنه الطريقة الوحيدة لقول شيء صحيح في مجلد ما وخاطئ في المجلد التالي. قاعدة مثل "كل نقطة نهاية (endpoint) تتحقق من مدخلاتها" تنتمي إلى جانب نقاط النهاية. في ملف جذري، سيتم تحميلها مع كل مهمة غير ذات صلة ولن تحقق أي فائدة. إذا كان ملفك الجذري قد نما بالفعل ليحتوي على قسم لكل خدمة، فإن تقسيمه إلى بنية متداخلة هو الحل، وهو يغطي القواعد التي يجب نقلها للأسفل وتلك التي يجب أن تبقى في الأعلى.

ما الذي يجب تضمينه في ملف AGENTS.md

دوّن المعلومات التي لا يمكن للوكيل استنتاجها من قراءة الكود. ابدأ بأوامر البناء والاختبار والتدقيق (lint) الدقيقة، بالصيغة التي ستنسخها في الطرفية (terminal). أضف الأمر الخاص بتشغيل اختبار واحد، لأن الوكيل الذي يعرف فقط كيفية تشغيل مجموعة الاختبارات الكاملة سيقوم بتشغيلها أربعين مرة. اذكر الاصطلاحات التي تختلف عن الإعدادات الافتراضية للأداة، حيث أن الوكيل يعرف الإعدادات الافتراضية مسبقاً ولا يحتاج إلا لمعرفة انحرافك عنها. أضف شكل رسالة الالتزام (commit message) وقواعد طلبات السحب (pull request) إذا كانت لديك.

كن محدداً بما يكفي للتحقق من الادعاء. "استخدم مسافة بادئة بمقدار مسافتين" هي تعليمات قابلة للتنفيذ لأنها إما حدثت أو لم تحدث. أما "نسّق الكود بشكل صحيح" فهي ليست كذلك، لأنه لا يمكن التحقق من أي شيء فيها. وينطبق الشيء نفسه على المواقع: "معالجات API توجد في src/api/handlers/" أفضل من "حافظ على تنظيم الملفات".

القواعد السلبية تستحق مكانها أيضاً. "لا تقم أبداً بتعديل الملفات الموجودة تحت dist/، فهي مُنشأة بواسطة npm run build" تمنع خطأً محدداً، ولأنها تسمي السبب، يمكن للوكيل استنتاج الحالة المماثلة التي لم تدونها. قاعدة حول النطاق (scope) تنتمي إلى هنا أيضاً، لأن الوكيل إذا تُرك لتقديره الخاص سيقوم بإعادة كتابة أكثر مما طلبت: مهارة واحدة منسوخة على نطاق واسع لا تفعل شيئاً سوى الإصرار على أصغر تغيير يعمل.

ما لا يجب تضمينه مطلقاً

لا تضع أي سر في أحد هذه الملفات. فهذا الملف يُرفع إلى git، ويُحمّل في السياق عند بدء كل جلسة، ويُرسل إلى مزود النموذج مع كل طلب. وجود مفتاح API داخل ملف AGENTS.md يعني أن مفتاح الـ API أصبح جزءاً من سجل المستودع الخاص بك ومن سجلات طرف ثالث. أشر إلى مكان السر بدلاً من لصقه: "كلمة مرور قاعدة البيانات موجودة في .env، وهو ملف مستثنى من git؛ اطلب الإذن قبل قراءته". يتم تناول الانضباط الأوسع في إبقاء بيانات الاعتماد بعيداً عن متناول الوكيل.

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

CLAUDE.md هو نسخة Claude Code من الفكرة ذاتها

يقرأ Claude Code ملف CLAUDE.md ولا يقرأ AGENTS.md تلقائياً. يوجد ملف المشروع في ./CLAUDE.md أو ./.claude/CLAUDE.md، بينما تُوضع التفضيلات الشخصية لكل مشروع في ~/.claude/CLAUDE.md، ويمكن للمؤسسة دفع ملف على مستوى الجهاز إلى /etc/claude-code/CLAUDE.md في أنظمة Linux. يتم دمج الملفات المكتشفة بدءاً من جذر نظام الملفات وصولاً إلى دليل العمل الخاص بك، لذا يُقرأ الملف الأقرب إلى الموقع الذي بدأت منه الجلسة أخيراً. تحمل كل جلسة تبدأها في ذلك الدليل نفس المكدس، وهذا ما يجعل تشغيل جلستين جنباً إلى جنب على جهاز واحد أمراً عملياً، ويمكن لتلك الجلسات تمرير المهام لبعضها البعض أثناء تشغيلها.

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

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

يعمل الرابط الرمزي (symlink) عندما لا يكون لديك أي إضافات:

ln -s AGENTS.md CLAUDE.md

لا يطبع الأمر شيئاً عند النجاح. في جلستك التالية، شغّل /context وتأكد من ظهور CLAUDE.md تحت قسم Memory files. إذا كان مفقوداً من تلك القائمة، فهذا يعني أن الملف لم يُحمّل، وبالتالي لم يُطبّق أي شيء فيه. لإنشاء مسودة أولى بدلاً من كتابتها يدوياً، شغّل /init: حيث يقرأ قاعدة الكود وينتج ملفاً أولياً، وعند وجود ملف CLAUDE.md بالفعل، فإنه يقترح تحسينات بدلاً من الكتابة فوقه.

حافظ على طول كل ملف تحت 200 سطر تقريباً. الملفات الأطول تستهلك مساحة أكبر من نافذة السياق وتقل دقة الالتزام بها. إذا أردت معرفة ما ينافس على تلك المساحة، فإن ما يملأ نافذة سياق الوكيل فعلياً يوضح ذلك بالتفصيل.

هناك نقطة تستحق التأكيد. ملف AGENTS.md هو توجيه وليس نظام صلاحيات. يصل المحتوى كسياق عادي، لذا يقرأه النموذج وعادة ما يمتثل له، لكن لا يوجد ما يمنع إجراءً يتعارض معه. عندما يتم تجاهل قاعدة كتبتها بهدوء ولا يمكنك معرفة السبب، راجع أسباب إسقاط التعليمات قبل إعادة صياغة النص للمرة الثالثة. بالنسبة للقاعدة التي يجب أن تُطبق في كل مرة، مثل "لا تدفع أبداً إلى الفرع الرئيسي" (never push to main)، استخدم خطافاً (hook) أو إعداد صلاحيات، لأن تلك تعمل ككود برمجي ولا تعتمد على قرار النموذج بالامتثال.

أدوات تتولى كتابة هذه الملفات نيابة عنك

يُظهر مشروعان ظهرا في قائمة المشاريع الرائجة على GitHub بتاريخ 30 يوليو 2026 الاتجاه الذي تسلكه هذه الممارسة.

مشروع agent0ai/dox (الذي حصد 1,368 نجمة حتى يوليو 2026) هو إطار عمل للحفاظ على تحديث شجرة من ملفات AGENTS.md. لا يتضمن المشروع أي حزمة برمجية أو بيئة تشغيل. أنت تقوم بنسخ محتويات ملف AGENTS.md الخاص به إلى ملف AGENTS.md الرئيسي في مشروعك، وهذا هو كل ما يتطلبه التثبيت. بالنسبة لمشروع موجود مسبقاً، يمكنك توجيه الوكيل (agent) الخاص بك كالتالي:

Initialize DOX tree for this project now.

يقوم الوكيل بعد ذلك بإنشاء ملفات AGENTS.md الفرعية وفهارسها، ثم يمسح الشجرة بالكامل قبل إجراء أي تعديل، ويحدّث الوثائق المتأثرة بعد تنفيذ أي تغيير. الرهان هنا هو أن الوثائق التي يحتفظ بها الوكيل كأثر جانبي لعمله تظل دقيقة، بينما الوثائق التي يحدّثها البشر يدوياً لا تظل كذلك.

HUMAN.md، الحيلة ذاتها مطبقة عليك

يُطبّق Intuition-Lab/personal-model (الذي حاز على 1,260 نجمة حتى يوليو 2026) النمط نفسه على الأشخاص بدلاً من المستودعات. يُصيغ المشروع ملف HUMAN.md الخاص بك كمخرجات للنظام بدلاً من كونه ملفاً تكتبه يدوياً: "نموذج حي لما يهمك الآن، وكيف تتخذ قراراتك، وإلى أين يتجه انتباهك". يعمل هذا المشروع محلياً على نظام macOS 13 أو أحدث، ويلتقط نشاطك بعد منح الأذونات اللازمة في macOS، ثم يعرض النتائج للوكلاء عبر بروتوكول MCP (model context protocol). مسار التثبيت المختصر هو:

uv tool install personal-model
persome onboard
persome model open --after 30

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

تنبيه واحد: ملف HUMAN.md هو ملف تعريف شخصي، لذا فهو حساس بطبيعته. احتفظ به بعيداً عن أي مستودع عام. ضعه في ~/.claude/CLAUDE.md، أو في ملف CLAUDE.local.md مُدرج ضمن gitignore في جذر المشروع، حيث يتم تحميله بجانب الملف الملتزم به (committed) ويُعامل بالطريقة نفسها.

قالب أساسي يمكنك نسخه

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

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

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

FAQ

هل ملف AGENTS.md هو نفس ملف CLAUDE.md؟

هما يمثلان الفكرة ذاتها تحت اسمي ملفين مختلفين. يقرأ Claude Code ملف CLAUDE.md ويتجاهل AGENTS.md ما لم تقم بربطهما. اجعل ملفاً واحداً هو المصدر الموثوق وقم بربط الآخر به، إما عبر سطر يحتوي على @AGENTS.md في أعلى ملف CLAUDE.md أو عبر ln -s AGENTS.md CLAUDE.md. إذا احتفظت بنسختين كاملتين بشكل منفصل، فستختلف محتوياتهما في غضون شهر.

هل كتابة ملف AGENTS.md تضمن التزام الوكيل بما ورد فيه؟

لا. يتم تقديم المحتوى كـ context، لذا يقرأه النموذج ويلتزم به غالباً، لكن لا يوجد ما يمنع تنفيذ إجراء يتعارض معه. التعليمات الغامضة هي الأقل موثوقية في التنفيذ، ووجود ملفين يقدمان توجيهات متناقضة سيجعل الوكيل يختار أحدهما عشوائياً. بالنسبة للقواعد التي يجب تطبيقها في كل مرة، استخدم hook أو قاعدة صلاحيات، حيث يتم فرضها من قبل العميل بغض النظر عما يقرره النموذج.

هل يجب رفع ملف AGENTS.md إلى git؟

نعم، لأي شيء يخص المشروع: أوامر البناء، هيكلية الملفات، والاتفاقيات. هذا هو الهدف من الملف، لأن وكلاء زملائك في الفريق سيبدؤون بنفس الـ context الذي تبدأ به أنت. أي شيء شخصي أو خاص بجهاز واحد يجب أن يوضع في ملف منفصل مدرج في gitignore، أما بيانات الاعتماد فلا يجب وضعها في أي منهما.

ما هو ملف HUMAN.md وهل أحتاج إليه؟

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