SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor · آخر تحديث في 2026-10-28

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

تجنب استهلاك سياق غير ضروري في المستودعات الكبيرة عبر توزيع ملفات 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 إحداهما بشكل عشوائي". تقسيم الملف لا يمنع القاعدة الأخرى من الدخول في السياق. يقوم Claude Code بدمج كل ملف تعليمات قام بتحميله بدلاً من السماح لملف واحد باستبدال الآخر، لذا يظل الملف الجذري موجوداً دائماً، وبمجرد أن يفتح الوكيل ملفات في كل من apps/web و services/worker، يستقر ملفا الدليلين معاً في السياق. ما يفعله الملف الخاص بكل دليل هو ربط كل قاعدة بالدليل الذي تحكمه. سمِّ الدليل في أعلى الملف، كما تفعل الأمثلة أدناه مع # apps/web، وسيظل كل أمر يوضح مكانه عند تحميل عدة ملفات في وقت واحد. عندما يتم تجاهل قاعدة أنت متأكد من أنك كتبتها بوضوح، فإن العمل من خلال أسباب عدم تنفيذ التعليمات أفضل من إعادة صياغة النص للمرة الرابعة.

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

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

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

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

وفيما يتعلق بالتعارضات:

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

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

يوضح Codex هذه الآلية صراحةً: «يضم Codex الملفات من الجذر نزولاً، ويفصل بينها بأسطر فارغة. تتجاوز الملفات الأقرب إلى مجلدك الحالي الإرشادات السابقة.» ويسلك Claude Code المسار نفسه. عند بدء الجلسة، يقرأ «كل AGENTS.md و.claude/AGENTS.md في مجلد العمل والمجلدات التي تعلوه»، وتوضح وثائقه نموذج التحميل بعبارة مباشرة: «تُضمَّن كل الملفات المكتشفة في السياق بدلاً من أن تحل محل بعضها.» أما المجلدات الموجودة أسفل مجلد العمل فتتصرف بشكل مختلف: يحمّل Claude Code ملف AGENTS.md في المجلد الفرعي عند الطلب، «عندما يفتح Claude ملفاً هناك باستخدام أداة Read».

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

جرى التحقق من هذا السلوك بالرجوع إلى وثائق Codex وClaude Code في 27 أكتوبر 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) ولا يمثل أي منهما ملفاً على القرص. في إصدار Claude Code v2.1.283 أو أحدث، يقوم /doctor prompt-audit بتشغيل تمريرة مشابهة لك: فهو يبحث عن "إشارات إلى ملفات أو أوامر غير موجودة" وعن ملفات تتناقض مع بعضها البعض، ويغطي ملفات AGENTS.md الخاصة بك افتراضياً، ولا يغير شيئاً حتى تطلب منه تطبيق التعديلات التي يقترحها.

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

No such file or directory

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

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

نعم، منذ Claude Code v2.1.277. وهذه القاعدة الدقيقة مهمة لأن التخطيط المتداخل يعتمد عليها. تم التحقق من ذلك مقابل الوثائق في 27 أكتوبر 2026: "يمكن لـClaude Code قراءة AGENTS.md باعتبارها تعليمات مشروعك، لذلك يعمل المستودع المهيأ مسبقاً لوكلاء برمجة آخرين من دون إضافة CLAUDE.md أو استيراد أو إعداد." قيمة Project instructions الافتراضية، claude-md-or-agents-md، تقرأ "ملفات AGENTS.md عندما لا يكون لديك CLAUDE.md أو CLAUDE.local.md في دليل العمل أو في أي دليل أعلى منه." وتشمل ذلك الملفات المتداخلة أيضاً: يقرأ Claude ملف AGENTS.md في دليل فرعي "عندما يفتح Claude ملفاً هناك باستخدام أداة Read"، ما دام "ذلك الدليل الفرعي لا يحتوي على أي من ملفات CLAUDE.md الثلاثة الخاصة به". وهذه الملفات الثلاثة هي CLAUDE.md و.claude/CLAUDE.md وCLAUDE.local.md، لذلك يكفي وجود CLAUDE.local.md شخصي في apps/web لمنع تحميل apps/web/AGENTS.md.

وهذا يحوّل النصيحة القديمة بوضع CLAUDE.md بجانب كل AGENTS.md إلى فخ. عند وجود AGENTS.md وCLAUDE.md أو CLAUDE.local.md في دليل العمل أو في أي دليل أعلى منه، تقول الوثائق إن Claude يقرأ "ملفات CLAUDE.md الخاصة بك فقط". وينطبق الأمر نفسه على .claude/CLAUDE.md. يخفي ملف مرافق واحد في الجذر، يحتوي على سطر واحد خاص بـClaude، كل AGENTS.md الموجودة في المسار، ويفعل CLAUDE.local.md الشخصي الشيء نفسه. إذا أردت الاحتفاظ بواحد منهما، فاكتب /config واضبط Project instructions على claude-md-and-agents-md، الذي يقرأ كليهما، بحيث يقرأ CLAUDE.md لكل دليل أولاً ثم AGENTS.md بعده.

لا يؤكد رقم الإصدار وحده نجاح العملية. تحتاج إلى v2.1.277 أو إصدار أحدث، لكن قبل v2.1.281 كانت بعض الجلسات، مثل الجلسات على Amazon Bedrock أو مع تعطيل القياس عن بُعد، تقرأ ملفات CLAUDE.md فقط. وفي بعض الحالات، تتجاوز الجلسة الأولى بعد الترقية من v2.1.276 أو إصدار أقدم AGENTS.md أيضاً؛ إذ تقول الوثائق: "يقرأ Claude AGENTS.md بدءاً من جلستك التالية." لذلك تحقّق من الجلسة نفسها. في الجلسة التفاعلية، يطبع Claude Code سطراً مثل no CLAUDE.md found; AGENTS.md loaded: متبوعاً بالمسار، وفي الإصدارات الحالية يعرض /memory الملف. قبل v2.1.280، لم يكن /memory و/context يعرضان AGENTS.md الذي قرأه Claude مباشرة، لذلك اسأل Claude في تلك الإصدارات عن محتوى تعليمات المشروع.

يبقى أسلوب الاستيراد صحيحاً عندما يتعذر على Claude قراءة AGENTS.md مباشرة: في إصدار أقدم، أو في جلسة قبل v2.1.281 على Amazon Bedrock أو مع تعطيل القياس عن بُعد، أو في جلسة عُطّل فيها المكوّن الإضافي المضمّن الذي يقرأه، أو في مشروع يحتفظ بملف CLAUDE.md مع ضبط Project instructions على claude-md. ضع ما يلي في services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

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

يكون أسلوب الرابط الرمزي مناسباً عندما لا توجد إضافة خاصة بأداة معينة.

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، يحتاج الرابط الرمزي إلى صلاحيات Administrator أو إلى تفعيل Developer Mode. كما أن Git يتحقق من الرابط الرمزي الملتزم به على أنه ملف نصي عادي ما لم يكن core.symlinks مفعّلاً، وبذلك تصبح في تلك النسخة المستنسخة قيمة CLAUDE.md المكونة من سطر واحد بدلاً من تعليماتك. إذا كان أي شخص يستنسخ المستودع ويعمل على Windows، فاستخدم استيراد @AGENTS.md. وإذا أعددت أياً من الحلين البديلين قبل أن يقرأ Claude Code AGENTS.md تلقائياً، فيمكنك تركه؛ إذ تقول الوثائق إن إبقاء الاستيراد "لا يجعل Claude يقرأ AGENTS.md مرتين أبداً"، وإن CLAUDE.md المرتبط برابط رمزي يُقرأ مرة واحدة.

هناك فخ آخر يرتبط بهذا الأمر. بعد /compact، يُعاد قراءة CLAUDE.md الموجود في جذر المشروع من القرص، لكن لا تُحقن الملفات المتداخلة في الأدلة الفرعية مرة أخرى. يعيد Claude Code تحميلها عند الطلب، في المرة التالية التي يعمل فيها الوكيل على ملف في ذلك الدليل. توضح الوثائق ذلك لملفات CLAUDE.md، ولا تصف الضغط بشكل منفصل لملف AGENTS.md المقروء مباشرة، لذلك توقّع أن تتصرف الملفات المتداخلة من كلا الاسمين بهذه الطريقة. إذا بدا أن قاعدة خاصة بدليل معين توقفت عن التطبيق في منتصف جلسة طويلة، فهذا هو السبب عادةً، وتؤدي قراءة أي ملف في الدليل إلى إعادتها.

إعدادات توجّه الوكلاء الآخرين إلى AGENTS.md

يقرأ Codex ملف AGENTS.md أصلاً. وفي كل مستوى، يبحث أولاً عن AGENTS.override.md، ما يتيح للدليل استخدام تجاوز محلي دون تعديل الملف المشترك. ويتوقف عن الدمج عندما يصل الحجم المجمع إلى 32 KiB، وهي قيمة project_doc_max_bytes الافتراضية، وهذا سبب إضافي للإبقاء على ملف الجذر صغيراً.

يتعامل Aider معه عبر .aider.conf.yml باستخدام السطر read: AGENTS.md.

يتعامل Gemini CLI معه عبر .gemini/settings.json باستخدام { "context": { "fileName": "AGENTS.md" } }.

توثّق المنبع إعادة تسمية متوافقة مع الإصدارات السابقة للمستودعات التي ما زالت تستخدم الاسم المفرد الأقدم: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

في مستودع monorepo كبير جداً، يتجاوز إعداد claudeMdExcludes في Claude Code ملفات الأسلاف حسب المسار أو glob، وهذا مفيد عندما يقع دليل فريق آخر فوق دليلك. وتنطبق أنماطه أيضاً على ملفات AGENTS.md التي يقرأها Claude Code.

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

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

ملف 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 المتداخل الملف الجذري أم يُضاف إليه؟

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

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

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

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

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

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

نعم، بدءاً من v2.1.277. وفقاً للوثائق التي جرى التحقق منها في 27 October 2026، يقرأ Claude Code AGENTS.md افتراضياً عندما لا يكون لديك CLAUDE.md أو CLAUDE.local.md في دليل العمل أو في دليل أعلى منه، ويقرأ AGENTS.md الخاص بدليل فرعي عندما يفتح ملفاً فيه باستخدام أداة Read، ولا يحتوي ذلك الدليل الفرعي على CLAUDE.md أو .claude/CLAUDE.md أو CLAUDE.local.md خاص به. لا تضف CLAUDE.md بجانب كل AGENTS.md؛ فعند وجود واحد في دليل العمل أو أعلى منه، يقرأ Claude «ملفات CLAUDE.md الخاصة بك فقط». إذا كنت تحتاج إلى CLAUDE.md أيضاً، فاضبط Project instructions على claude-md-and-agents-md في /config، أو ضع @AGENTS.md في سطره الأول. شغّل /memory في جلسة، وتحقق من ظهور مسار AGENTS.md في القائمة.

أين أضع قاعدة لا تنطبق إلا أحياناً؟

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

هل كان هذا المقال مفيدًا؟