Claude Code وOpenCode: دورة مكثفة في البرمجة الوكيلة خلال 90 دقيقة

15 مفهوماً، 80% من الاستخدام الحقيقي

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

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

المتطلب السابق: صياغة تعليمات الذكاء الاصطناعي في 2026. هذه الصفحة تفترض أنك تعرف briefing مثل زميل، والسياق بوصفه اللعبة كلها، وأنماط التفكير، والتأطير المحايد، وحلقة التكرار، ومراجعة نموذج بنموذج. هنا ترى ذلك الانضباط عندما يستطيع النموذج لمس نظام الملفات.

Claude Code وOpenCode تطبيقان للفكرة نفسها: وكيل برمجة يعمل داخل مشروعك، يقرأ الملفات، يشغل الأوامر، يكتب التغييرات، ويطلب الموافقة عند الحدود المهمة.

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

محدّث حتى مايو 2026. كلتا الأداتين تتحركان بسرعة. تتغير أسماء الأوامر ومخططات الإعداد. قبل أي جلسة طويلة شغّل claude update وopencode upgrade أو ارجع إلى الوثائق الرسمية للأداة التي تستخدمها.

اختر أداتك، والصفحة تتابعك

عندما تختلف الخطوات بين Claude Code وOpenCode ستجد switcher. اختر أداة واحدة، وسيظل الاختيار متزامناً عبر الصفحة.

تريد النسخة العميقة؟

هذه دورة مكثفة: خريطة الاستخدام اليومي. للمعالجة الكاملة لقواعد الملفات، وplan mode، وتشريح المهارات، وتنسيق subagents، والhooks، وCI/CD، وإدارة الجلسات، ارجع إلى الفصول العميقة المشار إليها في الكتاب. هذه الصفحة هي الخريطة؛ تلك الفصول هي التضاريس.

الجزء 1: الأساسيات

1. ما هذه الأدوات فعلاً

Claude Code وOpenCode ليسا محرري كود فقط، وليسا chatbot داخل terminal. هما حلقة وكيل: يقرأ النموذج الحالة، يقرر الخطوة التالية، يستدعي أداة، يرى النتيجة، ثم يكرر. الفرق العملي عن autocomplete هو أن الوكيل يستطيع العمل عبر ملفات وأوامر متعددة، لا داخل سطر واحد.

التثبيت يتغير، لكن الشكل العام يبقى:

# macOS / Linux / WSL
claude update
claude

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

2. Plan mode: أكثر ميزة لا يستخدمها الناس كفاية

Plan mode هو المكان الذي تحصل فيه على نفوذ حقيقي. قبل الكتابة، اطلب من الوكيل أن يقرأ، يشرح ما فهمه، يقترح خطة، ويذكر الملفات التي سيلمسها وأوامر التحقق. التصحيح في الخطة رخيص. التصحيح بعد diff ضخم مكلف.

تعليمة جيدة:

Read the relevant files first. Do not edit yet.
Give me a short plan with the files you expect to change and the verification command.
Wait for approval before writing.

3. انضباط الصلاحيات

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

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

الجزء 2: إدارة السياق

4. تعفّن السياق حقيقي

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

السياق ليس دلواً ترمي فيه كل شيء؛ هو stack. ضع في الأعلى ما يحتاجه النموذج الآن، واخرج ما لم يعد مفيداً.

5. /clear و/compact

استخدم /clear عندما يتغير الهدف أو تلاحظ انحرافاً. استخدم /compact عندما تكون الجلسة طويلة لكنك تريد حفظ الجوهر. لا تستخدمهما بوصفهما طقوساً؛ استخدمهما عندما يصبح السياق عبئاً.

قبل /compact اطلب ملخصاً عملياً:

Summarize the current state for continuation:
- goal
- decisions made
- files changed
- commands run
- open risks
- next exact step

6. استئناف الجلسات

Resume جيد عندما تعود إلى الهدف نفسه والسياق لا يزال نظيفاً. أما إذا تغير الهدف أو امتلأت المحادثة بالطرق المسدودة، فابدأ جلسة جديدة وانقل فقط ملخص الحالة.

تشخيص: متى يفسد السياق

علامات التحذير:

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

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

الجزء 3: ملف القواعد

7. CLAUDE.md وAGENTS.md عندما يكتبان جيداً

ملف القواعد هو ذاكرة المشروع التي تُحمّل في بداية الجلسة. يجب أن يكون قصيراً وحاداً. لا تضع فيه كل شيء؛ ضع ما يغير السلوك يومياً.

# Project: my-app

## Stack
- Next.js
- PostgreSQL
- Playwright

## Commands
- `pnpm test`
- `pnpm lint`
- `pnpm build`

## Critical rules
- Never edit generated files.
- Use existing UI components before adding new ones.
- Run `pnpm test` before claiming done.

المضاد السيئ هو ملف طويل يشرح تاريخ الشركة، وكل edge case، وكل رأي. هذا يحرق السياق ويجعل المهم غير مرئي.

الجزء 4: تخصيص أداتك

8. Slash commands

Slash command هو prompt محفوظ لمهمة متكررة. استخدمه عندما تكتب التعليمة نفسها كثيراً: "راجع هذا diff"، "اكتب خطة migration"، "لخص اجتماعاً"، "افتح تحقيقاً read-only".

# weekly-rollup

Read the notes in `notes/`.
Produce a concise weekly summary with decisions, blockers, and next actions.
Do not invent missing status.

9. المهارات

المهارة مجلد يعلّم الوكيل طريقة عمل كاملة. استخدمها عندما تحتاج إلى عملية لا مجرد تعليمة. مثال: استخراج transcript، كتابة eval، أو تشغيل TDD. المهارة الجيدة تحتوي SKILL.md، أمثلة قليلة، وربما ملفات مرجعية.

# Extract YouTube transcript

Use this skill when the user gives a YouTube URL and asks for a transcript.
Preserve timestamps. Do not summarize unless asked.

10. Hooks في Claude Code وPlugins في OpenCode

الhook أو plugin حارس حتمي لا يعتمد على ذاكرة النموذج. إذا كان يجب منع commit يترك الاختبارات حمراء، أو يمنع لمس ملف معين، أو يراجع مخرجات command، فضع ذلك في hook/plugin لا في prompt فقط.

export const BlockDangerousPlugin = async () => {
  // shape only: block destructive commands unless explicitly approved
};

11. Subagents

الوكيل الفرعي مفيد عندما تحتاج إلى عزل سياق: مستكشف يقرأ فقط، مراجع يفحص diff، أو باحث يتتبع bug. لا تستخدم subagent لأن الاسم جميل. استخدمه عندما يقلل التلوث أو يوازي عملاً مستقلاً.

الجزء 5: الاتصال بالعالم

12. MCP بصدق

MCP يربط الوكيل بأدوات وموارد خارجية بطريقة موحدة. ليس واجباً لكل مشروع. استخدمه عندما تحتاج إلى مصدر بيانات أو أداة يتكرر الوصول إليها، مثل قاعدة بيانات، نظام تذاكر، أو ذاكرة منظمة. لا تثبت MCP server لمشكلة يحلها ملف notes/.

الجزء 6: مثال كامل، مرتين

المهمة

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

# Monday Team Meeting - 2026-12-07

## Discussion
- Launch date moved by one week.
- Vendor contract still blocked.

## Action Items
- Sam: update launch plan.
- Lina: follow up with legal.

كيف تقرأ هذا القسم

لا تركز على صيغة الأمر الدقيقة. ركز على القرارات الثمانية:

1. تقليم ملف القواعد إلى الأساسيات.
2. التخطيط قبل الكتابة.
3. دفع الوكيل إلى توضيح الخطة عندما تكون فضفاضة.
4. السماح له بالعمل بعد أن تصبح الخطة قابلة للتحقق.
5. تلخيص الجلسة عندما تطول.
6. وضع حارس قبل commit.
7. إرسال مهمة جانبية إلى helper عندما تكون مستقلة.
8. حفظ ما تعلمته في skill أو notes.

ما الذي حدث فعلاً

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

الجزء 7: أين تشغله، وكيف تكبر

13. Terminal أم IDE أم desktop؟

استخدم terminal عندما تكون المهمة قريبة من repo والأوامر. استخدم IDE عندما تحتاج إلى قراءة وتعديل بصري داخل مشروع. استخدم desktop/cowork عندما تكون المهمة بين مستندات وبريد وجداول، لا بين ملفات كود. لا يوجد سطح واحد أفضل دائماً؛ السطح الصحيح هو الذي يقلل نقل السياق يدوياً.

14. ابن مكتبة سياق شخصية ببطء

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

15. الذاكرة بعد الأساسيات

ثلاثة خيارات عملية:

الحاجة	الحل
قرارات ومطبات لهذا repo	مجلد notes/ داخل المشروع
تذكّر شخصي عبر مشاريع	Memory MCP واضح بواجهات save/recall
بحث في تاريخ طويل	vector search عند وجود مشكلة حقيقية

لا تبدأ بالبنية الأكبر. ابدأ بالملفات لأنها رخيصة، قابلة للبحث، ومفهومة.

الخلاصة: قابلية النقل هي الجائزة

الأدوات ستتغير. أسماء الأوامر ستتغير. بعض النماذج ستغلو، وبعضها سيصبح أفضل، وبعض المنتجات ستختفي. ما يبقى هو خريطة الاحتكاك إلى الآلية: سياق فاسد -> clear/compact؛ تكرار ممل -> skill؛ خطة غامضة -> plan mode؛ خطر غير مقبول -> hook؛ ذاكرة متطايرة -> files.

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

مرجع سريع

المفهوم	المعنى المختصر
أدوات البرمجة الوكيلة	وكلاء يقرأون ويكتبون ويشغلون أوامر داخل مشروعك
Plan mode	إصلاح العمل قبل أن يتحول إلى diff
الصلاحيات	سلّم ثقة، لا زر واحد
تعفّن السياق	عندما تصبح المحادثة عائقاً
/clear	بداية نظيفة
/compact	ضغط حالة مفيدة للاستمرار
ملف القواعد	تعليمات المشروع المحمّلة دائماً
Slash command	تعليمة متكررة محفوظة
Skill	عملية مشفرة قابلة لإعادة الاستخدام
Hook/Plugin	حارس حتمي
Subagent	سياق معزول لمهمة محددة
MCP	بروتوكول ربط الأدوات والموارد
Worked example	القرارات أهم من الأوامر
سطح التشغيل	Terminal أو IDE أو desktop حسب العمل
الذاكرة	ملفات أولاً، بنية أكبر عند الحاجة