AGENTS.md وHUMAN.md: شرح عملي

ما هو AGENTS.md

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

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

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

مكان الملف وأي ملف له الأولوية

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

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

يستحق التداخل استخدامه، لأنه الطريقة الوحيدة لكتابة قاعدة صحيحة في مجلد وخاطئة في المجلد التالي. تنتمي قاعدة مثل "يتحقق كل endpoint من مدخلاته" إلى جانب endpoints. أما وضعها في ملف الجذر فيؤدي إلى تحميلها مع كل مهمة لا علاقة لها بها، من دون فائدة.

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

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

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

تستحق القواعد السلبية أن تُذكر أيضًا. «لا تعدّل الملفات الموجودة ضمن dist/، إذ ينشئها npm run build» تمنع خطأً محددًا. ولأنها تذكر السبب، يستطيع الوكيل استنتاج الحالة المكافئة التي لم تذكرها.

ما لا ينتمي إليها مطلقًا

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

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

ملف 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/`.

يعمل الرابط الرمزي عندما لا يكون لديك ما تضيفه:

ln -s AGENTS.md CLAUDE.md

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

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

تجدر الإشارة إلى نقطة مهمة. يُعد AGENTS.md ملف إرشادات، وليس نظام صلاحيات. يصل محتواه كسياق عادي، لذلك يقرأه النموذج ويمتثل له عادةً، لكن لا شيء يمنع تنفيذ إجراء يخالفه. بالنسبة إلى قاعدة يجب الالتزام بها في كل مرة، مثل "لا تدفع التغييرات إلى main مطلقًا"، استخدم hook أو إعداد صلاحيات، لأن هذه الآليات تعمل كشيفرة ولا تعتمد على قرار النموذج بالامتثال.

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

يوضح مشروعان من قائمة المشاريع الرائجة على GitHub في 30 July 2026 الاتجاه الذي يتجه إليه هذا الأسلوب.

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

Initialize DOX tree for this project now.

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

HUMAN.md، الحيلة نفسها موجّهة إليك

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

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

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

تنبيه واحد. ملف HUMAN.md هو ملف شخصي لشخص، ولذلك فهو حساس بطبيعته. لا تضعه في مستودع عام. ضعه في ~/.claude/CLAUDE.md، أو في ملف CLAUDE.local.md مستثنى من Git داخل جذر المشروع، حيث يُحمّل إلى جانب الملف المتعقَّب ويُعامل بالطريقة نفسها.

قالب ابتدائي يمكنك نسخه

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

# 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 أن يتبعه الوكيل؟

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

هل ينبغي إيداع AGENTS.md في git؟

نعم، لكل ما يتعلق بالمشروع: أوامر البناء، وبنيته، واصطلاحاته. هذا هو الغرض من الملف، لأن وكلاء زملائك يبدأون عندئذٍ بالسياق نفسه الذي يبدأ به وكيلك. ضع أي معلومات شخصية أو خاصة بجهاز واحد في ملف منفصل يتجاهله git، ولا تضع بيانات الاعتماد في أيٍّ منهما.

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

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