서브도메인 신규 서비스, 스캐폴딩으로 팀 협업 기반 구축

새로운 서브도메인 서비스 프로젝트를 시작할 때, 가장 먼저 해야 할 일은 코드를 짜는 게 아니라 팀이 협업할 '뼈대'를 만드는 것이다. 이번에 진행한 프로젝트 스캐폴딩 작업이 정확히 그것이었다.

스캐폴딩으로 세팅한 것들

변경 파일들을 보면 이 단계에서 준비한 기초 구조가 명확했다:

이 정도 준비는 "너무 꼼꼼하다"고 느껴질 수도 있지만, 경험상 이 단계를 건너뛰거나 대충 넘어가면 나중에 훨씬 더 큰 비용이 든다.

초기 구조가 팀 속도를 결정한다

팀이 3명 이상이 되는 순간, 각자 다르게 환경을 설정하고 문서를 작성하는 일은 혼란을 키운다. 누군가는 .env 파일을 Git에 올리고, 누군가는 로컬 설정만 하고 넘어가고, 누군가는 README에 자신만의 방식으로 셋업 가이드를 남긴다. 이런 상태에서 3개월이 지나면:

• 새로운 팀원이 온보딩하는 데 3-4시간이 걸림
• 환경변수 누락으로 인한 버그 리포트가 반복됨
• 코드리뷰할 때 "어느 문서를 봐야 맞는 거야?" 같은 질문이 나옴

스캐폴딩 단계에서 이 기초를 제대로 다져두면, 3개월 뒤에는 팀원 한 명이 깃 클론 받아서 README.md 따라 15분 만에 로컬 환경을 구성할 수 있게 된다. 이게 '팀 속도'의 진짜 차이다.

문서와 설정이 코드보다 먼저

개발자들은 보통 기능 구현부터 시작하려 한다. 하지만 팀 리드 관점에서는 우선순위가 다르다:

1. 환경 일관성 (.env.example, .gitignore) — 개발자마다 환경이 다르면 "내 컴퓨터에선 되는데?" 문제가 매일 반복됨
2. 문서와 계획 (CLAUDE.md, PLAN.md) — 누구나 같은 맥락에서 대화할 수 있게
3. 자동화 기반 (AGENTS.md) — 수작업 반복을 줄이고, 팀의 워크플로우를 표준화

이 순서를 무시하고 기능부터 구현하면, 나중에 "아, 이건 어떻게 배포하지?", "이 변수는 어디에서 관리하지?" 같은 질문이 자꾸 생긴다.

회고

이번 작업은 크게 주목할 만한 코드 변경은 없었지만, 팀이 앞으로 4-5개월간 일할 '집'을 짓는 작업이었다고 본다. 초기에 이렇게 정성을 들이는 것과 안 하는 것의 차이는 나중에 정산 단계에서 명확하게 드러난다. 일정이 촉박할수록, 팀 규모가 클수록 이런 기초 작업이 더 소중했다.

특히 기억에 남는 건, .gitignore와 .env.example 같은 파일들이 'boring'해 보이지만, 이것이 없으면 개발자들의 실수를 방지하고 CI/CD 파이프라인을 안정적으로 만드는 데 직결된다는 점이다. 팀장이라면 이런 '보이지 않는 안정성'에 더 신경 써야 한다.

🛒 이 글과 어울리는 추천 상품

• 기계식키보드 쿠팡에서 보기 →
• 노트북 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.