Claude Code
من أول خطوة إلى عمل متقن

كيف تستخدم هذا الدليل وما معنى التقدم فيه

هذا مرجع تعليمي متدرج للعمل مع Claude Code. يبدأ بالقارئ الذي لا يعرف معنى Terminal، وينتهي بقرارات التخصيص والربط والتقييم والتشغيل. المقصود بـZero to Hero هنا مسار مهارات يمكن إثباتها، وليس وعدًا بإتقان هندسة البرمجيات بمجرد القراءة.

سنتابع ثلاثة أمثلة تعليمية: أداة صغيرة لحساب عرض خدمة، وطلب خاص في موقع WordPress، ومساعد يراجع Brief حملة. الأمثلة الافتراضية موسومة كذلك؛ لا تمثل نتائج عملاء أو SaaS مطلقًا بالفعل.

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

الميزات قد تختلف حسب الإصدار والحساب والمزود والواجهة وسياسة المؤسسة. الملفات المرجعية تُراجع قبل نسخها، وتشغيل المثال المحلي يختلف عن إثبات تكامل حي مع حساب Claude.

المشروع والملف والمسار ونافذة الأوامر

Project هو مجموعة الملفات التي تحقق وظيفة. File وحدة محتوى باسم، وFolder مجلد يجمع الملفات، وPath عنوان الوصول إليها. مثلًا src/quote.mjs مسار نسبي يبدأ من مجلد العمل الحالي؛ المسار المطلق يحدد المكان من جذر نظام الملفات أو القرص.

Terminal النافذة التي تستضيف الأوامر. Shell البرنامج الذي يفسرها، مثل PowerShell أو Bash. وCLI واجهة برنامج تستدعيه بالأوامر، مثل claude. أما IDE فهو محرر وبيئة عمل مثل VS Code. لذلك قد تعمل بواجهة Claude Code داخل المحرر، أو في Terminal المحرر، وهما طريقتان مختلفتان للعرض.

الأمر cd يغير مجلد العمل. إذا شغلت أداة في المجلد الخطأ، فقد تقرأ مشروعًا آخر أو لا تجد ملفات الإعداد. قبل بداية الجلسة، اعرف اسم المجلد وما الذي يوجد بداخله. لا تنسخ مسار Windows إلى Bash كما هو وتتوقع نفس التفسير.

ملف مثل package.json يصف مشروع JavaScript وسكربتاته. وDependency مكتبة يعتمد عليها المشروع. تثبيت مساعد البرمجة يختلف عن تثبيت تبعيات التطبيق الذي سيبنيه. كذلك Runtime بيئة تنفيذ الكود؛ Node.js مثال لتشغيل JavaScript خارج المتصفح.

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

النموذج والتوكن والسياق ودورة الـAgent

النموذج ينتج القرارات والردود. وClaude Code يوفر حوله أدوات وإدارة للسياق ودورة تنفيذ. المصطلح المفيد هنا هو Harness: بيئة التشغيل والتنظيم المحيطة بالنموذج. ترجمته الحرفية إلى «حزام» لا توصل المعنى التقني.

الهدف: أضف حاسبة عرض خدمة
المعيار: نتيجة صحيحة لمدخل معلوم

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

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

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

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

LLM نموذج لغوي يولّد مخرجات بناءً على المدخلات المتاحة. Inference تشغيل النموذج على طلب؛ استخدام ملف في الطلب لا يعني أن النموذج دُرّب عليه من جديد. Token وحدة معالجة نصية وليست كلمة ثابتة، ونسبة التوكنز إلى الكلمات تختلف باختلاف اللغة والمحتوى.

Tool call استدعاء منظم لأداة، له اسم ومدخلات ونتيجة. قراءة ملف قد تعيد نصه؛ تشغيل اختبار قد يعيد نجاحًا أو فشلًا. تعود النتيجة إلى سياق العمل فتؤثر في القرار التالي. هذه صورة تعليمية للسلوك الظاهر، وليست كشفًا للتفكير الداخلي الخاص بالنموذج.

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

ثبّته وابدأ بخطوة محددة

استخدم المثبّت الرسمي لنظامك. هذه الأوامر تثبّت برنامجًا على جهازك؛ لو مؤسستك تدير التثبيت مركزيًا، اتبع إعداداتها.

macOS أو Linux أو WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

بعدها افتح Terminal جديدًا، وافحص التثبيت، ثم ادخل مجلد المشروع.

claude --version
claude doctor
cd your-project
claude

التثبيت الأصلي لا يحتاج Node.js لمجرد تشغيل Claude Code. المثال البرمجي والـHook الاختياريان في هذا الدليل يحتاجانه. وعلى Windows فرّق بين PowerShell وCMD وWSL؛ الأوامر والمسارات لا تنتقل بينها بلا تعديل. التوثيق الحالي يوصي بـGit for Windows لإتاحة Bash، ويشرح استخدام PowerShell عند غيابه.

اطلب في أول جلسة: «ارسم لي خريطة المشروع: نقاط البداية، وأوامر الفحص، والمكان المناسب لقاعدة حساب العرض. لا تعدّل الملفات». ثم قارن الشرح بما يوجد فعلًا.

اعرف الحساب ومسار الفوترة المستخدمين؛ الإتاحة والحدود وسياسة المؤسسة قد تختلف. ابدأ بمجلد مشروع محدد، وبيانات تعليمية.

أنت جاهز للانتقال عندما تعرف مجلد العمل والإصدار وفحصًا واحدًا قائمًا في المشروع. الإضافات تأتي عندما تظهر حاجة لها.

الواجهات وأول جلسة والأوامر التي تحتاجها

Claude Code متاح في Terminal ومحررات وتطبيق سطح المكتب والويب. اختيار الواجهة لا يجعل بيئة التنفيذ واحدة: الجلسة المحلية تعمل ضمن جهازك، والجلسة السحابية لها ملفات وإعداد وشبكة مختلفون. ابدأ بمسار واحد، وافهم أين توجد النسخة التي تعدّلها.

داخل أول مشروع اطلب: «اشرح الغرض، ونقطة البداية، وأمر التشغيل والفحص، دون تعديل». Entry point أول موضع يبدأ منه مسار التنفيذ؛ قد تكون صفحة HTML أو مسار خادم أو سكربتًا. لا تفترض مكانه من اسم التقنية وحده.

الأوامر التي تبدأ بـ/ تُكتب داخل الجلسة، وأوامر claude ... تُشغّل من واجهة الأوامر. عندما لا يظهر أمر، راجع الإصدار والواجهة والإعداد بدل نسخ قائمة قديمة.

العمل عن بُعد والفحص المرئي: استمرار جلسة محلية عبر وسيلة تحكم عن بُعد يختلف عن تشغيل نسخة سحابية مستقلة. اعرف الجهاز والملفات والهوية في كل حالة. ويمكن لأدوات المتصفح، حيث تتاح، تجربة أزرار وصفحات وقراءة أخطاء الواجهة؛ يظل فحص الخادم والبيانات مطلوبًا بحسب الوظيفة. والتكامل مع GitHub أو CI يضيف أفعالًا وإعدادات وفوترة يجب فهم نطاقها.

اكتب عقد المهمة قبل إطالة الـPrompt

الـPrompt المفيد يحدد ما الذي يجب أن يتحقق، وما الأدلة المتاحة، وأين تنتهي حرية التنفيذ. القالب التالي مثال تعليمي أصلي؛ ليس أمرًا خاصًا في Claude.

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

في WordPress تصبح النتيجة: «الزائر يرسل الطلب، والمدير المصرح له يقرأه، والزائر الآخر لا يستطيع الوصول إليه». وفي التسويق: «جهّز ثلاث زوايا إعلانية من العرض المعتمد، ووضّح المعلومة الناقصة».

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

تقرير الإتمام المفيد يوضح: ما تغيّر، وما فُحص، وما بقي غير مؤكد، والقرار الذي تدعمه الأدلة. هكذا تقدر تقيّم العمل بدل الاكتفاء بصياغة ختامية مطمئنة.

تمرين: حوّل «حسّن صفحة الهبوط» إلى مستخدم واحد، وفعل مطلوب، وقيد، وفحص. لو عجزت عن تحديد الفحص، راجع مشكلة البيزنس قبل إعادة تصميم الصفحة.

قسّم الطلب إلى Intent النتيجة، وContext معلومات القرار، وConstraints الحدود، وAcceptance criteria شروط القبول. اذكر مرجع الحقائق عندما يؤثر في الإجابة؛ «اكتب عرضًا» يختلف عن «استخدم الأسعار المعتمدة في الملف وعلّم المعلومات الناقصة».

المخرج المنظم Structured output يلتزم ببنية مثل JSON. صحة البنية لا تثبت صحة القيمة. قد يعيد النموذج price: 100 في JSON صحيح بينما السعر غير معتمد. اختبر المصدر والقيمة مستقلين عن التنسيق.

تمرين محلول: الطلب «حسّن النموذج» يتحول إلى «امنع الحفظ عند غياب العنوان، وأظهر رسالة عربية، وأبقِ البيانات المكتوبة، وأثبت نجاح الحالة الصحيحة وفشل الفارغة». هكذا أصبح للتعديل نطاق وفحص.

التخطيط والمعمارية وتقسيم المهمة

Architecture توزيع المسؤوليات والبيانات والاتصالات بين أجزاء النظام. الخطة الجيدة توضح ما سيتغير ولماذا، وما الذي سيؤجل، وكيف سنفحص الأثر. عدد الملفات أو صغرها وحده لا يثبت جودة المعمارية.

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

فكّك «أداة استقبال عميل» إلى رحلة رأسية صغيرة: مدخل صالح → تحقق → حفظ → عرض للمصرح له. ثم أضف الإشعار. هذا يكشف العلاقة بين الواجهة والخادم والبيانات مبكرًا.

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

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

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

فهم كود الويب والبيانات دون حفظه كله

HTML يحدد العناصر والمحتوى، وCSS المظهر، وJavaScript السلوك. Frontend الجزء الذي يتعامل معه المستخدم. Backend الجزء الذي يعالج القواعد والوصول والبيانات على الخادم. PHP لغة شائعة في WordPress وLaravel، وSQL لغة للتعامل مع قواعد البيانات.

عندما تضغط زرًا، قد يرسل المتصفح HTTP Request إلى عنوان Endpoint، ثم يستقبل Response. API عقد يسمح لبرنامج بالتعامل مع آخر. REST أسلوب شائع لتنظيم واجهات HTTP، وليس اسم خدمة معينة.

مثال: الواجهة ترسل كمية، والخادم يتحقق منها، ويحسب بقواعد معتمدة، ويعيد الإجمالي. تحقق المتصفح يحسن الاستخدام؛ تحقق الخادم يحمي قاعدة التنفيذ عند تجاوز الواجهة.

Authentication يثبت الهوية. Authorization يحدد ما تستطيع هذه الهوية فعله. نجاح تسجيل الدخول لا يمنح المستخدم قراءة طلب يخص مستخدمًا آخر. هذا الفرق يتكرر في مواقع العملاء وأدوات التسويق وSaaS.

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

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

Git وDiff والجلسات والرجوع للتغييرات

Repository مستودع للملفات وتاريخها. Branch مسار عمل، وCommit نقطة مسجلة، وDiff وصف ما تغيّر. قبل تسجيل التغيير، افحص الملفات والقيم التي ستدخل المستودع؛ استبعاد السر لاحقًا لا يمحو نسخه القديمة تلقائيًا.

git status
git diff

اقرأ الفرق كقرار: هل غيّر التعديل الوظيفة المطلوبة فقط؟ هل ظهرت تبعية أو ملف إعداد غير متوقع؟ اطلب تفسير التغيير، ثم شغّل الفحص المناسب. لا تجعل «كل ملف أقل من 300 سطر» بديلًا عن فهم المسؤولية والاعتماديات.

الجلسة تحتفظ بسياق الحوار، والمستودع يحتفظ بتاريخ الكود. استكمال الحوار لا يرجع قاعدة بيانات أو يعكس رسالة أُرسلت. وRewind يتعامل مع تغييرات متتبعة ضمن حدوده؛ Git وخطط الاستعادة يبقيان مهمين.

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

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

شخّص السلوك وأثبت الإصلاح

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

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

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

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

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

تحدٍ عملي: عطّل قاعدة تحقق في المثال المحلي. أي فحص اكتشفها؟ لو لم يكتشفها شيء، أضف حالة تصف السلوك ثم أصلح الكود.

Unit test يفحص قاعدة صغيرة، وIntegration test تفاعل مكونات، وEnd-to-end test رحلة استخدام كاملة. اختيار النوع يأتي من السلوك الذي تريد حمايته. نجاح حساب الإجمالي وحده لا يثبت أن الطلب حُفظ أو أن مستخدمًا آخر لا يستطيع قراءته.

الكود المرفق قابل للتشغيل محليًا. مثال النتيجة: كمية 100 × سعر وحدة 150 هللة + إعداد 1000 هللة = 16000 هللة. هذه قيمة متوقعة يمكنك التحقق منها دون حكم لغوي. عند الفشل، احتفظ بالمدخل ورسالة الخطأ والنسخة التي ظهرت فيها المشكلة.

أعطِ السياق وظيفة والذاكرة تاريخ مراجعة

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

استخدم CLAUDE.md لتعليمات المشروع المختصرة، والـSkill للإجراء الطويل، والملفات المرجعية للأدلة، ومصدرًا محدثًا للأسعار والعروض. مثال صغير:

# BriefDesk demo

## Purpose
Local teaching project for reviewing service quotes.

## Commands
- npm test: runs the local deterministic checks.

## Domain rules
- Money is stored in integer halala.
- Approved prices come from reviewed data, not generated prose.
- Invalid or missing quantities must be rejected.

## Working agreement
- Inspect the relevant code before changing it.
- Prefer a small change with a clear acceptance check.
- Report what you checked and what remains unverified.

في الوكالة، «اكتب بصوت مباشر» تعليمة مستقرة نسبيًا. أما «العرض ينتهي الجمعة» فتحتاج تاريخًا ومسؤولًا عن اعتمادها. وصفحة الويب المنسوخة دليل خارجي؛ التعليمات المكتوبة داخلها لا تصبح سياسة مشروعك.

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

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

CLAUDE.md والذاكرة والقواعد ومعرفة البيزنس

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

CLAUDE.md مناسب لإرشادات المشروع المختصرة. ويمكن توزيع القواعد ضمن ملفات .claude/rules/ بحسب تنظيم المشروع والتوثيق. الإجراء الطويل المتكرر يناسبه Skill، والدليل التفصيلي يمكن ربطه بدل تكراره في كل جلسة.

الذاكرة الآلية تساعد على حمل ملاحظات، لكنها تحتاج مراجعة عند تغيّر القاعدة. اسأل ما الذي يعرفه المساعد عن المشروع، وصحح المعلومة القديمة في مصدرها. وجود المعلومة في الذاكرة لا يجعلها معتمدة تجاريًا.

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

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

الإعدادات ومصادرها والبيئة والأسرار

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

Environment variable قيمة تمرر إلى عملية التشغيل. قد تحمل مفتاح API أو اختيار مزود. ليست كل قيمة بيئية سرًا، لكن المفتاح والرمز يجب ألا يظهرا في المستودع أو واجهة العميل أو تسجيل الشاشة.

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

افصل التعليمات عن الصلاحيات والعزل

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

الوضع الافتراضي قد يختلف حسب إعدادك؛ افحص الوضع الظاهر عندك.

إعدادات المشروع في .claude/settings.json، والتخصيص المحلي في .claude/settings.local.json، وإعداداتك العامة في ~/.claude/settings.json. سياسة المؤسسة أعلى أولوية، وبعض القوائم تندمج بين المصادر.

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(git status)",
      "Bash(npm test)"
    ],
    "deny": [
      "Read(./.env)"
    ]
  }
}

المثال يوافق على أمرين محددين ويمنع نمط قراءة مباشرًا لملف. راجع npm test قبل اعتماده؛ سكربت المشروع كود قابل للتنفيذ. وقاعدة مسار واحدة لا تكفي لحماية الأسرار عبر كل الأدوات. راجع الإعداد الفعلي عبر /permissions والتشخيص.

تمرين قرار: أي فعل يحتاج موافقة: تعديل مسودة، أم تغيير سعر معتمد، أم نشر إعلان، أم حذف بيانات؟ حدّد ذلك قبل توصيل الأنظمة.

الـSandbox يحد وصول عملية إلى ملفات أو شبكة وفق آليته؛ Worktree يفصل نسخ الكود؛ وبيئة الحاوية أو الجهاز الافتراضي لها خصائص عزلها. هذه طبقات مختلفة. اختَرها حسب ما ستشغله وبياناته، وتحقق من سياسة المؤسسة.

قراءة مستند لا تمنح تعليماته نفس سلطة طلبك. هذه نقطة مهمة في Prompt injection: نص خارجي يحاول توجيه المساعد بعيدًا عن غرض المهمة. خفّض أثره بتحديد الأدوات والوصول والتحقق من الإجراءات والنتائج؛ لا تعتمد على عبارة واحدة داخل Prompt كحماية كاملة.

اختَر الامتداد الذي يحل المشكلة بأقل تعقيد

جزء كبير من تعقيد الإعداد يبدأ باختيار إضافة قبل تحديد القدرة الناقصة. خريطة القرار التالية توصية عملية تساعدك تختار نقطة البداية.

لو بتكرر طلب مراجعة الحملة، اكتب الإجراء ومعياره وأمثلته. لو الناقص هو العرض الحالي داخل CRM، تحتاج وسيلة للوصول للمعلومة أيضًا. ولو المطلوب فحص يتكرر قبل تعديل ملف، قد يناسبه Hook.

اكتب لكل إضافة: «هذا المكوّن يوفّر… وسأعرف فائدته عندما…». لو الجملة غير واضحة، جرّب سير العمل الأساسي أولًا.

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

حوّل الإجراء المتكرر إلى Skill

الـSkill إجراء قابل للتكرار له غرض واضح. الجيد منها يحدد المدخلات والخطوات والمخرج والاستثناءات. مثال مراجعة العرض هنا صغير عن قصد.

راجع عرض الحملة
بنفس قائمة الفحص المعتادة

احفظه في مشروع تجريبي داخل .claude/skills/inspect-quote/SKILL.md بعد مراجعته:

---
name: inspect-quote
description: Review the quote calculation and explain edge cases in this demo.
disable-model-invocation: true
---

Inspect $ARGUMENTS and the tests that exercise it.
Explain the calculation, identify one plausible failure,
and point to evidence in the files. Do not change files.
If the evidence is incomplete, state what is missing.

استدعِه بـ/inspect-quote src/quote.mjs. المثال يطلب القراءة فقط، لكن الجملة المكتوبة وحدها لا تحصر الأدوات تقنيًا. عندما تحتاج حصرًا أقوى، استخدم Subagent بأدوات محددة أو إعداد أدوات مناسبًا.

فرق دقيق ومهم: حقل allowed-tools في الـSkill يمنح موافقات للأدوات المذكورة خلال دور الاستدعاء، لكنه لا يخفي تلقائيًا كل أداة أخرى. هذا يختلف عن tools داخل تعريف الـSubagent.

اختبر فائدته: حالة صحيحة، وأخرى بها مدخل ناقص، وثالثة فيها قاعدة أعمال غامضة. هل يفرق بين «خطأ» و«غير معروف» و«لم يُفحص»؟

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

رأس YAML في أول SKILL.md يسمى Frontmatter. الحقول مثل name وdescription تصف المهارة، وdisable-model-invocation: true يجعل استدعاءها بقرار المستخدم وفق عقدها. و$ARGUMENTS يمثل ما يُمرر مع الاستدعاء. حافظ على أسماء الحقول كما هي.

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

استخدم Hooks للفحوص المرتبطة بالأحداث

الـHook يعمل عند حدث محدد في دورة التنفيذ. في المثال التعليمي نريد أن ترفض أداتا Write وEdit تعديل approved-prices.json. نفترض بدء الجلسة من جذر المشروع، وإتاحة Node.js في PATH.

PreToolUse
محاولة تعديل ملف

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/guard-approved-data.mjs",
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

الحزمة تتضمن guard-approved-data.mjs: يقرأ JSON الخاص بالحدث، ويحدد مسار الملف، ويخرج بالكود 2 عند استهداف المسار المحمي. ويرفض أيضًا مدخلًا غير صالح. انقل السكربت بعد مراجعته إلى .claude/hooks/ فقط عند رغبتك في تفعيل المثال؛ تنزيل الحزمة لا يفعّله تلقائيًا.

نطاق المثال هو Write وEdit. أوامر الـShell والتكاملات الأخرى وتعديل الإعدادات والوصول عبر نظام التشغيل تحتاج ضوابطها. هذا شرح لسير عمل محدد، وليس حاجزًا شاملًا لحماية البيانات.

في PreToolUse يمنع الكود 2 استدعاء الأداة. أحداث أخرى لها قواعد مختلفة؛ فشل PostToolUse لا يعكس فعلًا وقع بالفعل. ووضعنا onFailure: "block" صراحةً لهذا المثال الذي يجب أن يمنع عند فشله.

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

اقرأ السكربت المرفق مع الإعداد، ثم جرّب Payload صالحًا وآخر تالفًا. الأحداث التي تقع بعد التنفيذ تناسب التسجيل والفحص، ولا تعكس الأثر السابق تلقائيًا. حدث Stop قد يعيد العمل للاستمرار؛ شرط يمنع التوقف إلى الأبد يصنع حلقة ضارة.

وثّق لكل Hook: الحدث، والمدخل، والأثر، والتبعيات، وسلوك الفشل، وما لا يغطيه. مثالنا لا يحل المسارات الرمزية ولا يمنع التعديل عبر كل أداة. لا تخفِ كل خطأ باستخدام exit 0 ثم تعتبر الفحص ناجحًا.

وصّل MCP عندما تحتاج المهمة هذا الاتصال

MCP اختصار Model Context Protocol. ينظم التفاعل مع خوادم الأدوات، لكنه لا ينظف قاعدة البيانات، ولا يمنح كل صلاحية، ولا يضمن حداثة المعلومات.

اعرض ملفات المشروع المتاحة

ابدأ بفحص الاتصالات الموجودة:

claude mcp list
claude mcp --help

الشكل التالي قالب لأمر HTTP، وليس عنوانًا يعمل كما هو. استبدل القيمتين من تعليمات مزود الخدمة الرسمية الحالية:

claude mcp add --transport http <name> <verified-provider-endpoint>

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

ومع WordPress فرّق بين صلاحيات التطبيق، والقدرة المتاحة عبر الـAdapter، وهوية المستخدم المتصل، وسياسة موافقة المساعد. نجاح الاتصال لا يحدد وحده ما ينبغي السماح بتعديله.

التوثيق الحالي يتضمن Tool Search للتعامل مع أدوات كثيرة. تجنب الأرقام العامة غير الموثقة من نوع «الدقة تنهار بعد عشر أدوات». اختبر مهمتك، واجعل وصف الأدوات وصلاحياتها مفهومًا.

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

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

بعد الإضافة: افحص /mcp، أكمل المصادقة بالطريقة الموثقة، جرّب قراءة محدودة، ثم تحقق من حالات الانقطاع وانتهاء الرمز. لا تضع كلمة مرور قاعدة بيانات داخل مثال منشور أو أمر يُحفظ في تاريخ الشاشة.

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

Plugins وMarketplaces وإعادة استخدام الإعداد

الـPlugin حزمة توزيع لمكونات. وMarketplace فهرس يحدد أين تجد الحزم. وجود حزمة في فهرس لا يثبت أن كل كودها مناسب لمشروعك. افحص المحتوى والناشر والإصدار والأوامر والاتصالات التي تضيفها.

/plugin

المهارة المستقلة تفيدك في مشروع. والحزمة تصبح مفيدة عندما تريد توزيع عدة مهارات وHooks وAgents معًا وإدارة تحديثها. مهارة داخل Plugin قد تُستدعى باسم ذي نطاق مثل /package:review لتجنب تضارب الأسماء.

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

لا تخلط حزمة Claude Code مع امتداد المحرر الذي يعرض Claude Code داخل VS Code. الأول يوسع القدرات، والثاني واجهة لاستخدامها.

Code intelligence وMods وتخصيص الواجهة

البحث النصي يجد اسمًا مكتوبًا. Code intelligence يستخدم معلومات لغة البرمجة للتنقل بين الرموز والتعريفات والمراجع وتشخيص أخطاء النوع. LSP بروتوكول يتيح هذا النوع من التكامل مع Language Server. التثبيت والإتاحة يعتمدان على اللغة والحزمة والبيئة.

أما Mod فيوسع أجزاء من الواجهة أو السلوك عبر وحدة Hooks برمجية. يمكن أن تضيف لوحة أو أمرًا ضمن ما تدعمه الواجهة. في أكتوبر أضيفت خصائص RTL موثقة لعناصر محددة؛ هذا لا يثبت دعم كل عنصر على كل واجهة.

تطبيق مناسب للتعليم: لوحة توضح مصدر العرض المعتمد وحالة الفحص بدل إغراق المستخدم بسجل التنفيذ. اجعل النص الطويل والعربية وحالات النقص جزءًا من مراجعة الواجهة.

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

Subagents والتفويض والحدود المستقلة

توزيع العمل يفيد عندما تكون للمهمة حدود ونتيجة تقدر تراجعها. باحث محدد يمكنه فحص قواعد العرض بينما تراجع أنت رحلة الطلب. أما تعديل نفس الدالة بواسطة أكثر من Agent في وقت واحد فقد يزيد شغل التنسيق.

مثال تعريف يوضع في .claude/agents/quote-reader.md:

---
name: quote-reader
description: Inspect quote rules and tests without editing the demo.
tools: Read, Glob, Grep
---

Find the quote calculation and its tests.
Return the rule, the relevant file references,
one missing edge case, and the evidence needed to resolve it.
Do not claim a test passed unless you have its execution result.

افحص إتاحته عبر /agents. الأدوات قد تختلف حسب البيئة ووضع التنفيذ. ونجاح قراءة التعريف لا يثبت أن المساعد شغّل اختبارات المشروع.

لو التعديلات تحتاج نسخ عمل مستقلة، استخدم Worktree:

claude --worktree quote-preview

الـGit Worktree يفصل تعديلات الملفات والفروع، لكنه لا ينشئ عزلًا على مستوى نظام التشغيل، وقد يشارك مفاتيح وخدمات خارجية.

Agent Teams تنظم جلسات زميلة، وما زالت تجريبية في المرجع الذي راجعناه. وDynamic Workflows تضع التنسيق في سكربت للمهام الأكبر المتكررة. اختَرها عندما تظهر فائدتها في العمل.

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

Worktrees وAgent Teams والتوازي الحقيقي

التوازي يحتاج تقسيمًا يسمح بتجميع النتائج. يمكن لمساعد مراجعة التحقق من المدخلات، وآخر مراجعة التوثيق، ما داما لا يكتبان نفس الجزء دون تنسيق. كل نتيجة تحتاج مراجعة ودمجًا وفحصًا بعد الدمج.

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

Agent Teams جلسات زميلة بآلية قيادة وتواصل ومهام. المرجع الحالي يصفها بأنها تجريبية ومعطلة افتراضيًا، وتُفعّل بالمتغير CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. تفعيلها قد يغير سلوك التفويض العادي، لذلك افهمه قبل اعتمادها لفريقك.

المهمة التسلسلية أو التعديل في نفس الملف قد يناسبهما مساعد واحد. قارن الزمن الكلي والتكلفة وجودة الدمج، لا عدد الـAgents. اطلب تقرير كل نتيجة ومصادرها وما لم يُتحقق منه.

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

Dynamic Workflows وخطة تنسيق يمكن إعادة تشغيلها

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

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

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

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

حدّد هدفًا له نهاية وسياسة توقف

ميزة /goal تجعل العمل يستمر نحو شرط إتمام، مع فحص بواسطة نموذج لمعرفة تحقق الشرط. لذلك جودة صياغة الشرط مهمة.

/goal تُرفض المدخلات غير الصالحة في حاسبة العرض، وتنجح الفحوص المحلية، ويذكر التقرير النهائي الفحوص التي شُغّلت فعلًا.

«حسّن المنتج كله» لا تعطي نهاية عملية. أما «ارفض الكميات غير الصالحة، وشغّل الفحوص المحددة، واذكر ما بقي غير مؤكد» فيمكن فحصها. واحتفظ بالتحقق الخارجي حتى مع حكم النموذج بأن الهدف اكتمل.

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

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

تمرين: اكتب هدفًا لتعديل صفحة هبوط ينتهي دون ادعاء زيادة مبيعات قبل تجربة فعلية. افصل الإتمام التقني عن نتيجة البيزنس التي ستقيسها لاحقًا.

افصل بين Goal شرط إتمام، وMonitor متابعة حدث أو خرج، وScheduled task تشغيل يبدأ وفق توقيت أو حدث مدعوم. تكرار طلب داخل جلسة مفتوحة ليس بالضرورة خدمة سحابية تعمل بعد إغلاق جهازك.

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

قيّم ما تضيفه الـSkill أو الـPlugin

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

تقييم الـPlugin يستطيع مقارنته بحالة دون Plugin — وهي الـBaseline. التشغيل يتضمن استدعاءات فعلية للنموذج، فتُحتسب ضمن حدود الحساب أو فاتورة API. المرجع يوثق الأمر بداية من 2.1.269؛ افحص إتاحته عندك.

claude plugin eval init
claude plugin eval . --no-publish

تُستخدم الأوامر من مجلد Plugin مناسب. يبدأ init عملية تفاعلية لتجهيز الحالات. وخيار --no-publish يمنع النشر التلقائي للتقرير حيث ينطبق. اختبارات الحاسبة المحلية المرفقة مسار مختلف.

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

لو نجح النموذج بالـPlugin ومن دونه، فالحالة لا تثبت أن الـPlugin أضاف قيمة. ولو أعجب المراجع الآلي بادعاء غير مسند، راجع معيار الحكم نفسه. كرر المحاولات عندما يهم التذبذب، واذكر حدود العينة.

سؤال يستحق التجربة: هل تحقق تعليمة أقصر نفس النتيجة بتكلفة أقل؟

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

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

احسب تكلفة المهمة المكتملة

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

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

Prompt Caching يعيد استخدام بادئة طلب متطابقة. ليس ذاكرة دائمة للحقائق. تغيير النموذج وتغييرات أخرى قد تؤثر في الكاش؛ لذلك قارن تكلفة المهمة كاملة.

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

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

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

اختَر النموذج بتجربة المهمة. Effort مستوى جهد استدلال تدعمه بعض النماذج والواجهات؛ لا يساوي ضمان الصحة. وFast mode، حيث يتاح، له شروط وفوترة؛ افحص المرجع بدل افتراض أنه اختيار مجاني أو دائم.

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

السجلات والتتبع وقراءة سلوك النظام

Log حدث مسجل، وMetric قياس مجمع، وTrace سلسلة مترابطة لخطوات مهمة. Observability قدرتك على فهم الحالة من هذه الأدلة. عدد الاستدعاءات أو الأسطر المعدلة وحده لا يثبت فائدة المنتج.

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

توثيق Claude Code يشرح تصدير بيانات عبر OpenTelemetry. بعض التتبع موصوف كـBeta، وتختلف الوجهات والسياسات. استخدم أقل بيانات كافية للتشخيص، وحدد من يقرأها ومدة حفظها، وراجع محتوى السجلات قبل نشر دراسة حالة أو تسجيل شاشة.

تطبيق: لديك ثلاث مهام فاشلة. هل السبب Timeout، أم مدخل ناقص، أم ادعاء خاطئ؟ تقرير يجمعها تحت «AI لم يعمل» لا يساعدك على اختيار إصلاح.

التشغيل البرمجي وJSON وحدود التنفيذ

التشغيل Headless مناسب عندما يستدعي برنامج آخر المهمة دون واجهة المحادثة المعتادة. ابدأ بطلب محدود ومعرفة ما يخرج منه وكيف يُفحص الفشل.

claude -p "Explain the local quote rule. Do not change files." --output-format json

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

استعمل إعداد أدوات صريحًا في التطبيقات التي تحتاج الحصر، وتحقق من الإعدادات والـMCP التي قد تُحمّل. لا تمرر نص مستخدم إلى Shell كما هو. افصل المدخل غير الموثوق عن الأمر والموافقة.

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

انتقل إلى Headless أو Agent SDK لسبب واضح

استخدم Claude Code التفاعلي عندما يقود شخص العمل. وHeadless لمهمة برمجية محددة دون الواجهة التفاعلية. أما Agent SDK فيناسب تطبيقك عندما يحتاج إدارة الجلسات والأدوات والحدود وتجربة المستخدم.

claude -p "اشرح قاعدة حساب العرض المحلي دون تعديل الملفات" --output-format json

الأمر يعيد خرجًا منظمًا، لكنه لا ينشئ وحده واجهة موافقات كاملة لتطبيقك. عالج الفشل وافهم عقد المخرجات الحالي قبل بناء قرار آلي عليه.

الحزمة تتضمن مثال Python يتيح Read وGlob وGrep فقط، ويحدد مصادر الإعداد وحدود الأدوار والتكلفة التقديرية. يحتاج SDK ووصول API مصرحًا؛ فُحصت صياغته ولم يُشغّل على حساب أثناء إعداد الدليل.

ثلاثة فروق مهمة: allowed_tools للموافقة المسبقة، أما tools فيحدد مجموعة الأدوات. وsetting_sources=[] يستبعد إعدادات ملفات المستخدم والمشروع والمحلي، لكنه لا يلغي سياسة المؤسسة وكل مصدر إعداد عام. وحد التكلفة التقديري من العميل قد يتجاوزه الاستدعاء، فلا تعتبره سقف فوترة قطعيًا.

في المنتج الفعلي، ابنِ الموافقة والتفاعل عبر الـCallback والمسار الموثقين. أداة AskUserQuestion وحدها لا تتولى الهوية والتفويض وتجربة المنتج.

اسأل قبل البناء: هل الميزة تحتاج Agent يتعامل مع الملفات، أم أن دالة ثابتة واستدعاء نموذج عادي يحققان الغرض بسهولة أكبر؟

اقرأ examples/sdk_readonly.py كاملًا. يحدد مجموعة الأدوات، وموافقاتها، ومصادر الإعداد، وسياسة MCP، وحدودًا تقديرية. المثال لا يثبت عزل كل ملفات الجهاز؛ عزل العملية نفسها موضوع تشغيل مستقل.

في TypeScript، النمط العام query({prompt, options}) يعيد أحداثًا يمكن لتطبيقك استهلاكها. وفي Python تستخدم async for مع query. احفظ هوية المهمة وحالة نهايتها، وابنِ واجهة موافقة واضحة حيث يتطلب التطبيق فعلًا خارجيًا. لا تعرض تسجيل دخول اشتراك شخصي كأنه ترخيص تلقائي لمنتجك.

ثلاثة مشاريع تربط الهندسة بالبيزنس

طلب خدمة خاص داخل WordPress

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

مسودة حملة من عرض معتمد

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

حاسبة تعليمية لعرض طباعة

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

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

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

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

تطبيق WordPress: اطلب فصل المحتوى والتصميم والمنطق، وحدد ما يدخل إضافة وما يخص القالب. في بيانات الطلبات، عرّف الخاص والعام والصلاحيات قبل إتاحة أي Endpoint أو MCP capability. الربط يُجرّب على Staging.

تطبيق تسويق: ابنِ Brief من مصادر معتمدة، ثم مسودة، ثم فحص حقائق، ثم اعتماد، ثم تجربة لها قياس. الذكاء الاصطناعي يساعد في العمل؛ نتيجة المبيعات تحتاج بيانات فعلية وفهم الإسناد وحدودها.

SSH وسيلة اتصال لتنفيذ أوامر على جهاز بعيد؛ يختلف عن MCP الذي ينظم استدعاء قدرات وأدوات. قبل أي عمل على استضافة WordPress، حدد الحساب والمجلد والبيئة ونسخة الاستعادة. ابدأ بقراءة وفحص معلومين على Staging، وافهم أثر الأمر قبل تشغيله. رفع ملف أو تغيير صلاحية أو تنفيذ Migration فعل مستقل يحتاج صلاحية واضحة.

الإطلاق والتشغيل والتعاون مع فريق

النسخة التي تعمل محليًا تحتاج تعريفًا لبيئة التشغيل قبل استخدامها فعليًا: من يشغلها، ومن يدخل، وأين البيانات، وما التبعيات، وكيف تتغير النسخ. Migration تغيير منظم في بنية البيانات، وRollback رجوع وفق خطة محددة؛ تغيير الملفات لا يعكس كل تغيير بيانات تلقائيًا.

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

للفريق: حدد مالك القاعدة، ومراجع التغيير، ومن يعتمد النشر، ومسؤول الحادث. مراجعة Codex لخطوات Claude Code يمكن أن تفيدك عندما تعتمد على ملفات وفروق ونتائج فحص؛ اتفاق مساعدين دون دليل لا يحسم الصحة.

سجل الأعطال والتعثرات المتكررة لتتحول إلى تحسين واختبار أو مثال تعليمي بإذن. ابدأ بإطلاق محدود يناسب قدرة الدعم. لا تَعِد بمراجعات شخصية أو تحديثات بلا حد إذا لم تملك سعة لتقديمها.

ابنِ المعمل المحلي وافحص الدليل

حزمة المصدر تحتوي معمل JavaScript صغيرًا بلا تبعيات خارجية. يعمل محليًا على Node.js 20 أو أحدث، ولا يحتاج استدعاء نموذج.

1. افتح مجلد examples بعد فك الحزمة.
2. اقرأ quote.mjs وحدود المثال التعليمي.
3. شغّل npm test.
4. اقرأ اختبارات الـHook مستقلّة عن اختبارات الحاسبة.
5. غيّر قاعدة تحقق واحدة ولاحظ الفحص الذي يفشل.
6. استعد القاعدة وأعد التحقق.

الأمثلة ملفات مرجعية: settings.example.json وskill-example.md وsubagent-example.md لا تُثبّت أو تُفعّل في الخلفية. يوضح الدليل موضعها المقصود إذا قررت تجربتها.

مثال SDK يحتاج تثبيت الحزمة الحالية وتهيئة API مصرح به في البيئة. قراءة الملف أو فحص صياغته لا يثبت المصادقة والفوترة والتوافق والتشغيل الفعلي.

هدف المعمل تدريب عادة مهنية: اجعل الادعاء محددًا بما يكفي لفحصه، واحتفظ بدليله بجواره.

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

Rubric مقترح من 100: فهم المشكلة 20؛ نجاح الوظيفة 20؛ البيانات والصلاحيات 20؛ الفحص 15؛ الاستخدام 15؛ التشغيل والتكلفة 10. خطأ وصول مهم أو فشل الوظيفة الأساسية يمنع اعتبار المشروع مكتملًا مهما كان المجموع. هذا معيار تعليمي مقترح ويُعاير بالتطبيق.

مرجع الأوامر والأعطال والأسئلة الشائعة

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

هل Rewind يغني عن Git؟ له نطاق تتبع ومدة احتفاظ محددان. آثار الأنظمة الخارجية وتغييرات قواعد البيانات والتغييرات غير المتتبعة تحتاج طريقة استعادة مناسبة.

هل أجعل كل ملف أقل من 300 سطر؟ الحجم إشارة للمراجعة. ترابط المسؤوليات والاعتماديات وسهولة الاختبار وحدود التغيير تساعدك أكثر على اتخاذ القرار المعماري.

هل أوصل كل أداة متاحة؟ وصّل ما تحتاجه المهمة، واختبر التكامل، ووضّح الهوية والصلاحيات.

هل مسار طرف ثالث منخفض التكلفة يعادل المنتج الرسمي؟ افحص التوافق والميزات والهوية وسلوك النموذج والشروط والحدود كلًّا على حدة. الدليل لا يعد بخدمة مجانية بلا حدود.

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

ماذا تغيّر في أكتوبر ولماذا يهمك

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

ليس كل موضوع مهم ميزة أُطلقت في أكتوبر. تقييم الـPlugins وDynamic Workflows وAgent Teams لها تاريخ أقدم؛ نناقشها لأنها مهمة للاستخدام الحالي. وقد تختلف الإتاحة حسب الإصدار والمزود والواجهة وإعدادات المؤسسة.

تخيل شرحًا يقول إن Hook على Windows يمنع تعديل ملف. المقال القابل للاعتماد يذكر الإصدار والـShell والمدخل التجريبي والنتيجة التي ظهرت. مجرد كتابة «آخر تحديث» لا يثبت عمل المثال على كل الأجهزة.

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

قاموس 80 مصطلحًا