---
id: P-REINFORCE-AUTO-9068BA
category: "[[10_Wiki/💡 Topics/Programming & Language]]"
confidence_score: 0.90
tags: [auto-reinforced]
last_reinforced: 2026-04-20
github_commit: "[P-Reinforce] Continuous Worker - Husky"
---

# [[Husky]]

## 📌 한 줄 통찰 (The Karpathy Summary)
> Husky는 개발 프로젝트에서 Git 훅(Git hooks)을 쉽게 설정, 관리 및 팀원들과 공유할 수 있도록 지원하는 소프트웨어 도구입니다 [1]. 기본적으로 버전 관리 대상이 아닌 Git 훅의 한계를 극복하여 `.husky/`와 같은 추적 가능한 디렉토리를 통해 훅 스크립트를 관리하게 해줍니다 [1, 2]. 주로 `lint-staged`와 결합하여 커밋이나 푸시 전에 자동으로 코드 린팅(linting) 및 포맷팅을 수행하여 코드 품질을 강제하는 데 사용됩니다 [3, 4].

## 📖 구조화된 지식 (Synthesized Content)
*   **Git 훅의 한계 극복 및 구동 원리:** Git의 기본 훅은 `.git/hooks/` 디렉토리에 저장되어 버전 관리 도구에 의해 추적되지 않습니다. 이로 인해 새로운 팀원이 프로젝트를 클론할 때 훅이 자동으로 설정되지 않는 문제가 발생합니다 [1]. Husky는 Git의 `core.hooksPath` 속성을 사용하여 추적 가능한 디렉토리(예: `.husky/`)에 실제 훅 파일(셸 스크립트)을 생성하고 관리함으로써 이 문제를 해결합니다 [1, 2].
*   **설치 및 자동화 설정:** `npx husky init` (또는 `husky-init`) 명령어를 실행하면 프로젝트 루트에 `.husky` 폴더가 생성되고 `package.json`에 `prepare` 스크립트가 추가됩니다 [5-7]. 이 `prepare` 스크립트는 팀원들이 로컬에서 `npm install`을 실행할 때 Husky 훅이 자동으로 설치되도록 보장하여 모든 팀원이 동일한 검사 환경을 갖추게 합니다 [5-7].
*   **lint-staged와의 결합:** 전체 프로젝트 코드를 매번 검사하는 것은 많은 시간이 소요되므로, Husky의 `pre-commit` 훅 내부에서 `lint-staged`를 호출하는 방식이 현대적인 표준 설정으로 사용됩니다 [1, 8, 9]. 이 조합을 통해 커밋을 위해 스테이징된(staged) 파일에 대해서만 ESLint나 Prettier를 실행함으로써 1~2초 내에 검사를 완료할 수 있습니다 [1, 9].
*   **검사 우회(Bypass) 및 환경 설정:** 개발 과정에서 미완성 코드를 커밋해야 하는 등 훅 실행을 건너뛰어야 할 때는 Git의 기본 기능인 `--no-verify` 플래그(예: `git commit --no-verify`)를 사용할 수 있습니다 [10, 11]. 또한 CI 서버나 프로덕션 환경 등 훅 설치 및 실행이 필요 없는 경우, `HUSKY=0` 환경 변수를 설정하여 Husky를 완전히 비활성화할 수 있습니다 [12].
*   **예외 상황 및 트러블슈팅:** 
    *   **GUI 및 버전 관리자 이슈:** SourceTree나 VS Code 같은 Git GUI 도구나 Node 버전 관리자(nvm, fnm 등)를 사용할 때 `PATH`가 제대로 초기화되지 않아 훅에서 명령어를 찾을 수 없는 오류(`command not found`)가 발생할 수 있습니다. Husky는 각 훅을 실행하기 전에 `~/.config/husky/init.sh`를 소싱(source)하여 이 문제를 우회할 수 있도록 지원합니다 [13, 14].
    *   **서브모듈 및 중첩 패키지:** 모노레포나 서브모듈(Submodules) 구조에서는 최상위 루트가 아닌 하위 디렉토리에 패키지가 위치할 수 있습니다. Git은 기본적으로 리포지토리 루트에서 훅을 실행하므로, 이런 경우 `prepare` 스크립트 내에서 경로를 이동하거나(cd) 서브모듈의 컨텍스트 내에 Husky를 개별적으로 설치하여 동작하도록 구성해야 합니다 [14, 15].

## ⚠️ 모순 및 업데이트 (Contradictions & RL Update)
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
- **정책 변화:** Programming & Language 분야의 자동 자산화 수행.

## 🔗 지식 연결 (Graph)
- **Related Topics:** [[Git Hooks]], [[lint-staged]], [[ESLint]], [[Prettier]]
- **Projects/Contexts:** [[CI/CD Pipeline]], [[Monorepo]], [[Submodules]]
- **Contradictions/Notes:** 소스에 따르면, 많은 개발자가 Husky와 `lint-staged`를 혼동하여 하나의 덩어리로 생각하곤 합니다. 하지만 두 도구는 명확히 구분되어야 합니다. Husky는 단순히 Git의 기본 훅을 관리하고 연결하는 '배선(hook wiring)' 역할을 할 뿐 작업 실행기(task runner)가 아니며, 실제 변경된 파일 단위로 작업을 오케스트레이션 하는 것은 `lint-staged`의 역할입니다 [2, 4, 16].

---
*Last updated: 2026-04-18*
- Raw Source: [[00_Raw/2026-04-20/Husky.md]]
---