Claude Code hooks: এজেন্টের নিয়মকে কীভাবে গ্যারান্টিতে পরিণত করবেন

Claude Code-এর হুক কী

হুক হলো একটি কমান্ড, যা মডেল নয়, বরং Claude Code প্রোগ্রাম নিজে এজেন্টের কাজের একটি নির্দিষ্ট মুহূর্তে চালায়। এজেন্ট rm -rf চালাতে যাচ্ছে — হুক চালু হয়ে ঠিক করে কমান্ডটি যেতে দেবে কি না। এজেন্ট একটি ফাইল সম্পাদনা করেছে — হুক ফরম্যাটার চালায়। এজেন্ট কাজ শেষ করতে চায় — হুক টেস্ট চালায় এবং টেস্ট লাল থাকলে থামতে দেয় না।

CLAUDE.md-এর নির্দেশনা থেকে এর মূল পার্থক্য: নির্দেশনা হলো লেখা, যা মডেল কিছু সম্ভাবনা নিয়ে বিবেচনা করে; আর হুক হলো নির্ধারিত কোড। সে সবসময় চলে, কনটেক্সট কতটা দীর্ঘ, এজেন্ট কী «ঠিক করেছে» বা সেশনের একশ মিনিটে নিয়মটি ভুলে গেছে কি না — তাতে কিছু যায় আসে না। তাই claude code hooks ইচ্ছাকে গ্যারান্টিতে পরিণত করার প্রধান উপায়।

কেন শুধু CLAUDE.md-এর নিয়ম যথেষ্ট নয়

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

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

ইভেন্ট: হুক কখন চলে

প্রতিটি হুক সেশনের জীবনচক্রের একটি ইভেন্টের সাথে যুক্ত। প্রধান ইভেন্টগুলো:

নির্ভরযোগ্যতার জন্য সবচেয়ে কার্যকর — PreToolUse, PostToolUse ও Stop: এরা এজেন্টের তিনটি দুর্বল জায়গা ঢেকে দেয় — বিপজ্জনক কাজ, যাচাই না করা সম্পাদনা এবং অকালে «হয়ে গেছে» বলা।

হুক কোথায় সেট হয়: settings.json

হুক Claude Code-এর সেটিংস ফাইলে বর্ণনা করা হয়:

• ~/.claude/settings.json — আপনার ব্যক্তিগত, সব প্রকল্পের জন্য;
• রিপোজিটরির .claude/settings.json — দলের জন্য সাধারণ, git-এ কমিট হয়;
• .claude/settings.local.json — প্রকল্পের স্থানীয়, git-এ যায় না।

কাঠামো এমন: ইভেন্ট → matcher-সহ গ্রুপের তালিকা → কমান্ডের তালিকা।

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/lint.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

matcher — টুলের নাম বা তার ওপর নিয়মিত অভিব্যক্তি: Bash, Edit|Write, .*। এটি টুল-সংক্রান্ত ইভেন্টের জন্য দরকার; Stop বা UserPromptSubmit-এর জন্য এটি না লিখলেও চলে। CLAUDE_PROJECT_DIR পরিবেশ পরিবর্তনশীল প্রকল্পের মূল ফোল্ডার দেখায়, তাই স্ক্রিপ্ট .claude/hooks/-এ রেখে একে দিয়ে ডাকা সুবিধাজনক। Claude Code-এর ভেতরে /hooks কমান্ড দিয়ে বর্তমান হুকগুলো দেখা যায়।

হুক ডেটা কীভাবে পায় এবং উত্তর দেয়

ইনপুট: stdin-এ JSON

Claude Code হুককে ইভেন্ট সম্পর্কে তথ্যসহ JSON পাঠায়: সেশনের আইডি, কাজের ফোল্ডার, ইভেন্টের নাম, আর টুলের ক্ষেত্রে tool_name ও tool_input। Bash-এর ক্ষেত্রে tool_input.command-এ কমান্ড থাকে, Edit ও Write-এর ক্ষেত্রে tool_input.file_path-এ ফাইলের পথ। jq দিয়ে পড়া সুবিধাজনক।

{
  "session_id": "abc123",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "rm -rf build/" },
  "cwd": "/home/dev/project"
}

আউটপুট: রিটার্ন কোড

Exit code 2 — মূল প্রক্রিয়া। এজেন্ট stderr-এর লেখা প্রতিক্রিয়া হিসেবে পায় এবং নিজেকে শুধরাতে পারে: কমান্ড আবার লিখতে পারে, টেস্ট ঠিক করতে পারে, ফাইলে হাত না দিতে পারে। তাই stderr-এ «ত্রুটি» নয়, বরং বোধগম্য কারণ এবং বিকল্প কী করতে হবে তা লিখুন।

রিটার্ন কোড ছাড়াও হুক stdout-এ JSON দিতে পারে, যেমন "decision": "block" ও "reason"। এটি সূক্ষ্ম নিয়ন্ত্রণের জন্য, তবে বেশিরভাগ কাজে কোড 2 ও stderr-ই যথেষ্ট।

উদাহরণ ১: সম্পাদনার পর লিন্টার ও টেস্ট

Edit|Write matcher-সহ PostToolUse হুক ফাইল বদলের পরে চলে। টুল আগেই চলে গেছে, সম্পাদনা ফেরানো যায় না, কিন্তু কোড 2 এজেন্টকে লিন্টারের আউটপুট ফেরত দেয়, এবং সে ত্রুটিটি আধঘণ্টা পরে নয়, সঙ্গে সঙ্গে ঠিক করে।

#!/usr/bin/env bash
# .claude/hooks/lint.sh
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.py)
    if ! out=$(ruff check "$file" 2>&1); then
      echo "লিন্টার $file-এ ত্রুটি পেয়েছে:" >&2
      echo "$out" >&2
      exit 2
    fi ;;
  *.php)
    if ! out=$(php -l "$file" 2>&1); then
      echo "$out" >&2
      exit 2
    fi ;;
esac
exit 0

এখানে পুরো টেস্ট স্যুট দশ মিনিট ধরে চালাবেন না: হুক প্রতিটি সম্পাদনায় চলে। সম্পাদনার পরে দ্রুত যাচাই (সিনট্যাক্স, লিন্টার, একটি মডিউলের টেস্ট) চালান, আর ভারী পরীক্ষা রাখুন Stop হুকে।

উদাহরণ ২: বিপজ্জনক কমান্ড নিষেধ

Bash matcher-সহ PreToolUse হুক কমান্ড চালানোর আগেই তা দেখে। কোড 2 কলটি বাতিল করে, এবং এজেন্ট কারণ জানতে পায়।

#!/usr/bin/env bash
# .claude/hooks/guard.sh
cmd=$(jq -r '.tool_input.command // empty')
if echo "$cmd" | grep -Eq 'rm -rf /|git push (-f|--force)|DROP (TABLE|DATABASE)'; then
  echo "কমান্ডটি প্রকল্পের নীতির কারণে ব্লক হয়েছে: $cmd। বিপজ্জনক কাজ করে মানুষ।" >&2
  exit 2
fi
exit 0

ফাইলও একইভাবে সুরক্ষিত: Edit|Write-এর হুক file_path যাচাই করে এবং .env, প্রোডাকশন কনফিগ, তৈরি করা কোড বা ইতিমধ্যে প্রয়োগ হওয়া মাইগ্রেশন ফাইলে লেখা আটকায়। মনে রাখবেন, নিয়মিত অভিব্যক্তির ফাঁক আছে — এজেন্ট কমান্ডটি অন্যভাবে লিখতে পারে। হুক শক্তিশালী নিরাপত্তা-জাল, কিন্তু অ্যাক্সেস অধিকার ও স্যান্ডবক্সের বিকল্প নয়।

উদাহরণ ৩: এজেন্ট «হয়ে গেছে» বলতে পারবে না, যতক্ষণ টেস্ট লাল

Stop হুক তখন চলে, যখন এজেন্ট কাজ শেষ করতে যায়। টেস্ট ব্যর্থ হলে কোড 2 তাকে থামতে দেয় না, এবং টেস্টের আউটপুট তার পরের কাজ হয়ে যায়। এটি Definition of Done-এর যান্ত্রিক রূপ।

#!/usr/bin/env bash
# .claude/hooks/done.sh
input=$(cat)
# অন্তহীন চক্র ঠেকানো: হুক একবার কাজ আগেই বাড়িয়েছে
if [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi
if ! out=$(npm test --silent 2>&1); then
  echo "টেস্ট পাস করেনি, কাজ এখনো শেষ হয়নি:" >&2
  echo "$out" | tail -n 40 >&2
  exit 2
fi
exit 0

ক্ষেত্র stop_hook_active true হয়, যদি এজেন্ট stop-হুকের কারণে আগেই কাজ চালিয়ে যাচ্ছে। এই পরীক্ষা ছাড়া হুক এজেন্টকে অন্তহীন চক্রে ঘোরাতে পারে — ঠিক সেই পরিস্থিতি, যখন এজেন্ট «সারা রাত ভুল দিকে কাজ করে»। স্বয়ংক্রিয় চক্রে আরও একটি চেষ্টার সীমা এবং এমন শর্ত যোগ করুন, যেখানে মানুষকে ডাকা হয়।

উদাহরণ ৪: সেশনের শুরুতে অবস্থা লোড করা

SessionStart-এ হুকের stdout কনটেক্সটে যায়। বর্তমান শাখা, অকমিট পরিবর্তন এবং পরিকল্পনা থেকে পরের কাজ দেখানো সুবিধাজনক, যাতে এজেন্ট শূন্য থেকে শুরু না করে।

#!/usr/bin/env bash
echo "শাখা: $(git branch --show-current)"
git status --short | head -n 20
[ -f PROGRESS.md ] && tail -n 15 PROGRESS.md
exit 0

কীভাবে হুক নিয়মকে গ্যারান্টিতে পরিণত করে

হারনেসের নিয়মগুলোকে তিন স্তরে ভাগ করা সুবিধাজনক। প্রথমটি CLAUDE.md-এর লেখা: কীভাবে কাজ করতে হবে তা বোঝায়, কিন্তু সম্ভাব্যতার ভিত্তিতে মানা হয়। দ্বিতীয়টি চালানো যায় এমন যাচাই: টেস্ট, E2E, স্থাপত্যের নিয়ম একটি স্ক্রিপ্ট হিসেবে, যা লঙ্ঘনে ব্যর্থ হয়। তৃতীয়টি হুক, যা সঠিক মুহূর্তে এই যাচাইগুলো মডেলের অংশগ্রহণ ছাড়া স্বয়ংক্রিয়ভাবে চালায়।

ব্যবহারিক নিয়ম: এজেন্ট যদি একই নিয়ম দুবার ভেঙে থাকে, CLAUDE.md-এ আরেকটি বড় হাতের সতর্কবার্তা যোগ করবেন না। জিজ্ঞেস করুন, লঙ্ঘনটি কি স্ক্রিপ্ট দিয়ে যাচাই করা যায়? যদি যায়, স্ক্রিপ্ট বানিয়ে হুকে ঝুলিয়ে দিন। তখন টেক্সটের নির্দেশনা ছোট হয় এবং আচরণ স্থিতিশীল হয়।

সাধারণ ভুল

• কোড 1 ব্যবহার করা কোড 2-এর বদলে। স্ক্রিপ্ট কোড 1-এ ব্যর্থ হয়, এজেন্ট কিছু জানে না, এবং কাজ এগিয়ে যায়। শুধু কোড 2 আটকায়।
• stdout-এ বার্তা। কোড 2-এ এজেন্ট পায় stderr। >&2 দিয়ে লিখুন।
• ঘন ঘন চলা ধীর হুক। PostToolUse-এ পুরো টেস্ট চালালে প্রতিটি সম্পাদনা এক মিনিটের হয়ে যায়। ভারী কাজ রাখুন Stop-এ।
• অন্তহীন Stop। stop_hook_active পরীক্ষা বা সীমা না থাকলে এজেন্ট অন্তহীন ঘোরে।
• আপেক্ষিক পথ। হুক সেশনের কাজের ফোল্ডারে চলে; $CLAUDE_PROJECT_DIR ব্যবহার করুন।
• যাচাই না করা অন্যের হুক। হুক আপনার অধিকারে, নিশ্চিতকরণ ছাড়াই চলে। অন্য রিপোজিটরির স্ক্রিপ্ট বিশ্বাস করার আগে পড়ে নিন।

সারসংক্ষেপ

Claude Code-এর হুক সবচেয়ে গুরুত্বপূর্ণ নিয়মগুলোকে টেক্সট থেকে কোডে নিয়ে যায়: PreToolUse বিপজ্জনক কাজ থামায়, PostToolUse প্রতিটি সম্পাদনা যাচাই করে, Stop এজেন্টকে অকালে প্রস্তুতির রিপোর্ট দিতে দেয় না, এবং SessionStart এজেন্টকে প্রকল্প সম্পর্কে স্মৃতি ফিরিয়ে দেয়। শুরু করুন দুই-তিনটি হুক দিয়ে, সেই নিয়মগুলোর জন্য যেগুলো এজেন্ট ইতিমধ্যে ভেঙেছে, এবং stderr-এর বার্তা বোধগম্য রাখুন — তাহলে এজেন্ট নিজেই ভুল শোধরায়, আর আপনি প্রক্রিয়া নয়, ফলাফল যাচাই করেন। যাচাই, প্রস্তুতির পরীক্ষা ও স্বয়ংক্রিয় চক্র হাতে-কলমে harness engineering কোর্সে আলোচিত হয়।