ملف AGENTS.md: كيف تضع قواعد واضحة لمساعد البرمجة بالذكاء الاصطناعي؟

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

الملف الذي نشرحه هنا يقدم نموذجًا لهذه القواعد باسم AGENTS.md. فكرته أن تمنح المساعد دليلًا للعمل داخل المشروع، بدل تكرار التعليمات نفسها في كل مهمة.

ما الذي يحتويه هذا الملف؟

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

ومن أهم المبادئ التي يتضمنها:

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

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

أول خطوة: تعريف المشروع بمعلومات مؤكدة

يتضمن النموذج جدولًا لملف المشروع: المستخدمون المستهدفون، أنظمة التشغيل، مدير الحزم، أوامر التشغيل والبناء، الاختبارات، وحدود البنية.

لكن هذه الخانات مكتوبة بصيغة «غير محدد». وهذه نقطة مهمة: الملف قالب عام، وليس وصفًا جاهزًا لمشروعك.

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

يمكن مثلًا تسجيل أمر اختبار موثّق، والمجلد الذي يُنفذ منه، وأي متطلبات لازمة لتشغيله.

كيف يوجّه المساعد أثناء تعديل الكود؟

لنفترض أنك طلبت إصلاح مشكلة في حساب إجمالي فاتورة.

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

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

الهدف هنا هو ربط كل تعديل بالمشكلة التي يحلها، وتجنب إعادة ترتيب أجزاء واسعة من المشروع دون حاجة.

لماذا يركز الملف على أدلة التحقق؟

من أقوى تعليمات النموذج أنه يمنع إعلان نجاح اختبار أو بناء أو تكامل دون مشاهدة نتيجته.

قراءة الكود قد تعطي انطباعًا بأنه صحيح، لكنها لا تعني أن التطبيق شُغّل. ونجاح اختبار محلي لا يثبت أن اتصالًا بخدمة خارجية يعمل.

لذلك ينبغي أن يكون تقرير الإنجاز محددًا، مثل:

تم تعديل حساب الإجمالي، واجتازت الاختبارات المرتبطة به. لم يُختبر الاتصال بخدمة الدفع لعدم توفر بيئة الاختبار.

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

العمل المحلي والصلاحيات الخارجية

يفصل النموذج أيضًا بين تنفيذ التعديلات المحلية والإجراءات التي تؤثر خارج المشروع.

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

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

كيف تستفيد من النموذج في مشروعك؟

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

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

قيمة AGENTS.md تأتي من دقة محتواه وقابليته للتطبيق. عندما يوضح طريقة العمل وحدود الصلاحيات ومعايير التحقق، يصبح التعاون مع مساعد البرمجة أسهل في المراجعة، وتصبح نتائج المهام أوضح لصاحب المشروع.