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

الملف الصغير الذي يجعل وكلاء البرمجة بالذكاء الاصطناعي أكثر موثوقية

وصف Meta:
وكلاء البرمجة بالذكاء الاصطناعي مثل Claude Code و Codex و Cursor يصبحون أكثر فاعلية عندما يحصلون على قواعد واضحة داخل المشروع. تعرّف كيف يمكن لملفات تعليمات بسيطة مثل CLAUDE.md و AGENTS.md أن تحسّن جودة التطوير بمساعدة الذكاء الاصطناعي.

المقدمة

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

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

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

ملف تعليمات صغير يمكن أن يغيّر هذا السلوك بشكل كبير.

ما هو ملف CLAUDE.md أو AGENTS.md؟

ملف CLAUDE.md هو ملف Markdown يحتوي على تعليمات دائمة مخصصة لمشروع معين، يستخدمها Claude Code لفهم طريقة العمل داخل هذا المشروع.

بنفس الفكرة، يستخدم OpenAI Codex ملفًا باسم AGENTS.md. كما أن Cursor وأدوات أخرى تدعم قواعد مشابهة للمشاريع.

اسم الملف ليس هو الأهم. الفكرة الأساسية هي أن هذا الملف يعمل كدليل تشغيل صغير لوكيل البرمجة بالذكاء الاصطناعي.

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

يمكن لملف التعليمات أن يوضح:

• كيف يجب على الوكيل فحص الكود قبل التعديل؛

• ما هي حدود المعمارية التي يجب احترامها؛

• ما هي أوامر الاختبار أو الفحص التي يجب تشغيلها بعد التعديل؛

• متى يجب أن يسأل قبل المتابعة؛

• ماذا يعني أن تكون المهمة “منتهية” داخل هذا الفريق؛

• ما هي الملفات أو السلوكيات التي لا يجب تغييرها بدون موافقة.

بهذا الشكل، لا يصبح الوكيل أسرع فقط، بل يصبح أكثر قابلية للمراجعة وأكثر التزامًا بطريقة عمل الفريق.

المشكلة الحقيقية: وكلاء الذكاء الاصطناعي متحمسون أكثر من اللازم

كثير من المطورين يعطون وكلاء البرمجة أوامر مثل:

“أضف هذا الـ endpoint.”
“أصلح خطأ التحقق.”
“حسّن هذا الاستعلام.”
“ابنِ هذه الميزة.”

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

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

في المشاريع الحقيقية، هذا قد يؤدي إلى مشاكل مثل:

• تعديل خمس ملفات رغم أن التغيير المطلوب بسيط؛

• استبدال نمط موجود في المشروع بنمط أحدث لكنه غير ضروري؛

• إضافة dependency جديدة رغم أن الإطار المستخدم يوفر الحل بالفعل؛

• إعادة هيكلة كود غير متعلق بالمهمة؛

• عدم تشغيل الاختبارات المناسبة؛

• إخفاء عدم التأكد خلف ملخص واثق جدًا.

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

لماذا القواعد القصيرة أفضل من الـ prompts الطويلة؟

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

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

القواعد القصيرة والواضحة عادةً تكون أفضل.

بدلًا من:

اكتب كود عالي الجودة.

اكتب:

اقرأ الملفات والاختبارات المتعلقة بالمشكلة أولًا، ثم اشرح السبب المتوقع قبل تعديل الكود.

بدلًا من:

تجنب التعقيد الزائد.

اكتب:

لا تضف abstraction جديدًا إذا كانت البنية الحالية قادرة على حل المتطلب بشكل واضح.

بدلًا من:

اختبر عملك.

اكتب:

شغّل أقرب اختبار متعلق بالتغيير أولًا، واذكر بوضوح ما لم تتمكن من التحقق منه.

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

القاعدة الأولى: افهم قبل أن تكتب الكود

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

في خطأ متعلق بالـ backend مثلًا، قد يحتاج إلى مراجعة:

• Route؛

• Middleware؛

• Controller؛

• Service أو Action؛

• Model logic؛

• Migrations أو database constraints؛

• الاختبارات الموجودة؛

• شكل الـ response المتوقع.

بعد ذلك فقط، يجب أن يكتب خطة تنفيذ قصيرة.

قاعدة مفيدة يمكن وضعها في ملف التعليمات:

قبل تعديل الكود، اشرح السبب المتوقع للمشكلة، اذكر الملفات المتأثرة، ووضح كيف سيتم التحقق من الحل.

هذه القاعدة تقلل الافتراضات الخاطئة قبل أن تتحول إلى كود.

القاعدة الثانية: اختر الحل الأبسط

نماذج الذكاء الاصطناعي تعرف الكثير من الأنماط البرمجية الحديثة: Factories، Interfaces، Events، Listeners، Repositories، Pipelines، Services، وملفات Config.

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

ليس كل تعديل صغير يحتاج إلى معمارية جديدة.

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

البساطة لا تعني الضعف. البساطة تعني أن الحل يلبي المتطلب الحالي بأقل قدر ضروري من التعقيد، وبطريقة تناسب الكود الموجود.

قاعدة جيدة:

اختر أبسط حل يلبي المتطلب الحالي ويتبع أنماط المشروع الموجودة.

القاعدة الثالثة: اجعل التعديل دقيقًا ومحدودًا

التعديل الجيد من وكيل الذكاء الاصطناعي ليس بالضرورة أن يكون أقصر تعديل، لكنه يجب أن يكون مركزًا.

التعديل الدقيق يغير فقط ما هو ضروري لحل المشكلة، ولا يوسّع نطاق المهمة بدون سبب.

أحيانًا قد يحتاج الحل الصحيح إلى أكثر من ملف: migration، validation، test، وربما documentation. المهم أن يكون لكل تغيير سبب واضح.

يجب على الوكيل تجنب:

• تغييرات formatting غير ضرورية؛

• refactoring لكود غير متعلق بالمشكلة؛

• تغيير public APIs بدون موافقة؛

• إعادة تسمية أشياء بدون قيمة وظيفية؛

• حذف كود يبدو غير مستخدم لكنه قد يكون مهمًا؛

• إنشاء مسارات معمارية موازية.

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

قاعدة قوية:

نفّذ أصغر diff متماسك يحل المشكلة بشكل صحيح. لا تعيد هيكلة كود غير متعلق بالمهمة إلا إذا طُلب منك ذلك صراحة.

القاعدة الرابعة: لا تقل “تم” قبل التحقق

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

بعد كل تعديل، يجب على الوكيل توضيح ما الذي تم التحقق منه.

حسب نوع المشروع، يمكن أن يشمل ذلك:

• أقرب Unit أو Feature Test متعلق بالتغيير؛

• مجموعة الاختبارات المتأثرة؛

• Static analysis؛

• Linting؛

• Formatting؛

• مراجعة الـ final diff؛

• توضيح ما لم يتم التحقق منه.

الشفافية هنا مهمة جدًا. من الأفضل أن يقول الوكيل:

اختبار منع تكرار الاشتراكات نجح. لم يتم تشغيل كامل test suite. لم أتمكن من التحقق من queue jobs المتعلقة بـ Redis محليًا.

هذا أفضل بكثير من:

Done, everything works.

مثال من مشروع Laravel

تخيل أن فريقًا يريد منع إنشاء سجلات Subscription مكررة.

وكيل متحمس أكثر من اللازم قد يعيد بناء الـ Service، يضيف Repository Layer، ويتحقق من التكرار باستخدام Query داخل التطبيق. هذا الحل قد يبدو صحيحًا، لكنه قد يفشل عند وجود requests متزامنة.

وكيل موجه بتعليمات أفضل سيقرأ أولًا الـ migrations، الـ model، الـ service، الـ controller، والاختبارات. بعدها قد يدرك أن قاعدة البيانات هي المكان الصحيح لفرض هذا الشرط بشكل موثوق.

الحل الأفضل غالبًا سيكون:

• إضافة composite unique index؛

• تحويل خطأ قاعدة البيانات إلى validation response متوافق مع المشروع؛

• الحفاظ على بنية الـ service الحالية؛

• إضافة feature test لحالة التكرار؛

• تجنب أي تغيير معماري غير ضروري.

في مشاريع Laravel تحديدًا، يمكن أن تكون القواعد التالية مفيدة جدًا:

• استخدام Form Requests للتحقق من طلبات HTTP؛

• الحفاظ على أنماط Service و Resource الموجودة؛

• تجنب تنفيذ Queries داخل loops؛

• حماية القواعد الحرجة باستخدام database constraints؛

• عدم تعديل migrations منشورة سابقًا، بل إنشاء migration جديد؛

• عدم إضافة dependencies جديدة بدون موافقة؛

• احترام شكل الـ response الحالي.

كيف تستخدم الفرق هذه الملفات في المشاريع الحقيقية؟

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

إذا كان الفريق يكرر دائمًا: “لا تعدل الملفات generated”، فهذه قاعدة يجب وضعها في ملف التعليمات.

إذا كان كل prompt يكرر نفس أمر الاختبار، يجب توثيق هذا الأمر في الملف.

إذا كان هناك نمط معماري مهم يجب احترامه دائمًا، يجب كتابته بوضوح.

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

من المهم أيضًا فهم أن ملف التعليمات ليس حاجزًا أمنيًا. هو لا يغني عن CI، Branch Protection، Code Review، Permissions، Tests، و Hooks.

هو فقط يجعل الوكيل يعمل بطريقة أقرب لطريقة الفريق.

مثال على ملف AGENTS.md أو CLAUDE.md قصير

# AI Coding Agent Instructions

## Before changing code
- Read the relevant files and understand the existing flow.
- Check existing tests before implementing a solution.
- State the likely root cause and a short implementation plan.
- Ask before adding dependencies or changing public behavior.

## While changing code
- Prefer the simplest solution that satisfies the requirement.
- Make the smallest coherent diff.
- Preserve existing conventions, APIs, naming, and response formats.
- Do not refactor unrelated code.
- Do not edit generated files unless explicitly requested.

## Verification
- Run the narrowest relevant test first.
- Run the broader affected suite when practical.
- Run formatting, linting, or static analysis required by the repository.
- Review the final diff for accidental changes.
- Report what changed, what was verified, and what remains uncertain.

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

الخلاصة

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

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

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

يمكنهم إنجاز الكثير، لكنهم يحتاجون إلى قواعد مشروع واضحة، حدود معمارية، واختبارات موثوقة.

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

عناوين بديلة للمقال

1. لماذا يجعل ملف تعليمات صغير وكلاء البرمجة بالذكاء الاصطناعي أكثر موثوقية

2. CLAUDE.md و AGENTS.md: قواعد أفضل لتطوير أفضل بالذكاء الاصطناعي

3. لا تكتب Prompt أطول، أعطِ وكيل الذكاء الاصطناعي قواعد أوضح

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

5. أهم ملف لتحسين جودة التطوير بمساعدة الذكاء الاصطناعي

مصادر وروابط إضافية

• multica-ai/andrej-karpathy-skills على GitHub

• Claude Code: Project Instructions and CLAUDE.md

• OpenAI Codex: Custom Instructions with AGENTS.md