تحليل تصميم harness في Claude Code

توضح Anthropic في مقال Effective harnesses for long-running agents أن مصدر الموثوقية هو harness لا النموذج، وأن الـ agent يحتاج إلى قيود «خارج النموذج». ويعد Claude Code التجسيد العملي لهذه الفكرة؛ إذ تصنّفه Anthropic رسميًا ضمن فئة agentic harness. وليس ذلك شعارًا تسويقيًا—فلعل Claude Code أكثر harness جرى تحليله علنًا حتى الآن: شيفرته المصدرية مفتوحة، وتقارير المجتمع البحثية عنه مفصلة، كما حوّل معظم الآليات الجوهرية في محاضرات الدورة (الذاكرة الطبقية، وcompaction السياق، وpermissions، وhooks، وsubagents، واستمرارية session) إلى تطبيق متكامل على مستوى المنتج.

نحلل في هذه المقالة Claude Code باستخدام إطار الأنظمة الفرعية الخمسة في الدورة، مع التركيز على كيفية تطبيقه مفاهيم harness الأساسية مثل «إدارة السياق» و«منع إعلان الإنجاز مبكرًا» و«القيود الحتمية».

التعريف في جملة واحدة

جوهر Claude Code حلقة while بسيطة: استدعاء النموذج، وتنفيذ الأدوات، وملاحظة النتائج، ثم استدعاء النموذج مجددًا. لكن الغالبية الساحقة من الشيفرة ليست داخل هذه الحلقة، بل في النظام المحيط بها—نظام permissions، ومسار compaction للسياق، وآليات التوسعة، وتنسيق subagents، وتخزين session. وهذه هي ماهية harness: الحلقة هي الهيكل العظمي، وما يقع خارجها هو ما يحدد الموثوقية.

النظام الفرعي للتعليمات: منظومة ذاكرة طبقية

يمثل نظام الذاكرة في Claude Code إسهامه الأكثر مباشرة في نظرية harness، وهو يقابل محاضرتي «المستودع هو مصدر الحقيقة» و«استمرارية السياق عبر sessions» في الدورة. توضح الوثيقة الرسمية «How Claude remembers your project» أن كل session يبدأ بنافذة سياق جديدة تمامًا، وأن المعرفة تنتقل بين sessions بواسطة آليتين: ملفات CLAUDE.md (التعليمات التي تكتبها) وauto memory (الملاحظات التي يكتبها Claude بنفسه).

ومن حيث النطاق، تقسم الوثائق الرسمية ملفات CLAUDE.md إلى أربع فئات (بترتيب التحميل من الأوسع إلى الأضيق):

• مستوى سياسة المؤسسة: تديره فرق IT/DevOps مركزيًا (مثل /etc/claude-code/CLAUDE.md) لقواعد المؤسسة.
• مستوى المستخدم ~/.claude/CLAUDE.md: التفضيلات والقواعد الشخصية العابرة للمشروعات.
• مستوى المشروع ./CLAUDE.md أو ./.claude/CLAUDE.md: مصدر الحقيقة للمشروع، ويشمل بنية المشروع، والمكدس التقني، وأوامر التحقق، ويُشارك مع المستودع.
• المستوى المحلي ./CLAUDE.local.md: التفضيلات الشخصية داخل المشروع، ويضاف عادة إلى .gitignore ولا يُعتمد.

وتوجد آليتان إضافيتان:

• التحميل عند الطلب على مستوى الدليل الفرعي: لا تُحمّل ملفات CLAUDE.md في الأدلة الفرعية عند بدء التشغيل، بل تدخل السياق عندما يقرأ Claude ملفًا في ذلك الدليل.
• الذاكرة التلقائية (auto memory): يكتب Claude ملاحظات بصورة استباقية بناءً على تصحيحاتك وتفضيلاتك؛ وتُشارك على مستوى المستودع وتعمل عبر worktree، مع تحميل أول 200 سطر أو 25KB كحد أقصى في كل session.

تشكل هذه النطاقات الأربعة تدرجًا للتعليمات: تقول الوثائق الرسمية إن «التعليمات الأكثر تحديدًا تدخل السياق في وقت لاحق» (فتظهر تعليمات المشروع بعد تعليمات المستخدم). وتكمن القيمة في ألّا يُجبر النموذج على استيعاب ملف تعليمات ضخم كامل في بداية كل محادثة، بل تُحمّل التعليمات محليًا بحسب نطاقها. وهذا هو الجواب العملي عن سؤال المحاضرة الرابعة: «لماذا يفشل ملف التعليمات العملاق الواحد؟».

النظام الفرعي للسياق: مسار compaction من خمس طبقات

تدير Claude Code السياق عبر مسار compaction من خمس طبقات (five-layer compaction pipeline)، لا بمجرد «التلخيص عند الامتلاء»—وتأتي هذه التفصيلة البنيوية من تحليل الشيفرة المصدرية في تقرير VILA Lab‏ «Dive into Claude Code». تشرح المحاضرة الخامسة أن «المهام الطويلة تفقد الاستمرارية»، وحل Claude Code هو قمع متعدد المراحل: يبدأ بالتقليم غير الفاقد (إزالة نتائج الأدوات الزائدة)، ثم الاستخلاص المنظم، ولا يلجأ إلى تلخيص LLM الفاقد إلا في النهاية، مع آلية قاطع دائرة تمنع compaction المفرط.

ويكمل ذلك تصميم تخزين session: تخزين session موجّه إلى الإلحاق (append-oriented storage)، تُلحق فيه كل السجلات بـ history.jsonl، مع دعم الاستئناف عبر /resume والتفرع fork. وهذا يضمن «إجراء تسليم جيد قبل نهاية كل session»—لا بفضل ذاكرة قوية، بل لأن طبقة التخزين إلحاقية وقابلة لإعادة التشغيل.

النظام الفرعي للأدوات: أربع آليات للتوسعة

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

• Skills: تعرفها الوثائق الرسمية بأنها معرفة إجرائية يصفها SKILL.md، وتُحمّل تلقائيًا وفق كلمات التشغيل، مع إفصاح تدريجي. وهي ملائمة لمعرفة المجال المتعلقة بـ «كيفية تنفيذ شيء ما».
• MCP: يربط بروتوكول JSON-RPC الوارد في الوثائق الرسمية الأنظمة الخارجية، وهو الواجهة القياسية التي «تمد يد النموذج إلى العالم الخارجي».
• Hooks: نصوص حتمية تعلّقها الوثائق الرسمية بأحداث دورة الحياة مثل PreToolUse وPostToolUse وStop.
• Plugins / Subagents: توكل الوثائق الرسمية المهام المعقدة إلى agent متخصص.

قرار التصميم الأساسي هو فصل المسؤوليات: يدير CLAUDE.md «ما هو الشيء»، وتدير Skills «كيفية فعله»، ويدير MCP «بماذا نتصل»، وتدير Hooks «متى نفرضه». وإذا خلط الفريق هذه الطبقات (مثل كتابة ما يخص MCP في CLAUDE.md)، ظهر تسرّب السياق الذي تصفه الدورة.

التغذية الراجعة والتحقق: قيود حتمية + تقسيم العمل بين الإنسان والآلة

تتناول المحاضرة العاشرة أن «التحقق الحقيقي لا يتم إلا بتشغيل المسار الكامل»، ويقابل ذلك في Claude Code مساران:

1. نظام permissions (قيود حتمية). لا يتعامل Claude Code مع permissions بمنطق «اسأل عن كل شيء»، بل يستخدم سبعة أوضاع + مصنّف قائم على ML: يسمح بالعمليات منخفضة المخاطر، ويسأل أو يرفض العمليات عالية المخاطر وفق السياسة (راجع التفاصيل البنيوية في تحليل VILA Lab). وهكذا تتحول فكرة «وضع حدود واضحة لكل مهمة agent» (المحاضرة السابعة) إلى فرض في runtime، بدل التوسل إليها في الموجّه.

2. Hooks (منع إعلان الإنجاز مبكرًا). يستطيع hook من نوع PostToolUse فرض تشغيل الفحوص بعد تنفيذ الأداة وكتابة النتائج مرة أخرى في السياق؛ ويتدخل hook من نوع Stop عندما يعلن الـ agent اكتمال العمل. وهذا يعني «فصل من ينفذ العمل عمن يفحصه»—إذ لاحظت Anthropic صراحة في مقال harness أن الـ agent يمدح عمله بثقة، ولذلك تستخدم hooks لحقن فحوص حتمية بدل الوثوق بالتقييم الذاتي للنموذج.

3. Subagents (عزل السياق). يُحفظ سجل محادثة كل subagent في ملف sidechain مستقل، ولا يؤدي إلى تضخيم سياق agent الأب (راجع تحليل VILA Lab). ويجمع ذلك بين «حدود المهمة» و«عزل السياق»: فعند تقسيم المهمة، يُعزل تلوث السياق أيضًا.

قابلية الرصد واستمرارية session

سجل Claude Code كامل وإلحاقي (history.jsonl)، ومع الأوامر الصريحة /compact و/clear و/init يمكنك إدارة حالة السياق استباقيًا، بدل انتظار امتلائه. ويحوّل /init فكرة «تهيئة الـ agent قبل كل عمل» (المحاضرة السادسة) إلى أمر—إذ تقول الوثائق الرسمية إنه يحلل قاعدة الشيفرة تلقائيًا وينشئ CLAUDE.md أوليًا (يتضمن أوامر البناء، وتعليمات الاختبار، وأعراف المشروع).

المواءمة مع إطار الدورة

النظام الفرعي	تطبيق Claude Code	التقييم
التعليمات	طبقات بحسب النطاق (المؤسسة/المستخدم/المشروع/المحلي) + ذاكرة تلقائية	الذاكرة الطبقية تطبيق مرجعي
الأدوات	أربعة أنواع من التوسعات: المهارات + MCP + الخطافات + الوكلاء الفرعيون	تقسيم واضح للمسؤوليات، وهو أبرز نقاط القوة
البيئة	إعدادات داخل المشروع + settings.json	تعتمد على وصف المستخدم الذاتي في CLAUDE.md
الحالة	تخزين جلسة إلحاقي + ضغط من خمس طبقات + resume/fork	قوي جدًا، وتطبيق مرجعي لاستمرارية المهام الطويلة
التغذية الراجعة	مصنّف أذونات + فحوص إلزامية عبر خطاف PostToolUse	يحوّل «منع إعلان الإنجاز مبكرًا» إلى آلية حتمية

تصميمات جديرة بالاقتباس

1. تقسيم التعليمات إلى طبقات بحسب النطاق، بدل تكديسها في ملف واحد. ويعد CLAUDE.md على مستوى الدليل تطبيقًا أنيقًا لـ «التحميل المحلي».
2. compaction قمع متدرج: غير فاقد أولًا ثم فاقد؛ فلا تبدأ بتلخيص النص كله.
3. استخدام hooks للفحوص الحتمية: منع إعلان الإنجاز مبكرًا يعتمد على الفرض في runtime، لا على التوسل في الموجّه.
4. عزل سياق subagents: قسّم السياق مع تقسيم المهمة، ولا تدع نتائج المهمة الفرعية تلوث الحلقة الرئيسية.
5. تخزين session إلحاقي وقابل لإعادة التشغيل: لا يعتمد التسليم على الذاكرة، بل تضمنه طبقة التخزين.

المصادر المرجعية (النص الأصلي / الشيفرة المصدرية)

يمكن تتبع كل ادعاء إلى النص الأصلي أو الشيفرة المصدرية أدناه، تجنبًا للنقل اعتمادًا على الانطباع:

• Claude Code — Memory: سياق جديد لكل session، وأربعة نطاقات لـ CLAUDE.md، والتحميل عند الطلب في الأدلة الفرعية، وauto memory ‏(200 سطر / 25KB)، وإنشاء CLAUDE.md بواسطة /init.
  https://code.claude.com/docs/en/memory
• Claude Code — Skills / MCP / Hooks / Sub-agents: تعريف آليات التوسعة الأربع وأحداثها (PreToolUse / PostToolUse / Stop).
  https://code.claude.com/docs/en/skills ｜ https://code.claude.com/docs/en/mcp ｜ https://code.claude.com/docs/en/hooks ｜ https://code.claude.com/docs/en/sub-agents
• VILA Lab — Dive into Claude Code: تحليل على مستوى الشيفرة المصدرية لمسار compaction ذي الطبقات الخمس، وسبعة أوضاع permissions + مصنّف ML، وsubagents عبر sidechain، وتخزين session الإلحاقي history.jsonl.
  https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf
• Anthropic — Effective harnesses for long-running agents: مصدر أفكار «الموثوقية تأتي من harness لا النموذج»، وأن الـ agent يمدح عمله بثقة، واستخدام hooks للتحقق.
  https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
• Claude Code Full Stack Guide: قراءة مجتمعية تكميلية عن فصل مسؤوليات طبقات CLAUDE.md / Skills / MCP / Subagents / Hooks.
  https://jsmanifest.com/claude-code-full-stack-guide

المحاضرات ذات الصلة: المحاضرة الثالثة · جعل مستودع الشيفرة مصدر الحقيقة الوحيد ｜ المحاضرة التاسعة · منع الـ agent من إعلان الإنجاز مبكرًا ｜ المحاضرة العاشرة · التحقق الحقيقي لا يتم إلا بتشغيل المسار الكامل