Claude Code hooks: முகவரின் விதிகளை உத்தரவாதங்களாக மாற்றுவது எப்படி

Claude Code hooks என்றால் என்ன

Hook என்பது மாதிரி அல்ல, Claude Code நிரலே குறிப்பிட்ட தருணத்தில் இயக்கும் கட்டளை. முகவர் rm -rf இயக்கப் போகிறது — hook இயங்கி கட்டளையை அனுமதிப்பதா என்று முடிவு செய்கிறது. முகவர் ஒரு கோப்பைத் திருத்தியது — hook formatter-ஐ இயக்குகிறது. முகவர் வேலையை முடிக்க நினைக்கிறது — hook சோதனைகளை இயக்கி, அவை சிவப்பாக இருக்கும் வரை நிற்க விடுவதில்லை.

CLAUDE.md-இன் அறிவுறுத்தலுக்கும் இதற்கும் உள்ள முக்கிய வேறுபாடு: அறிவுறுத்தல் ஒரு உரை, மாதிரி அதை ஒரு நிகழ்தகவுடன் மட்டுமே கருத்தில் கொள்கிறது; hook ஒரு நிர்ணயமான குறியீடு. Context எவ்வளவு நீளமாக இருந்தாலும், முகவர் என்ன «முடிவு செய்தாலும்», அமர்வின் நூறாவது நிமிடத்தில் விதியை மறந்தாலும் அது எப்போதும் இயங்கும். அதனால் claude code hooks விருப்பத்தை உத்தரவாதமாக மாற்றுவதற்கான முதன்மை வழி.

CLAUDE.md-இல் உள்ள விதிகள் ஏன் போதாது

வழக்கமான காட்சி: முகவர் ஒரு அம்சத்தை முடித்தது, unit சோதனைகள் பச்சையாக உள்ளன, அரட்டையில் நம்பிக்கையான «முடிந்தது». ஆனால் end-to-end சூழ்நிலை யாரும் இயக்கவில்லை, linter ஓடவில்லை, migration நடுவில் தோல்வியடைந்தது. CLAUDE.md-இல் «முடிப்பதற்கு முன் சோதனைகளை இயக்கு» என்று எழுதப்பட்டிருந்தாலும். மாதிரி வேண்டுமென்றே ஏமாற்றுவதில்லை — அது தன்னையே மதிப்பிடுகிறது, அந்த சுய மதிப்பீடு நம்பகமற்றது.

இதிலிருந்து harness-இன் கொள்கை வருகிறது: இயந்திரத்தால் சரிபார்க்கக்கூடிய அனைத்தையும் இயந்திரமே சரிபார்க்கிறது, மாதிரி அல்ல. «linter-ஐ இயக்கு» என்ற விதி linter-ஐ இயக்கும் hook ஆகிறது. «prod கட்டமைப்பைத் தொடாதே» என்ற விதி அந்தக் கோப்பில் எழுதுவதைத் தடுக்கும் hook ஆகிறது. உரை அறிவுறுத்தல் இருக்கும், ஆனால் முகவர் ஏன் நிறுத்தப்பட்டது என்பதை விளக்குவதற்கு மட்டுமே.

நிகழ்வுகள்: hooks எப்போது இயங்குகின்றன

ஒவ்வொரு hook அமர்வின் வாழ்நாள் நிகழ்வுடன் இணைக்கப்பட்டுள்ளது. முக்கிய நிகழ்வுகள்:

நம்பகத்தன்மைக்கு மிகவும் பயனுள்ளவை — PreToolUse, PostToolUse மற்றும் Stop: அவை முகவரின் மூன்று பலவீன இடங்களை மூடுகின்றன — ஆபத்தான செயல்கள், சரிபார்க்கப்படாத திருத்தங்கள், முன்கூட்டிய «முடிந்தது».

hooks எங்கே அமைக்கப்படுகின்றன: settings.json

Hooks Claude Code அமைப்புக் கோப்புகளில் விவரிக்கப்படுகின்றன:

• ~/.claude/settings.json — உங்கள் தனிப்பட்ட, எல்லா திட்டங்களுக்கும்;
• களஞ்சியத்தில் .claude/settings.json — குழுவுக்குப் பொதுவானது, git-இல் commit ஆகிறது;
• .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 என்பது கருவியின் பெயர் அல்லது அதன் மேல் ஒரு regular expression: Bash, Edit|Write, .*. கருவிகள் தொடர்பான நிகழ்வுகளுக்கு இது தேவை; Stop அல்லது UserPromptSubmit-க்கு குறிப்பிடத் தேவையில்லை. CLAUDE_PROJECT_DIR மாறி திட்டத்தின் வேர் அடைவைக் காட்டுகிறது, எனவே ஸ்கிரிப்டுகளை .claude/hooks/-இல் வைத்து அதன் வழியாக அழைப்பது வசதி. தற்போதைய hooks-ஐ Claude Code-க்குள் /hooks கட்டளையால் பார்க்கலாம்.

hook தரவைப் பெறுவது மற்றும் பதிலளிப்பது எப்படி

உள்ளீடு: stdin-இல் JSON

Claude Code hook-க்கு நிகழ்வின் தகவல்களை 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-இல் «பிழை» என்று மட்டும் எழுதாமல், தெளிவான காரணத்தையும் அதற்குப் பதிலாக என்ன செய்ய வேண்டும் என்பதையும் எழுதுங்கள்.

திரும்பும் குறியீட்டைத் தவிர, hook stdout-இல் "decision": "block" மற்றும் "reason" கொண்ட JSON-ஐயும் வெளியிடலாம். இது நுணுக்கமான அமைப்புக்குப் பயன்படும், ஆனால் பெரும்பாலான பணிகளுக்கு code 2 மற்றும் stderr செய்தி போதுமானது.

எடுத்துக்காட்டு 1: திருத்தம் ஒவ்வொன்றுக்குப் பின்னும் linter மற்றும் சோதனைகள்

Edit|Write matcher உடன் PostToolUse-இல் உள்ள hook கோப்பு மாற்றப்பட்ட பின் இயங்குகிறது. கருவி ஏற்கனவே இயங்கிவிட்டது, திருத்தத்தை ரத்து செய்ய முடியாது, ஆனால் code 2 linter-இன் வெளியீட்டை முகவருக்குத் திருப்பி அனுப்பும், அதனால் பிழையை அரை மணி நேரம் கழித்து அல்ல, உடனே சரி செய்யும்.

#!/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 "Linter $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

இங்கே பத்து நிமிட முழு சோதனை ஓட்டத்தை வைக்காதீர்கள்: hook ஒவ்வொரு திருத்தத்திலும் இயங்கும். திருத்தத்துக்குப் பின் விரைவுச் சோதனைகள் (தொடரியல், linter, ஒரு தொகுதியின் சோதனைகள்) — கனமானவை Stop hook-இல்.

எடுத்துக்காட்டு 2: ஆபத்தான கட்டளைகளைத் தடுத்தல்

Bash matcher உடன் PreToolUse-இல் உள்ள hook கட்டளையை இயங்குவதற்கு முன்பே பார்க்கிறது. Code 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-இல் உள்ள hook file_path-ஐச் சரிபார்த்து .env, prod கட்டமைப்புகள், உருவாக்கப்பட்ட குறியீடு அல்லது ஏற்கனவே பயன்படுத்தப்பட்ட migration கோப்புகளில் எழுதுவதைத் தடுக்கிறது. ஒன்றை கவனியுங்கள்: regular expression தேடலை சுற்றி வரலாம் — முகவர் கட்டளையை வேறு வழியில் எழுதலாம். Hook ஒரு வலுவான பாதுகாப்புத் தடுப்பு, ஆனால் அணுகல் அனுமதிகளுக்கும் sandbox-க்கும் மாற்று அல்ல.

எடுத்துக்காட்டு 3: சோதனைகள் சிவப்பாக இருக்கும்போது முகவர் «முடிந்தது» என்று சொல்ல முடியாது

Stop hook முகவர் முடிக்கப் போகும்போது இயங்குகிறது. சோதனைகள் தேறவில்லை என்றால் code 2 நிற்க விடாது, சோதனையின் வெளியீடு அடுத்த பணியாக முகவருக்குச் செல்லும். இது Definition of Done-இன் இயந்திர வடிவம்.

#!/usr/bin/env bash
# .claude/hooks/done.sh
input=$(cat)
# முடிவற்ற சுழற்சியிலிருந்து பாதுகாப்பு: hook ஏற்கனவே ஒரு முறை வேலையை நீட்டித்துள்ளது
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 hook காரணமாக வேலையைத் தொடர்ந்தால். இந்தச் சோதனை இல்லாவிட்டால் hook முகவரை முடிவில்லாமல் சுற்ற வைக்கலாம் — «இரவு முழுவதும் தவறான திசையில் உழைக்கும் முகவர்» என்ற நிலை. தன்னாட்சி சுழற்சிகளில் கூடுதலாக முயற்சி வரம்பையும், மனிதனை அழைக்கும் நிபந்தனையையும் சேர்க்கவும்.

எடுத்துக்காட்டு 4: அமர்வின் தொடக்கத்தில் நிலையை ஏற்றுதல்

SessionStart-இல் hook-இன் stdout context-இல் செல்கிறது. தற்போதைய கிளை, commit ஆகாத மாற்றங்கள், திட்டத்திலிருந்து அடுத்த பணி ஆகியவற்றை வெளியிடுவது வசதி; அப்போது முகவர் பூஜ்ஜியத்திலிருந்து தொடங்காது.

#!/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

Hooks விதிகளை உத்தரவாதங்களாக மாற்றுவது எப்படி

Harness-இன் விதிகளை மூன்று அடுக்குகளாகப் பிரிப்பது பயனுள்ளது. முதலாவது — CLAUDE.md-இல் உள்ள உரை: வேலை செய்யும் முறையை விளக்குகிறது, ஆனால் நிகழ்தகவுடன் மட்டுமே கடைப்பிடிக்கப்படுகிறது. இரண்டாவது — இயக்கக்கூடிய சரிபார்ப்புகள்: சோதனைகள், E2E, கட்டமைப்பு விதிகள் ஸ்கிரிப்டாக, மீறினால் தோல்வியடையும். மூன்றாவது — hooks, இவை சரியான தருணத்தில் இந்தச் சரிபார்ப்புகளை மாதிரியின் பங்கு இல்லாமல் தானாக இயக்குகின்றன.

நடைமுறை விதி: முகவர் ஒரே விதியை இரண்டு முறை மீறினால், CLAUDE.md-இல் இன்னொரு பெரிய எழுத்து எச்சரிக்கையைச் சேர்க்காதீர்கள். அந்த மீறலை ஸ்கிரிப்ட் மூலம் சரிபார்க்க முடியுமா என்று கேளுங்கள். முடிந்தால் ஸ்கிரிப்டை எழுதி அதை hook-இல் பொருத்துங்கள். அப்போது உரை அறிவுறுத்தல் சுருங்கும், நடத்தை நிலையாகும்.

அடிக்கடி நிகழும் தவறுகள்

• 2-க்குப் பதிலாக 1. ஸ்கிரிப்ட் code 1-உடன் தோல்வியடைகிறது, முகவர் எதையும் அறியாது, செயல் நடந்துவிடும். தடுப்பது code 2 மட்டுமே.
• stdout-இல் செய்தி. Code 2-இல் முகவருக்குச் செல்வது stderr. >&2 மூலம் எழுதுங்கள்.
• அடிக்கடி நிகழும் நிகழ்வில் மெதுவான hook. PostToolUse-இல் முழு சோதனை ஓட்டம் ஒவ்வொரு திருத்தத்தையும் ஒரு நிமிட வேலையாக்கும். கனமானவை Stop-இல்.
• முடிவில்லாத Stop. stop_hook_active சரிபார்ப்போ வரம்போ இல்லாவிட்டால் முகவர் முடிவில்லாமல் சுற்றும்.
• உறவினர் பாதைகள். Hook அமர்வின் வேலை அடைவில் இயங்குகிறது; $CLAUDE_PROJECT_DIR-ஐப் பயன்படுத்துங்கள்.
• சரிபார்க்கப்படாத வெளி hook. Hook உங்கள் அனுமதிகளுடன் உறுதிப்படுத்தல் இல்லாமல் இயங்குகிறது. வேறொருவர் களஞ்சியத்தின் ஸ்கிரிப்டுகளை நம்புவதற்கு முன் படியுங்கள்.

முடிவு

Claude Code hooks மிக முக்கியமான விதிகளை உரையிலிருந்து குறியீட்டுக்கு நகர்த்துகின்றன: PreToolUse ஆபத்தான செயல்களை நிறுத்துகிறது, PostToolUse ஒவ்வொரு திருத்தத்தையும் சரிபார்க்கிறது, Stop நேரத்துக்கு முன் «தயார்» என்று அறிவிக்க விடுவதில்லை, SessionStart முகவருக்குத் திட்டத்தின் நினைவைத் திருப்பித் தருகிறது. முகவர் ஏற்கனவே மீறிய விதிகளுக்காக இரண்டு-மூன்று hooks-உடன் தொடங்குங்கள், stderr செய்திகளை தெளிவாக வையுங்கள் — அப்போது முகவர் தன் பிழைகளைத் தானே சரி செய்யும், நீங்கள் செயல்முறையை அல்ல, முடிவைச் சரிபார்ப்பீர்கள். சரிபார்ப்பு, தயார்நிலை மற்றும் தன்னாட்சி சுழற்சிகள் பாடநெறியில் நடைமுறையில் விளக்கப்படுகின்றன.