> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# ملف تعليمات المشروع AGENTS.md وCLAUDE.md: ماذا تكتب فيه
- URL: https://arabroot.io/articles/ملف-تعليمات-المشروع-agents-md-وclaude-md-ماذا-تكتب-فيه/
- Published: 2026-11-19T20:24:14.000Z
- Updated: 2026-11-19T21:23:43.000Z
- Description: أين تضع ملف تعليمات الوكيل، وكيف تجمعه Codex وClaude Code وCopilot من المجلدات، ومتى يقطع دون أن يعرف النموذج، وماذا يتغير فعلاً عندما تكتبه.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, التطوير مع وكلاء الذكاء الاصطناعي

كل وكيل برمجة يبدأ عمله في مشروعك وهو لا يعرف عنه شيئاً، فهو لا يعرف أن الاختبارات Tests تعمل بأمر `make test` وليس `npm test`، ولا يعرف أن الفريق قرر قبل سنة ألا يستعمل `float` في المبالغ المالية، ولا يعرف أن مجلد `generated/` يكتب آلياً ولا يجب أن يلمسه أحد. والطريقة البسيطة أن تكتب له هذا كله في كل محادثة، وهي طريقة تتعبك بعد اليوم الثاني، وتنساها في اليوم الثالث، فيكتب الوكيل Agent كوداً يعمل ولكنه يخالف قواعد الفريق، ثم تقضي وقت المراجعة Review في تصحيح ما كان يمكن أن يعرفه من البداية. ولذلك ظهر ملف تعليمات المشروع، أي ملف نصي في المستودع يقرؤه الوكيل في بداية كل جلسة، واسمه المشترك اليوم `AGENTS.md`، ومعه أسماء خاصة ببعض الأدوات مثل `CLAUDE.md` و`.github/copilot-instructions.md`.

وفي [مقال كيف يعمل مساعد البرمجة من الداخل](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D9%8A%D8%B9%D9%85%D9%84-%D9%85%D8%B3%D8%A7%D8%B9%D8%AF-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D8%A8%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D9%85%D9%86-%D8%A7%D9%84%D8%AF%D8%A7%D8%AE%D9%84/) شرحنا أن تعليمات النظام System Prompt نص يضاف قبل كلامك، وهذا الملف هو الجزء من هذا النص الذي تكتبه أنت. ولكن الأسئلة العملية حوله كثيرة: أين تضعه؟ وماذا يحدث إذا كان في المستودع أكثر من ملف؟ وهل يقرؤه Claude Code كما يقرؤه Codex؟ وهل يتحسن عمل الوكيل فعلاً عندما تكتبه، أم أنه يكلفك توكنات فقط؟ ولذلك لم نكتف بقراءة التوثيق، وإنما شغلنا Codex CLI على سيرفر وهمي يحفظ كل طلب يرسله، لنرى بأعيننا أين يضع الملف ومتى يقطعه، ثم شغلنا Aider مع نموذج محلي صغير على ثلاث مهام، مرة دون ملف ومرة مع ملف قصير ومرة مع ملف منتفخ، وقسنا الفرق.

في هذا المقال سوف نتناول:

- ما هو ملف `AGENTS.md`، ومن يديره، وأي الأدوات تقرؤه في نوفمبر 2026.
- كيف يجمع Codex الملفات من المجلدات ويضعها في الطلب، كما رأيناه في طلب حقيقي.
- الحد الذي يقطع الملف الطويل في منتصف الجملة، والتحذير الذي لا يراه النموذج Model.
- كيف تتعامل Claude Code وGitHub Copilot وAider مع الملف نفسه.
- تجربة: المهام نفسها دون ملف، ومع ملف قصير، ومع ملف منتفخ، وما الذي تغير فعلاً.
- ماذا تقول أول دراسة محكمة عن هذه الملفات، وماذا تكتب فيه وماذا تترك.

## ما هو ملف AGENTS.md؟

ملف `AGENTS.md` ملف Markdown عادي في المستودع، يكتب فيه الفريق ما يحتاج الوكيل أن يعرفه عن المشروع، ويقرؤه الوكيل تلقائياً قبل أن يبدأ. و[موقع AGENTS.md](https://agents.md/?ref=arabroot.io) يصفه بأنه README للوكلاء، أي أن ملف README يكتب للإنسان الذي يريد أن يفهم المشروع أو يشغله، وهذا الملف يكتب للوكيل الذي سوف يعدل الكود، وفيه أوامر البناء Build والاختبار Test، وقواعد الكود Code Style، والأشياء التي لا يجب أن يلمسها. ولا توجد فيه حقول مطلوبة ولا صيغة خاصة، فهو Markdown بأي عناوين تريدها، وهذا مقصود، لأن الهدف أن يكون سهلاً بحيث يكتبه أي مطور في دقائق.

وقد يتساءل البعض: لماذا لا نضع هذه الأشياء في README نفسه؟ والإجابة أن README يقرؤه الناس، وإذا ملأته بتعليمات مثل «لا تعدل الملفات المولدة» و«شغل الفاحص Linter قبل أن تنتهي» و«لا تضف مكتبة جديدة دون أن تسأل» فإنه يصبح أصعب على الإنسان، ولذلك فصل الملفان، وكل واحد يكتب لقارئه.

والملف بدأ في 2025 من تعاون بين عدة أدوات، منها OpenAI Codex وAmp وGoogle Jules وCursor وFactory، بعد أن كانت كل أداة تطلب اسماً خاصاً بها، فكان المستودع الذي يستعمل فريقه ثلاث أدوات يحتاج ثلاثة ملفات بالمحتوى نفسه تقريباً. واليوم يذكر الموقع أن الصيغة تحت رعاية مؤسسة Agentic AI Foundation التابعة لمؤسسة Linux Foundation، ويعرض قائمة طويلة من الأدوات التي تقرؤه، منها Codex وJules وAider وGoose وOpenCode وZed وWarp وVS Code وCursor وGemini CLI ووكيل GitHub Copilot.

ولاحظ أن «يقرؤه» لا تعني الشيء نفسه في كل أداة، فبعضها يقرؤه تلقائياً من كل مجلد، وبعضها يقرؤه من الجذر فقط، وبعضها يحتاج أن تخبره به في ملف إعداداته، كما سوف نرى بعد قليل. ولذلك فإن السؤال الأول الذي يجب أن تسأله عن أي أداة ليس «هل تدعم AGENTS.md؟»، وإنما «متى تقرؤه، ومن أي مجلد، وإلى أي حجم؟».

## المختبر: سيرفر وهمي يرى ما يرسله الوكيل

التوثيق يقول لك ما يجب أن يحدث، والطلب الحقيقي يقول لك ما حدث، ولذلك فإن القسم الأول من المختبر يشغل [Codex CLI](https://github.com/openai/codex?ref=arabroot.io) بالإصدار 0.170.0، وهو وكيل مفتوح المصدر Open Source تحت رخصة Apache 2.0، داخل Container من `node:22-slim`، ولكنه لا يتصل بأي نموذج حقيقي، وإنما بسيرفر صغير كتبناه بلغة JavaScript في ملف واحد، يحفظ كل طلب يصله في ملف JSON ثم يرد برسالة قصيرة ثابتة. وبهذه الطريقة لا نحتاج أي مفتاح API ولا أي اشتراك، ونرى الطلب كما يخرج من الوكيل حرفاً حرفاً، والإعداد كما يلي:

```toml
# ~/.codex/config.toml داخل الـ Container
model = "qwen2.5-coder:3b"
model_provider = "stub"

[model_providers.stub]
name = "stub"
base_url = "http://127.0.0.1:9605/v1"
wire_api = "responses"
```

في الإعداد أعلاه لاحظ التالي:

- المزود Provider باسم `stub` يشير إلى السيرفر Server الوهمي على المنفذ 9605 داخل الـ Container نفسه، و`wire_api = "responses"` يعني أن Codex يرسل طلباته بصيغة Responses API، وهي الصيغة التي شرحنا الفرق بينها وبين Chat Completions في [دليل استدعاء نموذج اللغة من الكود](https://arabroot.io/articles/%D8%A7%D8%B3%D8%AA%D8%AF%D8%B9%D8%A7%D8%A1-%D9%86%D9%85%D9%88%D8%B0%D8%AC-%D8%A7%D9%84%D9%84%D8%BA%D8%A9-%D9%85%D9%86-%D8%A7%D9%84%D9%83%D9%88%D8%AF-%D8%B9%D8%A8%D8%B1-api-%D9%85%D8%AA%D9%88%D8%A7%D9%81%D9%82%D8%A9-%D9%85%D8%B9-openai/).
- اسم النموذج هنا لا يستعمل، لأن السيرفر الوهمي لا يشغل نموذجاً، ولذلك يظهر في المخرج تحذير أن Codex لا يعرف بيانات هذا النموذج، وهو تحذير لا يؤثر على ما نقيسه.

ثم يبني السكربت `capture.sh` مستودع git صغيراً فيه ملف `AGENTS.md` في الجذر وملف آخر في المجلد `services/payments`، ويشغل Codex من المجلد الفرعي بأمر واحد غير تفاعلي:

```bash
cd services/payments
codex exec --skip-git-repo-check "Summarize the current instructions."
```

والملفان كما يلي:

```markdown
# AGENTS.md

## Repository expectations
- Run `make test` before you say a task is done.
- Money is stored as integer halalas, never float.
```

```markdown
# Payments service
- Use `make test-payments` instead of `make test`.
- Never log card numbers.
```

## كيف يجمع Codex الملفات من المجلدات؟

[صفحة AGENTS.md في توثيق Codex](https://developers.openai.com/codex/guides/agents-md?ref=arabroot.io) تشرح القاعدة: يبدأ Codex من ملفك الشخصي في `~/.codex/AGENTS.md`، ثم يمشي من جذر المستودع نزولاً إلى المجلد الذي شغلته منه، ويأخذ من كل مجلد ملفاً واحداً على الأكثر، ويبحث فيه أولاً عن `AGENTS.override.md` ثم عن `AGENTS.md`، ثم يلصق الملفات بهذا الترتيب، فيكون ملف المجلد الأقرب إليك آخر ما يقرؤه النموذج، ولذلك يغلب على ما قبله عند التعارض. وهذا ما ظهر في الطلب المحفوظ، فالسكربت `inspect.cjs` يطبع أجزاء الطلب وحجم كل جزء، والمخرج سوف يكون كما يلي:

```text
$ node inspect.cjs captures/nested.json show
tools: 9 (17373 chars of JSON): exec_command, write_stdin, request_user_input, view_image, multi_agent_v1, get_goal, create_goal, update_goal, web_search
developer  16979 chars  You are a coding agent running in the Codex CLI, a terminal-based codi
developer   2456 chars  <skills_instructions>
user         767 chars  # AGENTS.md instructions for /work/repo/services/payments
user          35 chars  Summarize the current instructions.

# AGENTS.md instructions for /work/repo/services/payments

<INSTRUCTIONS>
# AGENTS.md

## Repository expectations
- Run `make test` before you say a task is done.
- Money is stored as integer halalas, never float.

# Payments service
- Use `make test-payments` instead of `make test`.
- Never log card numbers.

</INSTRUCTIONS>
```

في المخرج أعلاه لاحظ التالي:

- الملفان وصلا في رسالة واحدة من نوع `user` بعنوان `# AGENTS.md instructions for` ومعه المجلد الحالي، داخل وسم `<INSTRUCTIONS>`، أي أن Codex لا يضعهما في تعليمات النظام نفسها، وإنما في رسالة مستقلة قبل رسالتك.
- ملف الجذر جاء أولاً ثم ملف `services/payments`، ولذلك فإن القاعدتين المتعارضتين، `make test` في الجذر و`make test-payments` في المجلد، وصلتا معاً، والأخيرة هي التي تغلب لأنها الأقرب.
- Codex لا يقرر وحده كيف يحل التعارض، وإنما يخبر النموذج بالقاعدة، ففي تعليماته الثابتة التي حجمها 16,979 حرفاً قسم بعنوان `AGENTS.md spec` يقول للنموذج إن نطاق الملف هو المجلد الذي هو فيه وما تحته، وإن الملف الأعمق يغلب عند التعارض، وإن تعليماتك المباشرة في المحادثة تغلب على الملف كله.

والتشغيل الثاني أضاف ملفاً باسم `AGENTS.override.md` في المجلد نفسه فيه قاعدة واحدة تقول إن خدمة الدفع مجمدة هذا الأسبوع، والتشغيل الثالث أضاف ملفاً شخصياً في `~/.codex/AGENTS.md` يقول «Reply in Arabic»، والجزء المهم من الطلبين كما يلي:

```text
$ node inspect.cjs captures/override.json show
<INSTRUCTIONS>
# AGENTS.md
...
- Money is stored as integer halalas, never float.

# Payments override
- Payments is frozen this week: answer questions, change nothing.
</INSTRUCTIONS>

$ node inspect.cjs captures/global.json show
<INSTRUCTIONS>
# My defaults
- Reply in Arabic.

--- project-doc ---

# AGENTS.md
...
```

لاحظ أن ملف `services/payments/AGENTS.md` اختفى تماماً عندما وجد بجانبه `AGENTS.override.md`، أي أن الملف البديل لا يضاف إلى الأصلي وإنما يحل محله في ذلك المجلد، وهذا مفيد عندما تريد تغييراً مؤقتاً دون أن تحذف الملف المشترك، ولكنه خطير إذا نسيته هناك، لأن كل قواعد الملف الأصلي تتوقف دون أي إشارة. ولاحظ أيضاً أن ملفك الشخصي جاء قبل ملفات المستودع وبينهما سطر `--- project-doc ---`، أي أن ملف المستودع يقرأ بعده ويغلب عليه عند التعارض. والشكل التالي يجمع ما رأيناه في التشغيلين:

![على اليمين إطار بعنوان ما على القرص فيه خمسة مسارات: ~/.codex/AGENTS.md ملفك الشخصي، وrepo/AGENTS.md جذر المستودع، وpayments/AGENTS.md يتجاهله، وpayments/AGENTS.override.md يحل محله، وrepo/services/search/AGENTS.md خارج الطريق، وتحتها أن Codex يمشي من الجذر إلى المجلد الحالي ويأخذ ملفاً واحداً لكل مجلد. وعلى اليسار إطار بعنوان ما يصل إلى النموذج بهذا الترتيب: تعليماتك الشخصية، ثم سطر project-doc، ثم AGENTS.md في الجذر، ثم ملف المجلد الحالي، ثم معلومات البيئة، كلها في رسالة واحدة، والحد الافتراضي 32 KiB لكل الملفات معاً](https://arabroot.io/content/images/2026/11/agents-md-01-discovery.webp)

ترتيب الملفات كما ظهر في طلبين حقيقيين من Codex CLI 0.170.0: الأبعد أولاً والأقرب أخيراً، والملف البديل يلغي الأصلي في مجلده.

ولاحظ أن ملف `services/search/AGENTS.md` لم يقرأ أصلاً، لأنه ليس على الطريق بين الجذر والمجلد الحالي. وهذا يعني أن المكان الذي تشغل منه الوكيل يغير التعليمات Instructions التي يراها، فإذا شغلته من الجذر ثم طلبت منه أن يعدل ملفاً في `services/payments`، فإن قواعد ذلك المجلد لا تكون في الطلب الأول، وإنما يعتمد Codex على أن النموذج سوف يبحث عنها بنفسه كما تطلب منه تعليماته: «عندما تعمل في مجلد فرعي… ابحث عن أي AGENTS.md ينطبق عليه». والنموذج الكبير يفعل ذلك في الغالب، أما النموذج الصغير فلا تعتمد عليه في ذلك، وشغل الوكيل من المجلد الذي تعمل فيه.

## الحد الذي يقطع الملف في منتصف الجملة

التوثيق يذكر أن Codex يتوقف عن إضافة الملفات عندما يصل مجموعها إلى قيمة `project_doc_max_bytes`، وقيمتها الافتراضية 32 KiB، أي 32,768 بايت. ولكي نرى ماذا يحدث عند الحد، فإن التشغيل الرابع يكتب في الجذر ملفاً من 700 قاعدة عامة متشابهة، مثل «اكتب دوال قصيرة وأسماء واضحة»، وفي آخره قاعدة واحدة مهمة تقول `LAST RULE: never push to main`، فيصبح حجمه 40,665 بايت. وعند التشغيل ظهر في الطرفية Terminal هذان التحذيران:

```text
warning: Loaded only 32768 of 40665 bytes from `/work/repo/AGENTS.md` in environment `local` under the 32768-byte project instruction budget. Trim your project instructions to fit the budget. If you need to keep them all, increase `project_doc_max_bytes`.
warning: Skipped project instructions in environment `local` starting at `/work/repo/services/payments/AGENTS.md` because the 32768-byte budget was exhausted. Trim your project instructions to fit the budget. If you need to keep them all, increase `project_doc_max_bytes`.
```

وآخر ما وصل إلى النموذج من الملف كان هذا:

```text
$ node inspect.cjs captures/big.json tail
...gs clearly.
- Rule 563: keep functions short and name things clearly.
- Rule 564: keep functions short and name things clearly.
- Rule 565: keep functio
</INSTRUCTIONS>
AGENTS block: 32858 chars
```

في المخرج أعلاه لاحظ التالي:

- Codex قطع الملف عند البايت 32,768 بالضبط، أي في منتصف كلمة `functions`، ولم يحاول أن يقطع عند نهاية سطر أو قسم، ولذلك ضاعت القاعدة الأخيرة `never push to main` مع آخر 7,897 بايت.
- ملف `services/payments/AGENTS.md` لم يقرأ إطلاقاً، لأن الحد نفد قبل الوصول إليه، أي أن ملف الجذر الطويل لم يحذف آخره فقط، وإنما ألغى قواعد كل المجلدات التي تحته.
- التحذيران ظهرا لك أنت في الطرفية، أما النموذج فلا يرى أي إشارة إلى أن شيئاً حذف، فهو يرى ملفاً ينتهي في منتصف جملة، وإذا كنت تشغل الوكيل من أداة أخرى أو في خط النشر CI فقد لا يقرأ أحد هذا التحذير أصلاً.

![شريط أزرق طويل مكتوب فيه وصل إلى النموذج أول 32,768 بايت، وفي آخره على اليسار جزء أحمر متقطع مكتوب فيه حذف 7,897 بايت ومعه LAST RULE never push to main، وخط أحمر عند project_doc_max_bytes = 32768، وتحته شريط رمادي متقطع أن services/payments/AGENTS.md لم يقرأ أصلاً، وفي الأسفل نافذة طرفية فيها التحذيران كما ظهرا، وجملة أن النموذج لا يرى هذا التحذير](https://arabroot.io/content/images/2026/11/agents-md-03-budget.webp)

ملف من 40,665 بايت: وصل أوله فقط، وضاعت القاعدة الأخيرة وملف المجلد الفرعي كله، والتحذير ظهر في الطرفية وحدها.

وكم يكلف هذا الملف من السياق Context؟ عددنا التوكنات Tokens في كل جزء من الطلب بمكتبة tiktoken وترميز `o200k_base`، وهو الترميز الذي تستعمله نماذج OpenAI الحديثة، والمخرج سوف يكون كما يلي:

```text
== captures/nested.json
tools (9 definitions)                4059 tokens
developer: You are a coding agent running i   3523 tokens
developer: <skills_instructions>      536 tokens
user: # AGENTS.md instructions for /wo    191 tokens
user: Summarize the current instructio      7 tokens
total                                8316 tokens
== captures/big.json
tools (9 definitions)                4059 tokens
developer: You are a coding agent running i   3523 tokens
developer: <skills_instructions>      536 tokens
user: # AGENTS.md instructions for /wo   7508 tokens
user: Summarize the current instructio      7 tokens
total                               15633 tokens
```

أي أن الملفين القصيرين مع معلومات البيئة أخذا 191 توكناً فقط من طلب حجمه 8,316 توكناً، بينما الملف المنتفخ وحده أخذ 7,508 توكنات، أي أنه ضاعف حجم كل طلب تقريباً، وهذا الثمن لا تدفعه مرة واحدة، وإنما في كل دورة من دورات الوكيل، لأن الملف يرسل في بداية المحادثة ويبقى فيها حتى النهاية. وشرحنا في [دليل الوكيل بنموذج محلي](https://arabroot.io/articles/%D9%88%D9%83%D9%8A%D9%84-%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D8%A8%D9%86%D9%85%D9%88%D8%B0%D8%AC-%D9%85%D8%AD%D9%84%D9%8A-%D9%85%D8%B9-ollama-%D9%85%D8%A7%D8%B0%D8%A7-%D8%AA%D8%AA%D9%88%D9%82%D8%B9/) أن قراءة المدخل Prompt Processing على معالج عادي قد تأخذ دقائق لبضعة آلاف من التوكنات، ولذلك فإن الملف الطويل مع النموذج المحلي لا يكلف مالاً فقط، وإنما وقتاً تنتظره قبل كل رد.

## Claude Code: ملف CLAUDE.md، ومتى يقرأ AGENTS.md؟

لم نشغل Claude Code في المختبر، لأنه أداة تجارية تحتاج حساباً واشتراكاً، ولذلك نعتمد هنا على [صفحة الذاكرة Memory في توثيقه](https://code.claude.com/docs/en/memory?ref=arabroot.io) كما كانت في 19 نوفمبر 2026\. والأداة تقرأ ملفاً باسم `CLAUDE.md` من أربعة أماكن: ملف السياسة الذي توزعه الشركة على أجهزة الموظفين Managed Policy، وملفك الشخصي في `~/.claude/CLAUDE.md`، وملف المشروع في `./CLAUDE.md` أو `./.claude/CLAUDE.md` الذي يحفظ في git ويشترك فيه الفريق، وملف محلي باسم `CLAUDE.local.md` لتفضيلاتك أنت في هذا المشروع وتضيفه إلى `.gitignore`.

وطريقة الجمع تشبه Codex في الاتجاه وتختلف في التفاصيل، فالتوثيق يقول إن Claude Code يقرأ `CLAUDE.md` من المجلد الحالي ومن كل مجلد فوقه عند بداية الجلسة، ويلصقها كلها ولا يجعل أحدها يلغي الآخر، بترتيب من جذر نظام الملفات نزولاً إلى المجلد الحالي، فتكون التعليمات الأقرب إليك آخر ما يقرأ. أما الملفات في المجلدات الفرعية تحت المجلد الحالي فلا تقرأ عند البداية، وإنما عندما يقرأ الوكيل أو يعدل ملفاً في ذلك المجلد، وهذا يحل مشكلة رأيناها مع Codex، أي أن قواعد `services/payments` تصل عندما يبدأ العمل هناك فعلاً. وفي الملف يمكنك أن تستورد ملفاً آخر بكتابة `@path/to/file`، وإلى عمق أربع خطوات، ولكن التوثيق يذكر بوضوح أن الاستيراد ينظم الملف ولا يقلل كلفته، لأن الملف المستورد يحمل معه في السياق.

أما `AGENTS.md` فإن التوثيق يذكر أن Claude Code يقرؤه مباشرة بدءاً من الإصدار v2.1.277، ولكن بشرط: يقرؤه فقط إذا لم يجد `CLAUDE.md` أو `CLAUDE.local.md` في المجلد الحالي أو أي مجلد فوقه، فإذا وجد أحدهما قرأ ملفات CLAUDE وحدها. وهذا يعني أن الملف المحلي الصغير الذي تضيفه لتفضيلاتك الشخصية يوقف قراءة `AGENTS.md` المشترك دون أن تنتبه، والتوثيق نفسه يحذر من ذلك ويقترح أن تغير إعداد Project instructions إلى `claude-md-and-agents-md` إذا أردت الملفين معاً. والطريقة التي يقترحها التوثيق لمن يستعمل أكثر من أداة أن يبقى `AGENTS.md` هو المصدر الوحيد، ويكون `CLAUDE.md` سطراً واحداً يستورده:

```markdown
# CLAUDE.md
@AGENTS.md

## Claude Code only
- Use plan mode for changes under migrations/.
```

وفي التوثيق نصيحتان مهمتان عن الحجم: أن يبقى كل ملف تحت 200 سطر، لأن الملفات الأطول تأخذ من السياق وتقلل التزام النموذج بها، وأن تنقل التعليمات التي تخص جزءاً من المشروع إلى ملفات في `.claude/rules/` مع حقل `paths` يحدد الملفات التي تنطبق عليها، فلا تحمل إلا عندما يعمل الوكيل على تلك الملفات. ويقول التوثيق أيضاً إن التعليقات بصيغة HTML في الملف، مثل `<!-- ملاحظة للمشرفين -->`، تحذف قبل أن يصل الملف إلى النموذج، فتكتب فيها ملاحظات لزملائك دون أن تدفع ثمنها توكنات.

📌

الأمر `/init` في Claude Code يقرأ المستودع ويكتب لك نسخة أولى من `CLAUDE.md` فيها أوامر البناء والاختبار وما يكتشفه من القواعد، والأمر `/memory` يفتح الملفات التي حملت، والأمر `/context` يعرض كم أخذ كل جزء من السياق. ولكن لاحظ أن ما يكتشفه `/init` هو ما يستطيع الوكيل أن يكتشفه بنفسه أصلاً، والقيمة الحقيقية في الملف هي ما لا يستطيع أن يكتشفه، كما سوف نرى في التجربة.

## GitHub Copilot وAider والأدوات الأخرى

[صفحة تعليمات المستودع في توثيق GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions?ref=arabroot.io) تذكر ثلاثة أنواع من الملفات: ملف عام للمستودع في `.github/copilot-instructions.md`، وملفات خاصة بمسارات معينة باسم `NAME.instructions.md` داخل `.github/instructions/` وفي أولها حقل `applyTo` بصيغة glob مثل `"**/*.ts,**/*.tsx"`، وملفات `AGENTS.md` في أي مكان من المستودع يغلب أقربها إلى الملف الذي يعمل عليه الوكيل. ويذكر التوثيق أيضاً أنه يقبل بدلاً منها ملف `CLAUDE.md` أو `GEMINI.md` واحداً في جذر المستودع. وإذا أردت أن تعرف هل استعملت التعليمات فعلاً، فإن Copilot Chat يضع الملف في قائمة المراجع References أعلى الرد.

أما [Aider](https://aider.chat/docs/usage/conventions.html?ref=arabroot.io) فلا يبحث عن أي ملف بنفسه، وإنما تعطيه الملف بالخيار `--read` فيدخله في المحادثة للقراءة فقط، أو تكتبه مرة واحدة في ملف الإعداد `.aider.conf.yml` بالسطر `read: AGENTS.md`، وهذا ما يذكره موقع AGENTS.md نفسه. وGemini CLI يقرأ `GEMINI.md` افتراضياً، ويقرأ `AGENTS.md` إذا أضفته إلى إعداد `context` في `.gemini/settings.json`. والجدول التالي يجمع ما سبق:

| الأداة         | الملف الذي تقرؤه                                                                 | من أين                                                               | الحجم والحدود                                         |
| -------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- |
| Codex CLI      | AGENTS.md وAGENTS.override.md وأسماء تضيفها في project\_doc\_fallback\_filenames | الملف الشخصي، ثم من جذر git إلى المجلد الحالي، ملف لكل مجلد          | 32 KiB لكل الملفات معاً، ثم يقطع                      |
| Claude Code    | CLAUDE.md وCLAUDE.local.md، وAGENTS.md إذا لم يوجد أي منهما                      | المجلد الحالي وما فوقه عند البداية، والمجلدات الفرعية عند العمل فيها | ينصح بأقل من 200 سطر، والاستيراد @ إلى عمق أربع خطوات |
| GitHub Copilot | .github/copilot-instructions.md و\*.instructions.md وAGENTS.md                   | الجذر، والمسارات حسب applyTo، وأقرب AGENTS.md                        | لا يذكر التوثيق حداً بالبايت                          |
| Aider          | أي ملف تعطيه إياه                                                                | \--read أو read: في .aider.conf.yml                                  | يدخل كاملاً مع باقي المحادثة                          |
| Gemini CLI     | GEMINI.md، وAGENTS.md بالإعداد                                                   | إعداد context في .gemini/settings.json                               | حسب نافذة النموذج                                     |

![في الوسط صندوق داكن AGENTS.md وتحته Markdown عادي بلا حقول، ومنه أربعة أسهم إلى أربعة صناديق: Codex CLI يقرؤه تلقائياً من الجذر إلى المجلد الحالي وAGENTS.override.md يحل محله في مجلده و32 KiB للكل ثم يقطع، وClaude Code يقرأ CLAUDE.md وAGENTS.md فقط إذا لم يجد أي ملف CLAUDE بدءاً من v2.1.277 والحل CLAUDE.md فيه @AGENTS.md، وGitHub Copilot أقرب AGENTS.md إلى الملف يغلب ومعه .github/copilot-instructions.md وملفات instructions.md بحقل applyTo، وAider وGemini CLI لا يبحثان عنه وأنت تخبرهما به بالخيار --read أو read في .aider.conf.yml والإعداد context في .gemini/settings.json](https://arabroot.io/content/images/2026/11/agents-md-02-tools.webp)

الملف نفسه في أربع أدوات: متى تقرؤه كل أداة، ومن أين، وما الذي يوقفه.

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

## التجربة: ثلاث مهام دون ملف، ومع ملف قصير، ومع ملف منتفخ

رأينا أين يذهب الملف وكم يكلف، والسؤال الذي يهم الفريق: هل يغير شيئاً في الكود الذي يكتبه الوكيل؟ والقسم الثاني من المختبر يشغل [Aider](https://aider.chat/docs/usage/conventions.html?ref=arabroot.io) بالإصدار 0.86.2 داخل Container، مع نموذج `qwen2.5-coder:3b` على Ollama 0.40.13، على مستودع صغير لمكتبة فواتير فيه دالة واحدة `line_total` واستثناء `InvoiceError` واختباران. والمهام الثلاث كل واحدة جملة كما يكتبها مطور مستعجل:

- **vat:** «أضف دالة `vat(amount_halalas)` ترجع ضريبة القيمة المضافة على مبلغ».
- **format:** «أضف `format_amount(halalas)` تنسق المبلغ للعرض على الفاتورة».
- **discount:** «أضف `apply_discount(amount_halalas, percent)` ترجع المبلغ بعد خصم بالنسبة المئوية».

وكل مهمة تشغل ثلاث مرات على نسخة جديدة من المستودع: دون ملف تعليمات، ثم مع ملف `AGENTS.md` قصير من 755 بايتاً بالخيار `--read`، وهو الملف نفسه الذي في قالب القسم السابق، وفيه أن المال `int` بالهللات، وأن النسبة تحسب بالصيغة `(amount * percent + 50) // 100`، وأن الضريبة 15%، وأن العرض بصيغة `"1,234.50 SAR"`، وأن الخطأ `InvoiceError`، وأن لكل دالة جديدة اختباراً، ثم مع ملف منتفخ من 13,877 بايتاً فيه القواعد نفسها في آخره، بعد 60 نصيحة عامة و40 سطراً من «تاريخ المشروع». والأمر الذي يشغله السكربت `run.sh` كما يلي:

```bash
aider --model ollama_chat/qwen2.5-coder:3b --edit-format whole --map-tokens 0 --yes-always \
      --read AGENTS.md invoices/money.py tests/test_money.py --message "$TASK"
```

وبعد كل تشغيل يشغل السكربت `checks.py`، وفيه اختبارات قبول مخفية كتبناها من القواعد، مثل `vat(333) == 50` لأن 15% من 333 هي 49.95 تقرب إلى 50، و`format_amount(123450) == "1,234.50 SAR"`، وفحوص للقواعد نفسها بقراءة شجرة الكود AST، مثل ألا يكون في الدالة الجديدة عدد عشري ولا قسمة `/`.

### أول محاولة: رد لم ينته

أول تشغيل لم يكتمل، فمهمة `format` دون ملف بقيت ساعة كاملة، وسجل Ollama يبين السبب:

```text
slot print_timing: id  0 | task 0 | n_gen =  11811, tg =   3.32 t/s, tg_3s =   4.04 t/s
[GIN] 2026/11/19 - 19:28:18 | 500 |   1h0m0s |       127.0.0.1 | POST     "/api/chat"
# aider: litellm.Timeout: Connection timed out after 3600.0 seconds. Retrying in 0.2 seconds...
```

أي أن النموذج كتب 11,811 توكناً في رد واحد دون أن يتوقف، حتى انتهت مهلة Aider بعد 3,600 ثانية وبدأ يعيد المحاولة. وهذه مشكلة معروفة مع النماذج الصغيرة، وشرحنا مثلها في [مقال وكلاء البرمجة مفتوحة المصدر](https://arabroot.io/articles/%D9%88%D9%83%D9%84%D8%A7%D8%A1-%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D9%85%D9%81%D8%AA%D9%88%D8%AD%D8%A9-%D8%A7%D9%84%D9%85%D8%B5%D8%AF%D8%B1-aider-%D9%88cline-%D9%88openhands/)، والحل أن تضع حداً لطول الرد، ولذلك أضفنا إلى ملف إعداد النموذج في Aider السطر `num_predict: 1024` بجانب `num_ctx: 8192`، وأعدنا التشغيلات التسعة كلها بالإعداد الجديد حتى تكون المقارنة عادلة.

### النتيجة

والمخرج بعد الإعادة، مختصراً إلى سطر النتيجة وعدد التوكنات، كما يلي:

```text
## none / vat        Tokens: 837 sent, 124 received.   SCORE 4/9
## none / format     Tokens: 838 sent, 119 received.   SCORE 2/5
## none / discount   Tokens: 839 sent, 346 received.   SCORE 6/9
## agents / vat      Tokens: 1.1k sent, 132 received.  SCORE 1/3   (file written to path/to/invoices/money.py)
## agents / format   Tokens: 1.1k sent, 286 received.  SCORE 3/5
## agents / discount Tokens: 1.1k sent, 169 received.  SCORE 7/9
## bloated / vat     Tokens: 4.1k sent, 132 received.  SCORE 1/3   (file written to path/to/invoices/money.py)
## bloated / format  Tokens: 4.1k sent, 121 received.  SCORE 2/5
## bloated / discount Tokens: 4.1k sent, 169 received. SCORE 7/9
```

ولاحظ أن نسخة `checks.py` الأولى كان فيها خطأ منا، فالدالة التي تفحص أن الاستثناء من نوع `InvoiceError` عرفت بعد أن استعملت، فكان فحصا الاستثناء يفشلان دائماً، ولذلك أصلحناها وأعدنا الفحوص وحدها على المستودعات نفسها دون أن نشغل النموذج من جديد، والسكربت `rescore.sh` يفعل ذلك، والأرقام أعلاه بعد الإصلاح. وفيما يلي ما حدث في كل مهمة:

- **الخصم discount:** دون ملف كتب النموذج `amount_halalas * (1 - percent / 100)`، أي قسمة وعدد عشري، فرجعت الدالة 899.1 بدل 899 وبنوع `float`، ولكنه أضاف فحصاً يرمي `InvoiceError` إذا تجاوزت النسبة 100، لأنه رأى الاستثناء في الملف، وأضاف اختباراً. ومع الملف كتب `(amount_halalas * (100 - percent) + 50) // 100`، أي صيغة الملف حرفياً، فنجحت القيم ونوع الرد وقاعدة عدم استعمال `/`، ولكنه نسي فحص النسبة التي تتجاوز 100 ونسي الاختبار. أي أن الملف حسن ما فيه قاعدة صريحة، وأضعف ما لم يكن فيه.
- **الضريبة vat:** دون ملف كتب `amount_halalas * 0.15`، أي عدداً عشرياً. ومع الملف القصير والمنتفخ كتب `(amount_halalas * 15) // 100`، أي أنه التزم بالأعداد الصحيحة ولكنه قطع الكسر بدل أن يقربه، فرجعت `vat(333)` بـ 49 بدل 50\. والأغرب أنه في الحالتين كتب الملف في المسار `path/to/invoices/money.py`، وهو مثال المسار الذي تستعمله تعليمات Aider لصيغة التعديل `whole`، فأنشأ Aider مجلداً جديداً بهذا الاسم وعمل commit، وبقي الملف الحقيقي دون تغيير. ولو قيمنا الملف الذي كتبه وكأنه في المكان الصحيح لنجح في 6 فحوص من 9 مقابل 4 دون ملف، ولكن الذي يهمك هو ما حدث فعلاً: الدالة غير موجودة.
- **العرض format:** فشل في الحالات الثلاث، فقد كتب `f"{halalas:,}"` دون ملف، و`f"{halalas:,} SAR"` مع الملفين، أي أنه أخذ الوحدة من الملف ولم يقسم على 100، فعرض 123,450 SAR بدل 1,234.50 SAR. والقاعدة في الملف كانت مثالاً واحداً للصيغة، والنموذج نقل الجزء الظاهر منه وهو الكلمة SAR، ولم يستنتج الحساب الذي خلفه.
- **الملف المنتفخ:** أعطى النتائج نفسها تقريباً التي أعطاها الملف القصير، ولكن بكلفة 4.1 ألف توكن مرسل بدل 1.1 ألف، وأخذ تشغيل `vat` معه 337 ثانية بدل 77، ونسي الاختبار في مهمة العرض التي أضافه فيها مع الملف القصير. أي أن ستين نصيحة عامة لم تحسن شيئاً، وكلفت ثلاثة أضعاف التوكنات وأربعة أضعاف الزمن في أول مهمة.

![جدول ثلاثة في ثلاثة: الأعمدة دون ملف 837 توكناً لكل طلب، وAGENTS.md قصير 1.1 ألف توكن، وAGENTS.md منتفخ 4.1 ألف توكن، والصفوف ثلاث مهام: الضريبة vat دون ملف 4 من 9 مع float، ومع الملفين كتب الملف في path/to والدالة غير موجودة، والعرض format 2 من 5 ثم 3 من 5 ثم 2 من 5 مع 123,450 SAR بلا قسمة، والخصم discount 6 من 9 مع float ثم 7 من 9 بصيغة الملف حرفياً في الحالتين](https://arabroot.io/content/images/2026/11/agents-md-04-aider.webp)

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

وقد يتساءل البعض: هل هذه نتيجة عادلة لملف التعليمات، والنموذج صغير بحجم 3B؟ والإجابة أن النموذج الكبير كان سيلتزم بقواعد أكثر، وكان سيكتشف أن `path/to/` مثال، ولكن اتجاه النتيجة هو ما يهم: القاعدة التي لا يمكن أن يعرفها النموذج من الكود، مثل الصيغة الصحيحة للنسبة، لم يكن هناك أي طريق لها إلى الكود إلا الملف، وعندما كانت في الملف ظهرت في الكود حرفياً في مهمة الخصم. أما ما يستطيع النموذج أن يخمنه، أو ما يحتاج استنتاجاً من مثال، فالملف وحده لا يضمنه، والذي يضمنه هو الاختبار، ولذلك فإن أهم سطر في أي `AGENTS.md` هو الأمر الذي يشغل الاختبارات، وأهم شيء بعده أن تكون هناك اختبارات تفشل عندما يخالف الكود القاعدة.

## ماذا تقول الدراسات عن هذه الملفات؟

أكبر دراسة حتى الآن عن فائدة هذه الملفات نشرها فريق من جامعة ETH Zurich في فبراير 2026، وهي «Evaluating AGENTS.md» لـ Thibaud Gloaguen وNiels Mündler-Sasahara وMark Niklas Müller وVeselin Raychev وMartin Vechev، و[ملخصها على arXiv](https://arxiv.org/abs/2602.11988?ref=arabroot.io) يقول إنهم قاسوا وكلاء برمجة على مهام من SWE-bench مع ملفات كتبها نموذج لغة، وعلى مجموعة جديدة من المشكلات الحقيقية من مستودعات كتب مطوروها ملفاتها بأنفسهم، ووجدوا أن الملفات لا تحسن نسبة إنجاز المهام بشكل عام، بينما ترفع كلفة التشغيل بأكثر من 20% في المتوسط، وأن هذا تكرر مع نماذج ووكلاء مختلفين ومع الملفات المكتوبة يدوياً والمولدة آلياً. ولكن الجزء الأهم في الملخص هو التفصيل: الوكلاء يلتزمون بالتعليمات المكتوبة في الملفات بشكل جيد، أما نظرة عامة على المستودع Repository Overview، وهي ما ينصح به كثير من مزودي النماذج، فلا تفيد، والخلاصة التي يكتبونها أن الملفات مفيدة لتحديد الممارسات غير المعتادة في المشروع، وأن الملف الجيد يكتب الحد الأدنى من المتطلبات.

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

وهناك دراستان وصفيتان من الفريق نفسه تقريباً تبينان ما يكتبه المطورون فعلاً في هذه الملفات: الأولى «On the Use of Agentic Coding Manifests» لـ Worawalan Chatlatanagulchai وزملائه في سبتمبر 2025، و[ملخصها](https://arxiv.org/abs/2509.14744?ref=arabroot.io) يذكر أنهم حللوا 253 ملف `CLAUDE.md` من 242 مستودعاً، ووجدوا أن أغلبها بعنوان رئيسي واحد وأقسام قليلة، وأن محتواها أوامر التشغيل وملاحظات التنفيذ ونظرة عامة على البنية. والثانية «Agent READMEs» للباحثة نفسها وزملائها في نوفمبر 2025، و[ملخصها](https://arxiv.org/abs/2511.12884?ref=arabroot.io) يذكر أنهم درسوا 2,303 ملف سياق من 1,925 مستودعاً، ووجدوا أن هذه الملفات تتغير مثل ملفات الإعداد بإضافات صغيرة متكررة، وأن 75.9% منها فيها طريقة الاختبار، بينما الأمان Security يظهر في 14.8% فقط والأداء Performance في 14.5%. أي أن المطورين يكتبون ما يجعل الوكيل يعمل، ونادراً ما يكتبون ما يجعل كوده آمناً.

## المستودع الكبير Monorepo: ملف لكل مجلد

في المستودع الذي فيه عدة خدمات، مثل `services/payments` و`services/search` وتطبيق الواجهة، لكل جزء أوامره وقواعده، والملف الواحد في الجذر الذي يجمع كل ذلك يطول بسرعة ويقترب من حد Codex، وأغلب ما فيه لا يخص المهمة الحالية. ولذلك فإن الطريقة التي تدعمها الأدوات الثلاث هي ملف قصير في الجذر بالقواعد العامة فقط، مثل أمر تشغيل كل الاختبارات وقواعد الأمان، وملف في كل مجلد خدمة بأوامرها وقواعدها. ورأينا أن Codex يأخذ ملف المجلد الذي تشغله منه ويضعه بعد ملف الجذر، وأن Claude Code يحمل ملف المجلد الفرعي عندما يبدأ العمل فيه، وأن Copilot يأخذ أقرب ملف إلى الملف الذي يعدله. والقاعدة التي تجمع الثلاث: لا تكرر في ملف المجلد ما في ملف الجذر، واكتب في ملف المجلد ما يختلف فقط، مثل `make test-payments` بدل `make test`، لأن التكرار يضاعف الكلفة، والنسختان تختلفان مع الوقت فلا يعرف الوكيل أيهما يتبع.

## ماذا تكتب في الملف؟

إذا جمعت ما رأيناه في الطلبات المحفوظة وفي تجربة Aider وفي الدراسات، فإن القاعدة الأساسية بسيطة: اكتب ما لا يستطيع الوكيل أن يعرفه من الكود، واترك ما يستطيع أن يعرفه. وفيما يلي ما يستحق مكانه في الملف:

- **الأوامر Commands:** كيف تبني المشروع وتشغل الاختبارات والفاحص Linter، بالأمر الكامل الذي يعمل، مثل `python -m unittest discover -s tests -q`، لأن الوكيل إذا خمن الأمر قد يشغل أداة غير موجودة أو يشغل كل الاختبارات وهي تأخذ ساعة.
- **القرارات غير الظاهرة Non-obvious Decisions:** مثل «المبالغ بالهللة int»، و«نسبة من مبلغ تحسب بالأعداد الصحيحة»، و«لا تستعمل ORM في هذا المجلد»، وكل قرار اتخذه الفريق لسبب لا يظهر في الكود.
- **الحدود Boundaries:** المجلدات التي لا يلمسها مثل الملفات المولدة وملفات الترحيل Migrations المدمجة، والأفعال التي تحتاج موافقة مثل إضافة مكتبة أو تغيير ملف CI.
- **شكل العمل Workflow:** مثل «كل دالة عامة جديدة لها اختبار»، و«رسالة commit بصيغة Conventional Commits»، و«لا تفتح Pull Request قبل أن تمر كل الاختبارات».
- **الأمان Security:** مثل «لا تكتب أسراراً في الكود»، و«لا تطبع أرقام البطاقات في السجلات Logs»، وهي القواعد التي وجدت الدراسة أنها نادرة في الملفات مع أنها الأهم.

وفيما يلي ما يجب أن تتركه خارج الملف:

- **النصائح العامة:** «اكتب كوداً نظيفاً» و«استعمل أسماء واضحة» يعرفها النموذج من تدريبه، وكتابتها مئة مرة لا تجعله يلتزم بها أكثر، وإنما تدفن القاعدة المهمة بينها كما حدث مع القاعدة الأخيرة في تجربة الحد.
- **شرح البنية بالتفصيل:** قائمة بكل مجلد وكل ملف تصبح قديمة بعد أسبوع، والوكيل يستطيع أن يقرأ شجرة الملفات بنفسه، فاكتف بسطر أو سطرين عن الأجزاء غير الواضحة.
- **التاريخ:** متى ناقش الفريق ماذا، ولماذا تغيرت المكتبة في 2023، فهذا مكانه سجل التغييرات وليس تعليمات الوكيل.
- **الأسرار Secrets:** لا تكتب كلمات مرور أو توكنات أو عناوين سيرفرات داخلية في الملف، لأنه يحفظ في git ويرسل في كل طلب إلى مزود النموذج.

![عمودان: على اليمين بإطار أخضر وعلامة صح يستحق مكانه في الملف: الأوامر كاملة مثل python -m unittest discover -s tests -q، والقرارات غير الظاهرة في الكود مثل المبالغ int بالهللة والنسبة بالأعداد الصحيحة، والحدود مثل generated وmigrations و.github/workflows، وشكل العمل، والأمان، وضع المهم في أول الملف لأن آخره ما يقطع. وعلى اليسار بإطار أحمر وعلامة خطأ اتركه خارج الملف: النصائح العامة مثل write clean code، وشرح كل مجلد، وتاريخ القرارات، والأسرار والعناوين الداخلية، وقواعد مهمة مثل لا تدفع إلى main وحدها لأن المنع الحقيقي حماية الفرع والصلاحيات](https://arabroot.io/content/images/2026/11/agents-md-05-what-to-write.webp)

القاعدة في سطر: ما لا يستطيع الوكيل أن يعرفه من الكود يكتب في الملف، وما يعرفه يترك.

والقالب التالي نقطة بداية لمشروع صغير، وهو قريب من الملف الذي استعملناه في التجربة:

```markdown
# AGENTS.md

## Commands
- Install: `pip install -e .[dev]`
- Test: `python -m unittest discover -s tests -q` (run it before you say a task is done)
- Lint: `ruff check .`

## Rules that are not visible in the code
- Money is an `int` number of halalas. Never use `float` or `/` on money.
- A percentage of an amount is `(amount * percent + 50) // 100`.
- Invalid input raises `InvoiceError`, never `ValueError` or `assert`.

## Boundaries
- Do not edit `generated/` or merged files in `migrations/`.
- Ask before adding a dependency or changing `.github/workflows/`.

## Security
- No secrets in code or logs. Never log card numbers or national IDs.
```

## كيف تحافظ على الملف صحيحاً؟

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

1. راجع تغييراته في Pull Request مثل أي ملف آخر، واجعل من يغير أمر البناء في `Makefile` يغيره في الملف أيضاً.
2. إذا صححت الوكيل في الموضوع نفسه مرتين، فهذه علامة أن القاعدة مكانها الملف وليس المحادثة، والعكس صحيح، فالقاعدة التي لم يحتجها أحد منذ أشهر احذفها.
3. اختبر الملف بسؤال الوكيل عنه، مثل الأمر الذي استعملناه في المختبر `"Summarize the current instructions."`، فإذا لم يذكر القاعدة التي كتبتها فهي لم تصل، إما لأنها في ملف لم يقرأ أو لأنها بعد الحد.
4. راقب الحجم، فإذا اقترب الملف من 200 سطر أو من عشرات الكيلوبايت فانقل الأجزاء الخاصة إلى ملفات في المجلدات الفرعية أو إلى قواعد بمسارات أو إلى مهارات Skills، وهذا موضوع [المقال التالي في هذه المرحلة](#related).

⚠️

ملف التعليمات في مستودع لم تكتبه أنت هو نص يدخل إلى سياق وكيلك ويملك صلاحياته، ولذلك فإن مستودعاً مفتوح المصدر فيه `AGENTS.md` يطلب من الوكيل أن يرسل ملف `.env` إلى عنوان خارجي هو هجوم حقن تعليمات Prompt Injection كامل. وCodex وClaude Code يطلبان موافقتك على أشياء مثل الاستيراد من خارج المجلد، ولكن الحماية الحقيقية أن تقرأ الملف قبل أن تشغل الوكيل في مستودع غريب، وأن تشغله في صندوق معزول Sandbox كما شرحنا في [مقال بيئة تشغيل الوكيل](https://arabroot.io/articles/%D8%A8%D9%8A%D8%A6%D8%A9-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84-harness-%D8%A7%D9%84%D8%AD%D9%84%D9%82%D8%A9-%D9%88%D8%A7%D9%84%D8%B5%D9%84%D8%A7%D8%AD%D9%8A%D8%A7%D8%AA-%D9%88%D8%A7%D9%84%D8%B5%D9%86%D8%AF%D9%88%D9%82-%D8%A7%D9%84%D9%85%D8%B9%D8%B2%D9%88%D9%84/).

## أخطاء شائعة

- **ملف طويل فيه كل شيء:** رأينا أن Codex يقطع ما بعد 32 KiB في منتصف الجملة، وأن الملف الطويل يلغي ملفات المجلدات التي تحته، وأنه يضاعف حجم كل طلب، فاكتب القليل المهم.
- **القاعدة المهمة في آخر الملف:** إذا قطع الملف فإن آخره هو ما يضيع، فضع الأوامر والحدود والأمان في أوله.
- **ثلاثة ملفات بالمحتوى نفسه:** `AGENTS.md` و`CLAUDE.md` و`.github/copilot-instructions.md` منسوخة يدوياً تختلف بعد أسابيع، فاجعل واحداً منها المصدر والباقي استيراداً أو إعداداً.
- **نسيان `AGENTS.override.md`:** الملف البديل يلغي الملف الأصلي في مجلده دون أي إشارة، فإذا استعملته لتغيير مؤقت فاحذفه عندما ينتهي سببه.
- **ملف `CLAUDE.local.md` يوقف `AGENTS.md`:** في Claude Code وجود أي ملف CLAUDE في المجلد أو فوقه يجعل الأداة تقرأ ملفات CLAUDE وحدها، فاستورد `@AGENTS.md` أو غير الإعداد.
- **كتابة ما يعرفه النموذج:** النصائح العامة لا تغير سلوكه، والدراسة وجدت أن النظرة العامة على المستودع لا تفيد، فاكتب ما لا يظهر في الكود.
- **الاعتماد على الملف وحده للقواعد الخطيرة:** «لا تدفع إلى main» في ملف التعليمات طلب مهذب، أما المنع الحقيقي فهو حماية الفرع Branch Protection في GitHub وصلاحيات الوكيل، لأن النموذج قد يخالف التعليمات أو لا يراها أصلاً كما حدث في تجربة الحد.

## قائمة التحقق قبل أن تحفظ الملف

- هل أوامر البناء والاختبار مكتوبة كاملة، وهل جربتها بنفسك اليوم؟
- هل كل قاعدة في الملف شيء لا يستطيع الوكيل أن يعرفه من الكود؟
- هل الحدود والأمان في أول الملف، لا في آخره؟
- هل الملف أقل من 200 سطر، وأقل بكثير من 32 KiB مع كل الملفات التي فوقه؟
- هل الأدوات التي يستعملها فريقك كلها تقرؤه، بالاسم أو بالاستيراد أو بالإعداد؟
- هل سألت الوكيل عن تعليماته ورأيت القواعد في رده؟
- هل خلا الملف من الأسرار والعناوين الداخلية؟

## تدريب عملي

1. شغل `bash capture.sh nested` ثم غير مكان التشغيل في السكربت من `services/payments` إلى جذر المستودع، وانظر بالأمر `node inspect.cjs captures/nested.json show` هل ما زالت قاعدة `make test-payments` في الطلب.
2. في تشغيل `big` أضف إلى `config.toml` السطر `project_doc_max_bytes = 65536` وأعد التشغيل: هل وصلت القاعدة الأخيرة وملف المجلد الفرعي؟ وكم توكناً أصبح الطلب؟
3. خذ ملف التعليمات في مشروع حقيقي تعمل عليه، واحذف منه كل سطر يعرفه الوكيل من الكود، ثم أعد تشغيل مهمة عادية وقارن عدد التوكنات المرسلة في الحالتين.

## الخلاصة

- `AGENTS.md` ملف Markdown عادي يقرؤه الوكيل قبل أن يبدأ، وهو اليوم الاسم المشترك بين أغلب الأدوات، تحت رعاية Agentic AI Foundation.
- Codex CLI 0.170.0 جمع الملف الشخصي ثم ملفات المجلدات من الجذر إلى المجلد الحالي في رسالة واحدة، والأقرب آخر ما يقرأ، و`AGENTS.override.md` يلغي الأصلي في مجلده.
- الملف الذي حجمه 40,665 بايت قطع عند 32,768 بايت في منتصف كلمة، وضاعت القاعدة الأخيرة وملف المجلد الفرعي كله، والتحذير ظهر في الطرفية فقط.
- Claude Code يقرأ `CLAUDE.md`، ويقرأ `AGENTS.md` فقط إذا لم يجد أي ملف CLAUDE، والحل الأبسط ملف `CLAUDE.md` فيه `@AGENTS.md`.
- في تجربة Aider 0.86.2 مع qwen2.5-coder:3b ظهرت صيغة النسبة المكتوبة في الملف حرفياً في الكود، وارتفعت مهمة الخصم من 6 إلى 7 فحوص من 9، ولكن مهمة العرض فشلت في الحالات الثلاث، ومهمة الضريبة كتبت في مسار المثال `path/to/`، والملف المنتفخ أعطى النتيجة نفسها بأربعة أضعاف التوكنات.
- رد واحد دون حد لطوله كتب 11,811 توكناً في ساعة، فضع `num_predict` أو ما يشبهه في كل إعداد لنموذج محلي.
- دراسة ETH Zurich في 2026 وجدت أن الملفات لا ترفع نسبة النجاح بشكل عام وترفع الكلفة بأكثر من 20%، ولكن الوكلاء يلتزمون بما فيها، ولذلك اكتب فيه الحد الأدنى غير الظاهر.

وفي المقالات القادمة من هذه المرحلة بإذن الله نتحدث عن السياق كله وليس الملف وحده، وعن المهارات Skills التي تحمل التعليمات عند الحاجة فقط بدل أن تكون في كل طلب، وعن ربط الوكيل بأنظمة الفريق عبر MCP:

[![](https://arabroot.io/content/images/2026/11/context-engineering-cover-cover.webp)دليلهندسة السياق Context Engineering: ما يراه الوكيل وما لا يراهما الذي يرسله الوكيل فعلاً مع طلبك، ولماذا يخطئ النموذج عندما يكون أمامه ملف لا يحتاجه أو سجل طويل أو جلسة قصت من أولها، مع تجارب على نموذج محلي تغير السياق وحده.](https://arabroot.io/articles/%D9%87%D9%86%D8%AF%D8%B3%D8%A9-%D8%A7%D9%84%D8%B3%D9%8A%D8%A7%D9%82-context-engineering-%D9%85%D8%A7-%D9%8A%D8%B1%D8%A7%D9%87-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84/)[![](https://arabroot.io/content/images/2026/11/agent-skills-cover-cover.webp)دليلالمهارات Agent Skills: تعليمات يحملها الوكيل عند الحاجةكيف تكتب مهارة حسب المواصفة المفتوحة، وكيف يعرضها Codex على النموذج، وهل يختار نموذج صغير المهارة الصحيحة من وصفها ويتبع ما فيها.](https://arabroot.io/articles/%D8%A7%D9%84%D9%85%D9%87%D8%A7%D8%B1%D8%A7%D8%AA-agent-skills-%D8%AA%D8%B9%D9%84%D9%8A%D9%85%D8%A7%D8%AA-%D9%8A%D8%AD%D9%85%D9%84%D9%87%D8%A7-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84-%D8%B9%D9%86%D8%AF-%D8%A7%D9%84%D8%AD%D8%A7%D8%AC%D8%A9/)[![](https://arabroot.io/content/images/2026/11/mcp-for-developers-cover-cover.webp)دليلMCP للمطورين: اربط وكيلك بقاعدة البيانات والتذاكر والتوثيقكيف تضيف سيرفر MCP إلى Codex وClaude Code وCursor، وكيف تكتب سيرفراً للفريق يقرأ قاعدة البيانات دون أن يكتب فيها، وكم يكلف كل سيرفر من سياق الوكيل.](https://arabroot.io/articles/mcp-%D9%84%D9%84%D9%85%D8%B7%D9%88%D8%B1%D9%8A%D9%86-%D8%A7%D8%B1%D8%A8%D8%B7-%D9%88%D9%83%D9%8A%D9%84%D9%83-%D8%A8%D9%82%D8%A7%D8%B9%D8%AF%D8%A9-%D8%A7%D9%84%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D9%88%D8%A7%D9%84%D8%AA%D8%B0%D8%A7%D9%83%D8%B1/)[![](https://arabroot.io/content/images/2026/11/spec-driven-development-cover-cover.webp)دليلالتطوير من المواصفة Spec-driven Development: الخطة قبل الكودكيف تعمل Spec Kit من GitHub، وما الفرق بين المواصفة والخطة والمهام، وماذا حدث عندما بنى نموذج محلي صغير الميزة نفسها بثلاث طرق تحت اختبارات قبول لم يرها.](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D8%B7%D9%88%D9%8A%D8%B1-%D9%85%D9%86-%D8%A7%D9%84%D9%85%D9%88%D8%A7%D8%B5%D9%81%D8%A9-spec-driven-development-%D8%A7%D9%84%D8%AE%D8%B7%D8%A9-%D9%82%D8%A8%D9%84-%D8%A7%D9%84%D9%83%D9%88%D8%AF/)

## سجل التحديثات

- 20 نوفمبر 2026: كتابة المقال، وتشغيل المختبر على Codex CLI 0.170.0 مع سيرفر وهمي، وAider 0.86.2 مع Ollama 0.40.13 ونموذج qwen2.5-coder:3b.