# [[Husky & lint-staged]]

## 📌 Brief Summary
Husky와 lint-staged는 개발자가 코드를 Git 저장소에 커밋하기 전에 코드의 품질과 스타일을 자동으로 검사하고 수정할 수 있도록 돕는 도구입니다 [1, 2]. Husky는 Git 훅(Git hooks)을 버전 관리 시스템에 포함시켜 팀원 전체가 쉽게 공유하고 관리할 수 있도록 해주는 훅 관리 레이어입니다 [3, 4]. lint-staged는 전체 코드베이스가 아닌 커밋을 위해 스테이징된(staged) 파일에 대해서만 특정 명령어(Linter, Formatter 등)를 실행하도록 오케스트레이션하여 검사 속도와 효율성을 높여줍니다 [3, 4]. 이 두 도구를 결합하여 사용하면 잘못된 코드가 저장소에 병합되는 것을 사전에 방지하고 일관된 코드 퀄리티를 효율적으로 유지할 수 있습니다 [5].

## 📖 Core 소스 Content
*   **명확한 역할 구분:** Husky와 lint-staged는 밀접하게 함께 설정되지만 서로 다른 문제를 해결합니다. Husky는 Git 훅의 배선(wiring)을 담당하는 얇은 레이어로, `core.hooksPath`를 설정하여 훅 스크립트(`.husky/`)를 관리합니다 [4, 6]. 반면 lint-staged는 주로 `pre-commit` 훅 내부에서 실행되는 '스테이징 파일 라우터(staged-file router)'로서, Git에 의해 수정된 파일 집합에만 작업을 실행하도록 오케스트레이션합니다 [4, 7].
*   **Husky를 통한 Git 훅 공유:** Git 훅은 기본적으로 `.git/hooks/` 디렉토리에 저장되어 버전 관리가 되지 않으므로, 새로운 팀원이 자동으로 훅을 공유받을 수 없으며 리포지토리를 다시 클론하면 훅이 사라지는 문제가 있습니다 [3]. Husky는 설정 파일들을 버전 관리 대상에 포함시키고, `package.json`의 `prepare` 스크립트를 통해 `npm install` 시점에 훅 설정이 자동으로 이루어지도록 자동화합니다 [8-10]. 
*   **lint-staged의 최적화 및 자동화:** 중간 규모 이상의 프로젝트에서 매 커밋마다 전체 코드베이스에 대해 ESLint나 Prettier를 실행하면 수십 초가 걸릴 수 있습니다 [3, 11]. lint-staged는 변경되어 커밋 대기 중인 파일에 대해서만 작업을 수행하므로 검사 시간을 1-2초 내외로 단축시킵니다 [3, 11]. 또한 작업이 성공적으로 файлов을 변경(예: 자동 포맷팅)하면, lint-staged가 알아서 해당 변경 사항을 커밋에 다시 스테이징(auto-staging) 처리해 줍니다 [12, 13].
*   **적용 한계와 CI의 필요성:** 이 두 도구는 개발자 환경에서 빠르고 안전하게 문제를 잡아내는 데 특화되어 있으나, 클라이언트 측 Git 훅은 개발자가 `--no-verify` 옵션을 사용하거나 `HUSKY=0` 환경 변수를 설정하는 방식으로 쉽게 우회할 수 있습니다 [14-16]. 따라서 Husky와 lint-staged는 로컬에서의 편의성과 피드백 속도를 높여주는 역할일 뿐이며, 최종적인 코드 품질의 강제와 검증은 반드시 CI(Continuous Integration) 파이프라인에서 이루어져야 합니다 [14, 17-19].

## 🔗 Knowledge Connections
- **Related Topics:** [[Git Hooks]], [[ESLint]], [[Prettier]], [[Continuous Integration (CI)]]
- **Projects/Contexts:** [[Monorepo(Turborepo 등) 환경의 린트 관리]], [[프론트엔드 및 Node.js 개발 워크플로우]]
- **Contradictions/Notes:** 소스에 따르면 lint-staged의 자체적인 기능을 사용할 때 스크립트 명령어 내에서 수동으로 `git add`를 추가해서는 안 됩니다. lint-staged가 충돌(race condition)을 방지하기 위해 파일의 자동 스테이징을 내부적으로 직접 처리하기 때문입니다 [13, 16]. 또한 lint-staged는 파일 필터링 역할을 하므로, `tsc`와 같이 전체 프로젝트 문맥이 필요한 도구를 적용할 때는 단순히 명령어를 추가하는 것이 아니라 파일 인자가 무시되도록 별도의 함수 설정을 사용해야 하는 등 도구의 성격에 맞게 분리 적용할 필요가 있습니다 [16, 20, 21].

---
*Last updated: 2026-04-18*