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

الوحدة 2 — الحلقة الوكيليّة والأدوات المدمجة ونافذة السياق

وضعت الوحدة 1 Claude Code بين يديك؛ وهذه الوحدة ترفع الغطاء. فهم الحلقة الوكيليّة، وما يفعله كلّ أداة مدمجة، هو فهم لماذا قد تُكلّف جلسة عُشر ما تكلّفه جلسة مماثلة بعمل مكافئ. تلي ذلك الأوامر التي تقود السياق — /context و/compact و/clear و/btw و/usage — ثمّ، على Kiosque، رسم خريطة وضغط مُوجَّه.

الحلقة: سياق، فعل، تحقّق​

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

مكوّنان يُشغّلان الحلقة: النموذج الذي يستدلّ (يُختار عبر /model، وضبط الجهد عبر /effort)، والأدوات التي تعمل. الباقي — Claude Code — هو agentic harness: يُوفّر الأدوات، ويُدير السياق، وينفّذ، ويُعيد النتائج. وأنت تبقى داخل الحلقة: Esc يُقاطع النداء الجاري، وكتابة تصحيح دون إيقاف يُغيّر المسار في التور التالي دون فقدان العمل الجاري.

جرد الأدوات المدمجة​

تنتظم الأدوات المدمجة في خمس عائلات وظيفيّة. الأسماء المذكورة أدناه هي المعرِّفات الحرفيّة المستعملة في قواعد الأذونات (Outil(...))، وقوائم tools: للوكلاء الفرعيّين، وmatchers الخاصّة بـhooks.

  • الملفّات: Read يقرأ، Edit يُنفّذ استبدالاً مُستهدفًا، Write يُنشئ أو يُبدّل، NotebookEdit يُعدّل خليّة Jupyter. لا يطلب Read إذنًا داخل مسار العمل؛ ويطلبانه Edit وWrite في الوضع اليدويّ. قاعدة Edit(...) تمنح ضمنيًّا Read المقابل.
  • البحث: Grep (نمط داخل المحتوى)، Glob (نمط اسم)، LSP (تعريفات، مراجع، تشخيصات نوعيّة — عبر إضافة code intelligence).
  • التنفيذ: Bash (shell Unix)، PowerShell (Windows، حين يُفعَّل)، Monitor (عمليّة في الخلفيّة تُرجع كلّ سطر مخرج إلى Claude).
  • الويب: WebFetch (URL)، WebSearch (بحث).
  • التنسيق: Agent (وكيل فرعيّ بنافذته الخاصّة)، Skill (يُحمّل skill)، AskUserQuestion (سؤال متعدّد الخيارات)، SendMessage وListAgents (مراسلة بين الجلسات).

تُضاف إليها أدوات خدميّة: EnterPlanMode / ExitPlanMode (وضع plan، الوحدة 8)، EnterWorktree / ExitWorktree (git worktrees)، TaskCreate / TaskList / TaskUpdate (قائمة مهامّ)، CronCreate / CronList / CronDelete (prompts مجدولة عبر /loop)، RemoteTrigger (روتينات سحابيّة عبر /schedule)، ToolSearch (تحميل عند الطلب لأدوات MCP المؤجَّلة)، Workflow (workflow ديناميكيّ)، PushNotification (إشعار سطح مكتب أو موبايل). TodoWrite مُعطَّل افتراضيًّا لصالح عائلة Task*.

الأدوات التي تطلب إذنًا افتراضيًّا هي التي تكتب أو تنفّذ: Bash وEdit وWrite وNotebookEdit وPowerShell وMonitor وWebFetch وWebSearch وEnterWorktree وSkill وWorkflow وArtifact. يستثنى Bash لمجموعة معرَّفة من أوامر القراءة فقط (ls، pwd، git status) لا تطرح سؤالًا؛ يُضيف Bash(git log *) ما نشاء إلى قائمة السماح.

كلّ أداة تعرف وسيطها

تتبع قاعدة الإذن دائمًا الصيغة Outil(spécifieur). لـBash، المُحدِّد نمط أمر (Bash(npm run *))؛ لـRead/Edit/Write، مسار (Edit(app/**))؛ لـWebFetch، مجال (WebFetch(domain:docs.example.com))؛ لـSkill، اسم (Skill(deploy *)). تُفصِّل الوحدة 7 كلّ التوليفات.

نافذة السياق: ما يملؤها​

نافذة السياق هي كلّ ما يراه Claude في كلّ تور. تحتوي، بالترتيب:

  1. prompt النظام: تعليمات الأساس، تعريفات الأدوات، output-styles، نصّ --append-system-prompt.
  2. سياق المشروع: ملفّات CLAUDE.md المدمَجة من أعلى الشجرة إلى مجلّدك، القواعد بلا paths:، الذاكرة التلقائيّة (أوّل 200 سطر أو 25 كيلوبايت من MEMORY.md)، أوصاف skills.
  3. تعريفات أدوات MCP — فقط الأسماء وتعليمات الخادم: المخطّطات الكاملة مؤجَّلة عبر tool search (الوحدة 11).
  4. المحادثة: رسائلك، ردود Claude، نتائج الأدوات.

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

يعرض /context شبكة ملوَّنة للاستهلاك، مع اقتراحات تحسين، وملفّات الذاكرة المحمّلة، وكلفة خوادم MCP، والتجاوز إن وُجد. مرِّر all لتفصيل كلّ عنصر. اقرأ /context قبل أيّ compact: هي الطريقة الوحيدة الموثوقة لمعرفة من يلتهم الرموز.

/compact و/clear و/btw: تحرير الفضاء دون البدء من الصفر​

ثلاثة أوامر تُدير الفضاء:

  • /compact [instructions] يُلخّص المحادثة إلى تلك اللحظة ويُبدل السجلّ. بلا وسيط، يختار Claude ما يُبقيه؛ ومع تعليمة — /compact concentre-toi sur le bug de paiement, jette tout le reste — يستهدف. يُنتج الأمر طلبًا منفصلًا بنفس prompt النظام، وكلّ أدواتك، والسجلّ، وتعليمة تلخيص.
  • /clear [nom] يفتح محادثة فارغة. تبقى ذاكرة المشروع وملفّ CLAUDE.md محمَّلَين. اسم اختياريّ يوسم المحادثة السابقة في /resume. الأسماء البديلة: /reset و/new.
  • /btw [question] يطرح سؤالًا جانبيًّا لا يدخل جوابه السجلّ. مثاليّ لـ«بالمناسبة، ما optimistic lock؟» دون تلويث المحادثة. بلا وسيط، يُعيد /btw عرض آخر سؤال جانبيّ (v2.1.212+؛ سابقًا كان السؤال إلزاميًّا).

أوامر أخرى في المجال ذاته: /autocompact <auto|tokens> يضبط متى يُطلَق الضغط التلقائيّ (/autocompact 500k، /autocompact auto) — v2.1.221+؛ /rewind (الأسماء البديلة /checkpoint و/undo) يُرجع أو يُلخّص من رسالة محدَّدة، مُفصَّل في الوحدة 8؛ /recap يُنتج ملخّصًا من سطر دون المسّ بالسياق.

ما يصمد أمام /compact​

حين يُنفَّذ /compact، يُلخّص Claude Code المحادثة، لكنّه يُعيد قراءة أشياء من القرص:

  • prompt النظام وoutput style يبقيان سليمَين (خارج السجلّ).
  • ملفّ CLAUDE.md للمستودع، والقواعد بلا paths:، والذاكرة التلقائيّة، وخطّة وضع plan تُحقَن مجدَّدًا من القرص.
  • القواعد ذات frontmatter paths: وملفّات CLAUDE.md في المجلّدات الفرعيّة تُعاد تحميلها حين يُعيد Claude قراءة ملفّ يستدعيها.
  • تُعاد قراءة حتّى خمسة ملفّات مُعدَّلة حديثًا؛ ملفّ يتجاوز 5 000 رمز يعود مجرّد مرجع مسار.
  • تعود أجساد skills المُستدعاة، بسقف 5 000 رمز لكلّ skill و25 000 رمز إجمالًا.
  • تُعاد hooks SessionStart التي تتطابق مع مصدر compact، ويُضاف مخرجها.

نتيجة ذلك: تعليمة أعطيتها داخل المحادثة فقط تختفي. إن أردت لها البقاء، فمكانها ملفّ CLAUDE.md — الوحدة 3.

كاش الطلبات: لماذا تُكلِّف بعض الأفعال أكثر​

تُعيد الـAPI استعمال الجزء الأوّليّ — البادئة — من كلّ طلب إن كان مطابقًا للسابق. يُرتّب Claude Code عن قصد prompt النظام في البداية، ثمّ سياق المشروع، ثمّ المحادثة. إضافة في آخر المحادثة لا تكسر شيئًا؛ لكنّ تغييرًا في prompt النظام يُبطل كلّ ما يليه. لذلك تُطلق بعض الأوامر تورًا بطيئًا أغلى مرّة واحدة، ثمّ يعود إيقاع التوّرات التالية.

أفعال تُبطل الكاش:

  • تبديل النموذج (/model) — لكلّ نموذج كاشه؛ يُطلَب التأكيد ما دام الكاش ساخنًا.
  • تبديل مستوى الجهد على معظم النماذج (استثناء Fable 5.1 بمفتاح API أو باشتراك).
  • تفعيل الوضع السريع (/fast on): ترويسة تُغيّر cache key.
  • وصل أو فصل خادم MCP تدخل أدواته البادئةَ (نادر منذ tool search).
  • رفض أداة كاملة عبر قاعدة deny باسم مجرَّد (Bash, WebFetch): يخرج التعريف من prompt النظام.
  • تبديل output style عبر /config outputStyle=....
  • ضغط المحادثة بـ/compact.
  • تراكم صور بحيث يُزيل الـCLI أقدمها.
  • تحديث Claude Code: أوّل طلب بعد إعادة التشغيل يُعيد بناء الكاش.

أفعال تحافظ على الكاش: تحرير ملفّات المستودع، تحرير CLAUDE.md في وسط الجلسة (لا يُعاد قراءته إلّا عند الإطلاق أو بعد /clear / /compact)، تبديل وضع الأذونات، استدعاء skill أو أمر، تشغيل /recap أو /rewind.

اختر عند الانطلاق

حدِّد النموذج ومستوى الجهد قبل سؤالك الأوّل. كلّ تبديل في وسط الجلسة يُكلّفك تور بادئة كاملًا. القاعدة البسيطة: sonnet + high عند البدء، ولا نُبدّل إلّا لخطّة معقّدة.

التفويض إلى وكيل فرعيّ لتوفير السياق​

حين يجب أن يقرأ بحث ما عشرين ملفًّا، تضخيم النافذة الرئيسيّة للاحتفاظ بمجرّد ملخّص حساب سيّئ. وكيل فرعيّ (الوحدة 10) يعمل داخل نافذة سياق خاصّة به: يقرأ ويبحث ويربط ولا يُعيد إلّا الملخّص. أمران يُطلقان هذا التحويل: /subtask <tâche> يُطلق forked subagent يرث المحادثة وتعود نتيجته إلى الخيط الجاري؛ /fork [prompt] ينسخ المحادثة إلى جلسة خلفيّة جديدة ويُبقيك هنا (تُتابَع عبر claude agents أو /tasks).

قراءة الكلفة: /usage​

/usage (الأسماء البديلة /cost و/stats) يُعطي للجلسة: رموز الدخل والخرج، cache read وcache write لكلّ نموذج، السعر المقدَّر، مدّة نداءات API. سطر Prompt cache (main) يُشير إلى نسبة رموز الدخل المقدَّمة من الكاش، وعدد الـmisses، والسبب المرجَّح للأخير (مثلًا likely cause: tool definitions changed)، وهل الكاش ساخن أم بارد (v2.1.251+، تسميات v2.1.260+).

على اشتراك، يُضيف /usage التوزيع الأخير حسب skill والوكلاء الفرعيّين وplugins وخادم MCP (24 ساعة أو 7 أيّام، تبديل d/w)، مع تحذيرات فور تجاوز فئة 10 ٪. يفتح /usage-credits شاشة الرصيد أو يُرسل طلبًا إلى الأدمن.

الخيط الأحمر Kiosque: رسم خريطة وضغط​

داخل مستودع Kiosque، نُطلق جلسة بـsonnet بجهد high ونطلب:

Explique-moi le flux d'une commande de bout en bout : depuis la requête
HTTP `POST /commandes` jusqu'à la confirmation de paiement. Cite les
fichiers de app/ concernés et les tables SQLAlchemy touchées.

يستدعي Claude Read على app/commandes.py، وGrep على النماذج، ويفتح app/paiements.py، وRead على models.py، وGrep على الهجرات. كلّ نداء يبدو في النصّ (Ctrl+O). يكشف /context أنّ المحادثة بلغت 60 000 رمز، نصفها من الملفّات المقروءة.

قبل مهاجمة إعادة صياغة paiements.py، نُضغط بتعليمة:

/compact garde uniquement le résumé du flux de commande et les modèles
de données ; jette tout le reste, notamment les extraits de code lus.

يعود الملخّص إلى 8 000 رمز مفيدة. يُعاد بناء الكاش في التور التالي، ثمّ يؤكّد /usage أنّ سطر Prompt cache (main) مُكوَّش بنسبة 90 ٪.

خطأ شائع: /clear بدل /compact​

يُلقي /clear كلّ المحادثة، بما في ذلك ما فهمه Claude لتوّه عن المستودع: نُعيد قراءات مطابقة في التور التالي. احتفظ بـ/clear لتبديل مهمّة مستقلّة؛ بين مرحلتين من مهمّة واحدة، /compact بتعليمة يحفظ ما يهمّ.

الخلاصة​

  • الحلقة الوكيليّة تُتابع جمع السياق، والفعل، والتحقّق؛ كلّ أداة تُلاحظ النتيجة وتُغذّي الخطوة التالية.
  • الأدوات المدمجة ترتّب في خمس عائلات؛ المعرِّفات الحرفيّة (Read, Bash, Edit…) هي نفسها في قواعد الأذونات وmatchers الخاصّة بـhooks.
  • نافذة السياق تُكدِّس prompt النظام، وسياق المشروع، وتعريفات الأدوات، والمحادثة؛ يعرضها /context.
  • /compact بتعليمة أفضل من /clear في وسط مهمّة: نُبقي ما يهمّ.
  • كاش الطلبات يدفع البادئة مرّة واحدة؛ تبديل النموذج أو الجهد أو output style يُجبر على إعادة الحساب.
  • /usage يقرأ الكلفة الفعليّة، وسطر Prompt cache يُبيّن إن كانت جلستك تُعيد استعمال بادئتها كما ينبغي.
  • وكيل فرعيّ يُبقي القراءات الكبيرة خارج نافذتك الرئيسيّة؛ /subtask و/fork بوّابتا الدخول.

الوحدة التالية: CLAUDE.md والقواعد والذاكرة: تعليم Claude معالم المشروع — حتّى يُعاد تحميل نصف هذا السياق تلقائيًّا في كلّ جلسة دون كتابة أيّ شيء.