CLAUDE.md وAGENTS.md: ما هما، وماذا تكتب فيهما، ولماذا يتجاهل الوكيل القواعد

ما هما CLAUDE.md وAGENTS.md

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

CLAUDE.md هو الملف الذي يقرؤه Claude Code. وAGENTS.md صيغة مفتوحة تقوم على الفكرة نفسها، وتدعمها معظم وكلاء البرمجة. إذا استخدم فريقك عدة وكلاء، فمن الأفضل كتابة المحتوى الأساسي في AGENTS.md، والإشارة إليه من CLAUDE.md. ويدعم Claude Code استيراد ملف آخر باستخدام الرمز @:

# CLAUDE.md
@AGENTS.md

بهذه الطريقة تعيش القواعد في مكان واحد، ولا تختلف بين الملفين.

كيف يقرأ الوكيل هذه الملفات

يدخل محتوى ملف التعليمات إلى نافذة سياق النموذج مع موجّه النظام، ويبقى هناك طوال الجلسة. ومن هنا ثلاث نتائج مهمة.

• كل سطر يشغل مساحة في السياق.يُقرأ الملف كاملًا في كل تشغيل، حتى لو كانت المهمة الحالية تحتاج عُشر محتواه فقط.
• إنه نص، وليس قاعدة قابلة للتنفيذ.يأخذه النموذج في الحسبان كبقية السياق، ولا يوجد ما يضمن الالتزام التام به. القيود الصارمة تحتاج إلى آليات تدعمها: فحوصات، وخطافات، وصلاحيات وصول.
• يمكن تداخل الملفات.يحمّل Claude Code ملف CLAUDE.md من جذر المشروع ومن المجلد الشخصي ~/.claude/، أما الملفات الموجودة في المجلدات الفرعية فتُحمَّل عندما يتعامل الوكيل مع ملفات داخل تلك المجلدات. وهذا يتيح الاحتفاظ بقواعد الوحدة بجانب الوحدة نفسها.

ماذا تكتب في CLAUDE.md وAGENTS.md

ملف التعليمات الجيد خريطة وليس كتابًا مدرسيًا. يجيب عن الأسئلة التي كان الوكيل سيطرحها على زميل خبير في اليوم الأول.

1. كيفية بناء المشروع والتحقق منه

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

2. القيود الصارمة

قائمة قصيرة بما لا يجوز خرقه تحت أي ظرف: ثوابت الأمان والبيانات. اكتبها كثوابت وليس كتعليمات تنفيذ: «كل استعلامات SQL معاملة كمتغيرات» أفضل بكثير من «استخدم الدالة الفلانية في الملف الفلاني».

3. خريطة المشروع

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

4. مكان حفظ حالة العمل

أين ينظر الوكيل ليستأنف من حيث توقفت الجلسة السابقة: ملف الخطة، وسجل التقدم، وقائمة المهام المؤجلة. وهذا يعالج «فقدان الذاكرة» بين الجلسات.

ما الذي لا تكتبه

• ما يستطيع الوكيل قراءته من الشيفرة.قائمة التبعيات موجودة في package.json أو pyproject.toml، وبنية الفئات موجودة في الشيفرة نفسها.
• النصائح العامة.عبارات مثل «اكتب شيفرة نظيفة» أو «كن حذرًا» لا تغيّر السلوك، وتشغل المساحة فقط.
• تاريخ المشروع والملاحظات العابرة.«في مارس انتقلنا من MySQL 5.7» لا تفيد المهمة الحالية.
• التعليمات المفصلة للمهام النادرة.إجراءات النشر أو ترحيل البيانات تُنفَّذ مرة في الأسبوع، فانقلها إلى وثيقة منفصلة أو skill.
• الأسرار.الملف موجود في المستودع ويُرسل كاملًا إلى النموذج. الرموز وكلمات المرور تُحفظ في متغيرات البيئة فقط.

لماذا يتجاهل الوكيل قاعدة مكتوبة في الملف

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

تضخم الملف

ملف من 600 سطر يعادل تقريبًا 10 إلى 20 ألف رمز (token). تبدو نافذة السياق واسعة، لكن الشيفرة ومخرجات الأوامر وسجل المحادثة كلها تتنافس على المساحة نفسها. وكلما زادت مساحة التعليمات قلّ الاهتمام المتاح لكل قاعدة، وقلّت المساحة المتبقية للمهمة نفسها.

القاعدة في منتصف الملف

النماذج اللغوية أقل قدرة على استخدام المعلومات الواقعة في منتصف النص الطويل مقارنةً ببدايته ونهايته. القاعدة في السطر 300 من أصل 600 تقع في أضعف موضع.

غياب الأولويات

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

التعفن

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

الحل: موجّه بدلًا من الكتاب الطويل

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

1. اجعل ملف الدخول موجّهًا.بين 50 و150 سطرًا: أوامر التحقق، والقيود الصارمة، وخريطة المشروع، وروابط الوثائق المتخصصة.
2. انقل المواضيع إلى ملفات مستقلة.مثل docs/agents/deploy.md وdocs/agents/database.md. يفتحها الوكيل عند الحاجة. وفي Claude Code تناسب skills الإجراءات المتكررة، لأنها لا تُحمَّل إلا عند الحاجة.
3. ضع الأهم في الأعلى.القيود الصارمة في بداية الملف، في فقرة قصيرة مستقلة مع وسم واضح MUST.
4. أزل التناقضات.اجعل لكل موضوع قاعدة واحدة. وإذا وُجد استثناء، فاكتبه بجوار القاعدة.
5. ادعم القاعدة بآلية.إذا كان الخرق غير مقبول، فالنص وحده لا يكفي. تحتاج إلى فحص يكتشف الخرق: مدقق، أو اختبار، أو خطاف pre-commit، أو خطاف للوكيل، أو قيد على صلاحيات الوصول.
6. راجع الملف بانتظام.ضع حدًا لعدد الأسطر، وعند كل إضافة اسأل: ما الذي يمكن حذفه أو نقله؟

قاعدة أم فحص؟

مثال على AGENTS.md مختصر

# AGENTS.md — الواجهة الخلفية للدفع (FastAPI، PostgreSQL)

## MUST — لا تُخرق
- المبالغ المالية أعداد صحيحة (int) بالوحدات الصغرى، ولا تُستخدم float أبدًا
- SQL مُعامَل فقط، بلا f-strings
- لا تُعدَّل الترحيلات المطبّقة، أضف ترحيلات جديدة فقط
- الأسرار تُقرأ من متغيرات البيئة فقط

## التحقق قبل كلمة «اكتمل»
docker compose up -d     # البيئة
make lint                # ruff + mypy
make test                # pytest
make e2e                 # سيناريو إتمام الطلب
اختبارات الوحدة الناجحة دون e2e لا تعني «اكتمل».

## الخريطة
- app/payments/   — حساب المبالغ، والخصومات، وwebhooks المزوّد
- app/api/        — نقاط HTTP
- tests/e2e/      — سيناريوهات المستخدم
التفاصيل: docs/agents/architecture.md، docs/agents/database.md

## حالة العمل
- PLAN.md      — الهدف الحالي، ومعايير الإنجاز، والخطوة التالية
- PROGRESS.md  — ما تم وكيف تم التحقق منه، والطرق المسدودة
- BACKLOG.md   — ما لوحظ «على الهامش»: يُسجَّل هنا ولا يُصلَح الآن

في نهاية الجلسة حدّث PROGRESS.md والخطوة التالية في PLAN.md.

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

فقدان الذاكرة: ملف التعليمات وملف الخطة

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

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

كيف تتحقق من أن الملف يعمل

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

الخلاصة

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