구현보다 먼저: 팀 프로젝트를 위한 GitHub 협업 환경 구축기

게시 2026/05/29

By woolam

조회 14 분읽는 시간

들어가면서: 프로젝트를 시작하며

새로운 팀원들과 팀 프로젝트를 진행하게 되었습니다. 아이디어가 구체화되고 기술 스택이 정해지자마자, 다들 키보드에 손을 얹고 바로 코드를 작성하고 싶은 마음이 굴뚝같았습니다. 하지만 우리는 개발을 시작하기 전에 한 템포 쉬어가기로 했습니다. 바로 GitHub 협업 규칙부터 정하기로 한 것입니다.

처음에는 “일단 기능부터 빠르게 만들고 나중에 맞추면 되지 않을까?”라는 생각도 들었습니다. 하지만 과거의 경험을 돌이켜보면, 명확한 협업 규칙 없이 진행된 프로젝트는 결국 작업 현황 파악이 안 되고, 코드 리뷰는 생략되며, 역할 분담이 모호해지는 등 여러 문제에 부딪히곤 했습니다. 성공적인 프로젝트 완수를 위해서는 튼튼한 기반 공사가 먼저라고 판단했습니다.

왜 협업 규칙부터 정했을까?

우리가 가장 피하고 싶었던 상황은 다음과 같습니다.

“지금 누가 어떤 작업을 하고 있지?”: 팀원들의 작업 현황을 서로 모르는 상황
“어, 나도 그 부분 수정하고 있었는데!”: 작업 범위가 겹쳐서 충돌(Conflict)이 발생하는 상황
“이 코드는 왜 이렇게 작성된 거지?”: 아무런 리뷰나 논의 없이 코드가 메인 브랜치에 머지(Merge)되는 상황
“우리 프로젝트 지금 어디까지 진행된 거야?”: 전체적인 진행 상황을 한눈에 파악하기 어려운 상황

이러한 문제들을 사전에 예방하고, 효율적이고 투명한 개발 환경을 만들기 위해 우리는 GitHub Issue, PR(Pull Request) Template, Kanban Board를 적극적으로 도입하기로 결정했습니다.

GitHub Issue로 작업 정의하기: 무엇을 해야 하는가?

가장 먼저 도입한 것은 GitHub Issue입니다. Issue는 단순히 버그를 리포팅하는 용도를 넘어, 작업 단위를 명확하게 정의하는 훌륭한 도구입니다.

Issue를 사용하면 다음과 같은 이점이 있습니다.

명확한 작업 단위: 두루뭉술한 목표가 아니라, 구체적으로 구현해야 할 기능이나 수정해야 할 버그를 하나의 Issue로 정의할 수 있습니다.
책임 소재 명확화: Assignees 기능을 통해 해당 작업의 담당자를 명확히 지정할 수 있습니다.
작업 범위 문서화: 작업 시작 전에 해야 할 일(To-Do)을 체크리스트 형태로 정리하여, 작업의 범위를 명확히 문서화할 수 있습니다.

예를 들어, 주문 생성 API를 구현해야 한다면 다음과 같이 Issue를 작성합니다.

[Order] 주문 생성 API 구현

- [ ] 주문 생성 로직 구현
- [ ] 재고 차감 로직 연동
- [ ] 주문 상태(결제 대기 등) 저장
- [ ] 관련 단위 테스트 작성

우리는 “모든 작업은 Issue 생성에서 시작한다”는 규칙을 세웠습니다. 즉, 코드를 작성하기 전에 반드시 Issue를 먼저 생성하고, 해당 Issue 번호를 기반으로 브랜치를 생성(feature/#issue-number)하는 흐름을 만들었습니다.

Pull Request로 코드 리뷰하기: 어떻게 구현했는가?

작업이 완료되었다고 해서 바로 메인 브랜치에 코드를 합치는 것은 위험합니다. 우리는 PR(Pull Request)을 통해 변경 사항을 팀원들과 공유하고 리뷰하는 과정을 필수로 거치기로 했습니다.

PR을 도입한 이유는 다음과 같습니다.

변경 사항 공유: 내가 어떤 코드를 어떻게 수정했는지 팀원들에게 투명하게 공개합니다.
집단 지성을 통한 품질 향상: 코드 리뷰를 통해 혼자서는 발견하지 못했던 실수나 버그를 사전에 차단할 수 있습니다.
코드 품질 유지: 팀에서 합의한 코딩 컨벤션이나 아키텍처 원칙이 잘 지켜졌는지 확인하여, 프로젝트 전체의 코드 품질을 일정 수준 이상으로 유지할 수 있습니다.

효율적인 리뷰를 위해 우리는 직접 PR Template도 작성하여 적용했습니다. 템플릿을 사용하면 리뷰어가 코드를 이해하는 데 필요한 컨텍스트를 작성자가 빼놓지 않고 제공할 수 있습니다.

우리의 PR Template은 다음과 같은 항목들로 구성되었습니다.

작업 내용: 어떤 Issue를 해결하기 위한 PR인지 명시 (예: Resolves: #12)
변경 이유: 이 코드를 왜 이렇게 작성했는지, 어떤 문제를 해결하려 했는지 설명
주요 변경 사항: 리뷰어가 중점적으로 봐야 할 핵심 로직이나 파일 목록
테스트 및 확인: 로컬에서 어떤 테스트를 거쳤는지 명시
리뷰 포인트: 리뷰어에게 특별히 의견을 구하고 싶은 부분 (예: “이 부분의 성능 최적화 방법이 더 있을까요?”)
참고 사항: 관련 문서 링크나 스크린샷 등

Kanban Board로 진행 상황 관리하기: 어디까지 왔는가?

Issue와 PR이 개별 작업에 대한 관리라면, Kanban Board(GitHub Projects)는 프로젝트 전체의 흐름을 조망하는 도구입니다.

우리는 보드를 다음과 같은 상태(Status) 컬럼으로 구성했습니다.

Todo: 앞으로 해야 할 작업들 (생성된 Issue들이 모이는 곳)
In Progress: 현재 누군가 담당하여 진행 중인 작업
Review: 개발이 완료되어 PR이 생성되고, 코드 리뷰를 기다리거나 진행 중인 작업
Done: 리뷰가 완료되고 메인 브랜치에 머지되어 완전히 끝난 작업

Kanban Board를 도입함으로써 얻은 가장 큰 수확은 가시성(Visibility)입니다. 보드만 보면 현재 누가 어떤 작업을 하고 있는지, 리뷰가 밀려있는 작업은 없는지, 전체 프로젝트 중 완료된 작업의 비율은 어느 정도인지 한눈에 파악할

실제 작업 흐름: 물 흐르듯 자연스러운 협업

앞서 설정한 도구들을 바탕으로, 우리의 실제 개발 워크플로우는 다음과 같이 정립되었습니다.

Issue 생성: 새로운 기능이나 버그 수정이 필요하면 가장 먼저 Issue를 생성하여 작업 내용을 정의합니다.
담당자 지정: 해당 Issue를 처리할 담당자를 지정하고, Kanban Board에서 Todo 상태로 둡니다.
브랜치 생성: 담당자는 작업을 시작할 때 Issue 번호를 포함한 브랜치를 생성하고, 보드 상태를 In Progress로 변경합니다.
개발: 로컬 환경에서 열심히 코드를 작성합니다.
PR 생성: 작업이 완료되면 PR Template에 맞춰 PR을 생성하고, 보드 상태를 Review로 변경합니다.
코드 리뷰: 팀원들이 PR을 확인하고 피드백을 주고받습니다. 필요한 경우 코드를 수정합니다.
Merge: 리뷰가 승인(Approve)되면 코드를 메인 브랜치에 머지합니다.
Done 이동: 머지와 함께 연동된 Issue가 자동으로 닫히며, 보드 상태도 Done으로 이동합니다.

이러한 흐름은 개발 과정에서 발생할 수 있는 혼선을 최소화하고, 각 단계가 물 흐르듯 자연스럽게 이어지도록 만들어 주었습니다.

정리: 구현보다 협업 환경 구축이 먼저였다

“구현보다 협업 환경 구축이 먼저다.”

이번 프로젝트 준비 과정을 통해 얻은 가장 큰 깨달음입니다. 프로젝트 규모가 작거나 팀원이 적더라도, 명확한 협업 규칙은 선택이 아닌 필수라는 것을 느꼈습니다.

단순히 GitHub의 기능들을 사용하는 것을 넘어, “왜 이 기능이 필요한가?”에 대한 팀원 간의 공감대가 형성되었을 때 비로소 도구들이 제 역할을 다한다는 것을 알게 되었습니다. Issue, PR, Kanban Board를 유기적으로 연결하여 활용하니, 작업 관리가 훨씬 수월해졌고 협업의 효율성도 크게 높아졌습니다.

무엇보다, 본격적인 기능 구현에 앞서 팀의 협업 프로세스를 먼저 고민하고 세팅해 본 경험은 앞으로 어떤 프로젝트를 하더라도 든든한 밑거름이 될 것 같습니다.

Learned (배운 점)

문서화의 힘: Issue와 PR Template을 통한 문서화는 귀찮은 작업이 아니라, 미래의 나와 팀원들을 위한 훌륭한 컨텍스트 제공 수단임을 배웠습니다.
가시성의 중요성: Kanban Board를 통해 프로젝트 전체의 흐름을 시각화하는 것이 팀의 목표 달성 페이스를 유지하는 데 얼마나 중요한지 깨달았습니다.
프로세스의 가치: 좋은 코드를 작성하는 것만큼이나, 그 코드가 안전하게 통합되고 관리될 수 있는 프로세스를 구축하는 것이 개발자의 중요한 역량임을 배웠습니다.

References

Project, Collaboration