프로젝트 뼈대부터 팀 지침을 함께
목차
Create Next App으로 새 프로젝트를 시작했다. 겉으로는 "Initial commit" 한 줄일 수 있지만, 이 시점에 어떤 파일을 포함하고 어떻게 구조화하는지가 3-6개월 뒤 팀의 개발 속도와 코드 품질을 크게 좌우한다.
문서부터 코드까지, 초기 설정의 무게
이 초기 커밋에는 흥미로운 선택이 있다. 단순히 Next.js 스캐폴딩만 포함한 게 아니라, AGENTS.md와 CLAUDE.md 같은 문서를 처음부터 함께 커밋했다는 점이다.
많은 팀이 프로젝트 시작 후 한두 달 지나야 "아, 팀 규칙을 문서화해야겠다"고 생각한다. 그때쯤이면 이미 코드는 제각각 스타일로 쓰여 있고, 새로 들어온 개발자는 "왜 이렇게 했어?"라는 질문에 답변할 사람이 없는 상황이 된다. 초기부터 지침을 명시한다는 건 첫 번째 PR부터 팀의 기준을 적용할 수 있다는 뜻이다.
파일별 역할: 세우는 것부터 관리하는 것까지
| 파일 | 역할 | 초기 설정이 중요한 이유 |
|---|---|---|
.gitignore |
버전 관리 제외 파일 | 초기에 제대로 설정 안 하면 나중에 민감한 파일(.env, 배포 산출물)이 실수로 커밋되거나, 불필요한 node_modules가 계속 추적됨 |
AGENTS.md |
에이전트(자동화/팀 도구) 운영 지침 | 팀이 어떤 자동화 도구를 쓰고, 어떻게 사용하는지 초기부터 명시 |
CLAUDE.md |
프로젝트 개발 방침 (코드 스타일, 커밋 규칙 등) | 팀원이 입장할 때 첫 읽을 문서. 초기부터 명확하면 온보딩 시간이 1주일 단축될 수 있음 |
README.md |
프로젝트 개요 | 설정 방법, 의존성, 실행 방법 등 새 팀원의 첫 진입점 |
eslint.config.mjs |
코드 스타일 규칙 | 모든 개발자가 같은 스타일로 코드를 쓰도록 강제. 초기 설정이 약하면 PR 리뷰 때마다 "들여쓰기 고쳐줄래?"라는 반복이 계속됨 |
next.config.ts |
Next.js 런타임 설정 | 번들 최적화, API 라우트, 환경 변수 처리 등이 초기 설정에 따라 결정됨. 나중에 변경하면 기존 코드가 깨질 수 있음 |
초기 설정 = 초기 투자
내 경험상, 팀장으로서 프로젝트 초기에 1-2일을 투자해서 .gitignore, ESLint 규칙, 커밋 메시지 가이드를 정확히 설정하는 것이 후속 3개월간 매주 30분씩 절약되는 시간과 맞바뀐다.
왜냐하면:
- 코드 리뷰 시간 단축: "이건 우리 스타일 가이드에 맞지 않아요"라는 반복 지적을 줄일 수 있음
- 온보딩 가속: 새로 들어온 개발자가 문서를 읽고 "아, 이 팀은 이렇게 일하는구나"를 빨리 파악
- 자동화 활용: ESLint, Prettier 같은 자동 포맷팅을 처음부터 설정하면, 개발자는 로직에만 집중 가능
흔한 실수 vs. 좋은 초기 설정
초기 설정을 건너뛴 팀은 대개 이렇게 진행된다:
Week 1-2: "빨리 기능부터 만들자"
Week 4: "어라, PR마다 코드 스타일 지적이 계속 나네"
Week 8: "이번 기회에 ESLint를 도입하자" → 모든 파일을 수정해야 함
Week 12: 기술 부채 누적, 신입이 들어와도 "왜 이렇게 했어?"라는 질문 반복
반면 초기부터 지침을 명시한 팀은:
Week 1: 설정 완료, 첫 PR부터 규칙 적용
Week 2+: 기본기를 갖춘 PR들이 자연스럽게 들어옴
Month 3+: 팀이 같은 언어(코드 스타일, 아키텍처)로 대화 가능
다음
이 초기 커밋은 단순해 보이지만, 뒤에 올 수백 개의 커밋이 따를 기초를 만든다. 문서를 초기부터 포함한 선택이 좋은 신호라고 본다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.