كيفية تنظيم ملفات AGENTS.md متداخلة في Monorepo

ماذا يعني وجود ملفات AGENTS.md متداخلة في مستودع أحادي (monorepo)

يعني وجود ملف AGENTS.md متداخل في مستودع أحادي وجود ملف صغير في جذر المستودع وملف آخر داخل كل دليل خدمة. يحتوي ملف الجذر على القواعد القليلة التي تنطبق في كل مكان، بالإضافة إلى خريطة توضح أماكن وجود الملفات الأخرى. يحتوي ملف كل خدمة على الأوامر والاتفاقيات الخاصة بذلك الدليل وحده. عندئذٍ يقرأ الوكيل الذي يقوم بتحرير services/worker/queue.py ملف الجذر وملف العامل، ولا يستهلك أي سياق حول الواجهة الأمامية التي لن يلمسها أبداً.

لا يوجد شيء لتثبيته. ملف AGENTS.md هو مجرد اتفاقية، ويذكر المشروع الأساسي ذلك بوضوح:

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

لهذا السبب تستحق هذه التقنية التعلم بشكل صحيح. لن يتغير التنسيق الذي تعتمد عليه. ما قد يتعطل هو مكان وضع الملفات وصيانتها، وكلاهما من مسؤوليتك.

لماذا يتوقف ملف AGENTS.md واحد كبير في الجذر عن العمل؟

يفشل ملف AGENTS.md واحد بطول 600 سطر في جذر مستودع يحتوي على تطبيق ويب، وعامل خلفي (background worker)، ودليل Terraform، وذلك بأربع طرق منفصلة.

يصبح قديماً لأن أحداً لا يملكه. المهندس الذي يعيد تسمية نص برمجي للاختبار في apps/web يقوم بتعديل ملفات تحت apps/web. ملف AGENTS.md الموجود في الجذر ليس ضمن هذا الفرق (diff)، لذا لا يرى أي مراجع عدم التطابق. بعد ستة أسابيع، يصف الملف خطوة بناء لم تعد موجودة، ويكون الشخص الذي تسبب في كسرها قد نسي التغيير.

يستهلك سياقاً في كل مهمة. تُحمَّل هذه الملفات في بداية الجلسة، قبل أن يعرف الوكيل ما ستطلبه منه. تضع وثائق Claude Code رقماً محدداً لذلك: "استهدف أقل من 200 سطر لكل ملف CLAUDE.md. الملفات الأطول تستهلك المزيد من السياق وتقلل من الالتزام بالتعليمات". يتوقف Codex عن دمج ملفات التعليمات بمجرد وصول حجمها الإجمالي إلى 32 KiB، وهو الإعداد الافتراضي project_doc_max_bytes. ملف الجذر الذي يوثق أربع خدمات ينفق هذه الميزانية على ثلاث منها في كل مهمة فردية.

تبدأ التعليمات في التناقض مع بعضها البعض. دليل الويب يحتاج pnpm test. والعامل يحتاج pytest -q. عند كتابة كل قاعدة في ملف واحد، تصبح صحيحة فقط في بعض الأحيان، لذا يضطر الوكيل لتخمين أي منها ينطبق. تصف وثائق Claude Code النتيجة: "إذا تناقضت قاعدتان، فقد يختار Claude إحداهما بشكل عشوائي". الملف الخاص بكل دليل يزيل هذا التخمين، لأن قاعدة واحدة فقط من القاعدتين تكون موجودة في السياق. عندما يتم تجاهل قاعدة أنت متأكد من أنك كتبتها بوضوح، فإن العمل من خلال أسباب عدم تنفيذ التعليمات أفضل من إعادة صياغة النص للمرة الرابعة.

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

هل يقرأ الوكيل ملف الجذر، أم الأقرب فقط؟

هنا يخطئ معظم الناس في فهم النموذج، لذا يجدر بنا اقتباس الاتفاقية المعتمدة لدى المطورين بدلاً من إعادة صياغتها:

ضع ملف AGENTS.md آخر داخل كل حزمة. يقرأ الوكلاء تلقائياً أقرب ملف في شجرة الدليل، لذا فإن الملف الأقرب هو الذي له الأولوية، ويمكن لكل مشروع فرعي شحن تعليمات مخصصة.

وفيما يخص التعارضات:

الملف الأقرب إلى الملف الذي يتم تحريره هو الذي يسود؛ وتتجاوز مطالبات المستخدم الصريحة في المحادثة كل شيء آخر.

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

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

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

تم التحقق من هذا السلوك مقابل وثائق Codex وClaude Code في أغسطس 2026. تطبق الأدوات هذه الاتفاقية بشكل مختلف قليلاً وهي عرضة للتغيير، لذا تأكد من قواعد التحميل الخاصة بالوكيل الذي يستخدمه فريقك.

تخطيط عملي لمستودع يحتوي على ثلاث خدمات

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

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

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

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

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

ملف العامل (worker) له نفس الهيكل بمحتوى مختلف: أمر التثبيت، pytest -q، والسبب الذي يجعل المستهلك يجب أن يظل متماثلاً (idempotent)، وعملية الترحيل التي يجب تشغيلها قبل اجتياز الاختبارات. ملف البنية التحتية (infra) هو المكان الذي تكتب فيه القواعد التي تمنع الوكيل من إحداث ضرر. لا تقم أبداً بتشغيل terraform apply. قم بتشغيل terraform plan وتوقف عند ذلك، وقم بتسمية الواجهة الخلفية للحالة (state backend) التي تم إعدادها مسبقاً حتى لا يحاول الوكيل تهيئة واحدة جديدة.

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

من المسؤول عن تحديث الملف عند تغيير الكود؟

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

يعمل هذا الإجراء لسبب تقني، وليس لسبب تنظيمي. يظهر الملف الموجود في كل دليل ضمن نفس الـ diff الخاص بالكود، لذا يرى مراجع طلب السحب (pull request) كلا التغييرين معاً. أما ملف الجذر فهو ملك للجميع، مما يعني أنه لا يخص أحداً، ولا يظهر أبداً في الـ diff الذي يراجعه أي شخص حالياً.

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

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

في فرع (branch) أعاد هيكلة عميل API دون تعديل التوثيق، تظهر المخرجات بالشكل التالي:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

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

كيف أكتشف ملف AGENTS.md الذي أصبح قديماً؟

هناك فحصان يمكنك تشغيلهما اليوم، وعرض واحد ستلاحظه أثناء الجلسة.

قارن عمر كل ملف بعمر الكود الذي يصفه. يطبع %cs تاريخ الالتزام (commit) بصيغة YYYY-MM-DD.

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done

apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

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

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

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

اقرأ المخرجات بدلاً من دمج هذا الفحص في CI. كما يقوم هذا الفحص بتمييز الأنماط العامة (globs) مثل src/**/*.ts وأي رابط URL قمت باقتباسه، لأن كلاهما يحتوي على شرطة مائلة (slash) ولا يمثل أي منهما ملفاً على القرص.

العرض الذي يظهر في الجلسة. يقرأ الوكيل الملف، ويحاول فتح src/api/client.ts لأن الملف أمره بذلك، فتعيد الأداة:

No such file or directory

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

هل يقرأ Claude Code ملفات AGENTS.md؟

لا، ويجدر بنا التصريح بذلك بوضوح لأن التخطيط المتداخل يعتمد على هذا الأمر. اعتباراً من أغسطس 2026، تنص الوثائق على ما يلي: "يقرأ Claude Code ملف CLAUDE.md، وليس AGENTS.md." لا يزال النمط يعمل، لكنك تحتاج فقط إلى وضع CLAUDE.md بجانب كل AGENTS.md.

صيغة الاستيراد (import) تكون صحيحة عندما ترغب في إضافة أسطر خاصة بأداة معينة فوق الأسطر المشتركة. ضع هذا في services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

صيغة الرابط الرمزي (symlink) تكون صحيحة عندما لا توجد إضافات خاصة بأداة معينة.

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

لا يطبع ln أي شيء عند نجاحه، لذا تحقق من القائمة عبر: apps/web/CLAUDE.md -> AGENTS.md. بعد ذلك، ابدأ جلسة وشغّل /context، حيث ستظهر الملفات المحمّلة تحت Memory files. على نظام Windows، يتطلب الرابط الرمزي صلاحيات المسؤول أو وضع المطور (Developer Mode)، لذا استخدم استيراد @AGENTS.md هناك بدلاً من ذلك.

هناك فخ واحد يتعلق بهذا الأمر. بعد /compact، يُعاد قراءة الملف الجذري من القرص، لكن الملفات المتداخلة في المجلدات الفرعية لا تُحقن مجدداً. تعود هذه الملفات في المرة التالية التي يقرأ فيها الوكيل ملفاً داخل ذلك المجلد. إذا بدا أن قاعدة خاصة بمجلد معين توقفت عن التطبيق في منتصف جلسة طويلة، فهذا هو السبب عادةً، وسيؤدي لمس (touch) أي ملف في ذلك المجلد إلى استعادتها.

كيف يختلف هذا عن ذاكرة الوكيل أو المهارة؟

تبدو هذه الآليات متشابهة لكنها تفشل بطرق مختلفة تماماً، لذا من الضروري أن تكون دقيقاً بشأن الآلية التي تحتاجها.

ملف AGENTS.md تكتبه أنت، وتلتزم به في git، وتراجعه في pull request، ويكون متطابقاً لكل من يستنسخ المستودع. أما ذاكرة الوكيل (Agent memory) فيكتبها الوكيل، وتُخزّن خارج المستودع، وتكون محلية على جهاز واحد. تضع وثائق Claude Code الخط الفاصل نفسه: ملف CLAUDE.md يحتوي على "التعليمات والقواعد" التي تكتبها أنت، بينما تحتوي الذاكرة التلقائية على "التعلم والأنماط" التي يكتبها Claude، ولا تتم مشاركة دليل الذاكرة بين الأجهزة. الاختبار بسيط: إذا كانت الحقيقة يجب أن تكون صحيحة لزميل يعمل على نسخة مستنسخة حديثاً، فلا يمكن أن توجد في الذاكرة. يغطي كيفية استمرار ذاكرة الوكيل بين الجلسات هذا الجانب من الصورة.

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

تشير المصادر الأولية إلى أنه "في وقت كتابة هذا التقرير، يحتوي مستودع OpenAI الرئيسي على 88 ملف AGENTS.md". هذا الرقم هو الحجة الكاملة. المستودع الكبير لا يحتاج إلى ملف أكبر، بل يحتاج إلى المزيد من الملفات الصغيرة، حيث يوضع كل ملف بجوار الكود الذي يصفه، ويكون كل ملف مسؤولية الشخص الذي أجرى آخر تعديل على ذلك الكود.

FAQ

هل يحل ملف AGENTS.md المتداخل محل الملف الجذري أم يضيف إليه؟

هو يضيف إليه. يقول المصدر الأساسي إن "الملف الأقرب هو الذي يمتلك الأولوية"، وهذا يصف ما يحدث عند حدوث تعارض، لا ما يتم تحميله. يقوم Codex "بدمج الملفات من الجذر نزولاً، وربطها بأسطر فارغة"، بينما يقوم Claude Code بدمج كل ملف يجده أثناء مسح الأدلة بدءاً من دليل العمل بدلاً من استبدالها. الملف الأقرب هو الذي يسود فقط عندما يقدم ملفان تعليمات مختلفة حول الموضوع نفسه. اكتب القواعد المشتركة في الجذر مرة واحدة، ولا تكررها في كل دليل.

ما هو الحجم المناسب لملف AGENTS.md الجذري؟

يجب أن يكون صغيراً بما يكفي لكي لا تمانع إضافته إلى أعلى كل طلب ترسله في ذلك المستودع، لأن هذا هو ما يحدث فعلياً. تقترح وثائق Claude Code استهداف أقل من 200 سطر لكل ملف، وتحذر من أن الملفات الأطول "تقلل من الالتزام". يتوقف Codex عن دمج ملفات التعليمات عند وصولها إلى 32 KiB مجتمعة بشكل افتراضي. إذا كان ملفك الجذري يوثق أربع خدمات، فإن معظمه سيكون عبئاً غير ضروري لأي مهمة فردية. انقل التفاصيل إلى ملفات خاصة بكل دليل واترك خريطة توضيحية في الأعلى.

كيف أمنع هذه الملفات من أن تصبح قديمة؟

ضع قاعدة واحدة في الملف الجذري: أي شخص يغير الكود في دليل ما، عليه تحديث ملف AGENTS.md الخاص بذلك الدليل في نفس الـcommit. وضع الملف بجانب الكود هو ما يجعل القاعدة فعالة، لأن التغيير يظهر في نفس الـpull request diff الذي يراجعه المبرمج بالفعل. أضف تحذيراً في نظام CI يربط كل مسار تم تغييره بأقرب ملف AGENTS.md فوقه، وقارن من حين لآخر git log -1 --format=%cs لكل ملف مقابل نفس الأمر الذي يتم تشغيله على الدليل الذي يوثقه.

هل يقرأ Claude Code ملفات AGENTS.md؟

لا. اعتباراً من أغسطس 2026، تنص الوثائق على أن "Claude Code يقرأ CLAUDE.md، وليس AGENTS.md". أنشئ CLAUDE.md في نفس الدليل مع وضع @AGENTS.md في السطر الأول، مما يؤدي إلى تحميل الملف المشترك ويسمح لك بإضافة تعليمات خاصة بـ Claude تحته. يعمل الرابط الرمزي (symlink) الذي يتم إنشاؤه باستخدام ln -s AGENTS.md CLAUDE.md عندما لا يكون هناك شيء إضافي لإضافته، رغم أنه يتطلب صلاحيات المسؤول أو وضع المطور على نظام Windows. شغّل /context في جلسة عمل وتأكد من ظهور الملف ضمن ملفات الذاكرة (Memory files).

أين أضع قاعدة لا تهم إلا في بعض الأحيان؟

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