المشكلة: لماذا يفشل الذكاء الاصطناعي في كتابة الكود دائماً عند نفس النقطة

كل من يستخدم Cursor أو Windsurf أو Claude Code في مشاريعه مر بلحظة الانهيار نفسها: الذكاء الاصطناعي يولّد مقطعاً كاملاً من الكود، تنسخه وتلصقه وتشغّله—فيظهر خطأ في البناء، وفشل في الاختبارات، وتثبيت خاطئ للحزم. المشكلة ليست في ذكاء الـ AI، بل لأنه ببساطة لا يعرف «القواعد غير المكتوبة» لمشروعك.

AGENTS.md هو ملف Markdown تضعه في جذر المشروع، مكتوب خصيصاً ليقرأه الذكاء الاصطناعي، يخبره كيف يبني، كيف يختبر، وأي معايير يتبع. ملف README.md موجه للبشر، مليء بمقدمة المشروع وإرشادات المساهمة وقصة العلامة التجارية. حين يقرأ الـ AI هذه المحتويات، يشبه موظفاً جديداً في يومه الأول يُلقي بين يديه كتيباً دعائياً للشركة ثم يُطلب منه كتابة كود فوراً—يعرف ماذا تفعل الشركة، لكنه لا يعرف أمر البناء، ولا كيف تُشغّل الاختبارات، ولا قواعد ESLint. النتيجة أنك تعيد التصحيح في كل محادثة: «استخدم pnpm وليس npm»، «الاختبارات في packages/web»، «لا تنسَ تشغيل lint». تكرر التصحيح مئة مرة، والمشروع يبقى فوضوياً.

الخسارة في مشاريع الفريلانس أوضح: استلمت مشروع Next.js + Prisma، استخدمت Cursor للتسريع، فإذا بالـ AI ينفّذ npm install فيُفسد إعدادات pnpm workspace بالكامل؛ ولا يعرف أين مخطط قاعدة البيانات، فيولّد ملفات migration فيها أخطاء مباشرة. العميل يضغط للتسليم، وأنت تقضي ثلاث ساعات في إصلاح كود ولّده الذكاء الاصطناعي—أجر مُرهق.

ثلاثة سيناريوهات نموذجية لفشل الـ AI بسبب جهله بقواعد المشروع: ① مدير الحزم خاطئ (المشروع يستخدم pnpm والـ AI ينفّذ npm install افتراضياً)، فالحزم تُثبّت في مكان خاطئ وworkspace يتعطل؛ ② مدخل الاختبارات مفقود (اختبارات المشروع في packages/web، والـ AI يشغّل pnpm test من الجذر فتظهر رسالة «لم يُعثر على ملفات اختبار»); ③ أسلوب الكود غير متسق (المشروع يستخدم ESLint + Prettier، والكود الذي يولّده الـ AI به مسافات وعلامات اقتباس خاطئة فيفشل CI مباشرة.

الفرصة: AGENTS.md يفصل بين «وثائق البشر» و«وثائق الآلة» بشكل قاطع

مشروع AGENTS.md مفتوح المصدر على GitHub (الرابط github.com/agentsmd/agents.md، حتى 2026-08-25 تقريباً 24 ألف نجمة) يعالج هذه المشكلة بالضبط. فكرته بسيطة جداً: ضع ملف Markdown في جذر المشروع، يخبر الذكاء الاصطناعي صراحة كيف يبني، كيف يختبر، وأي أسلوب كود يتبع.

هذا الملف ليس بديلاً عن README، بل مُكمّل له. README يخدم المساهمين البشر، وAGENTS.md يخدم عملاء الذكاء الاصطناعي. كل منهما له دور واضح ولا يتداخلان.

حسب المصدر الأصلي، اعتمدت عشرات الآلاف من مشاريع المصدر المفتوح ملف AGENTS.md (الرقم الدقيق يحتاج تحقق)، ويغطي أدوات البرمجة بالذكاء الاصطناعي الرئيسية مثل VS Code وCursor وWindsurf وAider وGitHub Copilot (تأكيد مُوثّق)؛ كما تشير ردود فعل المجتمع إلى دعم OpenAI Codex وGoogle Jules أيضاً (⚠️ غير مُحقق). إن لم تتعلمه الآن، فأنت تترك الذكاء الاصطناعي يكلّمك بلهجة لا تفهمها.

المسار الأول: اكتب يدوياً ملف AGENTS.md بأقل محتوى ممكن

التكلفة شبه صفر. أنشئ ملفاً جديداً واكتب ثلاثة أقسام وستكفي.

مقدمة سريعة: الأمثلة التالية تستخدم pnpm (أخف على القرص من npm ويدعم monorepo workspace)، وturbo أداة لتنظيم مهام monorepo، ومعامل --filter يحدد حزمة فرعية واحدة فقط دون التأثير على كامل المستودع.

القسم الأول «Dev environment tips»: أخبر الـ AI أي مدير حزم يستخدم، كيف يقفز إلى حزمة فرعية، كيف ينشئ وحدة جديدة. مثلاً من المثال الرسمي:

• pnpm dlx turbo run where <project_name> — ينقلك مباشرة إلى مجلد الحزمة الفرعية دون الحاجة لـ ls والبحث يدوياً
• pnpm install --filter <project_name> — يثبّت تبعيات حزمة فرعية واحدة فقط دون لمس كامل monorepo
• pnpm create vite@latest <project_name> -- --template react-ts — ينشئ حزمة React + Vite جديدة مع فحص TypeScript

هذه الأوامر لا يستطيع الـ AI تخمينها، لكنك حين تكتبها ينفّذها حرفياً.

القسم الثاني «Testing instructions»: وضّح للـ AI كيف تُشغّل الاختبارات، أين خطة CI، وما يجب تشغيله قبل كل commit. المثال الرسمي يتضمن:

• pnpm turbo run test --filter <project_name> — يشغّل جميع فحوصات حزمة فرعية محددة
• pnpm vitest run -t "<test name>" — يشغّل اختباراً واحداً فقط يطابق اسماً معيناً
• «Fix any test or type errors until the whole suite is green» — لا تتوقف حتى تخضر جميع الاختبارات
• «Add or update tests for the code you change, even if nobody asked» — هذه الجملة حاسمة، بدونها كثيراً ما يتكاسل الـ AI عن كتابة الاختبارات

القسم الثالث «PR instructions»: حدّد صيغة عنوان الـ commit، وألزم تشغيل lint وtest. المثال الرسمي: Title format: [<project_name>] <Title>، و«Always run pnpm lint and pnpm test before committing».

هذه الأقسام الثلاثة لا تتجاوز 50 سطراً، لكنها ترفع بشكل ملحوظ نسبة نجاح الكود الذي يولّده الـ AI من أول مرة (حسب ردود فعل المجتمع، الأرقام الدقيقة تحتاج تحقق).

المسار الثاني: الاستخدام المتداخل في monorepo ضخم

لو استلمت مشروعاً مؤسسياً كبيراً، وقاعدة الكود فيه monorepo (عدة مشاريع مترابطة في مستودع Git واحد، مثل مجلد للواجهة، وآخر للخلفية، وثالث للكود المشترك)، فلن يكفي ملف AGENTS.md واحد. AGENTS.md يدعم التداخل: ضع نسخة مخصصة في كل مجلد فرعي، والـ AI يقرأ تلقائياً «أقرب ملف إليه».

التطبيق العملي: AGENTS.md في الجذر يكتب القواعد العامة (مدير الحزم، سير CI، ملاحظات الأمان)، ثم ضع نسخة في packages/web/ وpackages/api/ وpackages/shared/، تكتب فيها أوامر البناء الخاصة بهذه الحزمة، ومدخل الاختبار، والتبعيات الخاصة. مثلاً حزمة الواجهة تحتاج: «مكتبة المكونات shadcn، التنسيق Tailwind، الأيقونات lucide-react»؛ وحزمة الخلفية تحتاج: «ترحيل قاعدة البيانات عبر Prisma، مسارات API في src/routes، المصادقة عبر JWT».

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

المسار الثالث: حوّله إلى ميزة تنافسية في عروض الفريلانس

سوق الفريلانس بالذكاء الاصطناعي أصبح ساحة احتكاك شرسة—الجميع يستخدم Cursor، لكن جودة التسليم متفاوتة. لو كتبت في عرض السعر جملة واحدة: «هذا المشروع مُهيأ بوثيقة AGENTS.md المعيارية، والتطوير بمساعدة الذكاء الاصطناعي يتبع معايير المشروع»، سترتفع نسبة فوزك بالعروض مقارنة بمن يقول فقط «أستخدم الذكاء الاصطناعي في كتابة الكود».

الأسلوب العملي: بعد استلام المشروع، اقضِ 30 دقيقة في فهم بنية كود العميل، ثم اكتب AGENTS.md مخصصاً. هذه الوثيقة نفسها جزء من التسليم—العميل يستلمها ويستفيد منها لاحقاً حين يستخدم الذكاء الاصطناعي لصيانة الكود بنفسه.

ضع سعراً مستقلاً لخدمة إعداد AGENTS.md (مرجع تسعير، عدّل حسب السوق المحلي): النسخة الأساسية 70 دولاراً (ملف واحد + شرح README)، النسخة المؤسسية 450 دولاراً (monorepo متداخل + معايير أمان + تدريب فريق). قائمة التسليم: ① ملف AGENTS.md مخصص ② دعم عبر واتساب لمدة 30 يوماً ③ فيديو تدريب مدته 10 دقائق. مناسب لـ: عملاء لديهم اشتراك Cursor/Windsurf لكن لا يستخرجون منه نتائج. غير مناسب لـ: عملاء لا يزالون يعملون يدوياً بالكامل ولم يدمجوا أدوات الذكاء الاصطناعي.

دراسة حالة: خندق توافق AGENTS.md

AGENTS.md مرخص بموجب MIT (تأكيد من المصدر)، يديره المجتمع (هيكل الحوكمة الدقيق يحتاج تحقق)، والموقع الرسمي agents.md.

التوافق هو أكبر خندق له: تأكيد مُوثّق أن VS Code وCursor وWindsurf وAider وGitHub Copilot جميعها تقرأ AGENTS.md؛ وتشير ردود فعل المجتمع إلى دعم OpenAI Codex وClaude Code وGemini CLI وGoogle Jules أيضاً (⚠️ غير مُحقق). هذا يعني أنك تكتب ملفاً واحداً ويستفيد منه كل مساعد ذكاء اصطناعي رئيسي—لا حاجة لكتابة إعدادات منفصلة لكل أداة.

قارن بالحلول الأخرى: ملف .cursorrules في Cursor يعمل فقط على Cursor، انتقل إلى Windsurf فيُصبح عديم الجدوى؛ وCLAUDE.md في Claude Code يخدم Claude فقط؛ ونظام تعليمات GitHub Copilot منظومة منفصلة أخرى. خاصية «اكتب مرة واحدة، شغّل في كل مكان» في AGENTS.md هي السبب الجذري وراء اعتماده الواسع خلال فترة قصيرة.

تكلفة الانتقال بين الأدوات صفر. اليوم تستخدم Cursor، وغداً تنتقل إلى Windsurf، وAGENTS.md يُعاد استخدامه مباشرة دون إعادة كتابة القواعد.

دعوة للعمل: أضف دليل الآلة لمشروعك الليلة

قائمة إجراءات في 5 دقائق: ① افتح جذر المشروع ② أنشئ AGENTS.md ③ انسخ القالب الرسمي (github.com/agentsmd/agents.md) ④ أدخل ثلاثة أوامر (البناء، الاختبار، lint) ⑤ راقب النتائج في المرة القادمة التي تطلب فيها من الذكاء الاصطناعي كتابة كود.

لو كنت تستخدم monorepo، فخصص 20 دقيقة إضافية الليلة لإضافة نسخة متداخلة لكل حزمة فرعية. حين تبدأ العمل غداً ستلاحظ أن الكود الذي يولّده الـ AI لم يعد يحتاج تصحيحاً متكرراً منك.

AGENTS.md حالياً أعلى إعداد برمجي بالذكاء الاصطناعي من حيث العائد على الاستثمار—30 دقيقة استثمار، مقابل ساعات من وقت الـ debug كل شهر.