Claude Code के साथ Husky + lint-staged सेटअप: व्यावहारिक pre-commit गाइड

Claude Code एक ही सत्र में कई फाइलें बदल सकता है। यह refactor, tests और configuration के लिए उपयोगी है, लेकिन review में शोर भी बढ़ाता है। reviewer को business logic, API design और risk पर ध्यान देना चाहिए, न कि unused import, टूटी formatting या Markdown spacing पर।

Husky + lint-staged इस समस्या का व्यावहारिक समाधान है। Git hook वह छोटा script है जिसे Git किसी खास समय पर चलाता है, जैसे commit बनने से ठीक पहले। Husky इन hooks को repository में manage करने देता है, ताकि पूरी team वही नियम इस्तेमाल करे। lint-staged केवल उन files पर command चलाता है जिन्हें git add किया गया है। Claude Code hooks अलग feature हैं; वे Claude Code के lifecycle में चलते हैं। वे मदद कर सकते हैं, लेकिन हर commit को बचाने के लिए Git hook और CI ही भरोसेमंद base हैं।

इस guide का लक्ष्य local CI बनाना नहीं है। pre-commit को हल्का रखें, pre-push में project-level checks रखें, और CI को final gate रहने दें।

पूरा workflow

सबसे टिकाऊ design यह है: pre-commit में fast file-level checks, pre-push में typecheck/tests/build, और CI में full validation। इससे quality भी रहती है और लोग --no-verify का नियमित उपयोग नहीं करने लगते।

flowchart LR
  A["Claude Code files बदलता है"] --> B["developer git add से scope चुनता है"]
  B --> C["Husky pre-commit"]
  C --> D["lint-staged"]
  D --> E["ESLint / Prettier"]
  E --> F["commit"]
  C --> G["typecheck, tests, build pre-push या CI में"]

मैंने commands को current रखने के लिए Husky Get started, lint-staged README, Git hooks manual और Claude Code hooks reference देखे। आज Husky setup के लिए npx husky init recommended path है, और lint-staged को pre-commit hook के साथ file pattern configuration चाहिए।

न्यूनतम working setup

अगर project में ESLint या Prettier अभी stable नहीं हैं, तो पहले Claude Code ESLint guide और Prettier guide ठीक करें। Husky सिर्फ command चलाता है; actual quality उन commands से आती है।

Claude Code को यह prompt दें:

इस Node.js/TypeScript repository में Husky और lint-staged जोड़ें।
pre-commit केवल staged JS, TS, JSON, Markdown और CSS files पर चले।
pre-commit में ESLint auto-fix और Prettier चलाएं।
typecheck, tests और build को pre-commit में न रखें; उन्हें pre-push या CI में रखें।
अंत में manual verification commands भी लिखें।

Manual setup:

npm install --save-dev husky lint-staged eslint prettier
npx husky init

npx husky init .husky/pre-commit बनाता है और package.json में prepare script update करता है। generated hook को इस content से बदलें:

#!/usr/bin/env sh
npx lint-staged

फिर package.json में यह configuration जोड़ें। अगर scripts पहले से हैं, तो merge करें, overwrite नहीं।

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint --fix .",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix --max-warnings=0",
      "prettier --write"
    ],
    "*.{json,md,mdx,yml,yaml,css,scss}": [
      "prettier --write"
    ]
  }
}

एक खराब formatting वाली file stage करके test करें:

git add src/example.ts
npx lint-staged --debug
git commit -m "chore: verify pre-commit checks"

--debug बताता है कि कौनसी config पढ़ी गई, कौनसी files match हुईं और कौनसे commands चले। hook fail होने पर यही output Claude Code को दें।

maintainable lint-staged config

छोटे project में package.json ठीक है, लेकिन बड़े project में lint-staged.config.mjs बेहतर रहता है। इससे config readable रहती है और helper function लिखा जा सकता है। नीचे वाला example spaces वाले file paths को quote करता है।

// lint-staged.config.mjs
const shellQuote = (file) => `"${file.replaceAll('"', '\\"')}"`;
const joinFiles = (files) => files.map(shellQuote).join(" ");

export default {
  "*.{js,jsx,ts,tsx}": (files) => [
    `eslint --fix --max-warnings=0 ${joinFiles(files)}`,
    `prettier --write ${joinFiles(files)}`,
  ],
  "*.{json,md,mdx,yml,yaml,css,scss}": (files) =>
    `prettier --write ${joinFiles(files)}`,
};

यह file बनाने के बाद package.json से lint-staged key हटा दें। दो जगह config रहेगी तो team और Claude Code दोनों confuse होंगे।

तीन उपयोगी use cases

पहला use case TypeScript product app है। Claude Code अक्सर component, test और utility को साथ में बदलता है। ESLint auto-fix और Prettier review से पहले noise कम करते हैं। पूरा tsc --noEmit pre-commit में रखने से commit धीमा हो सकता है, इसलिए उसे pre-push या CI में रखें।

दूसरा use case Astro या Next.js content site है। MDX, JSON metadata, CSS और TypeScript एक साथ बदलते हैं। lint-staged article diff को साफ रखता है, ताकि reviewer content पढ़े, whitespace नहीं।

तीसरा use case monorepo है। सभी packages के tests pre-commit में चलाना अक्सर गलत निर्णय है। staged files पर formatting और lint चलाएं, फिर CI या task runner modified paths के हिसाब से package tests चुने।

commit-msg और pre-push अलग रखें

Commit message rule के लिए अलग commit-msg hook बेहतर है। Conventional Commits के लिए commitlint use करें।

npm install --save-dev @commitlint/cli @commitlint/config-conventional

// commitlint.config.mjs
export default {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "subject-max-length": [2, "always", 72],
  },
};

#!/usr/bin/env sh
npx --no -- commitlint --edit "$1"

इसे .husky/commit-msg में रखें। Heavy checks के लिए .husky/pre-push:

#!/usr/bin/env sh
npm run validate

validate script CI जैसा हो सकता है:

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "test:ci": "vitest run --coverage",
    "build": "vite build",
    "validate": "npm run typecheck && npm run lint && npm run format:check && npm run test:ci && npm run build"
  }
}

आम गलतियां

सबसे बड़ी गलती pre-commit को बहुत heavy बनाना है। अगर हर commit में दो मिनट लगेंगे, लोग hook bypass करेंगे। कुछ seconds का hook ही habit बनता है।

दूसरी गलती partial staging को न समझना है। lint-staged staged files पर काम करता है, लेकिन उसी file में unstaged changes भी हो सकते हैं। debug के लिए git status --short, git diff --staged और npx lint-staged --debug साथ देखें।

Windows, macOS और Linux वाली team में line endings भी ध्यान दें। Husky hooks shell scripts हैं, इसलिए LF safest रहता है।

* text=auto eol=lf
*.cmd text eol=crlf
*.bat text eol=crlf

|| true जैसी fix न अपनाएं। इससे failure छिपता है और quality gate बेकार हो जाता है। बेहतर है error छोटा करें, slow task को pre-push में ले जाएं, या fix command document करें।

मैंने क्या verify किया

मैंने यह setup एक छोटे TypeScript/Vite project में लगाया। जानबूझकर bad formatting, unused import और MDX spacing issue डाले। pre-commit fast रहा क्योंकि केवल staged files process हुईं। npx lint-staged --debug से target files साफ दिखीं। type errors को pre-commit में नहीं रखा; वे pre-push के npm run validate में पकड़े गए। इससे commit rhythm खराब नहीं हुआ और final safety भी बनी रही।

निष्कर्ष

Husky + lint-staged Claude Code workflow के लिए practical safety rail है। pre-commit को हल्का रखें, heavy checks को pre-push या CI में रखें, और Claude Code prompts में यह rule साफ लिखें। फिर hook एक बाधा नहीं, बल्कि team का shared quality baseline बनता है।

अगला कदम है ESLint guide से rules मजबूत करना और Prettier guide से formatting standard बनाना।