린팅·환경 설정으로 개발 시작 지점 마련
목차
새 프로젝트를 시작하는 첫 커밋은 대개 무심하게 넘어간다. 보일러플레이트를 깔고, 린팅 설정을 넣고, README 작성하고 — 별 거 아닌 일처럼 보인다. 하지만 초기 빌드(initial build)는 앞으로 6개월, 1년 동안의 개발 경험을 좌우하는 기초다. 이번에는 그 경험을 글로 남겨본다.
초기 세팅이 언제 빛나는가
프로젝트가 시작될 때 가장 먼저 다뤄야 할 것들은 "팀"이다. 개발자 한두 명이면 몰라도, 팀이 늘어나는 순간 각자의 코딩 습관과 선호도가 충돌한다. A 개발자는 들여쓰기를 2칸 선호하고, B 개발자는 4칸을 선호할 수 있다. C 개발자는 세미콜론을 붙이고, D 개발자는 뺀다. 이런 차이들이 커밋에 스며들면, 나중에 코드 리뷰 때 진짜 로직 변화와 스타일 변화를 분간하기 어려워진다.
린팅과 포매팅 설정이 필요한 이유가 여기 있다. "우리 팀은 이렇게 쓰기로 했다"는 규칙을 사전에 정해두면, 누군가의 에디터 설정과 무관하게 일관된 코드가 들어온다. 초기 세팅 단계에서 이 결정을 미루면, 5개월 뒤 "아, 좀 더 엄격한 규칙이 필요하네"라고 깨달았을 때 기존 코드 전체를 손봐야 한다. 그 비용은 생각보다 크다.
초기 빌드의 구성 요소
이번 커밋에서 다룬 파일들을 나열해보면:
| 파일 | 역할 | 팀 관점에서의 의미 |
|---|---|---|
eslint.config.mjs |
코드 스타일·품질 규칙 강제 | 팀 코딩 표준 통일 |
.env.example |
환경 변수 템플릿 | 신규 개발자 온보딩 시작점 |
.gitignore |
Git 추적 제외 목록 | 의도치 않은 커밋(비번, 키, 빌드 산출물) 방지 |
README.md |
프로젝트 개요·시작 가이드 | 팀 신입, 외부인을 위한 첫 문서 |
next.config.ts |
Next.js 빌드·런타임 설정 | 프레임워크 기본 동작 정의 |
next-env.d.ts |
TypeScript 타입 선언 | 타입 안전성 기초 구축 |
한 줄로 요약하면, 이 파일들은 "어떻게 개발할 것인가", "어떻게 배포할 것인가", "누가 와도 빠르게 시작할 수 있는가"를 정의한다.
신규 개발자 온보딩의 차이
초기 빌드를 철저하게 다지는 이유 중 하나는 팀 확장을 전제하기 때문이다. 신입 개발자가 입사했을 때를 생각해보자. 리포를 클론받고 npm install 한 뒤, 바로 기능 개발을 시작해야 한다. 하지만 .env.example이 없다면?
"어? 이 .env 파일은 뭔데? 왜 파일이 없지? 어떤 값을 넣어야 할까?" 하고 우왕좌왕한다. README에 ".env에 다음 변수들을 설정하세요"라고 써 놨는데도, 어떤 값을 넣어야 할지 헷갈린다. 이런 마찰은 사소해 보이지만, 온보딩 시간을 30분에서 2시간으로 늘린다.
반대로 .env.example이 있고, README에 명확한 지시가 있으면?
# .env 설정
1. .env.example 을 복사해 .env 를 만듭니다
2. 개발 환경에 맞게 다음 항목을 수정합니다
- DATABASE_URL: 로컬 개발 DB 연결 주소
- API_SECRET: 로컬 테스트용 키
이렇게 쓰면 30초 안에 해결된다. 이것이 초기 세팅의 가치다 — 개발팀의 진입 장벽을 낮추는 것.
린팅 설정과 코드 리뷰의 질
ESLint를 초기에 제대로 다지면, 코드 리뷰의 초점이 달라진다. 린팅이 없으면 리뷰어가 "세미콜론이 빠졌네", "들여쓰기가 이상한데?", "import 순서가 정렬되지 않았네" 같은 스타일 지적을 한다. 하지만 린팅이 있으면 이런 것들은 커밋 전에 자동으로 잡힌다. 리뷰어는 진짜 중요한 것에만 집중할 수 있다 — 로직의 정확성, 성능, 보안, 아키텍처.
특히 팀이 성장하면서 여러 리뷰어가 리뷰를 나누게 될 때, 린팅 규칙이 없으면 각 리뷰어마다 지적 기준이 달라진다. 어떤 리뷰어는 엄격하고, 어떤 리뷰어는 느슨하다. "이 팀은 정말 코딩 스타일이 일관성 없네"라는 인상을 팀 외부에 남기고 싶지 않다면, 초기 세팅 단계에서 규칙을 정해야 한다.
회고: 초기 결정의 장기 영향
초기 빌드를 제대로 하는 것의 중요성을 가장 절실하게 느끼는 순간은, 그걸 나중에 고치려고 할 때다. 6개월 뒤 "아, 린팅 규칙을 더 엄격하게 해야겠다"고 깨달아서 규칙을 추가하면, 기존 코드들 중 일부가 린팅에 걸린다. 그걸 일일이 손 봐야 한다. 500개의 파일 중 50개를 손 봐야 할 수도 있다. 리뷰이도, 반영이도 힘들다.
비슷하게 .env.example을 처음부터 차근차근 관리하지 않으면, 6개월 뒤 "어? 이 환경 변수는 뭐였더라?"라고 헷갈린다. 혹은 신입이 물어올 때 "음, 그 당시에 뭐였는지 기억 안 나네"라고 답해주지 못한다. 이런 일들이 누적되면 팀의 신뢰도가 깎인다.
따라서 초기 세팅은 미래를 위한 투자다. 지금의 2시간이 3개월 뒤 팀 전체의 5시간을 아낀다. 기술 리더로서 프로젝트를 시작할 때는 항상 이 관점으로 초기 빌드를 점검하려고 한다 — 1년 뒤에도 "좋은 결정이었다"고 팀이 느낄 수 있게.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.