환경변수 템플릿 도입으로 신규 팀원 온보딩 간소화

환경 설정 템플릿을 버전 관리에 포함시켰다. 작업 자체는 30분도 안 걸렸는데, 이게 신규 팀원 온보딩에 미치는 영향이 생각보다 크다는 걸 다시 한번 체감했다.

왜 `.env.example`이 필요한가

프로젝트를 처음 받았을 때 가장 답답한 순간이 뭐냐면, 어떤 환경 변수를 설정해야 하는지 알 수 없다는 거다. .env 파일은 보안상 git에 커밋하면 안 되니까 .gitignore에 등재하는 게 표준이다. 그런데 정작 어떤 키를 설정해야 하고, 어떤 형태여야 하고, 선택 옵션인지 필수인지는 문서화되지 않으면 추측의 영역이 된다.

흔하게 벌어지는 시나리오가 있다. 신입 개발자가 저장소 클론하고, 로컬 서버 띄우려고 하면 바로 에러. 스택트레이스 뒤져보면 DATABASE_URL 같은 변수 누락. 그 변수가 어디서 왔는지, 형식이 postgres://...인지 mysql://...인지 모름. 결국 옆 사람한테 물어보고, 그 사람이 본인 .env 열어서 키 목록 불러줌. 이게 팀 규모 작을 때는 그냥 넘어가지만, 사람 늘어날수록 반복 비용이 쌓인다.

.env.example은 이 문제를 깔끔하게 해결한다. 실제 값 없이 어떤 환경 변수가 필요한지, 어떤 형태인지만 예시로 남겨두는 방식이다.

# .env.example 예시
# 데이터베이스 연결 (필수)
DATABASE_URL=postgres://user:password@localhost:5432/mydb

# 인증 (필수)
JWT_SECRET=your-secret-key-here

# 외부 API (선택 — 없으면 알림 기능 비활성화)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# 개발 환경 설정
NODE_ENV=development
PORT=3000

주석으로 필수/선택 여부까지 명시해두면 더 좋다. "선택 — 없으면 알림 기능 비활성화" 같은 한 줄이 나중에 삽질을 꽤 줄여준다.

구조 정리

파일	역할	git 추적
`.env`	실제 민감한 값이 들어가는 파일	X
`.env.example`	필요한 환경 변수 키와 형식을 정의한 템플릿	O
`.gitignore`	`.env`를 버전 관리에서 제외하도록 설정	O

.gitignore에 .env를 명시하는 건 기본 중의 기본인데, 여기서 한 가지 자주 놓치는 게 있다. .env.local, .env.development.local, .env.production.local 같은 파생 파일들도 함께 처리해야 한다는 점이다. Next.js 같은 프레임워크는 이런 파일들을 계층적으로 로드하는 구조라, .env 하나만 ignore해놓고 나머지를 빠뜨리면 의도치 않게 API 키가 올라가는 경우가 생긴다.

# .gitignore
.env
.env.local
.env.*.local

이 정도는 처음부터 잡아두는 게 낫다.

온보딩 경험 개선

이제 새로운 개발자가 저장소를 클론하면, README에서 ".env.example을 참고해서 .env를 만들어줄 것" 정도만 안내하면 충분하다.

cp .env.example .env
# .env 열어서 실제 값 채우기
# 민감한 값(DB 패스워드, API 키 등)은 팀 내 비밀번호 관리 도구에서 가져올 것

여기서 cp 한 줄이 중요한 이유가 하나 더 있다. .env.example이 변경됐을 때 추적이 가능해진다는 점이다. 새 환경 변수를 추가하거나 기존 키 이름을 바꿨을 때, git diff로 바로 확인되고 PR 리뷰에도 포함된다. "아, 이번 배포에 REDIS_URL 추가됐네" 하고 팀 전체가 인지할 수 있는 채널이 생기는 거다. 문서 따로 업데이트 안 해도 된다.

이 흐름은 여러 장점이 있다:

명확성: 어떤 변수가 필요한지 한눈에 파악 가능
보안: 실제 값은 리포지토리에 기록되지 않음
일관성: 모든 팀원이 동일한 환경 변수 구조를 유지
변경 추적: .env.example이 수정되면 git diff로 추가/변경된 설정을 리뷰할 수 있음

트레이드오프도 있긴 하다. .env.example을 계속 최신 상태로 유지해야 한다는 관리 부담이다. 새 변수 추가할 때 코드에만 반영하고 .env.example 업데이트를 빠뜨리면, 결국 똑같이 신규 팀원이 막히는 상황이 반복된다. 이걸 강제하려면 CI에서 .env.example과 실제 사용 중인 환경 변수 목록을 비교하는 린트 스텝을 붙이는 방법도 있다. 팀 규모에 따라 오버엔지니어링일 수 있지만, 사람이 많아지면 한번 고려할 만하다.

회고

이런 "사소한 문서화"가 실은 가장 실용적이라는 걸 매번 느낀다. 화려한 아키텍처 문서보다, 실제로 개발자가 마주하는 첫 번째 순간에 필요한 정보가 딱 있는 게 훨씬 중요하다. 온보딩 첫날 셋업 때 막혀서 한 시간 씩이면, 그게 열 명이면 열 시간이다. 별거 아닌 것 같아도 쌓이는 비용이 크다.

특히 이 패턴은 대부분의 Node/Python/Go 프로젝트에서 사실상 표준이 되어 있다. 신입이 다른 오픈소스 프로젝트나 이전 직장에서 봤을 가능성이 높기 때문에, 별도 설명 없이도 편하게 적응할 수 있다는 것도 장점이다.

다음부터는 프로젝트를 시작할 때 가장 먼저 .env.example을 만드는 걸 체크리스트 1번에 넣을 생각이다. 나중에 빠진 거 채우러 돌아오는 것보다, 처음부터 있으면 관리가 훨씬 수월하다.