تعتمد جودة الكود الذي يولّده الذكاء الاصطناعي بالكامل تقريبًا على ما تطلبه وعلى طريقة طلبه. يتناول هذا الدليل الأنماط التي تعطي باستمرار نتائج أفضل مع Claude Code.
من تحديد نطاق المهام إلى مطالبات النظام، ومن التحسين التدريجي إلى التعليمات الخاصة بكل دور. تقنيات عملية يمكنك تطبيقها في جلسة البرمجة القادمة.
عندما تطلب من مطوّر بشري أن «ينشئ صفحة تسجيل دخول»، يطرح أسئلة توضيحية: أي مزوّد مصادقة؟ ما الحقول؟ هل يجب دعم OAuth؟ رسائل الخطأ؟ حالات التحميل؟
سيحاول وكلاء البرمجة بالذكاء الاصطناعي الإجابة عن كل هذه الأسئلة بأنفسهم. يصيبون أحيانًا، وغالبًا ما يخمّنون شيئًا معقولًا لكنه ليس ما أردته. الفجوة بين «معقول» و«صحيح تمامًا» هي ما تسدّه هندسة المطالبات.
الـ prompts الجيدة لا تحتاج أن تكون طويلة. يجب أن تكون محددة في ما يهم، وصامتة عمّا لا يهم. هذا التوازن هو موضوع هذا الدليل.
أنماط تحسن النتائج بصرف النظر عن المهمة.
بدلاً من قول «أنشئ مكوّن React، ثم أضف الحالة، ثم أضف التنسيق»، صِف النتيجة النهائية: «أنشئ شريطاً جانبياً قابلاً للطي يعرض أسماء المشاريع، ويدعم إعادة الترتيب بالسحب، ويستخدم سِمة Tailwind الحالية لدينا». ودع الوكيل يقرر كيف يصل إلى ذلك.
Avoid
أنشئ مكوّناً. أضف useState. أضف زر تبديل. نسّقه بـ Tailwind.
Better
أنشئ مكوّن شريط جانبي قابل للطي يعرض المشاريع بالاسم. يجب أن يدعم إعادة الترتيب بالسحب وأن يطابق سِمتنا الداكنة (bg-[#111318], border-[#262b38]). ويجب أن تبقى حالة الطي محفوظة بعد إعادة تحميل الصفحة.
يعمل الوكلاء بأفضل شكل عندما يعرفون الحدود. حدّد الملفات التي يجب تعديلها (أو تجنّبها)، والأنماط التي يجب اتباعها، وما الذي يعني أن العمل «انتهى». المهام غير المحدودة تؤدي إلى تغييرات متشعبة يصعب مراجعتها.
Avoid
أعد هيكلة نظام المصادقة.
Better
أعد هيكلة معالج تسجيل الدخول في src/api/auth/login.ts لاستخدام bcrypt بدلاً من sha256 في تجزئة كلمات المرور. لا تغيّر منطق JWT ولا معالجة كوكي الجلسة. وحدّث الاختبارات المرتبطة في tests/auth/.
يمكن لـ Claude Code قراءة ملفات مشروعك، لكنه لا يستطيع قراءة عقلك. إذا كان هناك اتفاقية تتبعها، مكتبة تفضلها، أو نمط قد أنشأته بالفعل، فقل ذلك. هذا يوفر إعادة العمل.
Avoid
أضف التحقق من النموذج.
Better
أضف التحقق من صحة الحقول إلى نموذج التسجيل باستخدام zod (نستخدمه بالفعل في نموذج الإعدادات في src/forms/settings.ts). اعرض رسائل الخطأ أسفل كل حقل مباشرة. اتبع تنسيق الأخطاء نفسه المستخدم في نموذج تسجيل الدخول.
الـ prompts المركّبة («ابنِ الـ API، واكتب الاختبارات، وحدّث التوثيق، وانشر») تجبر الوكيل على حمل أهداف كثيرة في وقت واحد. قسّم العمل المعقد إلى مهام متتابعة ومركّزة. كل مهمة تبني على نتيجة سابقتها.
Avoid
أنشئ صفحة الملف الشخصي للمستخدم، واكتب نقاط نهاية الـ API، وأضف الاختبارات، وحدّث ملف README، وأصلح شريط التنقل وأنت في الطريق.
Better
أنشئ نقطة النهاية GET /api/user/profile. أعِد الحقول id وname وemail وplan. استخدم الـ middleware الحالي للمصادقة.
إذا لم تكن النتيجة الأولى صحيحة، حسّن المطالبة بدلاً من البدء من الصفر. يحتفظ Claude بسياق المحادثة كاملاً. قل ما هو الخطأ، وما الذي يجب تغييره، وما الذي يجب الإبقاء عليه. التكرار أسرع من إعادة الاختراع.
Avoid
هذا خطأ. ابدأ من جديد وأنشئ المكوّن بطريقة مختلفة.
Better
التخطيط جيد لكن نقطة التوقف (breakpoint) الخاصة بالجوال خاطئة. تحت 768px، رتّب البطاقات عموديًا بدلًا من استخدام شبكة. أبقِ كل شيء آخر كما هو.
تحدد مطالبات النظام السلوك الأساسي للوكيل قبل أن تقول أي شيء. إنها أقل الأدوات استخدامًا في البرمجة بالذكاء الاصطناعي.
تخبر مطالبة النظام الوكيل بمن هو، وبما يجب أن يركّز عليه، وبما يجب أن يتجنّبه. وهي تنطبق على كل رسالة في الجلسة. اعتبرها الوصف الوظيفي للوكيل.
يأتي AgentsRoom مع 14 مطالبة نظام مخصصة للأدوار: واحدة لكل نوع من الوكلاء. تطلب مطالبة وكيل Frontend التركيز على المكونات وإمكانية الوصول والتصميم المتجاوب، بينما تطلب مطالبة وكيل QA التفكير في الحالات الحدية وكتابة اختبارات شاملة. ويمكنك تعديلها أو كتابة مطالباتك الخاصة.
أنت مطوّر Frontend خبير. ركّز على مكوّنات React، وتنسيق CSS/Tailwind، وإمكانية الوصول (WCAG AA)، والتصميم المتجاوب. استخدم مكتبة المكوّنات الحالية في المشروع قبل إنشاء مكوّنات جديدة. فضّل التركيب على الوراثة. اكتب HTML دلاليًا. لا تعدّل ملفات الـ backend أبدًا.
أكثر المطالبات فعالية لا تُكتب في المحادثة. إنها موجودة في مستودعك.
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 الحالي. تحقق من: الاستيرادات غير المستخدمة، ومعالجة الأخطاء المفقودة، ومشكلات أمان الأنواع، وحالات التسابق المحتملة، وتضارب التسميات. واقترح إصلاحاً لكل مشكلة تجدها.
أنشئ نقطة نهاية 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/" توفّر الكثير من إعادة العمل.
حشر خمس مهام في رسالة واحدة. سيحاول الوكيل تنفيذها كلها، لكن الجودة تنخفض وهو يوازن بين أهداف متنافسة. قسّمها بدلًا من ذلك إلى طلبات متتابعة ومركّزة.
البرمجة لم تعد هي العائق، التواصل هو الأصل. كيف تتحدث مع وكلاء الذكاء الاصطناعي Claude و Codex و Antigravity و Grok Build لتشحن أسرع، بدقة أعلى، وبتكلفة توكنز أقل.
تمرير ملفات PDF مباشرة إلى Claude أو أي نموذج لغوي يستهلك التوكنات بصمت: كل صفحة تتحول أيضًا إلى صورة. حوّل الملف إلى Markdown أولًا باستخدام MarkItDown، أداة Microsoft المجانية مفتوحة المصدر، واخفض فاتورة التوكنات بنسبة تصل إلى 80%. دليل كامل مع CLI وPython وإعداد MCP.
يوفر لك AgentsRoom تعليمات النظام، ومكتبة تعليمات، وتحرير CLAUDE.md مدمج. وقت أقل في صياغة التعليمات، ووقت أكثر في البناء.
التطبيق المرافق: تابع وكلاءك أينما كنت
استخدم Claude أو Codex أو Antigravity CLI أو أي مزود AI آخر.
أرسل الأخطاء والطلبات مباشرة إلى قائمة المهام العامة.