[Tooling] "따옴표 하나로 Git 충돌이?" ESLint와 Prettier로 협업 스트레스 날려버린 후기

팀 프로젝트에 처음 합류했을 때, 가장 저를 당황스럽게 만들었던 건 로직 에러가 아닌 'Git Merge 충돌(Conflict)'이었습니다. 분명히 저는 로그인 로직 코드 한 줄만 고쳤는데, PR(Pull Request)을 올려보니 파일 전체에 빨간 줄이 그어지며 충돌이 난 것이죠.

원인을 찾아보니 제 에디터는 파일 저장 시 작은따옴표(')로 자동 변환하고 있었고, 동료 개발자의 에디터는 큰따옴표(")와 세미콜론을 강제로 붙이고 있었습니다. 코드 리뷰 시간에 로직을 검토하기도 전에 "여기 들여쓰기 탭 간격 고쳐주세요", "따옴표 통일해 주세요" 같은 스타일 지적 주고받기로 수십 분을 허비하곤 했습니다.

이 소모적인 논쟁을 원천 차단하고 "저장(Ctrl+S) 버튼만 누르면 알아서 코드 스타일에 대한 약속을 지켜주는 환경"을 구축했던 경험을 정리해 봅니다.

1. ESLint와 Prettier: 파수꾼과 재단사 역할 분담하기

처음엔 ESLint 하나만 설치하면 포맷팅까지 다 되는 줄 알고 썼다가, 두 도구의 규칙이 서로 싸우면서 에러를 뿜어내는 현상을 겪었습니다. 이 둘은 역할이 엄연히 다릅니다.

• ESLint (Linter): 코드의 논리적 질(Quality)을 감시합니다.
  • "선언해 두고 안 쓰는 변수가 있어요!", "리액트 훅의 규칙을 어겼어요!" 같은 버그 유발 가능성을 경고합니다.
• Prettier (Formatter): 코드의 시각적 스타일(Style)을 재단합니다.
  • 줄 바꿈, 들여쓰기 2칸, 마지막 콤마(Trailing Comma) 등 외형을 통일해 줍니다.

2. 두 도구 충돌 없이 한 번에 세팅하기 (실무 설정)

제가 프로젝트에서 가장 안정적으로 사용 중인 패키지 조합입니다. 핵심은 eslint-config-prettier를 넣어서 Prettier가 담당하는 스타일 규칙에 ESLint가 태클 걸지 않도록 충돌을 끄는 것입니다.

 

💡 패키지 설치

npm install -D eslint prettier eslint-config-prettier eslint-plugin-react eslint-plugin-react-hooks @typescript-eslint/eslint-plugin @typescript-eslint/parser

 

💡 .eslintrc.json 설정 (리액트+타입스크립트 프로젝트)

{
  "parser": "@typescript-eslint/parser",
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react-hooks/recommended",
    "prettier" // ⭐ 반드시 가장 마지막에 넣어 스타일 규칙 충돌을 막아줍니다!
  ],
  "rules": {
    "no-unused-vars": "warn",
    "react/prop-types": "off",
    "react/react-in-jsx-scope": "off"
  }
}

3. "저장만 하면 알아서 고쳐지게": 팀 공통 VS Code 설정

팀원마다 각자 VS Code 플러그인 설정이 달라서 규칙이 깨지는 것을 막기 위해, 프로젝트 루트 디렉토리에 .vscode/settings.json 파일을 만들어서 Git에 공유했습니다.

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

이 설정을 공유하고 난 뒤, 팀원 모두가 Ctrl + S (저장)를 누르는 순간 자동으로 ESLint 규칙에 맞게 코드가 정돈되기 시작했습니다. 포맷팅 때문에 리뷰 코멘트를 남길 일이 100% 사라졌죠!

4. Git Hooks(Husky)로 '규칙 어긴 코드' 커밋 원천 봉쇄하기

설정을 공유해도 간혹 VS Code 확장 프로그램이 꺼져있거나, CLI에서 그대로 커밋을 올려서 엉망인 코드가 메인 브랜치로 들어오는 경우가 있었습니다. 이를 방지하기 위해 Husky와 lint-staged를 도입했습니다.

git commit 명령어를 내리는 순간, Husky가 작동하여 스테이징된(Staged) 파일들만 린트 검사를 돌립니다. 만약 ESLint 에러를 통과하지 못하면 아예 Git 커밋 자체가 거부되도록 강제했습니다.

5. 글을 마치며

ESLint와 Prettier를 제대로 세팅하는 데 들어간 시간은 불과 20~30분이었습니다. 하지만 이 초반 세팅 덕분에 저희 팀은 수개월 간의 프로젝트 기간 동안 단 한 번도 코드 스타일로 인한 Git 충돌이나 코드 리뷰 소모전을 겪지 않았습니다.

좋은 아키텍처와 협업의 시작은 거창한 시스템이 아니라, "팀원 모두가 일관된 정갈한 코드를 유지하는 시스템"을 만드는 데에 있습니다. 혼자 코딩하든 팀으로 코딩하든, 프로젝트 시작 시점에 이 두 도구를 세팅하는 습관을 들이시는 걸 강력히 추천합니다!