جودة الكود المولّد بالذكاء الاصطناعي تعتمد شبه كلياً على ما تطلبه وكيف تطلبه. هذا الدليل يغطي الأنماط التي تنتج نتائج أفضل باستمرار مع Claude Code.
من تحديد نطاق المهام إلى موجهات النظام، ومن التحسين التكراري إلى التعليمات الخاصة بالأدوار. تقنيات عملية يمكنك تطبيقها في جلسة البرمجة التالية.
عندما تطلب من مطور بشري 'ابنِ صفحة تسجيل دخول'، يسأل أسئلة توضيحية: أي مزود مصادقة؟ ما الحقول؟ هل تدعم OAuth؟ رسائل الخطأ؟ حالات التحميل؟
وكلاء البرمجة بالذكاء الاصطناعي سيحاولون الإجابة على كل تلك الأسئلة بأنفسهم. أحياناً يخمّنون صحيحاً. غالباً يخمّنون شيئاً معقولاً لكن ليس ما أردته. الفجوة بين 'معقول' و'صحيح تماماً' هي ما تسدّه هندسة الموجهات.
الموجهات الجيدة لا تحتاج أن تكون طويلة. تحتاج أن تكون محددة بشأن الأشياء المهمة وصامتة بشأن الأشياء غير المهمة. هذا التوازن هو ما يدور حوله هذا الدليل.
أنماط تحسّن النتائج بغض النظر عن المهمة.
بدلاً من 'أنشئ مكون React، ثم أضف state، ثم أضف تنسيقاً'، صف النتيجة النهائية: 'ابنِ شريطاً جانبياً قابلاً للطي يعرض أسماء المشاريع، يدعم إعادة الترتيب بالسحب، ويستخدم ثيم Tailwind الحالي.' دع الوكيل يقرر كيف يصل لذلك.
Avoid
أنشئ مكوناً. أضف useState. أضف زر تبديل. نسّقه بـ Tailwind.
Better
ابنِ مكون شريط جانبي قابل للطي يسرد المشاريع بالاسم. يجب أن يدعم إعادة الترتيب بالسحب ويتطابق مع ثيمنا الداكن (bg-[#1a1a2e], border-[#2a2a40]). حالة الطي يجب أن تستمر عبر إعادة تحميل الصفحة.
الوكلاء يعملون أفضل عندما يعرفون الحدود. حدد أي ملفات يُعدّلها (أو يتجنبها)، أي أنماط يتبع، وما شكل 'الاكتمال'. المهام بلا حدود تؤدي لتغييرات متناثرة صعبة المراجعة.
Avoid
أعد هيكلة نظام المصادقة.
Better
أعد هيكلة معالج تسجيل الدخول في src/api/auth/login.ts لاستخدام bcrypt بدل sha256 لتجزئة كلمات المرور. لا تغيّر منطق JWT أو معالجة ملفات تعريف جلسة الارتباط. حدّث الاختبارات ذات الصلة في tests/auth/.
Claude Code يمكنه قراءة ملفات مشروعك، لكنه لا يقرأ أفكارك. إذا هناك اصطلاح تتبعه أو مكتبة تفضلها أو نمط أسسته، قله. هذا يوفر إعادة العمل.
Avoid
أضف تحقق من النموذج.
Better
أضف تحقق للنموذج في نموذج التسجيل باستخدام zod (نستخدمه بالفعل لنموذج الإعدادات في src/forms/settings.ts). اعرض رسائل خطأ مدمجة أسفل كل حقل. اتبع نفس تنسيق الأخطاء كنموذج تسجيل الدخول.
الموجهات المركبة ('ابنِ الـ API واكتب اختبارات وحدّث التوثيق وانشر') تجبر الوكيل على حمل أهداف كثيرة في وقت واحد. قسّم العمل المعقد إلى مهام متسلسلة مركّزة. كل واحدة تبني على نتيجة السابقة.
Avoid
ابنِ صفحة ملف المستخدم واكتب نقاط نهاية API وأضف اختبارات وحدّث README وأصلح شريط التنقل أثناء ذلك.
Better
ابنِ نقطة نهاية GET /api/user/profile. أرجع حقول id و name و email و plan. استخدم وسيط المصادقة الحالي.
إذا لم تكن النتيجة الأولى صحيحة، حسّن الموجه بدلاً من البدء من جديد. Claude يحتفظ بسياق المحادثة الكامل. قل ما الخطأ وما يجب تغييره وما يبقى. التكرار أسرع من إعادة الاختراع.
Avoid
هذا خطأ. ابدأ من جديد وابنِ المكون بشكل مختلف.
Better
التخطيط جيد لكن نقطة القطع للهاتف خاطئة. تحت 768px، رتّب البطاقات عمودياً بدل الشبكة. أبقِ كل شيء آخر كما هو.
موجهات النظام تحدد السلوك الأساسي للوكيل قبل أن تقول شيئاً. أقل أداة مُستخدمة في البرمجة بالذكاء الاصطناعي.
موجه النظام يخبر الوكيل من هو وعلى ماذا يركز وما يتجنب. ينطبق على كل رسالة في الجلسة. فكّر فيه كوصف وظيفة الوكيل.
AgentsRoom يأتي مع 14 موجه نظام خاص بالأدوار: واحد لكل نوع وكيل. موجه وكيل الواجهة الأمامية يخبره بالتركيز على المكونات والوصولية والتصميم المتجاوب. موجه وكيل ضمان الجودة يخبره بالتفكير في الحالات الحدية وكتابة اختبارات شاملة. يمكنك تخصيصها أو كتابة موجهاتك.
أنت مطور واجهة أمامية خبير. ركّز على مكونات React وتنسيق CSS/Tailwind والوصولية (WCAG AA) والتصميم المتجاوب. استخدم مكتبة مكونات المشروع الحالية قبل إنشاء مكونات جديدة. فضّل التركيب على الوراثة. اكتب HTML دلالي. لا تعدّل ملفات الخلفية.
أكثر موجه فعّال لا يُكتب في دردشة. يعيش في مستودعك.
CLAUDE.md ملف ماركداون في جذر مشروعك يقرأه Claude Code تلقائياً. يحتوي هيكل المشروع والاصطلاحات وتفاصيل المجموعة التقنية والإرشادات التي تنطبق على كل جلسة وكيل في المشروع.
بدلاً من تكرار 'نستخدم Tailwind CSS 4 و Prisma ORM و Next.js 16' في كل محادثة، اكتبها مرة في CLAUDE.md. كل وكيل يرث هذا السياق. AgentsRoom يتضمن محرراً مدمجاً لـ CLAUDE.md لتحدّثه بدون مغادرة التطبيق.
CLAUDE.md مكتوب جيداً يساوي أكثر من عشرات الموجهات الفردية المصاغة بعناية. يتراكم: كل جلسة تستفيد منه.
توقف عن إعادة كتابة نفس التعليمات. احفظ ما يعمل وأعد استخدامه.
إذا تجد نفسك تكتب نفس نوع الطلبات عبر المشاريع ('اكتب اختبارات وحدة لهذا الملف'، 'أعد هيكلة هذا لاستخدام نمط المستودع'، 'أضف معالجة أخطاء لجميع مسارات API')، احفظها كموجه قابل لإعادة الاستخدام.
AgentsRoom يتضمن ميزة مكتبة موجهات بمستويين: موجهات لكل مشروع للمهام الخاصة بالمشروع، وموجهات عامة (متزامنة عبر السحابة) للأنماط التي تستخدمها في كل مكان.
مرشحون جيدون لموجهات المكتبة: قوائم مراجعة الكود، قوالب كتابة الاختبارات، سكربتات الترحيل، تعليمات بناء المكونات، خطوات التدقيق الأمني. أي شيء ستضعه في ويكي الفريق كإجراء معياري.
اكتب اختبارات وحدة لـ [الملف]. استخدم vitest. غطّ المسار السعيد والحالات الحدية (إدخال فارغ، null، أنواع غير صالحة) ومعالجة الأخطاء. قلّد التبعيات الخارجية. استهدف تغطية فروع >90%.
راجع التغييرات في فروقات git الحالية. تحقق من: استيرادات غير مستخدمة، معالجة أخطاء مفقودة، مشاكل أمان الأنواع، حالات سباق محتملة، وتناقضات التسمية. اقترح إصلاحات لكل مشكلة.
أنشئ نقطة نهاية REST لـ [المورد]. أضف تحقق إدخال بـ zod واستجابات خطأ مناسبة (400، 401، 404، 500) وأنواع TypeScript للطلب/الاستجابة وتعليق JSDoc يصف النقطة. اتبع النمط الحالي في src/api/.
تقنيات للمهام المعقدة التي تتجاوز الموجهات الفردية.
قسّم مهمة كبيرة إلى خطوات مرتبة. ابدأ الوكيل الأول بالخطوة الأولى، انتظر الاكتمال، ثم ابدأ الوكيل التالي بالخطوة الثانية (مشيراً لمخرجات الخطوة الأولى). كل خطوة أصغر وأكثر تركيزاً. مثال: الوكيل 1 يصمم مخطط قاعدة البيانات، الوكيل 2 يكتب API باستخدام ذلك المخطط، الوكيل 3 يكتب اختبارات لـ API.
بعد انتهاء وكيل، وجّه وكيلاً مختلفاً لمخرجاته. 'راجع التغييرات التي أجراها وكيل الواجهة الأمامية في src/components/. تحقق من مشاكل الوصولية وحالات الخطأ المفقودة.' وكيل جديد بدور مختلف يكتشف أشياء فاتت الوكيل الأصلي.
ابدأ بموجه مفتوح لرؤية كيف يتعامل الوكيل مع المشكلة. ثم أضف قيوداً في رسائل متابعة: 'هيكل جيد، لكن استخدم server components بدل client components.' 'أبقِ الـ hook لكن أزل useEffect واستخدم React Query mutation بدلاً.' كل تكرار يضيّق نحو الحل المطلوب.
وجّه الوكيل لكود موجود: 'ابنِ صفحة إعدادات بنفس نمط src/pages/profile.tsx. نفس هيكل التخطيط ومعالجة النماذج وعرض الأخطاء.' هذا غالباً أكثر فعالية من وصف النمط بالكلمات.
أنماط تنتج نتائج أسوأ باستمرار.
إخبار الوكيل بالضبط أي دوال يكتب وأي متغيرات يسمّي وأي ترتيب ينفّذ. هذه الإدارة التفصيلية تزيل قدرة الوكيل على إيجاد نهج أفضل. صف النتيجة، لا الإجراء.
طلب من وكيل 'حسّن قاعدة الكود' بلا قيود. بدون حدود، قد يعيد الوكيل هيكلة ملفات لم تردها محدّثة أو يغيّر APIs يعتمد عليها كود آخر أو ينفق رموزاً على تحسينات منخفضة الأولوية.
عدم ذكر أن نمطاً أو أداة مساعدة أو مكوناً موجود فعلاً في المشروع. الوكيل سينشئ واحداً جديداً. جملة بسيطة مثل 'لدينا بالفعل hook باسم useAuth في src/hooks/' توفر إعادة عمل كبيرة.
حشر خمس مهام في رسالة واحدة. الوكيل سيحاول إنجازها جميعاً، لكن الجودة تنخفض مع تعدد الأهداف المتنافسة. قسّمها إلى طلبات متسلسلة مركّزة بدلاً من ذلك.
AgentsRoom يمنحك موجهات نظام ومكتبة موجهات وتحرير CLAUDE.md مدمج. وقت أقل في صياغة الموجهات، وقت أكثر في البناء.
التطبيق المرافق: تابع وكلاءك أينما كنت
متوافق مع أي خطة Claude (Free، Pro، Max، Team، Enterprise)