هندسة المطالبات

مطالبات أفضل. كود أفضل.

تعتمد جودة الكود الذي يولّده الذكاء الاصطناعي بالكامل تقريبًا على ما تطلبه وعلى طريقة طلبه. يتناول هذا الدليل الأنماط التي تعطي باستمرار نتائج أفضل مع Claude Code.

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

لماذا تهمّ هندسة المطالبات في البرمجة

عندما تطلب من مطوّر بشري أن «ينشئ صفحة تسجيل دخول»، يطرح أسئلة توضيحية: أي مزوّد مصادقة؟ ما الحقول؟ هل يجب دعم OAuth؟ رسائل الخطأ؟ حالات التحميل؟

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

الـ prompts الجيدة لا تحتاج أن تكون طويلة. يجب أن تكون محددة في ما يهم، وصامتة عمّا لا يهم. هذا التوازن هو موضوع هذا الدليل.

خمسة مبادئ أساسية

أنماط تحسن النتائج بصرف النظر عن المهمة.

1

كن محدداً بشأن النتائج وليس الخطوات

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

Avoid

أنشئ مكوّناً. أضف useState. أضف زر تبديل. نسّقه بـ Tailwind.

Better

أنشئ مكوّن شريط جانبي قابل للطي يعرض المشاريع بالاسم. يجب أن يدعم إعادة الترتيب بالسحب وأن يطابق سِمتنا الداكنة (bg-[#111318], border-[#262b38]). ويجب أن تبقى حالة الطي محفوظة بعد إعادة تحميل الصفحة.

2

حدّد نطاق العمل بوضوح

يعمل الوكلاء بأفضل شكل عندما يعرفون الحدود. حدّد الملفات التي يجب تعديلها (أو تجنّبها)، والأنماط التي يجب اتباعها، وما الذي يعني أن العمل «انتهى». المهام غير المحدودة تؤدي إلى تغييرات متشعبة يصعب مراجعتها.

Avoid

أعد هيكلة نظام المصادقة.

Better

أعد هيكلة معالج تسجيل الدخول في src/api/auth/login.ts لاستخدام bcrypt بدلاً من sha256 في تجزئة كلمات المرور. لا تغيّر منطق JWT ولا معالجة كوكي الجلسة. وحدّث الاختبارات المرتبطة في tests/auth/.

3

قدّم السياق المهم

يمكن لـ Claude Code قراءة ملفات مشروعك، لكنه لا يستطيع قراءة عقلك. إذا كان هناك اتفاقية تتبعها، مكتبة تفضلها، أو نمط قد أنشأته بالفعل، فقل ذلك. هذا يوفر إعادة العمل.

Avoid

أضف التحقق من النموذج.

Better

أضف التحقق من صحة الحقول إلى نموذج التسجيل باستخدام zod (نستخدمه بالفعل في نموذج الإعدادات في src/forms/settings.ts). اعرض رسائل الخطأ أسفل كل حقل مباشرة. اتبع تنسيق الأخطاء نفسه المستخدم في نموذج تسجيل الدخول.

4

مهمة واحدة لكل مطالبة

الـ prompts المركّبة («ابنِ الـ API، واكتب الاختبارات، وحدّث التوثيق، وانشر») تجبر الوكيل على حمل أهداف كثيرة في وقت واحد. قسّم العمل المعقد إلى مهام متتابعة ومركّزة. كل مهمة تبني على نتيجة سابقتها.

Avoid

أنشئ صفحة الملف الشخصي للمستخدم، واكتب نقاط نهاية الـ API، وأضف الاختبارات، وحدّث ملف README، وأصلح شريط التنقل وأنت في الطريق.

Better

أنشئ نقطة النهاية GET /api/user/profile. أعِد الحقول id وname وemail وplan. استخدم الـ middleware الحالي للمصادقة.

5

حسّن ولا تبدأ من الصفر

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

Avoid

هذا خطأ. ابدأ من جديد وأنشئ المكوّن بطريقة مختلفة.

Better

التخطيط جيد لكن نقطة التوقف (breakpoint) الخاصة بالجوال خاطئة. تحت 768px، رتّب البطاقات عموديًا بدلًا من استخدام شبكة. أبقِ كل شيء آخر كما هو.

مطالبات النظام: سياق يدوم

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

تخبر مطالبة النظام الوكيل بمن هو، وبما يجب أن يركّز عليه، وبما يجب أن يتجنّبه. وهي تنطبق على كل رسالة في الجلسة. اعتبرها الوصف الوظيفي للوكيل.

يأتي AgentsRoom مع 14 مطالبة نظام مخصصة للأدوار: واحدة لكل نوع من الوكلاء. تطلب مطالبة وكيل Frontend التركيز على المكونات وإمكانية الوصول والتصميم المتجاوب، بينما تطلب مطالبة وكيل QA التفكير في الحالات الحدية وكتابة اختبارات شاملة. ويمكنك تعديلها أو كتابة مطالباتك الخاصة.

مثال: مطالبة النظام لوكيل Frontend

أنت مطوّر Frontend خبير. ركّز على مكوّنات React، وتنسيق CSS/Tailwind، وإمكانية الوصول (WCAG AA)، والتصميم المتجاوب. استخدم مكتبة المكوّنات الحالية في المشروع قبل إنشاء مكوّنات جديدة. فضّل التركيب على الوراثة. اكتب HTML دلاليًا. لا تعدّل ملفات الـ backend أبدًا.

كتابة مطالبات نظام فعّالة

  • ✓حدّد الدور وحدوده. على ماذا يجب أن يركّز الوكيل؟ وماذا يجب أن يتجاهل؟
  • ✓اذكر تقنيات وإصدارات محددة. «React 19 مع Server Components» أفضل من «React حديث».
  • ✓أشِر إلى اصطلاحات المشروع. «استخدم Zustand لإدارة الحالة» تخبر الوكيل بألّا يلجأ إلى Redux أو Context.
  • ✓حدّد توقعات الجودة. «اكتب TypeScript في الوضع الصارم، بلا أنواع any» تمنع الاختصارات.
  • ✓أضِف قيودًا سلبية. «لا تعدّل أبدًا الملفات في /api/» تُبقي الوكيل في مساره.

CLAUDE.md: سياق على مستوى المشروع

أكثر المطالبات فعالية لا تُكتب في المحادثة. إنها موجودة في مستودعك.

CLAUDE.md ملف markdown في جذر مشروعك يقرأه Claude Code تلقائيًا. يحتوي على بنية المشروع والاصطلاحات وتفاصيل حزمة التقنيات والإرشادات التي تنطبق على كل جلسة وكيل في المشروع.

بدلاً من تكرار «نحن نستخدم Tailwind CSS 4 وPrisma ORM وNext.js 16» في كل محادثة، اكتبها مرة واحدة في CLAUDE.md. يرث كل وكيل هذا السياق. ويتضمن AgentsRoom محرراً مدمجاً لملف CLAUDE.md حتى تتمكن من تحديثه دون مغادرة التطبيق.

ملف CLAUDE.md مكتوب جيداً يساوي أكثر من عشرات المطالبات الفردية المصاغة بعناية. أثره تراكمي: كل جلسة تستفيد منه.

بناء مكتبة المطالبات

توقّف عن إعادة كتابة التعليمات نفسها. احفظ ما ينجح وأعد استخدامه.

إذا وجدت نفسك تكتب النوع نفسه من الطلبات في مشاريع مختلفة («اكتب اختبارات الوحدة لهذا الملف»، «أعد هيكلة هذا لاستخدام نمط المستودع»، «أضف معالجة الأخطاء إلى كل مسارات API»)، فاحفظه كمطالبة قابلة لإعادة الاستخدام.

يتضمن AgentsRoom ميزة مكتبة مطالبات بمستويين: مطالبات لكل مشروع للمهام الخاصة به، ومطالبات عامة (متزامنة عبر السحابة) للأنماط التي تستخدمها في كل مكان.

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

أمثلة من مكتبة المطالبات

اكتب اختبارات الوحدة

اكتب اختبارات الوحدة لـ [file]. استخدم vitest. غطِّ المسار الطبيعي، والحالات الحدّية (مدخل فارغ، null، أنواع غير صالحة)، ومعالجة الأخطاء. استخدم mock للتبعيات الخارجية. استهدف تغطية فروع تزيد عن 90%.

مراجعة الكود

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

نقطة نهاية API

أنشئ نقطة نهاية REST لـ [resource]. أضف التحقق من المدخلات باستخدام zod، واستجابات أخطاء مناسبة (400, 401, 404, 500)، وأنواع TypeScript للطلب والاستجابة، وتعليق JSDoc يصف نقطة النهاية. واتبع النمط الحالي في src/api/.

أنماط متقدمة

تقنيات للمهام المعقدة التي تتجاوز المطالبة الواحدة.

تسلسل المطالبات

قسّم المهمة الكبيرة إلى خطوات مرتّبة. أطلق الوكيل الأول بالخطوة الأولى، وانتظر انتهاءه، ثم أطلق الوكيل التالي بالخطوة الثانية (مع الإشارة إلى ناتج الخطوة الأولى). كل خطوة أصغر وأكثر تركيزًا. مثال: الوكيل 1 يصمّم مخطط قاعدة البيانات، والوكيل 2 يكتب الـ API باستخدام هذا المخطط، والوكيل 3 يكتب اختبارات على الـ API.

مراجعة متقاطعة بين الوكلاء

بعد أن ينتهي وكيل، وجّه وكيلاً آخر إلى ناتجه. «راجع التغييرات التي أجراها وكيل Frontend للتو في src/components/. تحقق من مشكلات إمكانية الوصول وحالات الخطأ الناقصة». وكيل جديد بدور مختلف يلتقط ما فات الوكيل الأصلي.

القيود التدريجية

ابدأ بمطالبة مرنة لترى كيف يتناول الوكيل المشكلة. ثم أضف القيود في رسائل المتابعة: «البنية جيدة، لكن استخدم server components بدلًا من client components». «أبقِ الـ hook، لكن احذف useEffect واستخدم mutation من React Query بدلًا منه». كل تكرار يقترب أكثر من الحل الذي تريده.

التنفيذ المرجعي

وجّه الوكيل إلى كود موجود بالفعل: "أنشئ صفحة إعدادات بنفس نمط src/pages/profile.tsx: نفس بنية التخطيط، ونفس معالجة النماذج، ونفس طريقة عرض الأخطاء." غالباً ما يكون هذا أكثر فعالية من وصف النمط بالكلمات.

الأخطاء الشائعة

أنماط تعطي باستمرار نتائج أسوأ.

الإفراط في تحديد التنفيذ

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

غياب حدود النطاق

أن تطلب من وكيل «تحسين قاعدة الكود» دون أي قيود. بلا حدود، قد يعيد الوكيل هيكلة ملفات لم ترد المساس بها، أو يغيّر واجهات API يعتمد عليها كود آخر، أو يستهلك الرموز (tokens) في تحسينات قليلة الأولوية.

تجاهل الكود الموجود

عدم الإشارة إلى أن نمطاً أو أداة مساعدة أو مكوّناً موجود بالفعل في المشروع، فينشئ الوكيل نسخة جديدة منه. جملة بسيطة مثل "لدينا بالفعل خطاف useAuth في src/hooks/" توفّر الكثير من إعادة العمل.

المطالبات الضخمة المركّبة

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

الأسئلة الشائعة

اسألنا عن شيء آخر
ما الطول المناسب لمطالبة برمجية؟
أكثر الـ prompts فعالية في البرمجة تتكون من جملتين إلى خمس جمل. طويلة بما يكفي لتحديد النتيجة والنطاق والقيود الأساسية، وقصيرة بما يكفي كي لا يضيع الوكيل في التفاصيل. إذا كان الـ prompt الخاص بك فقرة كاملة، ففكّر في ما إذا كان جزء من هذا السياق مكانه CLAUDE.md أو system prompt بدلًا من ذلك.
هل يجب أن أكتب المطالبات بشكل مختلف لـ Opus مقارنة بـ Sonnet؟
قليلًا. يتعامل Opus مع الغموض بشكل أفضل ويستطيع استنتاج النية من سياق أقل. أما Sonnet فيستفيد من تعليمات أكثر وضوحًا وحدود نطاق أدق. ومع كلا النموذجين، يحسّن التحديد الدقيق للنتيجة المتوقعة النتائج.
كيف تساعد AgentsRoom في هندسة المطالبات؟
بثلاث طرق: مطالبات نظام مدمجة مخصصة للأدوار لكل نوع من أنواع الوكلاء الـ 14، ومكتبة مطالبات لحفظ المطالبات الفعّالة وإعادة استخدامها، ومحرر CLAUDE.md لسياق المشروع. هذه الطبقات تعني أنك تقضي وقتاً أقل في صياغة الرسائل الفردية لأن السياق الأساسي جيد أصلاً.
هل يمكنني مشاركة المطالبات مع الفريق؟
نعم. يحتفظ AgentsRoom بمطالباتك في حسابك: مكتبة لكل مشروع، إضافة إلى مكتبة «عام» متاحة في كل مشاريعك، وكلتاهما متزامنة بين أجهزتك وتطبيق الهاتف مع ذاكرة مؤقتة محلية للعمل دون اتصال. تبقى المطالبات الشخصية مرئية لك وحدك، ولا يُودَع أي شيء في المستودع.
ما الفرق بين مطالبة النظام و CLAUDE.md؟
ملف CLAUDE.md هو سياق المشروع الذي يقرأه كل وكيل تلقائياً: حزمة التقنيات، والبنية، والاصطلاحات. أما مطالبات النظام فهي تعليمات سلوكية خاصة بكل وكيل: الدور، ومجالات التركيز، والقيود. وهما يكملان بعضهما: يقول CLAUDE.md "هذا المشروع يستخدم Next.js 16 مع Prisma"، بينما تقول مطالبة النظام "أنت مطور خلفي يركز على مسارات API".

قراءات إضافية

اكتب مطالبات أفضل، وسلّم كوداً أفضل

يوفر لك AgentsRoom تعليمات النظام، ومكتبة تعليمات، وتحرير CLAUDE.md مدمج. وقت أقل في صياغة التعليمات، ووقت أكثر في البناء.

تحميلمجاني

التطبيق المرافق: تابع وكلاءك أينما كنت

استخدم Claude أو Codex أو Antigravity CLI أو أي مزود AI آخر.

أرسل الأخطاء والطلبات مباشرة إلى قائمة المهام العامة.