رَسْم خريطة وتدقيق منظومة Claude Code ديالك باستعمال harness-map

شنو كيدير harness-map

harness-map كيقرا الإعدادات اللي دايرة بـ Claude Code وكيحوّلها لخريطة بصرية وحدة ديال التجهيز. هاد الإعدادات المحيطة، اللي كنسمّيوها harness، كتشمل ملفات التعليمات بحال CLAUDE.md، الذاكرة التلقائية، خوادم MCP، المهارات، الصلاحيات، الخطّافات، القواعد، وإعدادات مرتبطة بها.

الـ harness الفعّال يقدر يتبدّل حسب الدوسي اللي كيبدا منّو Claude Code والطريقة اللي كيتطلق بها agent جديد. جلسة رئيسية، fork، subagent، agent ديال Explore ولا Plan، teammate، ولا استدعاء claude -p يقدرو يتوصلو بمعلومات مختلفة. harness-map كيخلّي هاد الاختلافات باينة لكل دوسي بداية وطريقة إطلاق مختارة.

المشروع كيستعمل Python 3 وما كيحتاج حتى package إضافية ديال Python. السكريبتات ديالو كتقرا الإعدادات بلا ما تبدّلها، وكتنتج ملف منظّم سميتو harness.json، وكتبني تقرير harness-map.html يمكن تشوفو فالمتصفح.

الخصائص الرئيسية

• تحليل حسب الدوسي: قارن عدد الدوسيات ديال البداية اللي بغيتي، غير عاود --cwd.
• تصوير تسليم الـ agents: شوف واش كل مكوّن موروث من جلسة أم، ولا تقرا من جديد من ملف، ولا ما كيتبعثش لـ agent جديد.
• تحليل تفاعل القواعد: فحص خمسة ديال طرق التعامل: التعويض، الدمج مع إعطاء الأولوية للمنع، تشغيل جميع القواعد، الجمع بلا أولوية، واختيار قاعدة وحدة فقط.
• حالات المخاطر والانتباه: تعرّف على حالات بحال تقسيم الذاكرة التلقائية حسب الدوسي، ولا كون وظائف الفريق كتخلي وضع الصلاحيات يتبعث لـ agent جديد.
• تقييم النضج: راجع المستويات من 1 حتى 5 عبر ستة مجالات ديال الـ harness فمخطط سداسي.
• إخراج كيراعي الخصوصية: سجّل المعطيات البنيوية مع حذف نصوص التعليمات، وقيم متغيرات البيئة، والتوكنات، ومعاملات الأوامر، وتفاصيل حساسة أخرى.
• عرض قابل للنقل: لسّق harness.json ديال شي شخص آخر فواجهة التقرير باش تعاود ترسم الخريطة ديالو.

قبل ما تبدا

خاصك Python 3، وGit، والولوج لإعدادات Claude Code ديال الحساب العادي ديالك. ما كايناش حاجة تثبّت packages باستعمال pip.

شغّل harness-map بنفس المستخدم اللي كيشغّل Claude Code. ما تستعملش sudo. التشغيل بصلاحيات المدير يقدر يبدّل الدوسي الرئيسي الفعّال ويكشف إعدادات مستخدم آخر، وداكشي علاش السكريبت كيرفض يخدم بهاد الطريقة.

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

التثبيت

دير clone للمستودع ودخل للدوسي ديالو:

git clone https://github.com/Dominic-DK/harness-map.git
cd harness-map

تقدر تراجع المشروع فـ github.com/Dominic-DK/harness-map. المشروع موزّع برخصة MIT.

الخطوة 1: فحص harness ديال Claude Code

شغّل harness-map.py مع argument واحد ديال --cwd لكل workspace بغيتي تقارن. الأمر التالي كيفحص جوج دوسيات كمثال وكيكتب النتيجة فـ harness.json:

python3 harness-map.py --cwd ~/work/a --cwd ~/work/b -o harness.json

تقدر تعاود --cwd قد ما بغيتي. إلا حيدتيه، harness-map كيفحص غير الدوسي الحالي:

python3 harness-map.py -o harness.json

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

بدّل الفترة ديال تاريخ المحادثات

الفترة الافتراضية ديال التجميع هي 30 يوم. استعمل --days ملي تحتاج نافذة ملاحظة مختلفة. مثلاً، الأمر التالي كيستعمل 90 يوم:

python3 harness-map.py --cwd ~/work/a --days 90 -o harness.json

تحليل المحادثات كيحسب غير الأحداث. ما كينسخش نص المحادثات، ولا محتوى الأوامر، ولا محتوى الملفات للنتيجة.

الخطوة 2: طبع خطة اختبار الـ agent

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

python3 harness-map.py --probe-plan

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

الخطوة 3: دير الاختبارات ولا تخطاها

خلّي agent ينفّذ خطة الاختبار المطبوعة ويسجّل الملاحظات ديالو فـ probes.json. كل اختبار كيسجّل شنو تدار وشنو تلاحظ كدليل داعم.

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

الخطوة 4: دمج نتائج الاختبارات

عاود دير الفحص بنفس دوسيات البداية وزيد --probes probes.json:

python3 harness-map.py --cwd ~/work/a --cwd ~/work/b --probes probes.json -o harness.json

استعمال نفس مجموعة --cwd كيخلي الحساب النهائي متوافق مع workspaces اللي شملها الفحص الأول.

الخطوة 5: بنِ وفتح التقرير

ولّد تقرير HTML من ملف JSON الكامل:

python3 build.py harness.json

فـ macOS، حلّو بهاد الطريقة:

open harness-map.html

فـ Linux، استعمل:

xdg-open harness-map.html

فـ Windows، استعمل:

start harness-map.html

كيفاش تقرا خريطة الـ harness

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

• الـ agent الجديد كيتوصل بيه مباشرة من الجلسة الأصلية.
• الـ agent الجديد كيقراه من جديد من ملف.
• المكوّن ما كيتبعثش للـ agent الجديد.

هاد المقارنة كتعاون تفسّر علاش جوج agents خدامين بنفس المستودع يقدرو يتصرفو بطرق مختلفة. مثلا، ممكن الـ subagent ما يتوصلش بكلشي اللي متاح للجلسة الرئيسية، بينما الإعدادات المرتابطة بمجلد بداية معيّن ما كتطبقش فبلايص خرين.

فهم القواعد المتداخلة

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

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

فهم تقييم مستوى النضج

‏harness-map كيقيم ستة ديال المجالات من المستوى 1 حتى للمستوى 5:

1. تصميم التعليمات
2. الذاكرة والموقع
3. نطاق الأدوات
4. المنع الوقائي
5. التحقق والمراقبة من بعد الإجراء
6. تصميم التفويض

السكريبت يقدر يحسب أوتوماتيكيا حتى للمستوى 4 ملي كتكون المعطيات المتاحة كافية. النتيجة كتسجل شنوما الشروط اللي دازو وفين وقف التقييم. تعريفات التنقيط مخزّنة فـ SCORECARD داخل harness-map.py.

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

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

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

المستويات العالية ماشي بالضرورة أحسن. ‏harness-map كيقدّر المستوى اللي كيحتاجو كل مجال انطلاقا من أنماط الاستعمال، بما فيها واش كتخدم بوحدك، شحال من مرة كتطلق agents تابعين، وشحال من مرة كتنفذ أوامر صعيب ترجع فيها للور. كيسلط الضوء على المجالات اللي أقل من الحاجة المقدّرة، وماشي كينبّه على كل نقطة أقل من المستوى 5.

الخصوصية ومراجعة المخرجات

السكانير كيقرا الملفات ولكن ما كيبدلش الإعدادات. وكيحد عمدا من المعطيات اللي كينسخ للمخرجات ديالو:

• بالنسبة لـ CLAUDE.md وملفات القواعد، كيسجل المسارات، وعدد السطور، وفاش كتتقرا، ولكن ما كيسجلش النص ديالها.
• بالنسبة للإعدادات، كيسجل أوضاع الصلاحيات، وعدد القواعد، وأسماء متغيرات البيئة، ولكن ما كيسجلش قيم متغيرات البيئة ولا محتوى القواعد.
• بالنسبة للـ hooks، كيسجل الحدث، والمصدر، واسم الملف التنفيذي، ولكن كيحيد arguments ديال الأوامر والمسارات.
• بالنسبة لخوادم MCP، كيسجل الأسماء والمصادر، ولكن كيحيد الأوامر، والـ arguments، والـ headers، والـ tokens.
• بالنسبة للمسارات، كيبدل البادئة الحقيقية ديال مجلد المستخدم بـ ~.

الملفات اللي ما قدرش يقراها كيتحطو فـ لائحة unreadable. وحسب المشروع، Claude Code حتى هو ما يقدرش يقرا هاد الملفات بنفس صلاحيات المستخدم.

المخرجات باقي فيها أسماء المجلدات ولائحة الإضافات المثبتة. حلّ وراجع harness.json وharness-map.html بجوج قبل ما تشاركهم.

ملف .gitignore ديال المستودع مضبوط باش يخلي harness.json وharness-map.html خارج تتبع التحكم فالإصدارات، ولكن خاصك مع ذلك تتأكد من الملفات المجهزة قبل ما تدير commit.

فوّض سير العمل لـ coding agent

تقدر تطلب من Claude Code ولا من coding agent آخر يتبع تعليمات المستودع. بدّل المجلدات اللي فالمثال بالمجلدات اللي كتستعمل غالبا باش تبدأ منها. طلب مناسب يقدر يكون:

قرا README فـ https://github.com/Dominic-DK/harness-map وتبع خطوات التنفيذ المباشر.
المجلدات اللي كنبدأ منها غالبا هي ~/work/a و ~/work/b.
دير فحوصات agents ديال الخطوة 3 حسب قواعد السلامة الموثقة وسجل النتائج.
ملي تسالي، حلّ harness-map.html فالمتصفح ولخّص النتيجة فحوالي خمسة ديال الجمل الواضحة.

خلي المراقبة البشرية فمرحلة الاختبار. خاص الـ agent يتبع بالضبط خطة السلامة اللي خرجات من --probe-plan.

نصائح متقدمة

فحص كل نقطة دخول مهمة

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

اختار فترة ملاحظة مناسبة لطريقة خدمتك

الفترة الافتراضية ديال 30 يوم مناسبة للنشاط الأخير، ولكن الأدوات اللي كتستعمل نادرا تقدر تحتاج مدة أطول. استعمل --days بوعي، حيث الدليل على عدم الاستعمال يقدر يأثر على تنقيط النضج.

فرّق بين الإعدادات والسلوك المتحقَّق منّو

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

قارن بين التقارير بلا ما تكشف الإعدادات الخام

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

استعمل البديل ملي ما يكونش Python متوفّر

إلا ما كانش Python 3 متوفّر، نسخ محتوى PROMPT.md ولسّقو فواحد الوكيل. الوكيل يقدر يقرا الإعدادات مباشرة، وينشئ JSON بنفس الصيغة، ويبني الشاشة. كينبّه README باللي هاد الطريقة أكثر عرضة من السكريبت باش تسقط عناصر ولا تحسبهم بطريقة غالطة.

القيود المعروفة

• قواعد التسليم ثابتة فـ SPAWN_RULES داخل harness-map.py؛ وما كتستنتجش من مراقبة الجلسات الحية ديالك.
• كيقول README باللي هاد القواعد متّبعة من توثيق Claude Code 2.1.287 اللي تراجع نهار October 2, 2026. السلوك يقدر يختلف فالإصدارات اللاحقة.
• المصادر المذكورة هي التوثيق الرسمي ديال الوكلاء الفرعيين، وفرق الوكلاء، والذاكرة.
• المشروع كيشير لواحد الاختلاف: التوثيق كيقول باللي الوكلاء الفرعيين ما كيقراوش الذاكرة التلقائية، بينما البيئة ديال الكاتب، حسب التقرير، دازت لائحة ديال الذاكرة لوكيل فرعي. التقرير كيصنّف هاد الشي كفرق بين التوثيق والملاحظة.
• الإعدادات اللي كتستعمل غير من سطر الأوامر، بحال --agents و--permission-mode، ما كتتخزّنش فالملفات، وبالتالي ما يقدرش الماسح يكتاشفها.
• بالنسبة للإضافات المثبّتة، الماسح كيقرا أحدث نسخة لقاها فمجلد تثبيت الإضافة.

الخلاصة

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