هندسة الـ Prompt

أمثلة على الـ prompts:

Make the app better

Fix the bugs

أمثلة على الـ prompts:

Add authentication

أمثلة على الـ prompts:

Build the entire user management system with authentication, authorization, profiles, settings, and admin dashboard

أمثلة على الـ prompts:

Update the validation logic

أمثلة على الـ prompts:

Expecting Verdent to know your specific business rules or constraints

أمثلة على الـ prompts:

Referencing files without including them in context

أمثلة على الـ prompts:

Repeatedly asking for the same thing when Verdent encounters errors

أمثلة على الـ prompts:

Requesting large refactorings or multi-file changes without using Plan Mode first

أمثلة على الـ prompts:

Using Auto-Run or Skip Permission Mode without Git initialized

أمثلة على الـ prompts:

Providing incomplete requirements and expecting Verdent to guess correctly

إنشاء وظيفة جديدة بمتطلبات وقيود واضحة:

Create a POST /api/tasks endpoint that:
- Accepts task title (required), description (optional), and category_id (required)
- Validates that the category exists in the database
- Returns 400 if validation fails with descriptive error messages
- Saves the task to the database and returns the created task with 201 status
- Add this to the existing tasks router in routes/tasks.js
- Create the controller method in controllers/taskController.js
- Use the existing error handling pattern from other controllers

ما الذي يجعل هذا فعالاً:

• متطلبات واضحة للمدخلات والتحقق منها
• مواقع ملفات محددة للتنفيذ
• إشارة إلى الأنماط الحالية للحفاظ على الاتساق
• رموز حالة HTTP المتوقعة ومعالجة الأخطاء

وصف المشكلات مع السياق والحلول المقترحة:

Fix the race condition in payment processing at checkout. When multiple users submit payments simultaneously, some transactions fail with "duplicate order ID" errors. The issue appears to be in PaymentController.js around line 45 where we generate order IDs. Implement proper locking or use UUID generation to ensure unique IDs even under concurrent load.

ما الذي يجعل هذا فعالاً:

• وصف واضح للمشكلة مع الأعراض
• موقع محدد للمشكلة (الملف ورقم السطر)
• سياق حول متى تحدث (مستخدمون متزامنون)
• أساليب حل مقترحة

تغيير التنفيذ مع الحفاظ على السلوك:

Refactor the authentication middleware in middleware/auth.js to use JWT tokens instead of session cookies. Keep the same authorization logic, but:
- Replace session validation with JWT verification
- Store tokens in httpOnly cookies
- Maintain the existing user object structure that routes expect
- Update only the authentication mechanism, don't change authorization rules
- Ensure all existing routes continue to work without modification

ما الذي يجعل هذا فعالاً:

• هدف واضح (JWT بدلًا من الجلسات)
• ملف محدد لإعادة هيكلته
• قيود صريحة (ما لا يجب أن يتغير)
• متطلب التوافق مع الإصدارات السابقة

كتابة اختبارات بتغطية شاملة:

Write comprehensive unit tests for the UserService class in services/UserService.js. Cover:
- User creation with valid and invalid data
- Email validation edge cases (empty, malformed, duplicate)
- Password hashing verification
- User lookup by ID and email
- Error handling for database failures
Use Jest and follow the testing patterns in existing service tests

ما الذي يجعل هذا فعالاً:

• فئة/ملف محدد للاختبار
• قائمة كاملة بالسيناريوهات المطلوب تغطيتها
• إطار الاختبار محدد
• إشارة إلى أنماط الاختبار الحالية

بناء مكونات واجهة المستخدم بمواصفات مفصّلة:

Create a reusable SearchBar component for the product catalog with:
- Text input with real-time debounced search (300ms delay)
- Category dropdown filter (fetch options from /api/categories)
- Price range slider (min $0, max $1000)
- Clear filters button
- Use Material-UI components to match existing design
- Emit search parameters via onChange callback to parent
- Include PropTypes for all props

ما الذي يجعل هذا فعالاً:

• قائمة ميزات كاملة بتفاصيل محددة
• مواصفات تقنية (تأخير 300 مللي ثانية، نطاق السعر)
• مكتبة واجهة المستخدم محددة (Material-UI)
• أسلوب التكامل (رد نداء إلى المكون الأصل)

الإشارة إلى ملفات أو مكونات أو وكلاء فرعيين محددين:

@auth.js @UserController.js Refactor authentication to use the same validation pattern

الفوائد:

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

انتقل إلى Plan Mode قبل التنفيذ للتغييرات الكبيرة:

Switch to Plan Mode
Refactor the entire API layer to use TypeScript with strict type checking

الفوائد:

• راجع أسلوب Verdent الكامل قبل تعديل أي ملفات
• يمنع الأخطاء المكلفة في عمليات إعادة الهيكلة الكبيرة أو التغييرات المعمارية
• كرّر الخطة أو أضف قيودًا أو أعد توجيهها كليًا قبل بدء التنفيذ
• اطلب من Verdent استيضاح متطلباتك عبر أسئلة توضيحية مسبقًا

تفويض المهام المتخصصة لوكلاء فرعيين مدمجين أو مخصصين:

@Code-reviewer Review the security vulnerabilities in authentication flow
@Explorer Find all files that import the deprecated API client
@Verifier Validate the authentication logic in the middleware

الفوائد:

• استفد من وكلاء متخصصين مُحسّنين لمهام محددة (الاستكشاف، التحقق، مراجعة الكود)
• خبرة مركّزة ونتائج أسرع من المعالجة العامة
• نفّذ عدة تحليلات بالتوازي لتقليل زمن التنفيذ الإجمالي بشكل كبير
• أنشئ وكلاء فرعيين مخصصين بمعرفة مجالية خاصة بمتطلبات مشروعك الفريدة

الوكلاء الفرعيون الافتراضيون المدمجون:

• @Verifier - فحوصات كود سريعة والتحقق منها
• @Explorer - استكشاف سريع لقاعدة الكود والعثور على الملفات
• @Code-reviewer - تقييم جودة الكود

فعّل التفكير الموسع للتحديات المعقدة:

Think: Design the optimal database schema for a multi-tenant SaaS application

الفوائد:

• يفعّل التفكير الموسع لتحليل أعمق للمشكلات المعقدة من زوايا متعددة
• يقيّم الأساليب البديلة والحالات الاستثنائية بدقة أكبر
• ينتج حلولًا قوية حيث تكون الدقة هي الأهم
• استجابات أبطأ واستهلاك أرصدة أعلى، لكنه يمنع إعادة العمل المكلفة الناتجة عن حلول متسرعة وغير مثالية

ابنِ على الاستجابات السابقة بتحسين تدريجي:

Initial: "Create a dashboard component"
Follow-up: "Add real-time data updates using WebSockets"
Follow-up: "Now add filtering and sorting capabilities"

الفوائد:

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

حدد ما لا يجب تغييره إلى جانب ما يجب تغييره:

Add caching to the API endpoints, but:
- Don't modify the authentication middleware
- Keep the existing error handling unchanged
- Maintain backward compatibility with mobile clients

الفوائد:

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

أشر إلى كود موجود كأمثلة للتنفيذ:

Implement the new ProductService following the same pattern as UserService.js, including error handling, validation, and database transaction management

الفوائد:

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

أنشئ ملف todos.md لتتبع المهام المعقدة متعددة الخطوات:

Create a todos.md file with these tasks:
1. Refactor authentication to use JWT tokens
2. Update all controllers to use new auth middleware
3. Add tests for authentication flow
4. Update API documentation

الفوائد:

• يوفر خارطة طريق واضحة ومكتوبة يمكن مراجعتها وتحسينها ومشاركتها مع زملاء الفريق
• يُعدَّل بسهولة مع تطور المتطلبات طوال المشروع
• يستمر عبر الجلسات لتتمكن من إيقاف العمل مؤقتًا واستئنافه لاحقًا وفهم موضع التوقف فورًا
• يُستخدم كأثر للمشروع يوثّق ما تم التخطيط له وإنجازه وما تبقى للصيانة المستقبلية والتأهيل

ابدأ جلسات جديدة بين المهام المختلفة لسياق نظيف:

After completing todo #1: "Start a new session"
Then: "Let's work on todo #2 from todos.md"

الفوائد:

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

استخدم خوادم MCP (Model Context Protocol) لحقن سياق متخصص:

• وثائق خاصة بالمشروع
• مواصفات API (OpenAPI، مخططات GraphQL)
• معرفة خاصة بإطار العمل

الفوائد:

• يعزز فهم Verdent لأطر العمل المخصصة والأدوات الداخلية والمجالات المتخصصة غير الموجودة في بيانات تدريبه
• يلغي الحاجة إلى تكرار شرح الأنظمة المخصصة من خلال حقن مواصفات API الخاصة بالمؤسسة والوثائق مباشرةً
• يتيح الاستخدام الصحيح لـ APIs الداخلية والأنظمة الخاصة التي يستحيل نقلها من خلال الـ prompts وحدها

ضمّن الملفات ذات الصلة صراحةً في السياق:

@models/User.js @controllers/UserController.js Add password reset functionality

متى تستخدمها:

• عند العمل مع ملفات مترابطة بشكل وثيق (النموذج والمتحكم، الخدمة والاختبارات)
• الإشارة إلى أنماط تنفيذ من ملف لتطبيقها في ملف آخر
• تنسيق التغييرات عبر عدة ملفات مترابطة
• في قواعد الأكواد الكبيرة ذات أسماء الملفات المتشابهة حيث قد يفوّت الاكتشاف التلقائي السياق
• استخدمها دائمًا عند طلب أن يتّبع Verdent "نفس نمط..." لضمان امتلاكه للكود الدقيق

ضمّن سياقًا رفيع المستوى حول مجموعة تقنياتك:

This is a MERN stack application (MongoDB, Express, React, Node.js) with JWT authentication. Add role-based access control following our existing middleware pattern.

متى تستخدمها:

• عند تنفيذ ميزات تحتاج إلى التكامل مع مجموعة تقنياتك الحالية
• العمل لأول مرة في قاعدة كود أو ميزات تمتد عبر طبقات متعددة (من الواجهة الأمامية إلى قاعدة البيانات)
• عندما تحمل مجموعة تقنياتك آراءً قوية (GraphQL مقابل REST، Redux مقابل Context API) تؤثر على خيارات التنفيذ
• عندما تحتاج Verdent لاختيار الأسلوب المناسب لنظامك بدلًا من حل عام

أشر إلى كود يوضّح أعرافك:

Follow the same error handling pattern used in ProductController.js - return consistent error objects with status codes and descriptive messages

متى تستخدمها:

• عندما تريد أن يحافظ الكود الجديد على الاتساق مع الأعراف الراسخة (معالجة الأخطاء، التحقق، التسجيل، الاختبار)
• تنفيذ وظائف مشابهة في منطقة جديدة من قاعدة الكود
• التأهيل لأجزاء غير مألوفة من قاعدة الكود حيث تريد تعلّم الأنماط الحالية وتكرارها
• عندما تريد تجنب وصف الأنماط بالتفصيل وتحتاج Verdent لاستيعاب فروق دقيقة يصعب التعبير عنها

اذكر القيود أو المتطلبات:

We're using TypeScript with strict mode enabled, React 18 with hooks only (no class components), and Material-UI v5 for styling

متى تستخدمها:

• عندما يحمل مشروعك متطلبات تقنية محددة (وضع TypeScript الصارم، React hooks فقط، بلا اعتماديات خارجية)
• العمل مع قيود قديمة (دعم IE11، توافق Node.js 14)
• عندما تحدد متطلبات الامتثال الخيارات (إتاحة الوصول WCAG، معالجة بيانات GDPR)
• استخدام إصدارات مكتبات محددة بتغييرات جذرية بين الإصدارات
• عندما تحتاج إلى منع Verdent من اقتراح حلول تنتهك الحدود التقنية لمشروعك

اشرح القواعد الخاصة بالمجال:

Users can only view tasks assigned to them or their team. Managers can view all tasks in their department. Admins can view everything.

متى تستخدمها:

• عند تنفيذ ميزات ذات قواعد خاصة بالمجال لا يمكن لـ Verdent استنتاجها من الكود وحده
• منطق التفويض (من يمكنه الوصول إلى ماذا)، سير عمل الأعمال (عمليات الموافقة، آلات الحالة)
• قواعد التحقق (سياسات كلمات المرور، قيود البيانات)، قيود المجال (حدود المخزون، قواعد التسعير)
• بناء نماذج بيانات حيث تحتاج علاقات الكيانات والكاردينالية إلى شرح
• تنفيذ حسابات (قواعد الخصم، حساب الضرائب، هياكل العمولات)
• عندما تحتاج Verdent لتطبيق قواعد عمل مؤسستك بشكل صحيح، وليس فقط كودًا وظيفيًا

شارك رسائل الأخطاء أو السجلات عند تصحيح الأخطاء:

Getting "TypeError: Cannot read property 'id' of undefined" at UserController.js:42 when trying to update user profiles. The req.user object exists but doesn't have an id property after the recent auth middleware changes.

متى تستخدمها:

• أدرج دائمًا رسائل الأخطاء الكاملة وتتبعات الكومة (stack traces) والسجلات عند إصلاح الأخطاء
• أخطاء وقت التشغيل (الاستثناءات، الأعطال)، فشل البناء (أخطاء التصريف، مخالفات الفحص)
• فشل الاختبارات (أخطاء التأكيد، مشاكل المهلة)، سلوك غير متوقع (مخرجات خاطئة، بيانات مفقودة)
• عندما تملك رسائل خطأ دقيقة مع أرقام الأسطر وتتبع الكومة الكامل الذي يوضّح سلسلة الاستدعاءات
• عندما يمكنك توفير سياق حول متى يحدث ذلك (دائمًا، متقطع، شروط محددة)
• عندما تريد تحسين قدرة Verdent بشكل كبير على تحديد الأسباب الجذرية بدلًا من التخمين

يحمّل Verdent تلقائيًا الملفات ذات الصلة استنادًا إلى طلبك:

• الملفات المذكورة بالاسم في الـ prompts
• الملفات ذات الصلة في نفس الدليل
• ملفات المشروع الشائعة الوصول إليها

متى تعتمد على هذا:

• للإشارات القياسية إلى الملفات حيث تكون العلاقات واضحة
• ذكر المكونات بالاسم واحتياج Verdent لتحميل ذلك الملف المحدد
• العمل مع ملفات في نفس الدليل التي تعمل معًا عادةً
• الوصول إلى ملفات المشروع المستخدمة كثيرًا (package.json، ملفات الإعداد)
• يعمل بشكل جيد في السيناريوهات المباشرة في قواعد الأكواد المنظمة جيدًا
• في إعادة الهيكلة المعقدة متعددة الملفات، أو أجزاء بعيدة من قاعدة الكود، أو أسماء ملفات غامضة، استخدم الإشارات بـ @ صراحةً بدلًا من ذلك

اضبط سياقًا دائمًا عبر ملفات القواعد (الإعدادات ← القواعد):

قواعد المستخدم (VERDENT.md): تفضيلات عامة تُطبَّق عبر جميع المشاريع

قواعد المشروع (AGENTS.md): معايير خاصة بالمشروع - الأنماط المعمارية، معايير الكود

قواعد الخطة (plan_rules.md): خصّص تنسيق الخطة ومحتواها في Plan Mode

متى تستخدمها:

• عند تقديم نفس السياق مرارًا عبر الجلسات
• قواعد المستخدم للتفضيلات الشخصية (أسلوب الكود، المكتبات المفضلة، الأنماط التي تفضلها)
• قواعد المشروع لمعايير الفريق (القرارات المعمارية، اصطلاحات التسمية، متطلبات الاختبار)
• قيّمة لتأهيل أعضاء فريق جدد (تدوّن المعرفة القبلية)
• الحفاظ على الاتساق عبر الفرق الكبيرة وتقليل إسهاب الـ prompts
• استثمر في ملفات القواعد عندما ينضج مشروعك بما يكفي لوجود أنماط راسخة تستحق التوثيق

أدرج لقطات شاشة أو نماذج تصميم أو مخططات:

@screenshot.png Implement this UI design with React components

متى تستخدمها:

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

أشر إلى وثائق أو أمثلة خارجية:

Ultrathink: Read this API documentation at https://api-docs.example.com/v1/endpoints and implement the authentication flow

متى تستخدمها:

• عند تنفيذ تكاملات مع APIs خارجية أو مكتبات تملك وثائق رسمية على الإنترنت
• قيّمة بشكل خاص عندما تحتوي المكتبة على خيارات إعداد معقدة أو تدفقات مصادقة
• استخدم بادئة "Ultrathink:" لتوجيه Verdent لجلب محتوى الويب وتحليله قبل إنشاء الكود
• ضروري لـ APIs سريعة التطور حيث تكون الوثائق أحدث من بيانات التدريب
• عند اتباع أنماط خاصة بإطار العمل (Router الخاص بتطبيقات Next.js، Vue Composition API)
• يضمن مطابقة التنفيذات لإصدارات API الحالية واتباع التوصيات الرسمية

الـ prompt الأولي:

Add authentication to the API

قد تكون استجابة Verdent عامة. حسّنها:

Use JWT tokens stored in httpOnly cookies, implement refresh token rotation, and follow the authentication pattern from our existing UserController

متى تستخدمها: البدء بطلب عام، ثم إضافة التفاصيل بناءً على الاستجابة الأولية

إذا لم يطابق تنفيذ Verdent توقعاتك:

The validation logic is good, but use Joi schema validation instead of manual checks. Match the validation pattern in ProductController.js

متى تستخدمها: بعد مراجعة المخرجات وتحديد تحسينات محددة

ابنِ تدريجيًا:

Initial: "Create a UserProfile component"
Follow-up: "Add an avatar upload feature with image preview"
Follow-up: "Add validation - max 5MB, only jpg/png formats"
Follow-up: "Show upload progress with a progress bar"

متى تستخدمها: بناء الميزات تدريجيًا ضمن نفس الجلسة

إذا بدا التنفيذ غير متوقع:

Why did you use Redux instead of Context API? Can you explain the trade-offs for this use case?

ثم حسّن بناءً على الفهم:

Actually, use Context API for consistency with the rest of our application

متى تستخدمها: فهم المنطق قبل طلب التغييرات

للتغييرات المعقدة:

Switch to Plan Mode
Show me how you would refactor the authentication system to support OAuth providers

راجع الخطة، اطرح الأسئلة، حسّن الأسلوب قبل التنفيذ.

متى تستخدمها: التغييرات المعمارية الكبرى التي تتطلب مراجعة

إذا لم يطابق أسلوب Verdent أسلوبك:

The component structure is close, but use this pattern instead:
[paste example of your preferred structure]
Apply this same pattern to the remaining components

متى تستخدمها: ترسيخ أو تعزيز تفضيلات أسلوب الكود

إذا خالفت المخرجات قيودًا غير مذكورة:

Good approach, but don't modify the database schema - work within the existing User table structure

متى تستخدمها: إضافة قيود اكتُشِفت بعد رؤية التنفيذ الأولي

ابدأ بالوظائف الأساسية، وأضف الميزات تدريجيًا:

Step 1: "Create basic CRUD endpoints for tasks"
Step 2: "Add pagination to the GET endpoint"
Step 3: "Add filtering by status and priority"
Step 4: "Add full-text search across title and description"

متى تستخدمها: بناء ميزات معقدة تدريجيًا مع الاختبار في كل خطوة