harness-map দিয়ে আপনার Claude Code হারনেস ম্যাপ ও অডিট করুন

harness-map কী করে

harness-map Claude Code-এর চারপাশের কনফিগারেশন পড়ে সেটিকে একটি একক ভিজ্যুয়াল অ্যাসেম্বলি ম্যাপে রূপান্তর করে। এই পারিপার্শ্বিক কনফিগারেশনকে harness বলা হয়; এতে CLAUDE.md-এর মতো নির্দেশনা ফাইল, স্বয়ংক্রিয় মেমরি, MCP সার্ভার, স্কিল, অনুমতি, হুক, নিয়ম এবং সংশ্লিষ্ট সেটিংস অন্তর্ভুক্ত থাকে।

Claude Code যে ফোল্ডার থেকে শুরু হয় এবং নতুন এজেন্ট যেভাবে চালু করা হয়, তার ভিত্তিতে কার্যকর harness পরিবর্তিত হতে পারে। একটি প্রধান সেশন, fork, subagent, Explore বা Plan এজেন্ট, teammate, অথবা claude -p invocation ভিন্ন তথ্য পেতে পারে। নির্বাচিত প্রতিটি শুরুর ফোল্ডার ও launch পদ্ধতির জন্য harness-map এই পার্থক্যগুলো দৃশ্যমান করে।

প্রকল্পটি Python 3 ব্যবহার করে এবং অতিরিক্ত কোনো Python প্যাকেজের প্রয়োজন হয় না। এর স্ক্রিপ্টগুলো কনফিগারেশন পরিবর্তন না করে পড়ে, একটি কাঠামোবদ্ধ harness.json ফাইল তৈরি করে এবং ব্রাউজারে দেখা যায় এমন harness-map.html রিপোর্ট বানায়।

প্রধান বৈশিষ্ট্য

• ফোল্ডারভিত্তিক বিশ্লেষণ: --cwd পুনরাবৃত্তি করে যতগুলো প্রয়োজন ততগুলো শুরুর ডিরেক্টরি তুলনা করুন।
• এজেন্ট হস্তান্তর ভিজ্যুয়ালাইজেশন: প্রতিটি কম্পোনেন্ট parent session থেকে উত্তরাধিকারসূত্রে এসেছে, ফাইল থেকে আবার পড়া হয়েছে, নাকি নতুন এজেন্টকে দেওয়া হয়নি, তা দেখুন।
• নিয়মের পারস্পরিক ক্রিয়া বিশ্লেষণ: পাঁচটি ব্যবস্থাপনা প্যাটার্ন পরীক্ষা করুন: প্রতিস্থাপন, অস্বীকৃতিকে অগ্রাধিকার দিয়ে একত্র করা, সব নিয়ম চালানো, অগ্রাধিকার ছাড়া সংযোজন, এবং কেবল একটি নিয়ম নির্বাচন।
• ঝুঁকি ও মনোযোগের বিষয়: ফোল্ডারভেদে স্বয়ংক্রিয় মেমরি বিভক্ত হওয়া বা team functionality-এর কারণে permission mode নতুন এজেন্টে চলে যাওয়ার মতো পরিস্থিতি শনাক্ত করুন।
• পরিপক্বতা মূল্যায়ন: একটি ষড়ভুজ চার্টে ছয়টি harness discipline জুড়ে ১ থেকে ৫ পর্যন্ত স্তর পর্যালোচনা করুন।
• গোপনীয়তাসচেতন আউটপুট: নির্দেশনার মূল লেখা, environment variable-এর মান, token, command argument এবং অন্যান্য সংবেদনশীল বিবরণ বাদ দিয়ে কাঠামোগত metadata সংরক্ষণ করুন।
• পোর্টেবল রেন্ডারিং: অন্য কারও harness.json রিপোর্ট ইন্টারফেসে পেস্ট করে তার ম্যাপ আবার আঁকুন।

শুরু করার আগে

আপনার Python 3, Git এবং স্বাভাবিক user account-এর Claude Code কনফিগারেশনে প্রবেশাধিকার থাকা দরকার। pip দিয়ে কোনো প্যাকেজ ইনস্টল করার প্রয়োজন নেই।

Claude Code যে user হিসেবে চালান, সেই একই user হিসেবে harness-map চালান। sudo ব্যবহার করবেন না। Administrator হিসেবে চালালে কার্যকর home directory পরিবর্তিত হতে পারে এবং অন্য user-এর কনফিগারেশন প্রকাশ পেতে পারে, তাই স্ক্রিপ্টটি এভাবে চালানো প্রত্যাখ্যান করে।

যে প্রকৃত ডিরেক্টরিগুলো থেকে আপনি সাধারণত Claude Code শুরু করেন, সেগুলো বেছে নিন। কোনো parent directory স্ক্যান করলে child project-এর ভেতর থেকে শুরু করার সময় প্রযোজ্য সব কনফিগারেশন প্রকাশ পায় না, কারণ প্রতিটি শুরুর ফোল্ডার থেকে কনফিগারেশন উপরের দিকে খোঁজা হয়।

ইনস্টলেশন

রিপোজিটরি clone করে তার ডিরেক্টরিতে প্রবেশ করুন:

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

আপনি github.com/Dominic-DK/harness-map-এ প্রকল্পটি পর্যালোচনা করতে পারেন। প্রকল্পটি MIT License-এর অধীনে বিতরণ করা হয়।

ধাপ ১: আপনার Claude Code harness স্ক্যান করুন

তুলনা করতে চান এমন প্রতিটি workspace-এর জন্য একটি করে --cwd argument দিয়ে harness-map.py চালান। নিচের command-টি দুটি উদাহরণ ফোল্ডার স্ক্যান করে ফলাফল 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

প্রাথমিক স্ক্যান কনফিগারেশন ফাইল পড়ে এবং ওই ফাইলগুলো ও কথোপকথনের ইতিহাসের সমষ্টিগত গণনা থেকে সম্পন্ন করা যায় এমন পরীক্ষা চালায়।

কথোপকথনের ইতিহাসের সময়কাল পরিবর্তন করুন

ডিফল্ট aggregation period হলো ৩০ দিন। ভিন্ন observation window প্রয়োজন হলে --days ব্যবহার করুন। উদাহরণস্বরূপ, এই command-টি ৯০ দিন ব্যবহার করে:

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

কথোপকথন বিশ্লেষণে কেবল event গণনা করা হয়। এটি কথোপকথনের লেখা, command-এর বিষয়বস্তু বা ফাইলের বিষয়বস্তু ফলাফলে কপি করে না।

ধাপ ২: agent probe plan প্রিন্ট করুন

কিছু পরীক্ষায় শুধু স্থির কনফিগারেশন পরিদর্শনের বদলে নিয়ন্ত্রিত পরীক্ষা চালানোর জন্য agent প্রয়োজন। প্রকল্পপ্রদত্ত পদ্ধতি ও নিরাপত্তা নিয়ম প্রিন্ট করুন:

python3 harness-map.py --probe-plan

এজেন্টকে পরীক্ষা চালাতে বলার আগে এই output পড়ুন। probe command নিজের মতো তৈরি না করে তৈরি হওয়া নির্দেশনা অনুসরণ করুন। পরীক্ষায় কনফিগারেশন পড়া, প্রাসঙ্গিক history event গণনা এবং একটি অস্থায়ী ডিরেক্টরির ভেতরে আচরণ পরীক্ষা অন্তর্ভুক্ত থাকতে পারে।

ধাপ ৩: probe সম্পন্ন করুন বা এড়িয়ে যান

এজেন্টকে প্রিন্ট করা probe plan সম্পন্ন করতে বলুন এবং তার পর্যবেক্ষণ probes.json-এ সংরক্ষণ করুন। প্রতিটি probe-এ কী চালানো হয়েছে এবং কী পর্যবেক্ষণ করা হয়েছে, তা সহায়ক প্রমাণ হিসেবে রেকর্ড করা হয়।

এই ধাপটি ঐচ্ছিক। কোনো probe না চালালে সংশ্লিষ্ট item not checked হিসেবে দেখা যাবে এবং level calculation থেকে বাদ পড়বে। প্রকৃতপক্ষে পর্যবেক্ষণ করা হয়নি এমন সফল আচরণ নিজে থেকে দাবি করা এড়িয়ে চলুন, বিশেষ করে level 5 পরীক্ষার ক্ষেত্রে।

ধাপ ৪: probe ফলাফল একত্র করুন

একই শুরুর ফোল্ডারগুলো দিয়ে আবার স্ক্যান চালিয়ে --probes probes.json যোগ করুন:

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

একই --cwd সেট ব্যবহার করলে চূড়ান্ত calculation প্রথম স্ক্যানে অন্তর্ভুক্ত workspace-গুলোর সঙ্গে সামঞ্জস্যপূর্ণ থাকে।

ধাপ ৫: রিপোর্ট তৈরি ও খুলুন

সম্পূর্ণ JSON ফাইল থেকে HTML রিপোর্ট তৈরি করুন:

python3 build.py harness.json

macOS-এ এটি খুলতে ব্যবহার করুন:

open harness-map.html

Linux-এ ব্যবহার করুন:

xdg-open harness-map.html

Windows-এ ব্যবহার করুন:

start harness-map.html

হানেস ম্যাপ পড়া

রিপোর্টে শুরু করার ফোল্ডার এবং লঞ্চ পদ্ধতির মধ্যে পরিবর্তন করে প্রতিটি পরিস্থিতির কার্যকর হানেস দেখতে পারেন। প্রতিটি কম্পোনেন্টের জন্য রিপোর্টটি তিনটি সরবরাহের অবস্থা আলাদা করে দেখায়:

• নতুন এজেন্ট এটি সরাসরি প্যারেন্ট সেশন থেকে পায়।
• নতুন এজেন্ট এটি আবার একটি ফাইল থেকে পড়ে।
• কম্পোনেন্টটি নতুন এজেন্টকে পাঠানো হয় না।

এই তুলনা বোঝাতে সাহায্য করে কেন একই রিপোজিটরি ব্যবহার করা দুই এজেন্ট ভিন্নভাবে আচরণ করতে পারে। উদাহরণস্বরূপ, সাবএজেন্ট মূল সেশনের জন্য উপলব্ধ সবকিছু নাও পেতে পারে, আবার নির্দিষ্ট কোনো শুরু করার ফোল্ডারের সঙ্গে যুক্ত সেটিংস অন্য স্থানে প্রযোজ্য নাও হতে পারে।

পরস্পর-ওভারল্যাপ করা নিয়ম বুঝুন

রিপোর্টটি ওভারল্যাপ করা নিয়ম কীভাবে সমাধান হয় তাও দেখায়। কনফিগারেশনের ধরনের ওপর নির্ভর করে পরবর্তী কোনো মান অন্য মানকে প্রতিস্থাপন করতে পারে, নিষেধাজ্ঞাকে অগ্রাধিকার দিয়ে নিয়মগুলো একত্রিত হতে পারে, মিলে যাওয়া প্রতিটি অ্যাকশন চালু হতে পারে, অগ্রাধিকারের ক্রম ছাড়াই টেক্সট যুক্ত হতে পারে, অথবা শুধু একটি অপশন নির্বাচন করা হতে পারে।

কোনো নির্দেশনা, অনুমতি বা হুক অকার্যকর মনে হলে এসব পারস্পরিক ক্রিয়া পর্যালোচনা করুন। সমস্যাটি কোনো ফাইল অনুপস্থিত থাকার বদলে নিয়ম একত্র করার আচরণেও হতে পারে।

পরিপক্বতা মূল্যায়ন বোঝা

harness-map ছয়টি ক্ষেত্রকে level 1 থেকে level 5 পর্যন্ত স্কোর দেয়:

1. নির্দেশনা নকশা
2. মেমোরি ও অবস্থান
3. টুলের পরিধি
4. প্রতিরোধমূলক ব্লকিং
5. অ্যাকশনের পর যাচাই ও পর্যবেক্ষণযোগ্যতা
6. ডেলিগেশন নকশা

উপলব্ধ ডেটা সমর্থন করলে স্ক্রিপ্টটি স্বয়ংক্রিয়ভাবে level 4 পর্যন্ত হিসাব করতে পারে। ফলাফলে কোন শর্তগুলো পূরণ হয়েছে এবং কোথায় মূল্যায়ন থেমেছে তা নথিভুক্ত থাকে। স্কোরিংয়ের সংজ্ঞাগুলো harness-map.py-এর ভেতরের SCORECARD-এ সংরক্ষিত আছে।

Level 5-এর জন্য বাস্তবে পর্যবেক্ষিত কোনো পরীক্ষার প্রমাণ প্রয়োজন। উদাহরণস্বরূপ, কোনো নিষেধাজ্ঞা সত্যিই একটি কমান্ড থামিয়েছে এমন রেকর্ড থাকলেই প্রতিরোধমূলক ব্লকিং level 5-এ পৌঁছায়। কনফিগারেশনে শুধু নিষেধাজ্ঞা থাকা যথেষ্ট নয়।

কনফিগারেশন থাকলেও সেটি অব্যবহৃত বলে মনে হলে মূল্যায়ন স্কোর কমাতে পারে। যেমন, নির্বাচিত ইতিহাসের সময়কালে কোনো টুল ব্যবহার না করা হলে, অথবা কনফিগার করা অনুমতি মোডের চেয়ে ভিন্ন কোনো অনুমতি মোডে সেশন চললে।

একাধিক শুরু করার ফোল্ডার স্ক্যান করা হলে প্রদর্শিত level হলো ফোল্ডার-ভিত্তিক স্কোরগুলোর মধ্যক। ফোল্ডারের সংখ্যা জোড় হলে নিচের মধ্যবর্তী মান ব্যবহার করা হয়। রিপোর্টটি সর্বনিম্ন থেকে সর্বোচ্চ পরিসরও দেখায়।

উচ্চতর level স্বয়ংক্রিয়ভাবে ভালো নয়। আপনি একা কাজ করেন কি না, কত ঘন ঘন অধস্তন এজেন্ট চালু করেন এবং কত ঘন ঘন ফিরিয়ে আনা কঠিন এমন কমান্ড চালান—এসব ব্যবহার-প্যাটার্নসহ তথ্যের ভিত্তিতে harness-map প্রতিটি ক্ষেত্রের প্রয়োজনীয় level অনুমান করে। level 5-এর নিচের প্রতিটি স্কোর সম্পর্কে সতর্ক করার বদলে, এটি আনুমানিক প্রয়োজনের নিচে থাকা ক্ষেত্রগুলোকে চিহ্নিত করে।

গোপনীয়তা ও আউটপুট পর্যালোচনা

স্ক্যানার ফাইল পড়ে, কিন্তু কনফিগারেশন পরিবর্তন করে না। আউটপুটে কী কপি করা হবে তা এটি ইচ্ছাকৃতভাবে সীমিত রাখে:

• CLAUDE.md এবং নিয়মের ফাইলের ক্ষেত্রে এটি পথ, লাইনের সংখ্যা এবং কখন সেগুলো পড়া হয়েছে তা নথিভুক্ত করে, কিন্তু তাদের টেক্সট নথিভুক্ত করে না।
• সেটিংসের ক্ষেত্রে এটি অনুমতি মোড, নিয়মের সংখ্যা এবং পরিবেশ ভেরিয়েবলের নাম নথিভুক্ত করে, কিন্তু পরিবেশ ভেরিয়েবলের মান বা নিয়মের বিষয়বস্তু নথিভুক্ত করে না।
• হুকের ক্ষেত্রে এটি ইভেন্ট, উৎস এবং এক্সিকিউটেবল ফাইলের নাম নথিভুক্ত করে, কিন্তু কমান্ডের আর্গুমেন্ট ও পথ বাদ দেয়।
• MCP সার্ভারের ক্ষেত্রে এটি নাম ও উৎস নথিভুক্ত করে, কিন্তু কমান্ড, আর্গুমেন্ট, হেডার এবং টোকেন বাদ দেয়।
• পথের ক্ষেত্রে এটি প্রকৃত হোম-ডিরেক্টরির প্রিফিক্সকে ~ দিয়ে প্রতিস্থাপন করে।

যেসব ফাইল পড়া যায় না, সেগুলো unreadable তালিকায় রাখা হয়। প্রকল্পের তথ্য অনুযায়ী, একই ব্যবহারকারীর অনুমতি নিয়ে Claude Code-ও এসব ফাইল পড়তে পারে না।

তবুও আউটপুটে ফোল্ডারের নাম এবং ইনস্টল করা প্লাগইনগুলোর তালিকা থাকে। শেয়ার করার আগে harness.json এবং harness-map.html দুটিই খুলে পর্যালোচনা করুন।

রিপোজিটরির .gitignore কনফিগার করা আছে যাতে harness.json এবং harness-map.html সংস্করণ নিয়ন্ত্রণের বাইরে থাকে, তবে কমিট করার আগে স্টেজ করা ফাইলগুলো যাচাই করা উচিত।

ওয়ার্কফ্লোটি একটি কোডিং এজেন্টকে অর্পণ করুন

রিপোজিটরির নির্দেশনা অনুসরণ করতে Claude Code বা অন্য কোনো কোডিং এজেন্টকে বলতে পারেন। উদাহরণের ফোল্ডারগুলোর বদলে আপনার নিয়মিত ব্যবহৃত শুরু করার ডিরেক্টরিগুলো দিন। উপযুক্ত অনুরোধ হতে পারে:

https://github.com/Dominic-DK/harness-map ঠিকানার README পড়ুন এবং সরাসরি এক্সিকিউশনের ধাপগুলো অনুসরণ করুন।
আমার নিয়মিত শুরু করার ফোল্ডার হলো ~/work/a এবং ~/work/b।
নথিভুক্ত নিরাপত্তা নিয়ম অনুযায়ী step 3 agent checks সম্পন্ন করুন এবং ফলাফল নথিভুক্ত করুন।
শেষ হলে ব্রাউজারে harness-map.html খুলে প্রায় পাঁচটি পরিষ্কার বাক্যে ফলাফল সংক্ষেপ করুন।

প্রোব ধাপের ওপর মানুষের নজরদারি বজায় রাখুন। এজেন্টের --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-এর মতো শুধু কমান্ড-লাইনে ব্যবহৃত সেটিংস ফাইলে সংরক্ষিত থাকে না, তাই স্ক্যানার সেগুলো শনাক্ত করতে পারে না।
• ইনস্টল করা প্লাগইনের ক্ষেত্রে, প্লাগইন ইনস্টলেশন ডিরেক্টরিতে পাওয়া সর্বশেষ সংস্করণটি স্ক্যানার পড়ে।

উপসংহার

প্রকল্প ও এজেন্ট চালুর বিভিন্ন মোডে Claude Code প্রকৃতপক্ষে যে কনফিগারেশন পায়, তা বোঝার একটি কার্যকর উপায় হলো harness-map। প্রথমে প্রতিটি গুরুত্বপূর্ণ কার্যকরী ডিরেক্টরি স্ক্যান করুন, প্রয়োজনে নথিভুক্ত প্রোব চালান, সেগুলোর প্রমাণসহ ডেটা পুনর্গঠন করুন এবং HTML প্রতিবেদন তৈরি করুন। কনফিগারেশনের ঘাটতি খুঁজে পেতে ভিজ্যুয়ালাইজেশন ও পরিপক্বতা মূল্যায়ন ব্যবহার করুন, তবে শেয়ার করার আগে তৈরি করা ফাইলগুলো পর্যালোচনা করুন এবং নথিভুক্ত হ্যান্ডঅফের নিয়মগুলো সংস্করণনির্ভর হিসেবে বিবেচনা করুন।