आठ Hooks जो AI Agent की विश्वसनीयता सुनिश्चित करते हैं

CLAUDE.md एक सुझाव है, कोई गारंटी नहीं। अगर आपने लिखा है “commit से पहले Prettier चलाओ,” तो एजेंट हर तीन में से एक बार इसे नज़रअंदाज़ कर देगा। और ज़्यादा precise instructions लिखने से यह समस्या हल नहीं होती। 80% compliance rate कोई model quality की समस्या नहीं है। यह एक structural limitation है, context window के अंदर rules डालकर यह उम्मीद करने की कि model उन्हें follow करेगा।

Hooks एक बिल्कुल अलग plane पर काम करते हैं। ये ऐसे scripts हैं जो specific lifecycle points पर automatically execute होते हैं, model के decision से बिल्कुल बेपरवाह। PreToolUse agent के किसी file को modify करने या command चलाने से ठीक पहले fire होता है। PostToolUse ठीक बाद में। Model यह नहीं चुनता कि इन्हें run करना है या नहीं। ये बस चलते हैं।

व्यावहारिक फ़र्क तुरंत दिखता है। CLAUDE.md में दस लाइनें जोड़ना और .claude/settings.json में एक Hook जोड़ना दोनों बिल्कुल अलग तरह के interventions हैं। Exit code 2 एजेंट की action को पूरी तरह block कर देता है। Exit code 0 उसे pass होने देता है। कोई और exit code warning log करता है लेकिन block नहीं करता। और चूँकि hooks settings.json में रहते हैं, एक बार commit करो और git के ज़रिए पूरी टीम को मिल जाते हैं।

Execution से पहले के चार guards

मैं छह महीने से ज़्यादा समय से hooks चला रहा हूँ। ये चार PreToolUse hooks हर प्रोजेक्ट में बिना हटाए बचे रहे।

Block Dangerous Commands rm -rf, git reset --hard, और DROP TABLE जैसे destructive patterns को regex matching से पकड़ता है, फिर exit code 2 return करके action होने से पहले ही उसे खत्म कर देता है। मैंने खुद देखा है एजेंट को rm -rf ऐसी directories पर try करते हुए जो उसे छूनी नहीं चाहिए थीं। इस hook के बिना नुकसान real होता।

Protect Sensitive Files .env, package-lock.json, *.pem, और ऐसी ही files पर किसी भी modification attempt को block करता है। एजेंट को कभी मौका नहीं मिलता lock file overwrite करने का या credentials को commit में leak करने का।

Require Tests Before PR pull request creation को passing tests पर gate करता है। Matcher को mcp__github__create_pull_request पर set करो और एजेंट literally PR open नहीं कर सकता जब तक tests pass न हों। “Tests बाद में fix कर दूँगा” वाली बात खत्म।

Log Every Command एजेंट द्वारा run की गई हर bash command को timestamps के साथ .claude/command-log.txt में लिखता है। तीन दिन बाद, जब कुछ गलत दिखे, आप exactly trace कर सकते हो कि क्या हुआ था।

Execution के बाद के तीन inspectors

PostToolUse hooks एजेंट के file modify करने के तुरंत बाद चलते हैं। मैं इन तीनों को sequence में chain करता हूँ।

Auto-Format हर changed file पर Prettier चलाता है। Python projects के लिए Black swap करो। Go के लिए gofmt। Formatter चलता है चाहे एजेंट format करना याद रखे या न रखे।

Auto-Lint formatting के ठीक बाद ESLint run करता है। अगर ESLint errors मिलती हैं, एजेंट उन्हें उसी turn में देख लेता है और fix करता है। Human code review तक पहुँचने वाले lint issues की संख्या लगभग शून्य हो जाती है।

Auto-Test हर file change के बाद relevant test suite चलाता है। जब test fail होता है, एजेंट को seconds में पता चल जाता है और वह fix attempt करता है। Output को tail -5 से pipe करके सिर्फ summary रखता हूँ, जिससे test output context window में flood नहीं करता।

क्रम मायने रखता है। पहले Prettier, फिर ESLint, फिर tests। जब तक कोई human code देखे, formatting और lint पहले ही pass हो चुके होते हैं। Code review में style comments गायब हो जाते हैं।

एजेंट के रुकने पर काम को preserve करना

एक Stop hook यह संभालता है: Auto-Commit हर बार git add -A && git commit run करता है जब एजेंट एक response finish करता है। काम की हर unit का अपना commit होता है। दो tasks कभी एक commit में नहीं मिलते।

इसे git worktrees के साथ combine करो और feature branches पर automatic per-branch commits मिलते हैं। एजेंट crash हो जाए या आप interrupt करो, काम का आखिरी chunk कभी नहीं खोता।

जो चीज़ें cleanly काम नहीं आईं

Hook chaining elegant लगती है, लेकिन failing chain को debug करना किसी single script को debug करने से कहीं ज़्यादा मुश्किल है। जब auto-test hook एक नए प्रोजेक्ट में silently fail होने लगा क्योंकि test runner install नहीं था, तो मैंने एक घंटा trace करने में बिताया कि एजेंट untested code क्यों produce कर रहा था। Hook exit code 0 return कर रहा था क्योंकि test script ही नहीं मिल रही थी, और shell “command not found” को non-blocking condition की तरह treat कर रहा था। मुझे test runner की existence के लिए explicit check जोड़नी पड़ी invoke करने से पहले।

Performance दूसरी constraint है। आम धारणा यह है कि बहुत सारे hooks सब कुछ slow कर देते हैं, लेकिन यह पूरी तरह सही नहीं है। असली सवाल यह है कि क्या हर individual hook 200 milliseconds से कम में finish होता है। Single file पर Prettier run लगभग 50ms लेता है। ESLint check लगभग 80ms। Tests vary करते हैं, लेकिन affected files तक scope रखने से ज़्यादातर runs fast रहते हैं। अगर कोई एक hook एक second से ज़्यादा लेता है, तो एजेंट का feedback loop sluggish लगने लगता है।

यह एक बड़े pattern से connect होता है

OpenAI के Harness Engineering blog ने एक बात कही थी कि agents rigid boundaries और predictable structure के अंदर सबसे अच्छा काम करते हैं। React का design philosophy components के बारे में यही कहता है: composable units with defined lifecycle phases and state।

Claude Code में Hooks उसी abstraction को follow करते हैं। State sessions और memory से correspond करता है। Hooks वे functions हैं जो lifecycle boundaries पर intervene करते हैं। PreToolUse boundaries set करता है। PostToolUse structure को predictable बनाता है। Stop result को preserve करता है।

“Prettier run करो” वाली लाइन जो CLAUDE.md में रखता था, अब वहाँ नहीं है। Hook उसे हर बार चलाता है, बिना कहे।