새 프로젝트, 처음부터 협업이 쉽도록

새 프로젝트를 시작할 때 가장 먼저 하는 일은 폴더를 정리하고 각 팀원이 진입할 문을 만드는 것이다. 이번엔 음악 정보를 다루는 구조화 데이터 플랫폼의 초기 구조를 잡는 작업(scaffold)을 했는데, 생각보다 이 "첫삽"이 얼마나 중요한지 다시 깨달았다.

chore 라고 분류한 이유, 하지만 그 이상

커밋 메시지에 chore를 붙인 건 이 작업이 기능 개발이나 버그 수정이 아니기 때문이다. 하지만 내가 본다면, 팀이 안정적으로 협업할 기반을 만드는 일이다. 사실 "chore"는 무심하게 처리되기 쉽지만, 프로젝트 초기에는 이게 나중의 수많은 결정과 생산성을 좌우한다.

이 6개 파일은 "기능이 없는 setup"처럼 보이지만, 실은 팀의 생산성과 코드 품질을 좌우하는 기초 공사다.

왜 처음부터 문서화를 강하게 밀어붙나

처음 프로젝트를 맡을 때, 나는 "빨리 기능부터 빌드하자"는 마인드였다. 환경 설정? README? "나중에 하면 되지"라고 생각했다. 하지만 두 번, 세 번 프로젝트를 거치면서 깨달았다:

• 새 팀원이 들어올 때, 문서가 없으면 내가 30분씩 일대일로 설명해야 한다.
• 3개월 후 내가 다시 코드를 볼 때, "이게 왜 이렇게 구조됐지?"라는 질문부터 시작한다.
• 데이터 모델이 명시되지 않으면, API를 설계할 때마다 논쟁이 생긴다.
• .gitignore를 제대로 세팅하지 않으면, 누군가는 항상 .env 파일을 실수로 커밋한다.

그래서 이번엔 처음부터 한다. .env.example을 만들고, DATA-MODEL.md에 데이터 흐름을 그려 넣고, CLAUDE.md에 "우리가 코드를 짤 때 지켜야 할 규칙"을 명시한다. 이건 투자다. 지금 1시간 투자하면 팀이 나중에 10시간을 아낀다. 온보딩 시간, 코드리뷰 왕복, 설계 논쟁—모두 문서 하나로 줄인다.

Astro 를 선택했다는 것의 무게

astro.config.mjs가 있다는 것은 "우리가 기술 스택을 선택했다"는 뜻이다. 음악 정보라는 구조화된 데이터를 다루는 사이트이기 때문에, 정적 생성(SSG)과 동적 콘텐츠를 섞을 수 있는 Astro가 좋은 선택이었다. 하지만 이건 팀원들도 알아야 할 정보고, 나중에 "왜 하필 Astro?"라는 질문에 대한 답이 필요하다.

이런 파일에는 "왜 이 선택을 했나"를 주석으로 남기는 게 좋다:

// astro.config.mjs
export default defineConfig({
  integrations: [react(), mdx()],
  // 선택 이유: SSG + 동적 라우팅 동시 필요
  // 대안: Next.js (오버스펙), SvelteKit (팀 경험)
  // 결정: 빌드 속도 + 학습 곡선 + 정적 콘텐츠 우위 고려
});

이렇게 남겨두면, 6개월 후 누군가 "왜 Astro인가?"라고 물었을 때 답할 수 있다. 그리고 "그 당시 상황이 이젠 달라졌으니 마이그레이션을 검토해보자"는 결정도 근거 있게 할 수 있다.

초기 설정이 놓치기 쉬운 이유

많은 팀이 스캐폴딩을 급하게 넘어간다. "일단 기능 하나 빨리 만들어야지" 마인드다. 하지만 내 경험상:

• 환경 설정이 명확하지 않으면, 개발자마다 다른 설정으로 작업한다.
• 데이터 모델이 없으면, 첫 API 설계부터 논쟁이 난다.
• 협업 규칙(코드 스타일, 커밋 메시지, 브랜칭 전략)이 없으면, 코드리뷰가 문화가 된다.

그래서 이번 작업은:

1. 환경 설정 — .env.example 작성, "누가 어떤 값을 채워야 하나" 명시
2. 버전 관리 규칙 — .gitignore에 환경, 로그, 빌드 산물, 의존성 파일 명시
3. 협업 지침 — CLAUDE.md에 네이밍, 커밋 메시지, 코드리뷰 기준 작성
4. 데이터 설계 — docs/DATA-MODEL.md에 엔티티, 관계, 유효성 제약 정의
5. 온보딩 가이드 — README.md에 설치, 실행, 배포를 한 번에 정리

이 다섯 가지가 명확하면, 팀원들이 "아, 여기서 나는 이걸 해야 하는군"이라고 빠르게 파악한다. 질문도 적어진다.

지금은 기능이 하나도 없지만

솔직히 지금 이 프로젝트는 기능이 하나도 없다. 데이터베이스도 없고, API도 없고, 화면도 없다. 하지만 틀은 서 있다. 다음 사람이 이 프로젝트에 들어올 때, 30분 안에 로컬 환경을 구성하고, README를 읽고, 데이터 모델을 이해하고 첫 기능 개발을 시작할 수 있다. 그게 "scaffold"의 가치다. 보이지 않는 투자지만, 팀의 생산성과 코드 품질을 좌우한다. 다음.

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

• 사무의자 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

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