كيف تكتب ملفات تعليمات فعالة لوكلاء البرمجة المدعومين بالذكاء الاصطناعي

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

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

تعامل مع السياق بوصفه مورداً محدوداً

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

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

ما الذي ينبغي أن يبقى في الملف؟

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

كما ينبغي توثيق أقصر مسار موثوق للبناء والتحقق، مع الاقتصار على الأوامر التي جرى اختبارها. ومن الأمثلة الواردة في المادة تشغيل dotnet restore App.slnx قبل أول عملية بناء، ثم استخدام dotnet build App.slnx --no-restore، وتشغيل اختبارات محددة عند تغيير واجهات البرمجة، أو أداة التحقق من الملفات المولدة بعد تعديل العقود. ويجب توضيح المتطلبات الخاصة، مثل حاجة اختبارات التكامل إلى Docker وعدم تشغيلها بالتوازي، لأن أمراً غير صحيح يتكرر بثقة أسوأ من غياب الأمر.

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

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

ما الذي يمكن حذفه أو نقله؟

تنصح المادة بحذف النصائح العامة من قبيل كتابة شفرة نظيفة، واتباع أفضل الممارسات، واستخدام أسماء ذات معنى، والتعامل المناسب مع الأخطاء. فهذه العبارات لا تحسم قراراً عملياً، بينما تكون القاعدة المحلية المحددة أكثر فائدة؛ مثل ربط أخطاء التحقق بالاستجابة 400، والموارد غير الموجودة بالاستجابة 404، وتعارضات التزامن بالاستجابة 409 باستخدام أدوات ProblemDetails الموجودة.

ولا تحتاج الملفات عادة إلى جرد شامل للمجلدات، لأن النموذج يستطيع قراءة بنية المستودع بسرعة. كما لا داعي لتكرار قواعد التنسيق التي تفرضها الأدوات، بل يكفي ذكر أمر التحقق المناسب، مثل dotnet format --verify-no-changes. وينبغي تجنب نسخ README وأدلة البنية والمساهمة بالكامل، حتى لا ترتفع كلفة الصيانة أو تظهر تناقضات بين الوثائق.

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

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

اختيار نطاق التعليمات ومراجعتها

ليس كل توجيه مناسباً لملف المستودع العام. تدعم GitHub Copilot تعليمات عامة في .github/copilot-instructions.md، وملفات خاصة بالمسارات تحت .github/instructions/، وتعليمات الوكلاء مثل AGENTS.md. ويُستخدم ملف التعليمات العام مع الملف الخاص بالمسار المطابق عند وجودهما.

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

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

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

جزء من صيانة المشروع

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

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