[DX 개선] 실수가 많아진다면 그것은 환경 문제이다 - Husky로 코드 품질 지키기

안녕하세요 ! 프론트엔드 개발하는 이효린입니다.

 

오늘은 사내 프로젝트에서 husky 도입하는 과정에서 왜 도입하게 되었고, 어떠한 부분을 기대할 수 있는지에 대해 작성해보겠습니다.

 

과거 취준생 시절 팀 프로젝트를 하던 당시에 다음처럼 CI/CD 파이프라인의 빌드 실패가 빈번하게 발생해 큰 불편을 겪었습니다.

 

주로 개발자마다 커밋 전에 타입 검사, 린트, 포맷 등을 개인 습관에 의존하다 보니, 사소한 코드 오류나 스타일 문제 조차 CI 단계에서 뒤늦게 발견되는 경우가 많았기 때문입니다.

 

이로 인해 다음과 같은 문제들이 발생했습니다.

• 코드 리뷰와 병합을 반복적으로 중단해야 함
• CI 실패 후 원인 파악과 수정으로 팀 생산성 저하
• 작은 실수로 인해 전체 파이프라인 낭비
• 팀 전체 코드 품질과 일관성 관리에 어려움
• 코드리뷰 과정에서 컨벤션에 대한 불필요한 논쟁이 일어남

뿐만 아니라 너무 급한 나머지 develop 브랜치에 밀어넣기, 코딩 스타일 안 따르기 등등… 초반엔 호기롭게 팀 컨벤션 및 규칙을 정했지만, 시간이 지날수록 규칙이 흐지부지되고 각자 개발에만 몰두하게 되면서 결국 팀 전체 개발 흐름에 혼선이 생겼습니다.

 

처음엔 팀원들 개인의 실수라고 생각했지만, 조금 시각을 바꾸어 생각해보니

규칙을 지켜지지 못하게 만드는 환경 자체를 개선해야한다.

 

는 생각이 들었습니다.

 

그 과정에서 자연스럽게 ‘코드 품질을 로컬 단계에서 사전에 강제해야 한다’는 필요성을 느꼈습니다. 특히, 개발자의 실수를 최소화하고 팀 전체 개발 흐름을 안정화할 방법을 고민했습니다.

 

---

 

1. dev 스크립트에 lint와 tsc 스크립트를 함께 실행

처음엔 단순히 pnpm dev처럼 개발 서버를 실행할 때, lint와 tsc 스크립트도 함께 실행하면 어떨까? 라는 생각이 들었습니다. 어차피 dev는 개발할 때 항상 실행하는 명령어니까, 자동으로 코드 검사도 함께 돌리면 실수를 미리 막을 수 있지 않을까 싶었기 때문입니다.

 

실제로 이 방법은 일부분에서는 효과가 있었습니다. 가끔 프론트 서버를 내렸다가 다시 실행하는 과정에서 tsc와 lint 검사가 함께 실행됐기 때문입니다.

 

하지만 이 방식이 근본적인 해결책은 아니었고, 오히려 생산성을 떨어뜨리는 부작용도 있었습니다.

1. 개발 과정에서 dev 스크립트를 재실행하지 않는 이상, 코드 오류를 실시간으로 발견할 수 없음
2. 기능 개발을 우선해야 하는 상황에서도 ts 또는 lint 에러로 인해 개발 흐름이 끊김

결국, 이 방법만으로는 실수를 완전히 막을 수 없고, 개발 속도까지 저해하는 한계가 분명했습니다.

 

 

2. Husky 도입

이러한 한계를 해결하기 위해 Husky를 도입했습니다. Husky를 통해 커밋과 푸시 단계에서 자동으로 타입 검사와 린트가 실행되도록 설정해, 개발자가 의도적으로 검사 명령어를 실행하지 않아도 코드 품질을 강제적으로 관리할 수 있게 만들었습니다.

 

 

pre-commit

git commit 명령어가 실행되기 직전에 동작하는 Git Hook입니다. 아래와 같이 pre-commit 스크립트를 설정했습니다.

#!/bin/sh

# Node 경로 우선 적용 (Mac/Linux)
NODE_PATH=$(command -v node)

if [ -z "$NODE_PATH" ]; then
  echo "❌ Node.js가 설치되어 있지 않습니다. Node.js를 설치하세요."
  exit 1
fi

export PATH=$(dirname "$NODE_PATH"):$PATH

# echo로 Node, pnpm 버전 확인 (디버깅에 도움)
echo "✅ Node 경로: $NODE_PATH"
echo "✅ Node 버전: $(node -v)"
echo "✅ pnpm 버전: $(pnpm -v)"

# 타입 검사
echo "🔍 타입 검사 실행..."
pnpm run type-check
TYPE_CHECK_EXIT_CODE=$?

# lint-staged 실행
echo "🔍 lint-staged 실행..."
npx lint-staged
LINT_EXIT_CODE=$?

# 결과 체크
if [ $TYPE_CHECK_EXIT_CODE -ne 0 ] || [ $LINT_EXIT_CODE -ne 0 ]; then
  echo "❌ 커밋이 중단되었습니다. 타입 오류 또는 린트 오류를 수정하세요."
  exit 1
fi

echo "✅ 타입 검사 및 린트 통과. 커밋을 진행합니다."
exit 0

 

동작 구조는 다음과 같습니다.

1. Node.js 설치 여부를 확인하고
2. pnpm run type-check로 타입 검사를 실행하며
3. npx lint-staged로 변경된 파일에 대해서 린트 및 포맷을 적용

이를 통해 실제로 아래처럼 타입 에러가 있는 상태에서 커밋을 시도하면,

 

이렇게 오류를 출력하며 커밋을 차단합니다. 

 

 

pre-push

git push 직전에 동작하는 Hook으로, 주요 브랜치 보호를 위해 설정했습니다.

 

#!/bin/sh

FORBIDDEN_REFS=("refs/heads/main" "refs/heads/develop")

read -r local_ref local_sha remote_ref remote_sha

for ref in "${FORBIDDEN_REFS[@]}"; do
  if [ "$remote_ref" = "$ref" ]; then
    echo "🚫 DO NOT PUSH to $ref"
    exit 1
  fi
done

exit 0

 

현재는 push 대상 브랜치가 main or develop일 경우 경고 메시지를 출력하고, exit 1로 push를 강제 차단할 수 있습니다.

이렇게 Husky를 통해 코드 품질 검사를 자동화하고, 주요 브랜치를 보호하는 개발 환경을 구축했습니다.

 

 

Husky 도입을 통해 다음과 같은 요소를 기대할 수 있었습니다.

• 타입 에러나 린트 오류를 CI단계 이전에 차단해 실수를 미리 발견
• 코드 리뷰 과정이 쓸데없는 스타일 논쟁 대신 본질적인 로직에 집중
• CI/CD 파이프라인 실패율 감소 및 팀 전체 개발 안정성 향상
• 개발 흐름을 방해하지 않으면서도 규칙이 자연스럽게 습관화

이제 코드 품질을 지키는 일이 개인의 의지가 아닌, 시스템적으로 강제되는 환경을 통해 팀 전체 개발 효율과 안정성을 높일 수 있었습니다.