كيفية تنظيم ملفات AGENTS.md في المستودعات الأحادية

ماذا يعني وجود ملفات 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)، لذا لا يرى أي مراجع عدم التطابق. بعد ستة أسابيع، يصف الملف خطوة بناء لم تعد موجودة، ويكون الشخص الذي تسبب في كسرها قد نسي التغيير.

يستهلك سياقاً (context) في كل مهمة. تُحمَّل هذه الملفات في بداية الجلسة، قبل أن يعرف الوكيل ما ستطلبه منه. تضع وثائق 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.

ملف العامل له نفس الشكل بمحتوى مختلف: أمر التثبيت، pytest -q، والسبب الذي يجعل المستهلك يجب أن يظل متماثلاً (idempotent)، وعملية الترحيل التي يجب أن تعمل قبل اجتياز الاختبارات. ملف البنية التحتية هو المكان الذي تكتب فيه القواعد التي تمنع الوكيل من إحداث ضرر. لا تقم أبداً بتشغيل 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

على فرع قام بإعادة هيكلة عميل 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 عندما لا يكون هناك شيء إضافي لإضافته، علماً أنه يتطلب صلاحيات المسؤول أو وضع المطور (Developer Mode) على نظام Windows. شغّل /context في جلسة عمل وتأكد من ظهور الملف ضمن ملفات الذاكرة (Memory files).

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

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