harness-map کے ساتھ اپنے Claude Code Harness کا نقشہ اور آڈٹ بنائیں

harness-map کیا کرتا ہے

harness-map Claude Code کے اردگرد موجود configuration پڑھتا ہے اور اسے ایک واحد بصری assembly map میں تبدیل کرتا ہے۔ یہ اردگرد کی configuration، جسے harness کہا جاتا ہے، میں CLAUDE.md جیسی instruction files، خودکار memory، MCP servers، skills، permissions، hooks، rules اور متعلقہ settings شامل ہوتی ہیں۔

موثر harness اس folder کے مطابق بدل سکتا ہے جہاں سے Claude Code شروع کیا جاتا ہے اور اس طریقے کے مطابق بھی جس سے نیا agent شروع کیا جاتا ہے۔ مرکزی session، fork، subagent، Explore یا Plan agent، teammate، یا claude -p invocation کو مختلف معلومات مل سکتی ہیں۔ harness-map ہر منتخب starting folder اور launch method کے لیے ان فرقوں کو نمایاں کرتا ہے۔

یہ project Python 3 استعمال کرتا ہے اور اسے Python کے اضافی packages درکار نہیں۔ اس کے scripts configuration میں کوئی تبدیلی کیے بغیر اسے پڑھتے ہیں، ایک منظم harness.json file تیار کرتے ہیں، اور browser میں دیکھی جا سکنے والی harness-map.html report بناتے ہیں۔

اہم خصوصیات

• Folder-specific analysis: --cwd کو بار بار لکھ کر جتنی starting directories درکار ہوں ان کا موازنہ کریں۔
• Agent handoff visualization: دیکھیں کہ ہر component parent session سے inherit ہوا ہے، file سے دوبارہ پڑھا گیا ہے، یا نئے agent کو منتقل نہیں کیا گیا۔
• Rule interaction analysis: handling کے پانچ patterns کا جائزہ لیں: replacement، denial کو ترجیح دیتے ہوئے merging، تمام rules چلانا، priority کے بغیر concatenation، اور صرف ایک rule منتخب کرنا۔
• Risk and attention cases: ایسی صورت حال کی نشاندہی کریں، جیسے folder کے لحاظ سے automatic memory کا تقسیم ہو جانا یا team functionality کے باعث permission mode کا نئے agent کو منتقل ہو جانا۔
• Maturity assessment: hexagonal chart میں harness کی چھ disciplines کے لیے levels 1 سے 5 کا جائزہ لیں۔
• Privacy-aware output: instruction bodies، environment variable values، tokens، command arguments اور دیگر حساس تفصیلات شامل کیے بغیر structural metadata ریکارڈ کریں۔
• Portable rendering: کسی دوسرے شخص کی harness.json کو report interface میں paste کر کے اس کا map دوبارہ بنائیں۔

شروع کرنے سے پہلے

آپ کو Python 3، Git، اور اپنے معمول کے user account سے متعلق Claude Code configuration تک رسائی درکار ہے۔ pip کے ذریعے package installation کی ضرورت نہیں۔

harness-map اسی user کے طور پر چلائیں جو Claude Code چلاتا ہے۔ sudo استعمال نہ کریں۔ Administrator کے طور پر چلانے سے مؤثر home directory تبدیل ہو سکتی ہے اور کسی دوسرے user کی configuration ظاہر ہو سکتی ہے، اس لیے script اس طریقے سے چلنے سے انکار کرتی ہے۔

وہ اصل directories منتخب کریں جہاں سے آپ عموماً Claude Code شروع کرتے ہیں۔ Parent directory کو scan کرنے سے وہ تمام configuration ظاہر نہیں ہوتی جو child project کے اندر سے شروع کرتے وقت لاگو ہوتی، کیونکہ configuration ہر starting folder سے اوپر کی سمت resolve ہوتی ہے۔

Installation

Repository کو clone کریں اور اس کی directory میں جائیں:

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

آپ project کا جائزہ github.com/Dominic-DK/harness-map پر لے سکتے ہیں۔ یہ project MIT License کے تحت تقسیم کیا جاتا ہے۔

مرحلہ 1: اپنا Claude Code harness scan کریں

harness-map.py کو ہر اس workspace کے لیے ایک --cwd argument کے ساتھ چلائیں جس کا آپ موازنہ کرنا چاہتے ہیں۔ درج ذیل command دو مثال والے folders کو scan کرتی ہے اور نتیجہ harness.json میں لکھتی ہے:

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

آپ ضرورت کے مطابق --cwd جتنی بار چاہیں دہرا سکتے ہیں۔ اگر اسے چھوڑ دیں تو harness-map صرف موجودہ directory کو scan کرتا ہے:

python3 harness-map.py -o harness.json

ابتدائی scan configuration files پڑھتا ہے اور ایسی checks انجام دیتا ہے جو ان files اور aggregate conversation-history counts سے مکمل کی جا سکتی ہیں۔

Conversation-history period تبدیل کریں

پہلے سے aggregation period 30 دن ہے۔ جب آپ کو مختلف observation window درکار ہو تو --days استعمال کریں۔ مثال کے طور پر، یہ command 90 دن استعمال کرتی ہے:

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

Conversation analysis صرف events گنتا ہے۔ یہ conversation text، command contents یا file contents کو result میں copy نہیں کرتا۔

مرحلہ 2: agent probe plan پرنٹ کریں

کچھ checks کے لیے agent کو صرف static configuration کا معائنہ کرنے کے بجائے controlled tests انجام دینے پڑتے ہیں۔ project کی فراہم کردہ procedures اور safety rules اس command کے ذریعے پرنٹ کریں:

python3 harness-map.py --probe-plan

کسی agent سے checks انجام دینے کو کہنے سے پہلے یہ output پڑھیں۔ probe commands خود سے بنانے کے بجائے تیار کردہ instructions پر عمل کریں۔ ان checks میں configuration پڑھنا، متعلقہ history events گننا، اور temporary directory کے اندر behavior کی جانچ شامل ہو سکتی ہے۔

مرحلہ 3: probes انجام دیں یا چھوڑ دیں

Agent سے پرنٹ کیا گیا probe plan انجام دینے کو کہیں اور اس کے مشاہدات probes.json میں محفوظ کریں۔ ہر probe اس بات کا ریکارڈ رکھتا ہے کہ کیا چلایا گیا اور supporting evidence کے طور پر کیا مشاہدہ کیا گیا۔

یہ مرحلہ اختیاری ہے۔ اگر آپ probe انجام نہ دیں تو متعلقہ item not checked کے طور پر ظاہر ہوگا اور level calculations سے خارج رہے گا۔ ایسے کامیاب behavior کا دستی طور پر دعویٰ کرنے سے گریز کریں جس کا واقعی مشاہدہ نہ کیا گیا ہو، خاص طور پر level 5 checks کے لیے۔

مرحلہ 4: probe results merge کریں

اسی starting folders کے ساتھ scan دوبارہ چلائیں اور --probes probes.json شامل کریں:

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

وہی --cwd set استعمال کرنے سے final calculation ان workspaces کے مطابق رہتی ہے جنہیں پہلے scan میں شامل کیا گیا تھا۔

مرحلہ 5: report بنائیں اور کھولیں

مکمل شدہ JSON file سے HTML report تیار کریں:

python3 build.py harness.json

macOS پر اسے اس طرح کھولیں:

open harness-map.html

Linux پر استعمال کریں:

xdg-open harness-map.html

Windows پر استعمال کریں:

start harness-map.html

ہارنَس میپ پڑھنا

رپورٹ میں ابتدائی فولڈرز اور لانچ کے طریقوں کے درمیان تبدیل ہو کر ہر صورتحال کے لیے مؤثر ہارنَس دیکھیں۔ ہر جزو کے لیے رپورٹ ترسیل کی تین حالتوں میں فرق کرتی ہے:

• نیا ایجنٹ اسے براہِ راست پیرنٹ سیشن سے حاصل کرتا ہے۔
• نیا ایجنٹ اسے دوبارہ کسی فائل سے پڑھتا ہے۔
• جزو نئے ایجنٹ کو منتقل نہیں کیا جاتا۔

یہ موازنہ سمجھانے میں مدد دیتا ہے کہ ایک ہی ریپوزٹری استعمال کرنے والے دو ایجنٹس مختلف انداز میں کیوں کام کر سکتے ہیں۔ مثال کے طور پر، سب ایجنٹ کو وہ تمام چیزیں موصول نہیں ہوتیں جو مرکزی سیشن کے لیے دستیاب ہیں، جبکہ کسی مخصوص ابتدائی فولڈر سے وابستہ ترتیبات دوسری جگہوں پر لاگو نہیں ہو سکتیں۔

اوورلیپ کرنے والے قواعد کو سمجھیں

رپورٹ یہ بھی دکھاتی ہے کہ اوورلیپ کرنے والے قواعد کیسے حل ہوتے ہیں۔ کنفیگریشن کی قسم کے لحاظ سے، بعد کی قدر دوسری قدر کو بدل سکتی ہے، قواعد ضم ہو سکتے ہیں جن میں ممانعت کو ترجیح حاصل ہو، ہر مماثل کارروائی چل سکتی ہے، متن کو ترجیحی ترتیب کے بغیر جوڑا جا سکتا ہے، یا صرف ایک اختیار منتخب کیا جا سکتا ہے۔

جب کوئی ہدایت، اجازت یا ہُک غیر مؤثر دکھائی دے تو ان تعاملات کا جائزہ لیں۔ مسئلہ کسی فائل کے غائب ہونے کے بجائے قواعد کے امتزاج کے رویے میں ہو سکتا ہے۔

پختگی کے جائزے کو سمجھنا

harness-map چھ شعبوں کو سطح 1 سے سطح 5 تک اسکور کرتا ہے:

1. ہدایت کا ڈیزائن
2. میموری اور مقام
3. ٹول کا دائرۂ کار
4. احتیاطی روک تھام
5. کارروائی کے بعد تصدیق اور مشاہدہ پذیری
6. تفویض کا ڈیزائن

جب دستیاب ڈیٹا اس کی حمایت کرے تو اسکرپٹ خودکار طور پر سطح 4 تک حساب لگا سکتا ہے۔ نتیجہ ریکارڈ کرتا ہے کہ کون سی شرائط پوری ہوئیں اور جائزہ کہاں رک گیا۔ اسکورنگ کی تعریفیں harness-map.py کے اندر SCORECARD میں محفوظ ہیں۔

سطح 5 کے لیے کسی حقیقی مشاہدہ شدہ جانچ سے ثبوت درکار ہوتا ہے۔ مثال کے طور پر، احتیاطی روک تھام صرف اس وقت سطح 5 تک پہنچتی ہے جب کوئی ریکارڈ دکھائے کہ ممانعت نے واقعی کسی کمانڈ کو روک دیا تھا۔ صرف کنفیگریشن میں ممانعت کا موجود ہونا کافی نہیں ہے۔

اگر کنفیگریشن موجود ہو لیکن استعمال شدہ دکھائی نہ دے تو جائزہ اسکور کم بھی کر سکتا ہے، مثلاً ایسا ٹول جو منتخب کردہ تاریخی مدت کے دوران استعمال نہ ہوا ہو، یا ایسے سیشنز جو کنفیگر کردہ اجازت کے موڈ سے مختلف موڈ میں چلے ہوں۔

جب کئی ابتدائی فولڈرز اسکین کیے جائیں تو دکھائی جانے والی سطح فولڈر کی سطح کے اسکورز کا میڈین ہوتی ہے۔ فولڈرز کی تعداد جفت ہونے کی صورت میں درمیان کی نچلی قدر استعمال کی جاتی ہے۔ رپورٹ کم سے زیادہ کی حد بھی دکھاتی ہے۔

زیادہ سطحیں خودکار طور پر بہتر نہیں ہوتیں۔ harness-map استعمال کے نمونوں کی بنیاد پر اندازہ لگاتا ہے کہ ہر شعبے کو کس سطح کی ضرورت ہے، جس میں یہ بھی شامل ہے کہ آیا آپ اکیلے کام کرتے ہیں، ماتحت ایجنٹس کتنی بار لانچ کرتے ہیں، اور ایسی کمانڈز کتنی بار چلاتے ہیں جنہیں واپس پلٹنا مشکل ہو۔ یہ ہر سطح 5 سے کم اسکور کے بارے میں انتباہ دینے کے بجائے ان شعبوں کو نمایاں کرتا ہے جو اندازہ شدہ ضرورت سے کم ہوں۔

رازداری اور آؤٹ پٹ کا جائزہ

اسکینر فائلیں پڑھتا ہے لیکن کنفیگریشن تبدیل نہیں کرتا۔ یہ جان بوجھ کر اپنے آؤٹ پٹ میں نقل کی جانے والی معلومات کو محدود رکھتا ہے:

• CLAUDE.md اور قواعد کی فائلوں کے لیے یہ راستے، لائنوں کی تعداد اور انہیں پڑھے جانے کا وقت ریکارڈ کرتا ہے، مگر ان کا متن نہیں۔
• ترتیبات کے لیے یہ اجازت کے موڈز، قواعد کی تعداد اور ماحول کے متغیرات کے نام ریکارڈ کرتا ہے، مگر ماحول کے متغیرات کی قدریں یا قواعد کا متن نہیں۔
• ہُکس کے لیے یہ ایونٹ، ماخذ اور قابلِ اجرا فائل کا نام ریکارڈ کرتا ہے، مگر کمانڈ کے دلائل اور راستے شامل نہیں کرتا۔
• MCP سرورز کے لیے یہ نام اور ماخذ ریکارڈ کرتا ہے، مگر کمانڈز، دلائل، ہیڈرز اور ٹوکنز شامل نہیں کرتا۔
• راستوں کے لیے یہ حقیقی ہوم ڈائریکٹری کے سابقے کو ~ سے بدل دیتا ہے۔

جن فائلوں کو پڑھا نہیں جا سکتا انہیں unreadable فہرست میں رکھا جاتا ہے۔ پروجیکٹ کے مطابق، Claude Code بھی انہی صارف اجازتوں کے تحت ان فائلوں کو نہیں پڑھ سکتا۔

آؤٹ پٹ میں پھر بھی فولڈر کے نام اور انسٹال شدہ پلگ اِنز کی فہرست شامل ہوتی ہے۔ انہیں شیئر کرنے سے پہلے harness.json اور harness-map.html دونوں کھول کر جانچ لیں۔

ریپوزٹری کی .gitignore کو اس طرح کنفیگر کیا گیا ہے کہ harness.json اور harness-map.html ورژن کنٹرول سے باہر رہیں، لیکن پھر بھی کمٹ کرنے سے پہلے اسٹیج کی گئی فائلوں کی تصدیق کریں۔

ورک فلو کسی کوڈنگ ایجنٹ کے سپرد کریں

آپ Claude Code یا کسی دوسرے کوڈنگ ایجنٹ سے ریپوزٹری کی ہدایات پر عمل کرنے کو کہہ سکتے ہیں۔ مثال میں دیے گئے فولڈرز کو اپنی عام استعمال کی ابتدائی ڈائریکٹریز سے بدل دیں۔ مناسب درخواست یہ ہے:

Read the README at https://github.com/Dominic-DK/harness-map and follow the direct execution steps.
My usual starting folders are ~/work/a and ~/work/b.
Perform the step 3 agent checks according to the documented safety rules and record the results.
When finished, open harness-map.html in a browser and summarize the result in about five clear sentences.

پروب کے مرحلے پر انسانی نگرانی برقرار رکھیں۔ ایجنٹ کو --probe-plan سے تیار کردہ عین حفاظتی منصوبے پر عمل کرنا چاہیے۔

اعلیٰ درجے کی تجاویز

ہر بامعنی انٹری پوائنٹ اسکین کریں

یہ فرض نہ کریں کہ ریپوزٹری کی جڑ کو اسکین کرنے سے اندرونی پروجیکٹس بھی شامل ہو جاتے ہیں۔ ہر اس ڈائریکٹری کو، جہاں سے آپ حقیقتاً Claude Code لانچ کرتے ہیں، الگ --cwd کے طور پر شامل کریں۔ اس سے وراثتی ہدایات، میموری کی حدود اور ٹول کی دستیابی کا زیادہ مفید موازنہ حاصل ہوتا ہے۔

اپنے کام کے مطابق مشاہدے کی مدت منتخب کریں

حالیہ سرگرمی کے لیے ڈیفالٹ 30 دن کی مدت مناسب ہے، لیکن کم استعمال ہونے والے ٹولز کے لیے زیادہ طویل مدت درکار ہو سکتی ہے۔ --days سوچ سمجھ کر استعمال کریں، کیونکہ عدم استعمال کا ثبوت پختگی کے اسکور کو متاثر کر سکتا ہے۔

ترتیبِ تشکیل کو تصدیق شدہ رویے سے الگ رکھیں

فائل پر مبنی نتائج کو مطلوبہ ترتیبِ تشکیل کا ثبوت سمجھیں، نہ کہ اس بات کا ثبوت کہ کوئی کنٹرول رن ٹائم پر کام کرتا ہے۔ جب آپ کو یہ یقین درکار ہو کہ ہُکس، پابندیاں یا دیگر رویے واقعی مؤثر ہیں، تو اختیاری پروبز استعمال کریں۔

خام ترتیبِ تشکیل ظاہر کیے بغیر رپورٹس کا موازنہ کریں

اگر کوئی آپ کو جائزہ شدہ harness.json بھیجے تو اسے دوبارہ بنانے کے لیے رپورٹ کے پیسٹ ایریا کا استعمال کریں۔ اگرچہ حساس اقدار حذف کر دی جاتی ہیں، پھر بھی دونوں فریقوں کو پہلے JSON کا جائزہ لینا چاہیے، کیونکہ پروجیکٹ کے نام، فولڈر کے نام اور پلگ اِن کے نام بدستور موجود رہتے ہیں۔

Python دستیاب نہ ہو تو متبادل طریقہ استعمال کریں

اگر Python 3 دستیاب نہ ہو تو PROMPT.md کا مواد کسی ایجنٹ میں کاپی کریں۔ ایجنٹ ترتیبِ تشکیل کو براہِ راست پڑھ سکتا ہے، اسی فارمیٹ میں JSON بنا سکتا ہے اور اسکرین تیار کر سکتا ہے۔ README خبردار کرتا ہے کہ اس طریقے میں اسکرپٹ کے مقابلے میں آئٹمز چھوٹ جانے یا ان کی تعداد غلط شمار ہونے کا امکان زیادہ ہے۔

معلوم حدود

• ہینڈ آف کے قواعد harness-map.py میں موجود SPAWN_RULES میں مقرر ہیں؛ یہ آپ کے لائیو سیشنز کا مشاہدہ کر کے اخذ نہیں کیے جاتے۔
• README کے مطابق یہ قواعد 2 اکتوبر 2026 کو جانچی گئی Claude Code 2.1.287 کی دستاویزات کی پیروی کرتے ہیں۔ بعد کے ورژنز میں رویہ مختلف ہو سکتا ہے۔
• حوالہ دیے گئے ذرائع سرکاری sub-agents، agent teams اور memory کی دستاویزات ہیں۔
• پروجیکٹ میں ایک تضاد کی نشاندہی کی گئی ہے: دستاویزات کہتی ہیں کہ سب ایجنٹس خودکار میموری نہیں پڑھتے، جبکہ مصنف کے ماحول میں مبینہ طور پر ایک میموری فہرست سب ایجنٹ کو دی گئی۔ رپورٹ اسے دستاویزات اور مشاہدے کے درمیان فرق کے طور پر نشان زد کرتی ہے۔
• --agents اور --permission-mode جیسی صرف کمانڈ لائن پر مبنی ترتیبات فائلوں میں محفوظ نہیں ہوتیں، اس لیے اسکینر انہیں دریافت نہیں کر سکتا۔
• انسٹال شدہ پلگ اِنز کے لیے اسکینر پلگ اِن کی تنصیب کی ڈائریکٹری میں ملنے والا جدید ترین ورژن پڑھتا ہے۔

نتیجہ

harness-map ان ترتیبات کو سمجھنے کا ایک عملی طریقہ فراہم کرتا ہے جو Claude Code کو مختلف پروجیکٹس اور ایجنٹ لانچ موڈز میں حقیقتاً موصول ہوتی ہیں۔ ہر اہم ورکنگ ڈائریکٹری کو اسکین کر کے آغاز کریں، اختیاری طور پر دستاویزی پروبز چلائیں، ان کے شواہد کے ساتھ ڈیٹا دوبارہ بنائیں اور HTML رپورٹ تیار کریں۔ ترتیبِ تشکیل کے خلا تلاش کرنے کے لیے بصری جائزے اور پختگی کے جائزے کا استعمال کریں، لیکن شیئر کرنے سے پہلے تیار کردہ فائلوں کا جائزہ لیں اور دستاویزی ہینڈ آف قواعد کو ورژن پر منحصر سمجھیں۔