[팀프로젝트] 우리 팀의 협업 효율을 높인 규칙들

 

 

안녕하세요! 모바일 청첩장 제작 서비스 '드림카드'를 진행중인 도비팀입니다.

내일배움캠프 수강생인 프론트엔드 개발자 5명, 디자이너 1명이 모여 열심히 프로젝트를 만들고있습니다.

 

드림카드는 내일배움캠프에서의 최종 프로젝트로, 이전보다 규모가 크고 기간이 길어진만큼 팀원 전체가 프로젝트의 흐름을 공유하고 정확한 규칙으로 협업 효율을 높이는 것이 중요하다는 생각이 들었습니다. 당장 기획하고 구현에 돌입하기도 마음이 급한데, 규칙을 정하기 위해 오랜 시간 논의했고 코드리뷰나 PR 작성 등 구현만 하는 것에 비해 시간이 더 소요되는 일들이 많아졌는데요. MVP 집중 구현 기간이 끝난 지금 돌이켜생각해보면 시간을 들여 디테일한 규칙을 정한 것이 오히려 빠른 흐름 속에 중심을 잡고 서로의 코드를 붙여나갈 중심점이 되어준 것 같습니다.

 

기획부터 MVP 구현까지 주어진 2주를 불태워 계획한 MVP 요구사항들을 모두 구현했습니다. 효율적인 협업을 이끈 우리팀의 규칙들을 소개합니다!

 

 

💌 코드 컨벤션 구체화하기

코드 컨벤션을 정하며 팀원들 모두가 중요하게 생각한 포인트는 다음과 같았습니다.

1) 한 사람이 작성한듯 통일감있는 코드 작성하기

2) 코드 퀄리티를 이전 프로젝트들보다 높이기

3) 상세 구현 방법을 알지 못하더라도 팀원 모두가 프로젝트의 흐름을 이해하기!!

 

빠른 구현이 필요한만큼 중구난방으로 코드를 작성하지 않고, 명확한 규칙으로 코드리뷰에서도 구현 흐름이 아닌 코드 자체를 이해하기위해 소요되는 시간을 줄이고자 했습니다. 또한 함수나 컴포넌트에 명확한 이름을 붙여 같은 기능은 중복으로 구현하지 않고 공유하고자 하는 목표가 있었습니다.

 

아래는 우리 팀의 코드 컨벤션입니다!

 

1. 파일 및 컴포넌트명

• 컴포넌트 파일명: 파스칼 케이스 사용
• 페이지 컴포넌트: 페이지 경로명 + Page 접미사로 통일

 

2. 함수 및 변수 명명 규칙

• 변수명: 카멜 케이스 사용 (userName, isLoggedIn).
• 함수명: 동사로 시작하여 동작을 명확히 표현 (fetchData, updateUser).
• 이벤트 함수: handle 접두어로 시작 (handleClick, handleSubmit).
• 네트워크 요청 비동기 함수: HTTP 메서드를 접두어로 사용 (get, post, delete 등).
• 상수명: 전체 대문자 + 스네이크 케이스 (MAX_LENGTH, DEFAULT_VALUE).
• props에 함수 전달 시: onClick과 같이 on 접두어 붙여 이벤트와 연관된 요소임을 명확히하기 (onSubmit={handleSubmit}).

• 함수명, 변수명을 명확히해 역할을 쉽게 파악할 수 있게하면서 네트워크 요청 함수는 HTTP 요청을 접두사로 붙이기 등 함수 명명 규칙을 경우마다 지정해 함수의 의미를 더 쉽게 분류할 수 있도록 했습니다.

 

3. 타입

• any 타입 사용 금지: 타입을 명확히 지정.
• type 정의 위치: type 폴더에 정의.
• 파일명 규칙: 파일명에 types.ts를 접미사로 사용 (database.types.ts).

• 관리할 파일이 많아지면서 파일의 위치나 목적을 파악하기 어려웠던 경험이 있었는데요. type에는 .types를 접미사로 붙여 해당 파일에 타입들이 정의돼있다는 것을 명확히했습니다. 또한 타입을 명확히 지정해 구현 과정에서의 실수를 줄이고, 다른 팀원이 봤을 때도 어떤 데이터로 어떤 동작을 하는 코드인지 확인할 수 있도록 했습니다!

4. 커스텀 훅

• 커스텀 훅 명명: use 접두어 사용

 

5. Tanstack Query / Query Key 관리

• TanStack Query 훅: useQuery, useMutation 등 TanStack Query 훅도 커스텀 훅으로 분리하여 깔끔하게 유지. (useGetUserData, useUpdateUser 등)
• queryKey 관리: queries/queryKeys에서 함수 선언을 통해 받아옴

• 이렇게 선언하면 실수로 키가 잘못되는 것을 방지하고, 여러 사람이 같은 키를 쉽게 관리할 수 있어 더 안전하고 편리하게 서버상태를 관리할 수 있습니다.

6. 주석

• 최소한으로 사용: 복잡한 로직을 설명할 때만 사용.
• 공용 함수 주석: /** */를 활용하되, 최대한 함수명으로 의미를 드러냄.

7. 공용 컴포넌트

• Button 및 Input 등은 공용 컴포넌트로 정의하여 재사용 (<CommonButton />, <CommonInput />).

8. 코드 스타일

• ESLint 및 Prettier 사용: 코드 일관성 유지 및 자동 포맷팅 적용.
• Early Return: if (조건) return; 처럼 조건에 대한 실행이 한 줄일 때는 {}를 생략하고 개행 없이 작성.

• 코드의 가독성을 높이고 위의 경우처럼 previewRef.current가 아직 없을 때 동작을 방지하는 등 발생할 수 있는 문제를 예방할 수 있도록 early return을 적극 활용했습니다.

 

이 중 Tanstack Query의 쿼리키를 관리하는 컨벤션은 구현 과정에서 다른 데이터를 같은 쿼리키로 관리해 발생한 에러가 있어 도입한 컨벤션이었는데요. 사용하는 쿼리키를 한 파일에 모아 관리해 중복 위험을 줄이고, 동시에 쿼리키를 텍스트로 직접 입력할 때 발생할 수 있는 오타 등의 실수를 방지할 수 있게 되었습니다. 개인 프로젝트를 진행할 때도 활용할 수 있지만, 특히 여러 사람이 같은 데이터를 관리해야할 때 유용한 방식이라고 생각합니다.

 

💌 적극적으로 코드리뷰 하기

코드리뷰는 왜 해야할까요? 여러가지 이유가 있지만, 우리 팀의 목적은 다음과 같았습니다.

1) 코드컨벤션 규칙을 잘 지켜 코드의 일관성 높이기

2) 더 나은 방향성이 있다면 적극적으로 공유하여 코드 퀄리티를 높이기

 

빠른 구현을 위해 구현에 집중할 수 있는 시간을 확보하고, 그 외 시간을 정해 하루동안 제출된 PR을 확인하며 서로의 코드에 궁금한 부분을 질문하는 시간을 가졌습니다. 담당 작업을 하며 중간중간 코멘트를 남기거나 급한 내용이 있다면 팀원들에게 공유하여 리뷰를 요청하는 등 유동적으로도 진행하며, 빠른 구현과 빠른 병합 사이의 밸런스를 유지할 수 있도록 노력했습니다.

 

1.  슬랙 + 깃허브 앱을 활용하여 PR, deploy 등 진행 상태를 틈틈히 확인하기
2. 매일 저녁 8시 서로의 PR에 질문하고 의견을 나누는 시간을 마련
3. 변경 사항을 빠르게 기록, 확인할 수 있는 PR 템플릿을 도입
4. 브랜치 룰을 설정해 규칙에 맞는 PR만 develop 브랜치로 merge 하기

• 2명 이상 approve와 comment
• 빌드 에러가 없는 경우 (Vercel 프리뷰를 활용해 확인)

 

 

프로젝트를 진행하다보면 코드 혹은 구현 맥락과 함께 다른 팀원들에게 상황을 공유해야하는 경우가 있습니다.

이럴 때 구현한 내용이 changed files에 남아있기 때문에, 전달하고자하는 내용을 덧붙여 더 정확한 맥락으로 전달하는 데에 도움이 되기도 했습니다.

 

 

처음 코드리뷰의 목적처럼 다른 팀원들의 구현 사항에도 적극적으로 의견을 남기고, 또한 의견을 적극적으로 수용/반영하며 모두가 더 좋은 프로젝트를 만들 수 있도록 노력했습니다.

 

💌 필요에따라 적극적으로 역할 분담하기

중간 발표 전 최종 수정사항을 정리하고 기존 담당과 관계없이 작업이 끝나는 순서대로 빠르게 남은 일감을 분담한 흔적입니다.

이 때 특히 다른 팀원이 구현한 부분도 상관없이 수정을 진행했는데요. 일관적으로 코드를 작성하고 코드리뷰를 적극적으로 한 노력이 빛을 발한 순간이었다는 생각이듭니다.

 

위 상황뿐만 아니라 매일 아침저녁으로 진행 상황을 공유하며 담당 기능 구현이 끝났는데 다른 일감이 남은 경우 도움이 필요한 팀원의 기능을 분담하는 등 모두가 팀 전체의 완성을 목표로 적극적으로 역할을 분담했습니다.

 

 

💌 회의 내용 문서화하기

 

진행 상황이나 결정 사항을 공유하기 위해 기능명세서와 데일리스크럼 기록을 적극 활용했습니다.

역할 분담이 필요할 때 참고가 되기도 했고, 중간중간 급하게 진행한 회의들의 내용도 기록하여 결정사항을 다르게 알고 있는 팀원이 생기지 않도록 했습니다.

 

특히 기능명세서는 작성에 시간이 꽤 소요됐지만, 모두가 기획을 하는 상황에서 생각한 요구사항이 달라 불필요한 구현을 하는 상황을 방지하고 필요한 부분에 집중하는 것에 큰 도움이 되었습니다.

 

여기까지 우리 팀이 효율적인 협업을 위해 논의하고 실천한 규칙들을 정리해보았습니다!