الدليل الشامل لكتابة System Prompts لوكلاء الذكاء الاصطناعي — دروس من الهندسة العكسية لـ Claude Code

فككت الـ system prompt لـ Claude Code، ودرست الكود المصدري لـ DeepAgents، وبنيت الـ AI agent الخاص بي من الصفر. معظم أدلة الـ prompt هي مجرد "تنظير".

هناك وهم جماعي يحدث في عالم الذكاء الاصطناعي الآن.

كل درس تعليمي يخبرك أن تكتب موجهات النظام (system prompts) وكأنك تلقي تعويذة سحرية — فقط ابحث عن الكلمات المناسبة وسيطيعك النموذج. "أنت مهندس خبير وموهوب للغاية ولديك 20 عامًا من الخبرة..." هل يبدو هذا مألوفًا؟

لقد قضيت الأشهر القليلة الماضية في بناء VibeCom، وهو مستشار شركات ناشئة يعمل بالذكاء الاصطناعي، يقوم بإجراء أبحاث سوقية عميقة ويولد تحليلات بمستوى الصناديق الاستثمارية (VC-grade). خلال هذه الرحلة، قمت بعمل هندسة عكسية لموجه النظام الخاص بـ Claude Code، وقرأت الكود المصدري للبرمجيات الوسيطة (middleware) الخاصة بـ DeepAgents، واستهلكت من أرصدة الـ API أكثر مما أود الاعتراف به. الدرس الأكبر الذي تعلمته؟ معظم ما يعتقده الناس مهمًا في موجهات النظام ليس كذلك. والأشياء التي تهم حقًا، لا يكاد يتحدث عنها أحد.

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

1. فلسفة التصميم: ثق في النموذج

"الوكيل (agent) هو نموذج. ليس إطار عمل. وليس سلسلة من الموجهات." — shareAI-lab/learn-claude-code

هذه الفكرة غيرت كل شيء بالنسبة لي. النموذج اللغوي الكبير (LLM) يعرف بالفعل كيف يحلل، ويخطط، وينفذ. موجه النظام الخاص بك لا يعلمه كيف يفكر — بل يهيئ له بيئة العمل التي سيعمل فيها.

تخيل الأمر وكأنك توظف مهندسًا خبيرًا (Senior Engineer). أنت لا تسلمه قائمة تحقق (checklist) من 20 خطوة لكل مهمة. بل تقول له: هذا من نحن، وهذه هي حدودنا، وهذا هو شكل العمل الممتاز بالنسبة لنا. ثم تبتعد عن طريقه وتدعه يعمل.

موجه النظام الخاص بك لديه أربع وظائف بالضبط:

أخبره من هو — الدور والهوية
أخبره أين تقع الجدران — قيود الأمان
أخبره كيف يبدو العمل الجيد — معايير الجودة
امنحه الأدوات — القدرات والمعرفة

هذا كل شيء. أي شيء آخر هو مجرد ضوضاء.

عقلية إطار التوجيه (The Harness Mindset)

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

موجه النظام الخاص بك هو دليل التشغيل لإطار التوجيه هذا. أنت لا تصمم مسار عمل (pipeline) صارم — أنت تصمم بيئة يمكن للنموذج أن يقدم فيها أفضل ما لديه باستقلالية.

لا تكتب موجه النظام الخاص بك على شكل مخطط انسيابي (flowchart). النموذج سيقرر ترتيب التنفيذ بنفسه.

2. هيكل الموجه وترتيب الأقسام

التخطيط الموصى به (مستخرج بالهندسة العكسية من Claude Code v2.0.14)

┌─────────────────────────────────────────────┐
│ 1. Identity                                  │  ← Read first, anchors behavior
│ 2. Security & Safety                         │  ← IMPORTANT markers, non-negotiable
│ 3. Tone & Style                              │  ← Controls output format
│ 4. Core Workflow                             │  ← How to do the work
│ 5. Tool Usage Policy                         │  ← Tool selection priorities
│ 6. Domain Knowledge                          │  ← On-demand, not pre-loaded
│ 7. Environment Info                          │  ← Runtime context, dynamically injected
│ 8. Reminders                                 │  ← Re-state critical rules
├─────────────────────────────────────────────┤
│ [Tool Definitions — system-injected]         │  ← Not editable, usually very long
├─────────────────────────────────────────────┤
│ [User Message]                               │
└─────────────────────────────────────────────┘

لماذا هذا الترتيب مهم؟

النماذج اللغوية (LLMs) لديها منحنى انتباه على شكل حرف U — فهي تولي أكبر قدر من الانتباه لبداية ونهاية الموجه الخاص بك، وتفقد التركيز في المنتصف. هذا هو تأثير "الضياع في المنتصف" (Lost in the Middle)، وهو موثق جيدًا.

الهوية + الأمان في الأعلى: يحدد النموذج دوره وحدوده أولاً (تأثير الأولوية - Primacy effect).
سير العمل الأساسي في النصف العلوي: القسم الأهم — كيف ينجز الوكيل عمله.
تعريفات الأدوات يتم حقنها بواسطة النظام بعد الموجه الخاص بك: تعريفات أدوات Claude Code تستهلك حوالي 11,438 توكن. هذا يعني أن المحتوى المخصص الخاص بك ينتهي به المطاف أقرب إلى البداية مما تتوقع — وهو ما يساعد في التزام النموذج بالتعليمات.
التذكيرات في الأسفل: استغلال انحياز الحداثة (Recency bias) لتعزيز القواعد الحاسمة.

3. كتابة كل قسم

3.1 الهوية — من هو هذا الوكيل؟

الهدف: تثبيت دور النموذج في 1-3 جمل.

You are Claude Code, Anthropic's official CLI for Claude.
You are an interactive agent that helps users with software engineering tasks.

الإرشادات:

اجعله موجزًا — 3 جمل كحد أقصى.
اذكر الدور بوضوح (يساعد النموذج على تمييز السياقات).
اذكر المسؤولية الأساسية ("يساعد في X")، وليس عبارة غامضة مثل "أنت مساعد مفيد".
اذكر الـ SDK/المنصة إذا كان ذلك مناسبًا ("مبني على Anthropic's Claude Agent SDK").

الممارسات الخاطئة:

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

3.2 الأمان والسلامة — الحدود الصارمة

الهدف: وضع قيود سلوكية لا يمكن كسرها.

IMPORTANT: Assist with defensive security tasks only.
Refuse to create, modify, or improve code that may be used maliciously.
IMPORTANT: You must NEVER generate or guess URLs for the user.

الإرشادات:

استخدم بادئة IMPORTANT: — التدريب الهرمي للتعليمات في Claude يعطي هذا وزنًا إضافيًا.
استخدم لغة مطلقة: NEVER (أبدًا)، MUST NOT (يجب ألا)، Refuse to (ارفض أن).
اذكر ما هو مسموح به وما هو محظور (القيود ثنائية الاتجاه أكثر وضوحًا).
ضعها في الأعلى تمامًا، ولا تدفنها في المنتصف.
كرر قواعد الأمان الحاسمة في النهاية — Claude Code يفعل هذا بالضبط.

لماذا التكرار؟ تأثير الأولوية (في البداية) + تأثير الحداثة (في النهاية) = تعزيز مزدوج. يظهر إعلان الأمان الخاص بـ Claude Code في بداية ونهاية الموجه. ليس لأن المهندسين كانوا كثيري النسيان — بل لأنهم يفهمون منحنى الانتباه على شكل حرف U.

3.3 النبرة والأسلوب — التحكم في المخرجات

الهدف: التحكم في تنسيق المخرجات وصوتها.

## Tone and style

- Your responses should be short and concise.
- Only use emojis if the user explicitly requests it.
- Use Github-flavored markdown for formatting.
- NEVER create files unless absolutely necessary.

الإرشادات:

اذكر سلوكيات محددة، وليس عبارات غامضة مثل "كن محترفًا".
يجب أن تكون كل قاعدة قابلة للاختبار (صح/خطأ) ("قصير وموجز" مقابل "حاول أن تكون مختصرًا").
قم بتضمين متطلبات تنسيق المخرجات (Markdown؟ JSON؟ نص عادي؟).
قم بتضمين ما يجب ألا يفعله — العديد من مشكلات الأسلوب تتعلق بحظر سلوكيات معينة.

جوهرة Claude Code — الموضوعية المهنية:

Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation.

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

3.4 سير العمل الأساسي — القسم الأهم

الهدف: تعليم النموذج كيف يعمل — المنهجية، وليس الإجراءات الصارمة.

هذا هو أصعب قسم يمكن كتابته بشكل جيد، والأكثر تأثيرًا عندما تتقنه.

المبدأ الأساسي: قدم مبادئ، لا إجراءات.

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

نهج Claude Code:

## Doing tasks

The user will primarily request software engineering tasks.
For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required

لاحظ كلمة "موصى بها" (recommended) — وليس "يجب عليك اتباع هذه الخطوات بالضبط". اختيار هذه الكلمة الواحدة يمنح النموذج مساحة للتكيف.

تعريف جيد لسير العمل:

1. Understand first — read existing code before modifying it
2. Plan first — break complex tasks into steps before executing
3. Minimal changes — only change what's necessary, don't "refactor while you're in there"
4. Verify — confirm your changes work (run tests, lint, etc.)

كل قاعدة تحتوي على "لماذا" ضمنية — يمكن للنموذج فهم القصد وتعميمه على سيناريوهات جديدة.

الممارسات الخاطئة:

إجراء صارم من 20 خطوة — سينفذ النموذج بشكل ميكانيكي وسيتجمد عند المدخلات غير المتوقعة.
"أولاً افعل أ، ثم افعل ب، ثم افعل ج" — هذه سلسلة موجهات (prompt chain)، وليست موجه وكيل (agent prompt).
التوجيه المفرط في أشياء يجيدها النموذج بالفعل — يهدر التوكنز.

لقد تعلمت هذا الدرس بالطريقة الصعبة مع VibeCom. الإصدارات الأولى كانت تحتوي على سير عمل بحثي من 10 خطوات. كان النموذج ينفذ جميع الخطوات العشر بطاعة حتى عندما كانت الخطوة 3 تجيب بالفعل على سؤال المستخدم. عندما تحولت إلى المبادئ ("ابحث حتى يكون لديك أدلة كافية، ثم قم بالتلخيص")، ارتفعت الجودة وانخفضت تكاليف التوكنز.

الاستثناء: عندما تُستهلك المخرجات بواسطة آلات أخرى (تواصل بين الوكلاء، تنسيقات استجابة API)، يجب عليك تحديد تنسيقات صارمة. المبادئ مخصصة للسلوك؛ المخططات (schemas) مخصصة للواجهات.

3.5 سياسة استخدام الأدوات — حل الغموض

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

## Tool usage policy

- Use specialized tools instead of bash commands:
  - Read for reading files instead of cat/head/tail
  - Edit for editing instead of sed/awk
  - Grep for searching instead of grep/rg
- You can call multiple tools in a single response. If independent, call in parallel.
- Use the Task tool for file search to reduce context usage.

الإرشادات:

استخدم "بدلاً من" (instead of) للتعبير عن الأولوية (أ بدلاً من ب).
اشرح لماذا يجب تفضيل أدوات معينة ("يوفر تجربة مستخدم أفضل"، "يقلل من استخدام السياق").
حدد استراتيجية التوازي (مستقلة ← بالتوازي، معتمدة على بعضها ← بالتسلسل).
اذكر قيود الأمان لاستخدام الأدوات (التحقق من المسار، التحقق من الصلاحيات).

العلاقة الحاسمة بين الأدوات والموجهات:

عادةً ما يتم حقن تعريفات الأدوات بواسطة النظام ولا يمكنك تعديلها مباشرة. تعريفات أدوات Claude Code تبلغ حوالي 11,438 توكن. هذا يعني:

لا تكرر المعلومات الموجودة بالفعل في تعريفات الأدوات.
استخدم موجه النظام للتوجيه الاستراتيجي: متى تستخدم كل أداة، لماذا تفضل واحدة على أخرى، ترتيب الأولويات.
جودة تعريف الأداة تؤثر بشكل مباشر على فعالية الوكيل — إذا كنت تبني وكيلك الخاص، فاستثمر الوقت في كتابة أوصاف ممتازة للأدوات.

3.6 المعرفة المتخصصة — التحميل عند الطلب، وليس مسبقًا

الهدف: توفير معرفة متخصصة قد تفتقر إليها بيانات تدريب النموذج.

المبدأ الأساسي: الكشف التدريجي (progressive disclosure)، وليس تفريغ المعرفة.

❌ Paste all 200 API endpoints into the system prompt → token explosion
✅ Give the model a tool to look things up → "Load knowledge when you need it"

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

مناهج التنفيذ:

ضع مؤشرات في موجه النظام: "استخدم أداة get_api_docs لاسترداد الوثائق عند الحاجة".
استخدم CLAUDE.md / AGENTS.md لسياق المشروع — يتم تحميلها في وقت التشغيل، وليس برمجتها بشكل ثابت (hardcoded).
استخدم Skills / SKILL.md لاكتشاف القدرات — يرى النموذج قائمة بالمهارات المتاحة، ويجلب المواصفات الكاملة عند الطلب.

3.7 معلومات البيئة — سياق وقت التشغيل

الهدف: منح النموذج وعيًا ببيئة التنفيذ الخاصة به.

<env>
Working directory: /Users/fengliu/Desktop/tfm/vibecom
Is directory a git repo: true
Platform: darwin
Today's date: 2026-03-21
</env>
You are powered by the model named Claude Opus 4.6.

الإرشادات:

قم بتوليدها ديناميكيًا، ولا تقم ببرمجتها بشكل ثابت أبدًا.
قم بتضمين: دليل العمل، نظام التشغيل، التاريخ، اسم النموذج، حالة git.
استخدم تنسيقًا منظمًا (علامات XML أو كتل برمجية) لسهولة التحليل.
التاريخ مهم — يحتاج النموذج إلى معرفة "الآن" للحكم على حداثة المعلومات.

3.8 التذكيرات — التعزيز النهائي

الهدف: إعادة صياغة القواعد الأكثر أهمية في نهاية الموجه.

يكرر Claude Code قيود الأمان الخاصة به ومتطلبات TodoWrite في الأسفل:

IMPORTANT: Assist with defensive security tasks only. [repeated]
IMPORTANT: Always use the TodoWrite tool to plan and track tasks. [repeated]

الإرشادات:

كرر فقط 2-3 من القواعد الأكثر أهمية — لا تكرر كل شيء.
استغل انحياز الحداثة (recency bias) — يتذكر النموذج المحتوى الأخير بقوة أكبر.
أفضل المرشحين: قيود الأمان، القواعد التي يتم انتهاكها بشكل متكرر، تذكيرات سير العمل الأساسي.

4. ميزانية التوكنز وإدارة السياق

مرجع تخصيص الميزانية

القسم	التوكنز الموصى بها	ملاحظات
الهوية + الأمان	200-500	موجز ولكن غير قابل للتفاوض
النبرة والأسلوب	300-800	يجب أن تكون القواعد محددة، ولكن لا تطل
سير العمل الأساسي	500-2,000	القسم الأهم، يستحق الاستثمار
سياسة استخدام الأدوات	300-1,000	يعتمد على عدد الأدوات
المعرفة المتخصصة	0-1,000	يفضل التحميل عند الطلب
معلومات البيئة	100-300	يتم توليدها ديناميكيًا
التذكيرات	100-300	كرر الأساسيات فقط
المجموع الخاص بك	1,500-6,000
تعريفات الأدوات (النظام)	5,000-15,000	ليست تحت سيطرتك

منحنى تدهور السياق

قامت اختبارات المجتمع (Reddit u/CodeMonke_) برسم خريطة لتدهور الالتزام في العالم الحقيقي:

< 80 ألف توكن: يبقى الالتزام بالموجه مستقرًا.
80 ألف - 120 ألف توكن: يبدأ اتباع التعليمات في التدهور.
> 120 ألف توكن: تدهور كبير — "ينسى" النموذج التعليمات المبكرة.
> 180 ألف توكن: تدهور حاد.

نافذة السياق التي تبلغ 200 ألف توكن لا تعني 200 ألف توكن من السياق الفعّال. خطط بناءً على ذلك.

استراتيجيات التخفيف:

حافظ على موجه النظام الخاص بك رشيقًا (< 6,000 توكن للجزء الخاص بك).
استخدم التلخيص لضغط تاريخ المحادثة (DeepAgents يبدأ التلخيص عند حوالي 80 ألف حرف).
ضع القواعد الحاسمة في كلا طرفي الموجه (منحنى الانتباه على شكل حرف U).
احقن علامات <system-reminder> في منتصف المحادثة (المزيد عن هذا في القسم 8).

5. مبادئ الكتابة

5.1 قدم مبادئ، لا إجراءات

❌ "Step 1: Read the file. Step 2: Find the bug. Step 3: Fix it. Step 4: Run tests."
✅ "Always understand existing code before modifying it. Verify your changes work."

المبادئ قابلة للتعميم. الإجراءات لا يمكن اتباعها إلا بشكل ميكانيكي. عندما يواجه النموذج موقفًا لم تتوقعه، فإن المبادئ توجهه للقرار الصحيح. الإجراءات لا تفعل ذلك.

استثناء: عندما تُستهلك المخرجات بواسطة آلات (تواصل بين الوكلاء، تنسيقات API)، حدد مخططات (schemas) صارمة.

5.2 استخدم لغة مطلقة للقيود الصارمة

القوة	اللغة	تستخدم لـ
حظر مطلق	`NEVER`, `MUST NOT`	الأمان، العمليات غير القابلة للعكس
متطلب قوي	`ALWAYS`, `MUST`	قواعد سير العمل الأساسية
توصية	`recommended`, `prefer`	أفضل الممارسات مع وجود استثناءات
اقتراح	`consider`, `you may`	تحسينات اختيارية

أمثلة من Claude Code:

NEVER update the git config — حظر مطلق.
ALWAYS prefer editing an existing file — قوي، ولكن توجد استثناءات.
The following steps are recommended — سير عمل مقترح.

5.3 استخدم الأمثلة بدلاً من الشروحات

## Code References

When referencing specific functions or pieces of code include
the pattern `file_path:line_number`.

<example>
user: Where are errors from the client handled?
assistant: Clients are marked as failed in the `connectToServer`
function in src/services/process.ts:712.
</example>

مثال واحد يعلم أكثر من 100 كلمة من الشرح:

تتعلم النماذج الأنماط من الأمثلة بشكل أكثر موثوقية من الأوصاف المجردة.
غلفها بعلامات <example> لفصلها عن القواعد.
قدم أمثلة إيجابية ("افعل هذا") وسلبية ("لا تفعل هذا").
استخدم أمثلة حقيقية ومحددة — وليس عناصر نائبة مثل "foo/bar".

5.4 القيود ثنائية الاتجاه

✅ "Use dedicated tools: Read for reading files, Edit for editing files."
✅ "Do NOT use bash for file operations (cat, head, tail, sed, awk)."

قول "افعل هذا" فقط ← النموذج لا يعرف متى يجب ألا يفعله. قول "لا تفعل هذا" فقط ← النموذج لا يعرف البديل. ثنائي الاتجاه ← واضح ولا لبس فيه.

5.5 اشرح "لماذا"، وليس فقط "ماذا"

❌ "Don't use git commit --amend."
✅ "Avoid git commit --amend. ONLY use --amend when either
   (1) user explicitly requested amend OR
   (2) adding edits from pre-commit hook.
   Reason: amending may overwrite others' commits."

شرح السبب يتيح للنموذج اتخاذ أحكام صحيحة في الحالات الاستثنائية (edge cases). بروتوكول أمان git الخاص بـ Claude Code هو درس احترافي — كل قاعدة تتضمن مبررها.

5.6 الهيكلة تتفوق على السرد

عناوين Markdown (##، ###) — النماذج تتعرف على التسلسل الهرمي.
القوائم النقطية بدلاً من الفقرات — كل قاعدة قابلة للاختبار بشكل مستقل.
علامات XML للمحتوى الخاص: <example>، <env>، <system-reminder>.
الجداول للمقارنات والتعيينات.
لا تقم أبدًا بتفريغ نص غير منظم — الموجهات المنظمة تتفوق باستمرار على النثر باللغة الطبيعية في اختبارات الالتزام.

6. الممارسات الخاطئة التي تهدر التوكنز الخاصة بك

سلاسل الموجهات المتنكرة في هيئة وكلاء

"First call tool A to get data.
Then call tool B with the result.
Then format the output as JSON.
Then save to file."

هذا ليس موجه وكيل — إنه سكريبت مسار عمل (pipeline script). سينفذ النموذج بشكل ميكانيكي وسيفقد قدرته على التخطيط المستقل.

الحل: أخبر النموذج بالهدف والقيود. ودعه يقرر الخطوات.

هندسة الإطراء (Flattery Engineering)

"You are an EXTREMELY TALENTED and INCREDIBLY EXPERIENCED
senior software engineer with 20 years of experience..."

المجاملات وصيغ التفضيل لا تحسن جودة المخرجات. النموذج ليس لديه غرور لتعزيزه. وفر هذه الـ 15 توكن لقاعدة حقيقية.

تفريغ المعرفة العشوائي

"Here is the complete API documentation for our 200 endpoints..."

هذا يلتهم نافذة السياق الخاصة بك ويسرع من تدهور السياق. استبدله بالتحميل عند الطلب:

"Use the get_api_docs tool to retrieve API documentation when needed."

تكرار أوصاف الأدوات

إذا كان تعريف الأداة يقول بالفعل "أداة Read تقرأ ملفًا من نظام الملفات"، فلا تقله مرة أخرى في موجه النظام الخاص بك. أضف فقط التوجيه الاستراتيجي الذي لا يغطيه تعريف الأداة — متى تستخدمها، ولماذا تفضلها، وترتيب الأولويات.

تجاهل التعامل مع الفشل

بدون توجيه صريح، ستحاول النماذج إعادة استدعاء الأدوات الفاشلة في حلقة مفرغة (infinite loop). قم دائمًا بتضمين:

"If a tool call is denied, do not re-attempt the exact same call.
Think about why it was denied and adjust your approach."

تجاهل تدهور نافذة السياق

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

7. نقاط الحقن والأولوية

طرق التخصيص الثلاث في Claude Code

الطريقة	تستبدل	الموضع	الأفضل لـ
Output Styles	أقسام "Tone and style" + "Doing tasks"	قبل تعريفات الأدوات مباشرة	تغيير أسلوب التفاعل
--append-system-prompt	لا شيء (إضافية)	بعد أسلوب المخرجات، وقبل تعريفات الأدوات	إضافة سلوكيات محددة
--system-prompt	موجه النظام بالكامل	يحتفظ بتعريفات الأدوات + سطر هوية واحد	التخصيص الكامل (الخيار الجذري)

إذا كنت تستخدم أكثر من طريقة: Output Style ← Append Prompt ← Tool Definitions

التسلسل الهرمي للتعليمات

تم تدريب Claude خصيصًا باستخدام تسلسل هرمي للتعليمات:

1. User's explicit instructions (CLAUDE.md, direct requests)  ← Highest priority
2. Custom system prompt additions                               ← High
3. Default system prompt                                        ← Medium
4. Tool definitions                                             ← Reference level

هذا يعني:

قواعد CLAUDE.md تتجاوز سلوك موجه النظام الافتراضي.
الطلبات المباشرة للمستخدم تتجاوز كل شيء.
الموجه المخصص الخاص بك يتجاوز الموجه الافتراضي.

آليات الحقن الديناميكي

<system-reminder> — الحقن في أي رسالة في منتصف المحادثة لتذكير النموذج بالقواعد الحاسمة.
CLAUDE.md / AGENTS.md — يتم تحميلها في وقت التشغيل من الملفات، وتُلحق بموجه النظام.
Skills / SKILL.md — يتم تحميلها عند الطلب عبر استدعاءات الأدوات، ولا تستهلك مساحة في موجه النظام.

8. الحقن في منتصف المحادثة — السلاح السري

يظهر موجه النظام مرة واحدة فقط، في بداية مصفوفة الرسائل (messages array). لكن النماذج اللغوية تقبل مصفوفة الرسائل الكاملة (تتناوب بين المستخدم / المساعد / رسائل الأدوات) كمدخلات، ويمكنك حقن الموجهات في رسائل المستخدم ونتائج الأدوات أيضًا. يستخدم Claude Code هذه التقنية بكثافة في بيئة الإنتاج.

لماذا هي ضرورية؟

محاربة تدهور السياق. مع زيادة طول المحادثات، يتدهور التزام النموذج بتعليمات موجه النظام (يُلاحظ عند 80 ألف+ توكن). حقن التذكيرات في منتصف المحادثة = تحديث القواعد عبر انحياز الحداثة.

النموذج الذهني:

موجه النظام = الدستور (يتم تأسيسه مرة واحدة، سلطة طويلة الأمد).
تذكيرات رسائل المستخدم = المذكرات (تُرسل بشكل دوري، للحفاظ على التنفيذ).

ثلاث نقاط حقن في مصفوفة الرسائل

Messages Array:
┌─────────────────────────────────────┐
│ System Prompt                       │ ← Appears once, primacy effect
│   (identity, safety, workflow...)   │
├─────────────────────────────────────┤
│ User Message 1                      │
│ Assistant Message 1                 │
│ User Message 2 + <system-reminder>  │ ← Mid-conversation injection
│ Assistant Message 2                 │
│ Tool Result + <system-reminder>     │ ← Can inject into tool results too
│ ...                                 │
│ User Message N + <system-reminder>  │ ← Latest message, strongest recency
└─────────────────────────────────────┘

الموقع	الميزة	العيب
موجه النظام	تأثير الأولوية، يُقرأ أولاً	يظهر مرة واحدة، "يُنسى" في المحادثات الطويلة
حقن رسالة المستخدم	انحياز الحداثة، تحديث دوري	كل حقن يكلف توكنز
حقن نتيجة الأداة	نقطة الحقن الأكثر طبيعية	يعمل فقط عند استدعاء الأدوات

كيف يستخدمها Claude Code فعليًا

المتطلب الأساسي — صرّح عن العلامات في موجه النظام:

Tool results and user messages may include <system-reminder> tags.
<system-reminder> tags contain useful information and reminders.
They are automatically added by the system, and bear no direct
relation to the specific tool results or user messages in which they appear.

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

الاستخدام 1: التذكيرات السلوكية (تحديث دوري للقواعد)

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate...
</system-reminder>

يستخدم Claude Code هذا لتذكير النموذج بالتخطيط باستخدام TodoWrite — لأن النماذج تميل إلى "نسيان" التخطيط والبدء في كتابة الكود مباشرة.

الاستخدام 2: تبديل الأوضاع (وضع التخطيط - Plan Mode)

<system-reminder>
Plan mode is active. The user indicated that they do not want you to
execute yet -- you MUST NOT make any edits, run any non-readonly tools,
or otherwise make any changes to the system.
</system-reminder>

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

الاستخدام 3: إشعارات تغيير الملفات

<system-reminder>
Note: /path/to/file.ts was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account.
</system-reminder>

عندما تقوم عملية خارجية (linter، formatter، تعديل يدوي) بتعديل ملف، يقوم النظام بإخطار النموذج عبر تذكير — مما يمنع اتخاذ قرارات بناءً على محتويات ملف قديمة.

الاستخدام 4: السياق الديناميكي (التواريخ، قواعد المشروع)

<system-reminder>
Today's date is 2026-03-21.
Current branch: dev
claudeMd: [CLAUDE.md content injected here]
</system-reminder>

يتم حقن سياق وقت التشغيل (التاريخ، حالة git، قواعد المشروع) عبر رسائل المستخدم، وليس برمجتها بشكل ثابت في موجه النظام.

إرشادات كتابة التذكيرات

غلفها بعلامات XML (<system-reminder>) — يمكن للنموذج التمييز بين حقن النظام وكلام المستخدم.
صرّح عن العلامات مسبقًا في موجه النظام — وإلا فقد يحاول النموذج الرد على التذكير.
لا تحقن في كل رسالة — كل حقن يكلف توكنز، احقن فقط عند الحاجة.
اجعلها قصيرة — التذكير ليس موجه نظام ثانٍ، بل مجرد قاعدة أو قاعدتين حاسمتين.
لا تناقض موجه النظام — التذكيرات تكمل وتعزز، ولا تلغي.
استخدمها للتبديل الديناميكي — وضع التخطيط، وضع القراءة فقط، أعلام الميزات (feature flags).

متى تستخدم موجه النظام مقابل تذكير رسالة المستخدم

السيناريو	موجه النظام	تذكير رسالة المستخدم
تعريف الدور	✅	❌
قيود الأمان	✅ الإعلان الأول	✅ تكرار دوري
منهجية سير العمل	✅	❌
تبديل الأوضاع (وضع التخطيط)	❌	✅
إشعارات تغيير الملفات	❌	✅
التاريخ / معلومات البيئة	✅ القيمة الأولية	✅ القيمة المحدثة
التصحيح السلوكي	❌	✅
تذكيرات استخدام الأدوات	✅ تعريف القاعدة	✅ دفعات التنفيذ

9. التخزين المؤقت للموجهات (Prompt Cache) — وفر 90% من التوكنز المتكررة

يتيح لك التخزين المؤقت للموجهات من Anthropic تخزين البادئة الثابتة (static prefix) لمصفوفة الرسائل الخاصة بك. عندما تشارك الطلبات اللاحقة نفس البادئة، فإنها تصل إلى ذاكرة التخزين المؤقت — مما يوفر المال ويقلل من زمن الوصول (latency).

بالنسبة للوكلاء، هذا يهم كثيرًا: أنت تعيد إرسال موجه النظام + تعريفات الأدوات في كل استدعاء للنموذج داخل المحادثة.

الأرقام الرئيسية

المقياس	القيمة
تكلفة إصابة الذاكرة (Cache hit)	10% من السعر العادي (توفير 90%)
تكلفة كتابة الذاكرة (Cache write)	125% من السعر العادي (علاوة 25% على الكتابة الأولى)
مدة الصلاحية (TTL)	5 دقائق (تنتهي إذا لم تكن هناك طلبات)
الحد الأدنى للطول القابل للتخزين	1,024 توكن (Claude 3.5+)
دقة التخزين المؤقت	مطابقة البادئة — من البداية إلى نقطة توقف محددة
الحد الأقصى لنقاط التوقف	4

كيف يغير هذا تصميم الموجه

المبدأ الأساسي: المحتوى الثابت أولاً، المحتوى الديناميكي أخيرًا.

✅ Cache-friendly layout:
  System prompt (static)      ← Cache breakpoint 1
  Tool definitions (static)   ← Cache breakpoint 2
  CLAUDE.md / project rules   ← Cache breakpoint 3 (changes occasionally)
  Conversation history         ← Breakpoint 4 for rolling window

❌ Cache-destroying layout:
  System prompt
  DYNAMIC TIMESTAMP            ← Changes every request, everything after = cache miss
  Tool definitions
  Conversation history

الفخ الذي لا يحذرك منه أحد: إذا وضعت طابعًا زمنيًا ديناميكيًا (timestamp) في منتصف موجه النظام الخاص بك، فإن كل شيء بعده يصبح إخفاقًا في الذاكرة المؤقتة (cache miss). في. كل. طلب. طابع زمني واحد في المكان الخطأ وستدفع السعر الكامل لآلاف التوكنز.

استخدام الـ API

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    {
      type: "text",
      text: "You are a startup advisor...",
      cache_control: { type: "ephemeral" }  // ← marks a cache breakpoint
    }
  ],
  messages: [...]
});

استراتيجية نقاط التوقف المتعددة

Breakpoint 1: System prompt           ← Almost never changes
Breakpoint 2: Tool definitions         ← Almost never changes
Breakpoint 3: Project rules / CLAUDE.md ← Changes occasionally
Breakpoint 4: First N history messages  ← Rolling window cache

حتى عندما يتغير سجل المحادثة، فإن نقاط التوقف الثلاث الأولى لا تزال تصيب الذاكرة المؤقتة. محادثة من 10 أدوار توفر تقريبًا 40-60% من تكاليف توكنز الإدخال.

توصيات التصميم

لا تضع قيمًا ديناميكية عالية التردد في موجه النظام — التاريخ لا بأس به (يتغير يوميًا)، الطوابع الزمنية الدقيقة ليست كذلك.
ضع السياق الديناميكي (حالة git، إلخ) في حقن رسائل المستخدم — وليس في موجه النظام، وإلا ستدمر الذاكرة المؤقتة.
حافظ على استقرار تعريفات الأدوات — لا تقم بإضافة/إزالة الأدوات ديناميكيًا في وقت التشغيل.
استخدم نافذة متدحرجة (rolling window) لسجل المحادثة — قم بتخزين أول N رسالة، فقط الرسالة الأحدث هي التي ستكون cache miss.

10. قائمة التحقق (The Checklist)

بعد كتابة موجه النظام الخاص بك، راجعه مقابل هذه القائمة:

الهيكل

هل الهوية في الأعلى تمامًا؟
هل قيود الأمان مميزة بـ IMPORTANT ومكررة في النهاية؟
هل هناك فصل واضح بين الأقسام باستخدام العناوين؟
هل الأمثلة مغلفة بعلامات <example>؟

ميزانية التوكنز

هل الجزء الخاص بك < 6,000 توكن؟
هل تتجنب تكرار المعلومات الموجودة بالفعل في تعريفات الأدوات؟
هل يتم تحميل المعرفة المتخصصة عند الطلب، وليس مسبقًا؟
هل يخلو من القصص الدرامية أو الخلفيات الطويلة للشخصية؟

جودة القواعد

هل كل قاعدة قابلة للاختبار (صح/خطأ)؟
هل تستخدم القيود الصارمة لغة مطلقة (NEVER/MUST)؟
هل تستخدم الاقتراحات المرنة لغة التوصية (recommended/prefer)؟
هل تشرح القواعد الحاسمة السبب، وليس فقط الماذا؟
هل توجد قيود ثنائية الاتجاه (افعل هذا + لا تفعل ذلك)؟

سلوك الوكيل

هل تم تقديم مبادئ، وليس إجراءات صارمة خطوة بخطوة؟
هل تمت معالجة سيناريو "رفض استدعاء الأداة"؟
هل تمت معالجة استراتيجية "مواجهة عقبة" (عدم المحاولة بالقوة الغاشمة)؟
هل توجد استراتيجية لإدارة السياق (حد التلخيص)؟

ما يجب ألا تفعله

لا يوجد إطراء أو صفات تفضيل مبالغ فيها؟
لا توجد إعلانات زائدة مثل "أنت ذكاء اصطناعي مفيد"؟
لم يُكتب كسلسلة موجهات (prompt chain)؟
لا توجد هندسة مفرطة (ميزات لم يطلبها أحد)؟

لو كنت سأبدأ اليوم

إليك بالضبط ما سأفعله:

ابدأ بالهوية + الأمان في الأسطر الثلاثة الأولى. جملتان توضحان من هو الوكيل. قيود صارمة باستخدام NEVER/MUST. كرر قواعد الأمان في النهاية.
اكتب سير العمل الأساسي الخاص بك كمبادئ، وليس كخطوات. بحد أقصى 4-5 نقاط. استخدم "موصى به" و"يفضل" للقواعد المرنة، و"NEVER" و"MUST" للقواعد الصارمة.
خصص ميزانية 1,500-6,000 توكن للجزء الخاص بك. ستضيف تعريفات الأدوات 5,000-15,000 أخرى. إذا تجاوزت 6 آلاف، فمن المحتمل أنك تقوم بتفريغ معرفة يجب تحميلها عند الطلب.
قم بهيكلة كل شيء. عناوين Markdown، قوائم نقطية، علامات XML للأمثلة. الموجه المنظم يتفوق على النثر باللغة الطبيعية في كل مرة.
قم ببناء تذكيرات منتصف المحادثة منذ اليوم الأول. صرّح عن <system-reminder> في موجه النظام الخاص بك. احقن تذكيرات للقواعد الحاسمة، وتبديل الأوضاع، وتحديثات السياق.
صمم من أجل الذاكرة المؤقتة (Cache). المحتوى الثابت أولاً، المحتوى الديناميكي أخيرًا. لا تضع أبدًا قيمًا متغيرة في جسم موجه النظام الخاص بك.

المفارقة في كل هذا العمل؟ أفضل موجهات النظام هي القصيرة. التعليمات المخصصة لـ Claude Code (باستثناء تعريفات الأدوات) موجزة بشكل مدهش. كل سطر يثبت جدارته بوجوده.

كنت أعتقد أن هندسة الموجهات (prompt engineering) تتعلق بإيجاد حيل ذكية. الآن أعتقد أنها تتعلق بالانضباط — قول القليل، وقوله بدقة، والثقة في النموذج لاكتشاف الباقي. النموذج أذكى من الموجه الخاص بك. صمم بيئة العمل، ولا تفرض السلوك.

المراجع

المصدر	الرؤية الرئيسية
Claude Code v2.0.14 System Prompt	مرجع كامل لهيكل موجه وكيل في بيئة الإنتاج
Reddit: Understanding Claude Code's 3 System Prompt Methods	تعمق في Output Styles / --append / --system-prompt، وبيانات واقعية عن تدهور السياق
shareAI-lab/learn-claude-code	فلسفة "النموذج هو الوكيل"، ومنهجية هندسة إطار التوجيه (harness engineering)
Anthropic Prompt Engineering Docs	أفضل الممارسات الرسمية للموجهات
DeepAgents Framework	البرمجيات الوسيطة للتلخيص، والكشف التدريجي للمهارات