AI এজেন্টের পর্যবেক্ষণযোগ্যতা: এজেন্ট কী করেছে তা কীভাবে বুঝবেন এবং কী লগ করবেন

AI এজেন্টের পর্যবেক্ষণযোগ্যতা কী

AI এজেন্টের পর্যবেক্ষণযোগ্যতা হলো আর্টিফ্যাক্ট দেখে — স্মৃতি বা এজেন্টের কথার উপর নির্ভর না করে — তিনটি প্রশ্নের উত্তর দেওয়ার ক্ষমতা: সে কী করেছে, কেন ঠিক এভাবে করেছে এবং কীসে প্রমাণ হয় যে ফলাফল সঠিক। বিশ মিনিট কাজের পর এজেন্ট যদি বলে «হয়ে গেছে, তবে দুটি টেস্ট ফেল করছে, সম্ভবত টাইমিংয়ের কারণে», আর প্রশ্ন করা হলে কোন পথগুলো প্রভাবিত হয়েছে তা বলতে না পারে, «কোড দেখান» বলে — তাহলে পর্যবেক্ষণযোগ্যতা নেই। এজেন্ট বোকা নয়: তার কাছে দেখানোর মতো কিছু নেই।

সমস্যাটি ব্যবস্থাগত। একই এজেন্ট এক সপ্তাহে দশবার সৎভাবে «হয়ে গেছে» বলতে পারে, আর প্রতিবার তার অর্থ আলাদা হবে: কোথাও সব টেস্ট চালানো হয়েছে, কোথাও শুধু একটি, কোথাও কিছুই না। প্রকল্প যত দীর্ঘ চলে, প্রতিটি পরের সেশন তত দামি হয়, কারণ তা খোঁড়াখুঁড়ি দিয়ে শুরু হয়।

দুটি স্তর: রানটাইম ও প্রক্রিয়া

পর্যবেক্ষণযোগ্যতাকে লগের সাথে গুলিয়ে ফেলা হয়, কিন্তু লগ শুধু অর্ধেক।

শুধু রানটাইম: দেখা যায় কী ভাঙল, কিন্তু বোঝা যায় না কী চাওয়া হয়েছিল। শুধু প্রক্রিয়া: বোঝা যায় কী চাওয়া হয়েছিল, কিন্তু দেখা যায় না কেন সফল হয়নি। দুটিই দরকার।

এজেন্ট নিজে কেন এটি করতে পারে না

এজেন্টকে বলা «আরও ভালো লগ করো» কাজ করে না, তিনটি কারণে।

• সে জানে না কী জানে না। যে সংকেতের গুরুত্ব সে আঁচ করতে পারে না, তা সে লগ করবে না।
• ফরম্যাট ওঠানামা করে। এক সেশনে সে বিস্তারিত লেখে, অন্যটিতে এক লাইনে। সেশনের তুলনা করা বা সমষ্টি গণনা করা অসম্ভব হয়।
• প্রক্রিয়া লগ দিয়ে বন্ধ করা যায় না। «কেন এভাবে» প্রশ্নের উত্তর আছে কাজের আগে তৈরি নথিতে, কমান্ডের আউটপুটে নয়।

তাই পর্যবেক্ষণযোগ্যতা বসানো হয় হারনেসে — এজেন্টের পরিবেশে: টেমপ্লেট, হুক, স্ক্রিপ্ট, বাধ্যতামূলক রিপোর্টের ফরম্যাট।

কী লগ করবেন: ন্যূনতম সেট

ভালো জার্নাল সবকিছুর স্টেনোগ্রাফি নয়, বরং এমন তথ্যের সেট, যা দিয়ে কাজের ধারা পুনর্গঠন করা যায় এবং পরিসংখ্যান গণনা করা যায়।

• শনাক্তকারী: সেশনের আইডি, কাজ বা ফিচারের আইডি, এজেন্টের মডেল।
• পার্শ্বপ্রতিক্রিয়াসহ কর্ম: কোন কমান্ড চালানো হয়েছে, কোন ফাইল বদলেছে। ফাইল পড়া সাধারণত লেখার দরকার নেই।
• যাচাইয়ের ফলাফল: কোন যাচাই-কমান্ড, রিটার্ন কোড, কতটা টেস্ট পাস ও ফেল।
• পুনরায় চেষ্টা: একটি ধাপে কতবার চেষ্টা লেগেছে এবং চেষ্টাগুলো কীভাবে আলাদা ছিল।
• খরচ: টোকেন ও সময়, যদি টুল তা দেয়।
• ফলাফল: কাজ গৃহীত, প্রত্যাখ্যাত বা পরিত্যক্ত, এবং কেন।

কী লিখবেন না: সিক্রেট, অ্যাক্সেস টোকেন, কমান্ডের আউটপুট থেকে ব্যক্তিগত তথ্য। জার্নাল শেয়ার হতে পারে, অথবা আবার মডেলের কনটেক্সটে ফিরে আসতে পারে।

Claude Code-এর হুক দিয়ে কর্মের জার্নাল

Claude Code-এ জার্নাল রাখা হুকের মাধ্যমে সুবিধাজনক — যে কমান্ড মডেল নয়, টুল নিজে চালায়, তাই তা সবসময় চলে। হুক ইভেন্টের বর্ণনাসহ JSON পায়: সেশনের আইডি, টুলের নাম ও প্যারামিটার। এখানে .claude/settings.json-এর একটি সেটআপ দেওয়া হলো, যা প্রতিটি Bash, Edit বা Write কলের পরে জার্নালে একটি লাইন যোগ করে:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — একটি কর্মের জন্য একটি JSON লাইন
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

JSONL ফরম্যাট (প্রতি লাইনে একটি JSON রেকর্ড) সুবিধাজনক, কারণ এটি jq দিয়ে সহজে ফিল্টার করা যায় এবং যেকোনো বিশ্লেষণ সিস্টেমে লোড করা যায়। এ ছাড়া Claude Code সেশনের সম্পূর্ণ ইতিহাস নিজেও স্থানীয়ভাবে ~/.claude/projects/ ফোল্ডারে রাখে — যুক্তি ও আউটপুট পুরোটা দেখতে চাইলে সেখানে দেখা যায়, কিন্তু পরিসংখ্যানের জন্য নিজের সংক্ষিপ্ত জার্নালই সুবিধাজনক।

ট্রেসিং: প্রতি সেশনে একটি ট্রেস, প্রতি কাজে একটি span

যখন এজেন্ট অনেক থাকে বা সময়সূচিতে চলে, শুধু টেক্সট-জার্নাল যথেষ্ট নয়: সমষ্টি দরকার। এখানে কাজে লাগে বিতরণকৃত ট্রেসিংয়ের সাধারণ টুল এবং OpenTelemetry মান।

• ট্রেস — এজেন্টের একটি সেশন।
• Span — সেশনের ভেতরে একটি কাজ।
• ভেতরের span — যাচাইয়ের ধাপ: বিল্ড, টেস্ট, e2e।

প্রতি span-এ ন্যূনতম অ্যাট্রিবিউট: ফিচারের ও সেশনের আইডি, মডেল, যাচাইয়ের ফলাফল, টোকেন, পুনঃচেষ্টার সংখ্যা। এমন তথ্য Jaeger, Grafana Tempo, Honeycomb-এ পড়া যায় এবং এমন প্রশ্নের উত্তর দেয়, যা এক সেশনে দেখা যায় না: কোন ধরনের কাজে বেশি পুনঃচেষ্টা লাগে, এজেন্ট কোথায় সবচেয়ে বেশি টোকেন খরচ করে, হারনেসের কোন পরিবর্তনের পর গৃহীত কাজের অনুপাত পড়ে গেল। Claude Code-এর মেট্রিক ও ইভেন্ট OpenTelemetry-তে রপ্তানির ব্যবস্থা আছে — তা পরিবেশের ভেরিয়েবল দিয়ে চালু হয়, বিস্তারিত টুলের ডকুমেন্টেশনে।

কমিট হিসেবে জার্নাল

সবচেয়ে সস্তা ও নির্ভরযোগ্য জার্নাল আপনার কাছে আগে থেকেই আছে — git। শুধু তাকে পড়ার উপযোগী করতে হবে।

1. একটি কমিট — একটি কাজ। তাহলে git log করা কাজের তালিকার সাথে মেলে, আর কাজ ফেরাতে লাগে একটি git revert।
2. বার্তায় — কী বদলেছে এবং কীভাবে যাচাই হয়েছে। «fix» নয়, লিখুন «কী বদলানো হলো, কেন, কোন কমান্ড দিয়ে যাচাই হয়েছে»।
3. শুধু সবুজ যাচাইয়ের পরে কমিট। তাহলে ইতিহাসের প্রতিটি বিন্দু একটি কার্যকর অবস্থা, এবং git bisect দোষী খুঁজে পায়।

fix(payments): ছাড়ের রাউন্ডিং পয়সা পর্যন্ত

ছাড় float-এ হিসাব হচ্ছিল, 999.99-এর মতো যোগফলে একটি পয়সা হারিয়ে যেত।
হিসাব পয়সার পূর্ণসংখ্যা (int) এ সরানো হয়েছে।
যাচাই: make test (142 passed), make e2e checkout — ঠিক আছে।
পরিধির বাইরে: রিপোর্টে রাউন্ডিং, BACKLOG.md-তে লেখা হয়েছে।

এজেন্টের রিপোর্ট: অনুভূতির বদলে প্রমাণ

এজেন্টের চূড়ান্ত বার্তাও পর্যবেক্ষণযোগ্যতার আর্টিফ্যাক্ট, যদি তার স্থির রূপ থাকে। AGENTS.md বা CLAUDE.md-এ একটি টেমপ্লেট লিখে রাখুন:

## কাজের শেষের রিপোর্ট
- কী করা হয়েছে: পরিবর্তনের তালিকা (ফাইল — মূল কথা)
- কীভাবে যাচাই হয়েছে: সুনির্দিষ্ট কমান্ড ও তার ফলাফল
- কী যাচাই হয়নি এবং কেন
- কাজের চুক্তি থেকে বিচ্যুতি
- মানুষের কাছে খোলা প্রশ্ন

প্রধান নিয়ম: প্রতিটি দাবি একটি প্রমাণের দিকে নির্দেশ করে — ফাইল ও লাইন, টেস্টের আউটপুট, জার্নালের এন্ট্রি। «ঠিক মনে হচ্ছে» বা «আমার মনে হয় ঠিক আছে» রিপোর্ট হিসেবে গণ্য নয়। «কী যাচাই হয়নি» অনুচ্ছেদটি বিশেষভাবে মূল্যবান, কারণ তা সততার সাথে দেখায় আস্থার সীমা কোথায়।

কাজের আগে চুক্তি, কাজের পরে রুব্রিক

প্রক্রিয়ার স্তর কাজের আগে শুরু হয়। একটি ছোট কাজের চুক্তি (sprint contract) পরিধি, গ্রহণযোগ্যতার মানদণ্ড, «পরিধির বাইরে» অংশ এবং মানুষের সিদ্ধান্তের জন্য খোলা প্রশ্ন ঠিক করে। «পরিধির বাইরে» অংশটি ফলাফল নিয়ে অর্ধেক বিতর্ক আগেই আটকায়।

কাজের পরে ফলাফল মূল্যায়িত হয় রুব্রিক দিয়ে, অনুভূতি দিয়ে নয়। নইলে দুজন অভিজ্ঞ রিভিউয়ার ভিন্ন রায় দেবেন, এবং মূল্যায়ন লটারি হয়ে যাবে।

প্রতিটি মাত্রা A/B/C/D দিয়ে মূল্যায়িত হয়, এবং রেফারেন্সবিহীন মূল্যায়ন অবৈধ। সরল সিদ্ধান্তের নিয়ম: একটি D বা দুটি C — প্রত্যাখ্যান, সঙ্গে কী ঠিক করতে হবে তার তালিকা। একই রুব্রিক একটি আলাদা যাচাইকারী এজেন্টও প্রয়োগ করতে পারে।

এজেন্ট একটি সেশনে কী করেছে তা কীভাবে বিশ্লেষণ করবেন

রিপোর্ট না থাকলে, বা তাতে আস্থা না থাকলে, আর্টিফ্যাক্ট ধরে এই ক্রমে যান।

1. গাছের অবস্থা: git status — কী কমিট হয়নি, কোনো অপ্রয়োজনীয় ফাইল আছে কি না।
2. ইতিহাস: সেশনের শুরু থেকে git log --stat — কোন কমিট ও ফাইল।
3. পরিবর্তনের মাত্রা: git diff --stat main...HEAD, তারপর গুরুত্বপূর্ণ ফাইলের পুরো ডিফ।
4. কর্মের জার্নাল: কোন কমান্ড চালানো হয়েছিল এবং যাচাইগুলো কী ফেরত দিয়েছে।
5. পুনরায় যাচাই: নিজে বিল্ড ও টেস্ট চালান। এজেন্টের বর্ণনার চেয়ে কমান্ডের আউটপুটে বিশ্বাস করুন।

# শেষ সেশনে এজেন্ট কোন কমান্ড চালিয়েছে
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# কোন ফাইল সবচেয়ে বেশি বদলেছে
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

সাধারণ ভুল

• সবকিছু লগ করা। গিগাবাইট স্টেনোগ্রাফি কেউ পড়ে না। পার্শ্বপ্রতিক্রিয়াসহ কর্ম ও যাচাইয়ের ফলাফল লিখুন।
• মুক্ত ফরম্যাট। জার্নালের ফরম্যাট যদি এজেন্ট নিজে ঠিক করে, পরিসংখ্যান মিলবে না। ফরম্যাট ঠিক করে হারনেস।
• আউটপুট ছাড়া রিপোর্টে বিশ্বাস। «টেস্ট সবুজ» কমান্ডের আউটপুট ছাড়া শুধু একটি মত।
• অন্ধ পুনঃচেষ্টা। কারণ না জেনে এজেন্ট এলোমেলো জায়গায় সম্পাদনা করে। আগে লগের লিংকসহ রোগনির্ণয় চান, তারপর সম্পাদনা।
• «পরে পরিষ্কার করব»। ডিবাগ ফাইল ও অকমিট পরিবর্তন পরের সেশনকে বিভ্রান্ত করে: সে অস্থায়ী ও ইচ্ছাকৃত পার্থক্য করতে পারে না।

সারসংক্ষেপ

AI এজেন্টের পর্যবেক্ষণযোগ্যতা গড়ে ওঠে দুটি স্তর দিয়ে: রানটাইম (হুকের মাধ্যমে কর্মের জার্নাল, ট্রেস, যাচাইয়ের বিবরণসহ কমিট) এবং প্রক্রিয়া (কোডের আগে কাজের চুক্তি, রুব্রিক ও প্রমাণসহ রিপোর্ট)। তখন «হয়ে গেছে» প্রতিটি সেশনে একই অর্থ বহন করে, এবং এজেন্টের কাজ বিশ্লেষণে লাগে কয়েক মিনিট। এই বিষয় একটি বাস্তব পেমেন্ট ব্যাকএন্ড প্রকল্পে harness engineering কোর্সে হাতে-কলমে শেখানো হয়।