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

<Callout type="info" title="مسودة أولى، وليست نهائية">
فكر في أمرك الأول كمسودة أولية. حتى مهندسو الأوامر ذوو الخبرة نادراً ما يصيبون الهدف من المحاولة الأولى.
</Callout>

## دورة التكرار

يتبع تحسين الأوامر الفعال دورة يمكن التنبؤ بها: الكتابة، والاختبار، والتحليل، والتحسين. كل تكرار يقربك من أمر ينتج النتائج التي تحتاجها بشكل موثوق.

<IterativeRefinementDemo />

## أنماط التحسين الشائعة

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

### المشكلة: المخرجات طويلة جداً

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

<DiffView 
  before="Explain how photosynthesis works."
  after={`Explain how photosynthesis works in 3-4 sentences suitable for a 10-year-old.`}
  beforeLabel="الأصلي"
  afterLabel="المحسّن"
/>

### المشكلة: المخرجات غامضة جداً

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

<DiffView 
  before="Give me tips for better presentations."
  after={`Give me 5 specific, actionable tips for improving technical presentations to non-technical stakeholders. For each tip, include a concrete example.`}
  beforeLabel="الأصلي"
  afterLabel="المحسّن"
/>

### المشكلة: نبرة خاطئة

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

<DiffView 
  before="Write an apology email for missing a deadline."
  after={`Write a professional but warm apology email for missing a project deadline. The tone should be accountable without being overly apologetic. Include a concrete plan to prevent future delays.`}
  beforeLabel="الأصلي"
  afterLabel="المحسّن"
/>

### المشكلة: معلومات أساسية مفقودة

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

<DiffView 
  before="Review this code."
  after={`Review this Python code for:
1. Bugs and logical errors
2. Performance issues
3. Security vulnerabilities
4. Code style (PEP 8)

For each issue found, explain the problem and suggest a fix.

[code]`}
  beforeLabel="الأصلي"
  afterLabel="المحسّن"
/>

### المشكلة: تنسيق غير متسق

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

<DiffView 
  before="Analyze these three products."
  after={`Analyze these three products using this exact format for each:

## [Product Name]
**Price:** $X
**Pros:** [bullet list]
**Cons:** [bullet list]
**Best For:** [one sentence]
**Rating:** X/10

[products]`}
  beforeLabel="الأصلي"
  afterLabel="المحسّن"
/>

## نهج التحسين المنهجي

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

### الخطوة 1: تشخيص المشكلة

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

<div className="my-4 grid gap-2">
  <div className="grid grid-cols-3 gap-2 p-3 bg-muted/50 rounded-lg text-sm">
    <span className="font-semibold">العَرَض</span>
    <span className="font-semibold">السبب المحتمل</span>
    <span className="font-semibold">الحل</span>
  </div>
  <div className="grid grid-cols-3 gap-2 p-3 bg-red-50 dark:bg-red-950/20 rounded-lg text-sm">
    <span>طويل جداً</span>
    <span className="text-muted-foreground">لا يوجد قيد على الطول</span>
    <span className="text-green-600 dark:text-green-400">أضف حدود للكلمات/الجمل</span>
  </div>
  <div className="grid grid-cols-3 gap-2 p-3 bg-red-50 dark:bg-red-950/20 rounded-lg text-sm">
    <span>قصير جداً</span>
    <span className="text-muted-foreground">يفتقر لطلب التفاصيل</span>
    <span className="text-green-600 dark:text-green-400">اطلب التوسع</span>
  </div>
  <div className="grid grid-cols-3 gap-2 p-3 bg-red-50 dark:bg-red-950/20 rounded-lg text-sm">
    <span>خارج الموضوع</span>
    <span className="text-muted-foreground">تعليمات غامضة</span>
    <span className="text-green-600 dark:text-green-400">كن أكثر تحديداً</span>
  </div>
  <div className="grid grid-cols-3 gap-2 p-3 bg-red-50 dark:bg-red-950/20 rounded-lg text-sm">
    <span>تنسيق خاطئ</span>
    <span className="text-muted-foreground">لم يُحدد التنسيق</span>
    <span className="text-green-600 dark:text-green-400">حدد الهيكل بالضبط</span>
  </div>
  <div className="grid grid-cols-3 gap-2 p-3 bg-red-50 dark:bg-red-950/20 rounded-lg text-sm">
    <span>نبرة خاطئة</span>
    <span className="text-muted-foreground">الجمهور غير واضح</span>
    <span className="text-green-600 dark:text-green-400">حدد الجمهور/الأسلوب</span>
  </div>
  <div className="grid grid-cols-3 gap-2 p-3 bg-red-50 dark:bg-red-950/20 rounded-lg text-sm">
    <span>غير متسق</span>
    <span className="text-muted-foreground">لم تُقدم أمثلة</span>
    <span className="text-green-600 dark:text-green-400">أضف أمثلة توضيحية</span>
  </div>
</div>

### الخطوة 2: قم بتغييرات مستهدفة

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

```
Iteration 1: Add length constraint
Iteration 2: Specify format
Iteration 3: Add example
Iteration 4: Refine tone instructions
```

### الخطوة 3: وثّق ما ينجح

معرفة هندسة الأوامر تُفقد بسهولة. احتفظ بسجل لما جربته ولماذا. هذا يوفر الوقت عندما تعود للأمر لاحقاً أو تواجه تحديات مماثلة:

```markdown
## Prompt: Customer Email Response

### Version 1 (too formal)
"Write a response to this customer complaint."

### Version 2 (better tone, still missing structure)
"Write a friendly but professional response to this complaint. 
Show empathy first."

### Version 3 (final - good results)
"Write a response to this customer complaint. Structure:
1. Acknowledge their frustration (1 sentence)
2. Apologize specifically (1 sentence)  
3. Explain solution (2-3 sentences)
4. Offer additional help (1 sentence)

Tone: Friendly, professional, empathetic but not groveling."
```

## مثال واقعي على التكرار

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

### المهمة: توليد أسماء منتجات

<VersionDiff versions={[
  {
    label: "الإصدار 1",
    content: "Generate names for a new productivity app.",
    note: "عام جداً، لا يوجد سياق"
  },
  {
    label: "الإصدار 2",
    content: `Generate names for a new productivity app. The app uses AI to automatically schedule your tasks based on energy levels and calendar availability.`,
    note: "تمت إضافة سياق، لا يزال عاماً"
  },
  {
    label: "الإصدار 3",
    content: `Generate 10 unique, memorable names for a productivity app with these characteristics:
- Uses AI to schedule tasks based on energy levels
- Target audience: busy professionals aged 25-40
- Brand tone: modern, smart, slightly playful
- Avoid: generic words like "pro", "smart", "AI", "task"

For each name, explain why it works.`,
    note: "تمت إضافة قيود وتفسير"
  },
  {
    label: "الإصدار 4 (النهائي)",
    content: `Generate 10 unique, memorable names for a productivity app.

Context:
- Uses AI to schedule tasks based on energy levels
- Target: busy professionals, 25-40
- Tone: modern, smart, slightly playful

Requirements:
- 2-3 syllables maximum
- Easy to spell and pronounce
- Available as .com domain (check if plausible)
- Avoid: generic words (pro, smart, AI, task, flow)

Format:
Name | Pronunciation | Why It Works | Domain Availability Guess`,
    note: "تنسيق منظم، متطلبات محددة"
  }
]} />

## استراتيجيات التحسين حسب نوع المهمة

المهام المختلفة تفشل بطرق يمكن التنبؤ بها. معرفة أوضاع الفشل الشائعة تساعدك على تشخيص المشكلات وإصلاحها بشكل أسرع.

### لتوليد المحتوى

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

<InfoGrid items={[
  { icon: "target", title: "عام جداً", description: "أضف قيوداً وسياقاً محدداً", example: "\"Write about dogs\" → \"Write about golden retrievers for first-time owners, focusing on training and exercise needs\"" },
  { icon: "scissors", title: "طويل جداً", description: "حدد حدود الكلمات/الفقرات", example: "Add: \"Keep response under 150 words\" or \"Maximum 3 paragraphs\"" },
  { icon: "palette", title: "أسلوب خاطئ", description: "قدم أمثلة على الأسلوب", example: "\"Write in the style of this example: [paste sample text]\"" },
  { icon: "megaphone", title: "بعيد عن الهوية", description: "ضمّن إرشادات صوت العلامة التجارية", example: "\"Use friendly, casual tone. Avoid jargon. Address reader as 'you'.\"" }
]} />

### لتوليد الكود

يمكن أن يفشل مخرج الكود تقنياً (أخطاء نحوية، ميزات لغة خاطئة) أو معمارياً (أنماط سيئة، حالات مفقودة). المشكلات التقنية تحتاج تحديد الإصدار/البيئة؛ المشكلات المعمارية تحتاج توجيهات التصميم.

<InfoGrid items={[
  { icon: "code", title: "أخطاء نحوية", description: "حدد إصدار اللغة", example: "\"Use Python 3.11+ syntax with type hints\" or \"ES2022 JavaScript\"" },
  { icon: "git-branch", title: "نهج خاطئ", description: "صف الأنماط المفضلة", example: "\"Use functional approach, avoid classes\" or \"Follow repository pattern\"" },
  { icon: "shield", title: "حالات حدية مفقودة", description: "اذكر السيناريوهات للتعامل معها", example: "\"Handle: empty input, null values, network timeouts, invalid formats\"" },
  { icon: "tag", title: "تسمية سيئة", description: "ضمّن اتفاقيات التسمية", example: "\"Use camelCase for variables, PascalCase for classes, UPPER_SNAKE for constants\"" }
]} />

### للتحليل

غالباً ما تنتج مهام التحليل نتائج سطحية أو غير منظمة. وجّه النموذج بأطر عمل محددة (SWOT، قوى بورتر الخمس)، اطلب وجهات نظر متعددة، أو قدم قالباً لهيكل المخرجات.

<InfoGrid items={[
  { icon: "layers", title: "سطحي جداً", description: "اطلب أطر عمل محددة", example: "\"Analyze using SWOT framework\" or \"Apply Porter's Five Forces\"" },
  { icon: "scale", title: "متحيز", description: "اطلب وجهات نظر متعددة", example: "\"Present arguments for and against\" or \"Include skeptic's viewpoint\"" },
  { icon: "database", title: "بيانات مفقودة", description: "حدد ما يجب تحليله", example: "\"Focus on: market size, growth rate, key players, entry barriers\"" },
  { icon: "layout", title: "غير منظم", description: "قدم قالب تحليل", example: "\"Format as: Summary → Key Findings → Implications → Recommendations\"" }
]} />

### للأسئلة والأجوبة

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

<InfoGrid items={[
  { icon: "plus", title: "قصير جداً", description: "اطلب التوسع", example: "\"Explain in detail with examples\" or \"Elaborate on each point\"" },
  { icon: "minus", title: "طويل جداً", description: "اطلب إجابة موجزة", example: "\"Answer in 2-3 sentences\" or \"Give me the TL;DR\"" },
  { icon: "help-circle", title: "غير مؤكد", description: "اطلب مستوى الثقة", example: "\"Rate your confidence 1-10\" or \"Note any assumptions made\"" },
  { icon: "link", title: "بدون مصادر", description: "اطلب اقتباسات", example: "\"Cite sources for claims\" or \"Include references where possible\"" }
]} />

## تقنية حلقة التغذية الراجعة

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

```
I used this prompt:
"[your prompt]"

And got this output:
"[model output]"

I wanted something more [describe gap]. How should I modify 
my prompt to get better results?
```

## اختبار A/B للأوامر

للأوامر التي ستُستخدم بشكل متكرر أو على نطاق واسع، لا تختر فقط أول أمر يعمل. اختبر الاختلافات لإيجاد النهج الأكثر موثوقية وأعلى جودة.

```
Prompt A: "Summarize this article in 3 bullet points."
Prompt B: "Extract the 3 most important insights from this article."
Prompt C: "What are the key takeaways from this article? List 3."
```

شغّل كل واحد عدة مرات، وقارن:
- اتساق المخرجات
- جودة المعلومات
- ملاءمتها لاحتياجاتك

## متى تتوقف عن التكرار

الكمال عدو الجيد الكافي. اعرف متى يكون أمرك جاهزاً للاستخدام ومتى تكون مجرد تلميع مع عوائد متناقصة.

<div className="my-6 grid md:grid-cols-2 gap-4">
  <div className="border rounded-lg bg-green-50/50 dark:bg-green-950/20 border-green-200 dark:border-green-900">
    <p className="text-sm font-semibold text-green-700 dark:text-green-400 px-4 pt-3 flex items-center gap-2 m-0!"><IconCheck className="h-4 w-4" /> جاهز للإطلاق</p>
    <div className="text-sm p-4 pt-2 space-y-1">
      <p className="m-0!">المخرجات تلبي المتطلبات باستمرار</p>
      <p className="m-0!">الحالات الحدية تُعالج بشكل مناسب</p>
      <p className="m-0!">التنسيق موثوق وقابل للتحليل</p>
      <p className="m-0!">التحسينات الإضافية تُظهر عوائد متناقصة</p>
    </div>
  </div>
  <div className="border rounded-lg bg-red-50/50 dark:bg-red-950/20 border-red-200 dark:border-red-900">
    <p className="text-sm font-semibold text-red-700 dark:text-red-400 px-4 pt-3 flex items-center gap-2 m-0!"><IconX className="h-4 w-4" /> استمر في التكرار</p>
    <div className="text-sm p-4 pt-2 space-y-1">
      <p className="m-0!">المخرجات غير متسقة عبر التشغيلات</p>
      <p className="m-0!">الحالات الحدية تسبب فشلاً</p>
      <p className="m-0!">المتطلبات الحرجة مفقودة</p>
      <p className="m-0!">لم تختبر اختلافات كافية</p>
    </div>
  </div>
</div>

## التحكم في الإصدارات للأوامر

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

<Callout type="tip" title="إدارة الإصدارات المدمجة">
prompts.chat يتضمن سجل إصدارات تلقائي لأوامرك. كل تعديل يُحفظ، لذا يمكنك مقارنة الإصدارات واستعادة التكرارات السابقة بنقرة واحدة.
</Callout>

للأوامر التي تديرها بنفسك، استخدم هيكل مجلدات:

```
prompts/
├── customer-response/
│   ├── v1.0.txt    # Initial version
│   ├── v1.1.txt    # Fixed tone issue
│   ├── v2.0.txt    # Major restructure
│   └── current.txt # Symlink to active version
└── changelog.md    # Document changes
```

## الملخص

<Callout type="tip" title="النقاط الرئيسية">
ابدأ ببساطة، راقب بعناية، غيّر شيئاً واحداً في كل مرة، وثّق ما ينجح، واعرف متى تتوقف. أفضل الأوامر لا تُكتب—بل تُكتشف من خلال التكرار المنهجي.
</Callout>

<Quiz 
  question="ما هو أفضل نهج عند تحسين أمر ينتج نتائج خاطئة؟"
  options={[
    "إعادة كتابة الأمر بالكامل من الصفر",
    "إضافة المزيد من الأمثلة حتى يعمل",
    "تغيير شيء واحد في كل مرة واختبار كل تغيير",
    "جعل الأمر أطول ما يمكن"
  ]}
  correctIndex={2}
  explanation="تغيير شيء واحد في كل مرة يتيح لك عزل ما يعمل وما لا يعمل. إذا غيرت أشياء متعددة في وقت واحد، لن تعرف أي تغيير أصلح المشكلة أو أي تغيير جعلها أسوأ."
/>

## تدريب: حسّن هذا الأمر

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

<BeforeAfterEditor
  title="حسّن أمر البريد الإلكتروني هذا"
  badPrompt="Write an email."
  idealPrompt={`You are a professional business writer.

Task: Write a follow-up email to a potential client after a sales meeting.

Context:
- Met with Sarah Chen, VP of Marketing at TechCorp
- Discussed our analytics platform
- She expressed interest in the reporting features
- Meeting was yesterday

Requirements:
- Professional but warm tone
- Reference specific points from our meeting
- Include a clear next step (schedule a demo)
- Keep under 150 words

Format: Subject line + email body`}
  task="حوّل أمر البريد الإلكتروني الغامض هذا إلى شيء سينتج نتيجة احترافية وفعالة."
/>

في الفصل القادم، سنستكشف استخدام JSON و YAML في الأوامر لتطبيقات البيانات المنظمة.
