انتقل إلى المحتوى الرئيسي

الوحدة 1 — تثبيت Claude Code وإنجاح أوّل جلسة

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

Claude Code ليس أداة إكمال تلقائيّ​

Claude Code وكيل ترميز يعيش في طرفيّتك: يقرأ مستودعك، ويحرّر ملفّات، وينفّذ أوامر، ويستدعي Git، ويُصحّح نفسه انطلاقًا من المخرجات التي يرصدها. يدور حول حلقة وكيليّة — جمع سياق، عمل، تحقّق — تُفصِّلها الوحدة 2. خلافًا لإكمالات inline، يرى Claude مشروعك كاملًا، ويقرأ عدّة ملفّات في التور نفسه، ويُشغّل اختباراتك ويقترح تصحيحًا متماسكًا يمسّ كامل الوحدات.

المكتبة نفسها تعمل على عدّة أسطح: الـCLI، وإضافة VS Code (وCursor)، وإضافة JetBrains، وتطبيق Desktop لـmacOS وWindows، وClaude Code على الويب عبر claude.ai/code، وتكامل Chrome لقيادة متصفّح، وRemote Control لاستئناف جلسة محلّيّة من هاتف. كلّ سطح يُوصَل بالمحرّك نفسه: يعمل ملفّ CLAUDE.md وإعداداتك وخوادم MCP في كلّ مكان بالطريقة ذاتها.

التثبيت​

على macOS وLinux وWSL، يجري التثبيت الأصيل بسطر واحد:

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

على Windows، طريقان:

# PowerShell
irm https://claude.ai/install.ps1 | iex
:: cmd.exe
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

التثبيت الأصيل يُحدَّث تلقائيًّا في الخلفيّة. على macOS وLinux، يقترح brew install --cask claude-code قناة مستقرّة وclaude-code@latest قناة سريعة؛ لا واحد منهما يُحدَّث لوحده، بل يجب تشغيل brew upgrade. على Windows، winget install Anthropic.ClaudeCode يقوم بالمكافئ. على Debian وFedora وRHEL وAlpine، مدراء الحزم apt وdnf وapk مدعومون.

تحقّق بعد ذلك بـclaude --version: يطبع الأمر رقم إصدار متبوعًا بـ(Claude Code). على Windows الأصيل، يُنصح بتثبيت Git for Windows، وإلّا استعمل Claude Code لـPowerShell بديلًا للـshell ممّا يُقلّل قابليّة نقل النصوص. تحت WSL، لا حاجة إلى أيّ حزمة Windows إضافيّة.

المصادقة واختيار المزوِّد​

في أوّل جلسة، يفتح claude المتصفّح ليُوصلك. ثلاثة خيارات كبرى تتعايش:

  • اشتراك Claude (Pro، Max، Team، Enterprise): الحساب الرئيسيّ للمطوّرين الأفراد والفرق. متابعة الكلفة تجري داخل حساب claude.ai.
  • Claude Console: فوترة بالاستهلاك مع رصيد مسبق الدفع؛ عند أوّل اتّصال، يُنشَأ فضاء «Claude Code» لتوحيد التكاليف.
  • المزوّدون السحابيّون للمؤسّسات: Amazon Bedrock أو Google Cloud's Agent Platform أو Microsoft Foundry أو Claude apps gateway مُستضاف ذاتيًّا لوصل SSO مؤسّستك.

إن كان متغيّر ANTHROPIC_API_KEY مضبوطًا مسبقًا، يتخطّى Claude Code شاشة الدخول ويطلب منك فقط الموافقة على المفتاح. لتبديل الحساب لاحقًا، اكتب /login ثمّ /logout داخل جلسة. claude auth status يطبع حالة المصادقة بصيغة JSON ويخرج بـ0 إن كنت متّصلًا، و1 وإلّا — عمليّ داخل سكربت.

أوّل claude في مستودع​

انتقل إلى مجلّد المشروع وشغّل الأمر بلا وسائط:

cd ~/code/kiosque
claude

عند أوّل مرّة يستقبل فيها مجلّد Claude Code، يسألك صندوق حوار الثقة الإذن بالتنفيذ. ليست مجرّد شكليّة: لن تُطلَق hooks وإعدادات المشروع إلّا بعد هذه الموافقة. بعد التصديق، يعرض السطر الإصداريّ رقم الإصدار والنموذج الجاري ومسار العمل. اكتب /help لرؤية القائمة المصفّاة للأوامر المتاحة.

أوامر الدقائق الأولى​

هذه الأوامر العشرة تكفي لفهم ما يجري في جلسة جديدة؛ كلّها موجودة فعلًا في الجرد المدمج، ومفصّلة في الوحدة 4.

  • /help: يعرض الأوامر والskills المتاحة لحسابك. تُصفّى القائمة أثناء الكتابة ويُبرز أفضل تطابق منذ Claude Code v2.1.236.
  • /status: يفتح تبويب Status في الإعدادات؛ حيث نقرأ الإصدار والنموذج الفعّال والحساب وحالة الاتّصال. يستجيب /status حتّى بينما يعمل Claude.
  • /doctor: تشخيص كامل مع اقتراح إصلاحات. يرصد التثبيتات المكرّرة، ومشاكل PATH، وملفّات الإعدادات غير القابلة للقراءة، والskills غير المستعملة، وخوادم MCP الخاملة التي تُكلّف سياقًا، ويقترح تنحيف ملفّ CLAUDE.md المُثقَل بالانتقال إلى skills وإلى CLAUDE.md مُدمَجة (v2.1.206+). من الطرفيّة، يطبع claude doctor الشيء نفسه بوضع قراءة فقط.
  • /init: يُولّد CLAUDE.md مبدئيًّا من استكشاف المستودع. مع CLAUDE_CODE_NEW_INIT=1، يتحوّل /init إلى تدفّق تفاعليّ متعدّد المراحل يقترح كذلك skills وhooks.
  • /model: تبديل النموذج. بلا وسيط، يفتح مُنتقيًا؛ زرّ s على سطر يطبّق الاختيار على الجلسة الجارية فقط.
  • /effort: يضبط مستوى جهد الاستدلال (low, medium, high, xhigh, max, ultracode, auto, status).
  • /config: يفتح واجهة Settings. منذ v2.1.181، يكتب /config clé=valeur مفتاحًا مباشرةً، مثلًا /config theme=dark أو /config model=sonnet.
  • /theme: يختار سمة عرض، ومنها auto التي تتبع خلفيّة الطرفيّة، أو متغيّرات لعمى الألوان، أو سمة مخصَّصة من ~/.claude/themes/.
  • /terminal-setup: يُثبّت الاختصار المناسب للانتقال إلى سطر جديد (Shift+Enter في VS Code وCursor وAlacritty وZed؛ Option+Enter على Apple Terminal).
  • /release-notes: يفتح مُنتقي إصدار لقراءة changelog داخل النصّ، دون تلويث المحادثة.

يُكمِل /powerup اللوحة: دروس تفاعليّة مع عروض متحرّكة لاكتشاف ميزة كلّ يوم، دون الدخول في المحادثة.

النماذج المتاحة ومستويات الجهد​

يقبل مُنتقي /model أسماء بديلة ثابتة بدل أرقام إصدارات متحرّكة:

  • sonnet للاستعمال اليوميّ.
  • opus للاستدلال المعقّد.
  • fable للمهامّ الطويلة جدًّا التي تتجاوز جلسة واحدة؛ في أيلول/سبتمبر 2026، يُشير fable إلى Fable 5.1 افتراضيًّا.
  • haiku للسرعة على مهامّ بسيطة.
  • opusplan: وضع خاصّ يستعمل Opus أثناء وضع plan ثمّ يتحوّل إلى Sonnet عند التنفيذ.
  • best: الأفضل المتاح على حسابك (Fable إن كان متاحًا، وإلّا Opus).
  • sonnet[1m] وopus[1m]: النماذج نفسها مع نافذة سياق مليون رمز، مفيدة على مستودعات كبيرة.

مستويات الجهد المتاحة تعتمد على النموذج. على Opus 5 وSonnet 5 وOpus 4.8 وOpus 4.7 وFable 5.1 وFable 5، تُقبل المستويات الخمس low وmedium وhigh وxhigh وmax. على Opus 4.6 وSonnet 4.6، xhigh غير موجود — يتراجع Claude Code إلى high. ultracode ليس مستوى جهد في النموذج بل ضبط في Claude Code يُرسل xhigh ويطلب من Claude تنسيق workflow ديناميكيّ للمهامّ الجوهريّة.

اختر دون تعذيب

ابدأ كلّ جلساتك بـsonnet وجهد high. انتقل إلى opus فقط لخطّة معقّدة، وإلى fable لمهمّة تتجاوز ساعتين. تبديل النموذج في وسط الجلسة يُبطل الكاش: توضّح الوحدة 2 السبب.

كلفة الجلسة: /usage​

/usage (بديلاه /cost و/stats) يفتح شاشة التكاليف. يعرض قسم Session:

  • الكلفة الإجماليّة بالدولار، محسوبة محلّيًّا بالتعرفة العلنيّة، إلّا إن دفعت مؤسّستك ‏modelPricing تفاوضيًّا؛
  • المدّة التراكميّة لنداءات API والمدّة الساعيّة؛
  • الأسطر المضافة والمحذوفة؛
  • الاستهلاك بحسب النموذج: رموز الدخل والخرج، cache read، cache write.

على اشتراك Pro أو Max أو Team أو Enterprise، يُضيف /usage توزيعًا حسب الخطّة: حصص skills والوكلاء الفرعيّين وplugins وخوادم MCP على 24 ساعة أو 7 أيّام (تبديل d / w). ترجع إليه الوحدة 15؛ للآن، احفظ أنّ هذه الأرقام تُصفَّر عند /clear.

اختصارات لوحة المفاتيح التي نستعملها في كلّ جلسة​

  • Tab في حقل الإدخال: يقبل اقتراح الإكمال التلقائيّ، خاصّة بعد / أو @fichier أو :emoji:.
  • Esc: يقاطع Claude في وسط تور. الرسائل المصفوفة في الطابور تُرسَل بعده؛ ويبقى ما أُنجز.
  • Esc Esc: على حقل إدخال فارغ، يفتح قائمة rewind لإرجاع الشيفرة والمحادثة إلى checkpoint. على حقل غير فارغ، يمسح المسوّدة ويحفظها في السجلّ.
  • Shift+Tab: يُدوِّر أوضاع الأذونات (default, acceptEdits, plan، ثمّ bypassPermissions وauto حسب التوفّر).
  • Ctrl+C: يقاطع عمليّة. على إدخال فارغ، ضغطة ثانية تُنهي Claude Code.
  • Ctrl+O: يبدّل إلى transcript viewer لرؤية تفاصيل نداءات الأدوات والطوابع الزمنيّة والنموذج المستعمَل لكلّ إجابة.
  • Ctrl+R: بحث معكوس في سجلّ الأوامر.
  • \ ثمّ Enter: سطر جديد قابل للنقل. Ctrl+J يقوم بالشيء ذاته دون ضبط. Shift+Enter يعمل أصلاً في iTerm2 وWezTerm وKitty وGhostty وWarp وApple Terminal وWindows Terminal؛ في غيرها، يتكفّل /terminal-setup بذلك.

يسمح ملفّ ~/.claude/keybindings.json (يفتحه /keybindings) بإعادة ربط أغلب هذه الأفعال.

الخيط الأحمر Kiosque: أوّل جلسة​

Kiosque تطبيق أخذ طلبات صغير لعربات الطعام: واجهة FastAPI في app/ (commandes.py وmenu.py وpaiements.py وnotifications.py)، واختبارات pytest بتغطية 41 ٪ مع اختبار غير مستقرّ (test_paiements_delai)، وواجهة أماميّة صغيرة بـReact في web/، وأدوات ruff وmypy وMakefile. يتكوّن الفريق من نادية (قائدة) وكريم (backend) وليا (frontend)؛ ومهمّتك تجهيز الجميع بـClaude Code.

الجلسة الأولى، بالترتيب:

git clone git@github.com:kiosque/kiosque.git
cd kiosque
claude

بعد الموافقة على المجلّد ومطالعة /help، نطلب من Claude وصف ما يراه:

Explore le dépôt et donne-moi en 15 lignes : structure des dossiers,
comment lancer les tests, ce que fait chaque module de app/, et les
trois points où le code m'a l'air le plus fragile.

يستدعي Claude Read وGrep وGlob، ويفتح Makefile وpyproject.toml، وبعض ملفّات app/، ثمّ يُجيب. بعدها نُشغّل:

/init

يُحلّل Claude المستودع ويقترح CLAUDE.md. يرصد Makefile، ويقترح « Run make test before committing »، ويستنبط بعض الاصطلاحات. نتركه يكتب، ثمّ نقرأ الملفّ المولَّد: هو صحيح لكنّه ثرثار قليلًا، يُكرّر ما تقوله الشيفرة أصلًا (شجرة المجلّدات، التبعيّات)، ويُفوّت ما لم يستطع استنباطه (خلط أسماء بالفرنسيّة والإنجليزيّة، .env متروك في الجذر، test_paiements_delai غير مستقرّ). سنُعيد كتابة CLAUDE.md نظيفًا في الوحدة 3.

أخيرًا، نُطالع التكلفة:

/usage

يُشير قسم Session إلى بضع مئات الآلاف من الرموز المقروءة (معظمها من الكاش بعد التور الأوّل) وتكلفة ببضعة سنتات. هذا هو الإيقاع الطبيعيّ لاستكشاف.

لا تُبالغ في تقدير /init

يُنتج /init مسوّدة جيّدة، لا CLAUDE.md جاهزًا للإنتاج. عامله معاملة مخرج متدرّب متحمّس: لا غنى عنه للانطلاق، لكن يجب تنقيحه قبل دفعه إلى الفريق. توضّح الوحدة 3 كيف.

خطأ شائع: نسيان /terminal-setup​

في كثير من الطرفيّات، تُرسِل محاولة الانتقال إلى سطر جديد بـEnter الرسالةَ حالًا. فيكتب المستخدم prompts في سطر واحد لا ينتهي، ويعتقد أنّ Claude Code سيّئ التصميم. شغّل /terminal-setup مرّة واحدة لكلّ جهاز؛ على iTerm2 تُفعّل أيضًا الوصول إلى الحافظة الذي يحتاجه /copy.

الخلاصة​

  • Claude Code وكيل في الطرفيّة، لا أداة إكمال تلقائيّ: يرى المشروع كاملًا، ويُنفّذ الأوامر، ويُصحّح نفسه.
  • التثبيت: سكربت أصيل (macOS/Linux/WSL/Windows)، أو Homebrew، أو WinGet، أو حزم Linux؛ التثبيت الأصيل الوحيد الذي يُحدَّث لوحده.
  • المصادقة: اشتراك Claude، أو Console API، أو مزوّد سحابيّ مؤسّسيّ؛ claude auth status يستجيب بصيغة JSON.
  • خمسة أوامر للبداية: /help و/status و/doctor و/init و/usage؛ احفظ أيضًا /model و/effort و/config.
  • خمسة اختصارات ينبغي معرفتها: Tab وEsc وEsc Esc وShift+Tab وCtrl+O.
  • CLAUDE.md الذي يُولّده /init مجرّد مسوّدة: تُعيد الوحدة 3 كتابته لـKiosque.

الوحدة التالية: الحلقة الوكيليّة والأدوات المدمجة ونافذة السياق — لفهم ما يملأ السياق حتّى نتوقّف عن دفع ثمن الطلب نفسه مرّتين.