팀 프로젝트 시작 체크리스트

저장소 셋업 체크리스트

팀 프로젝트 저장소를 처음 만들 때 확인할 항목들입니다.

순서	항목	설명
1	빈 저장소 생성	의미 있는 이름으로 생성, Public/Private 결정 (README, .gitignore 등 추가하지 않기)
2	프로젝트 초기 코드	로컬에서 프로젝트 생성 도구로 보일러플레이트 생성 후 push (README, .gitignore 자동 포함)
3	Collaborator 초대	팀원 전원 초대 및 수락 확인
4	브랜치 보호 규칙(Ruleset)	main 브랜치 보호 규칙 설정

프로젝트를 시작하기 위한 최소 조건은 1, 2, 3번입니다. 4번인 브랜치 보호 규칙은 바로 설정하는 것을 권장하지만, 시간이 부족하다면 프로젝트를 시작한 직후에 적용해도 됩니다. README는 프로젝트를 진행하면서 보완해도 괜찮습니다.

팀 규칙 합의 체크리스트

코드를 작성하기 전에 팀원끼리 협업 규칙을 먼저 정해두세요. 정한 내용은 README에 간단히 적거나, 필요하다면 별도 문서(예: CONTRIBUTING.md)로 분리해 둘 수 있습니다.

브랜치 네이밍 규칙


합의 예시:
- feature/기능명 (새 기능)
- fix/버그명 (버그 수정)
- 브랜치명은 영문 소문자와 하이픈(-) 사용

커밋 메시지 컨벤션


합의 예시:
- 한글 또는 영문 중 하나로 통일
- 동사로 시작 (추가, 수정, 삭제 / Add, Fix, Remove)
- 50자 이내로 요약

좋은 예: "로그인 페이지 폼 유효성 검사 추가"
나쁜 예: "수정함", "ㅋㅋ 이거 고침", "asdf"

PR 규칙


합의 예시:
- PR 제목은 변경 사항을 한 줄로 요약
- PR 설명에 무엇을, 왜 변경했는지 작성
- 최소 1명 이상 리뷰 후 merge
- 리뷰어가 24시간 내에 리뷰하지 않으면 알림

규칙은 적을수록 좋습니다. 처음에는 최소한의 규칙으로 시작하고, 필요할 때 하나씩 추가하세요. 규칙이 많으면 지키기 어려워집니다.

첫 PR까지의 온보딩 체크리스트

팀원이 초대를 수락한 후, 첫 번째 PR을 만들기까지의 과정입니다.

저장소 clone


git clone https://github.com/owner/repo-name.git
cd repo-name

프로젝트 실행 확인


npm install
npm run dev

새 브랜치 생성


git switch -c feature/my-first-task

간단한 변경 (예: README에 이름 추가)

커밋 및 push


git add README.md
git commit -m "팀원 목록에 이름 추가"
git push origin feature/my-first-task

GitHub에서 PR 생성
팀원에게 리뷰 요청
리뷰 완료 후 merge

첫 PR은 가볍게 첫 번째 PR은 복잡한 기능 구현보다 README 수정 같은 간단한 작업으로 시작하세요. 전체 워크플로우를 연습하는 것이 목적입니다.

자주 하는 실수와 해결법

실수	원인	해결법
main에 직접 push 시도	브랜치를 만들지 않고 작업	branch protection 설정, 작업 전 항상 `git switch -c`
push가 거부됨	다른 팀원이 같은 브랜치에 먼저 push함(원격 브랜치가 로컬보다 앞서 있음)	`git pull origin <브랜치명>` 후 다시 push
Collaborator 초대를 못 받음	이메일/사용자명 오류	정확한 GitHub 사용자명 확인, 스팸함 확인
merge 충돌	같은 파일을 여러 명이 수정	자주 pull 받기, 작업 영역 분담
.env 파일이 push됨	.gitignore 미설정	.gitignore에 `.env` 추가, 이미 push된 경우 `git rm --cached .env` (`--cached`는 Git 추적만 해제하고 로컬 파일은 유지합니다)
node_modules가 push됨	.gitignore 미설정	.gitignore에 `node_modules/` 추가

브랜치 보호 규칙이 설정된 상태에서 main에 직접 push하면 다음과 같이 거부됩니다.

터미널에서 main 브랜치에 직접 push 시도 시 repository rule에 의해 거부되는 에러 메시지

.env 파일을 실수로 push했다면 git rm --cached .env로 추적을 해제하고 .gitignore에 추가한 뒤 커밋하세요. 다만 이미 커밋된 내용은 Git 히스토리에 남아 있으므로, API 키 등 민감한 값은 반드시 폐기하고 새로 발급받아야 합니다.

프로젝트 종료 후 포트폴리오 정리

매 단계 새 프로젝트를 진행하는 환경에서는, 프로젝트가 끝난 뒤 포트폴리오 정리를 해두는 것이 좋습니다.

Owner인 경우 - 저장소가 Public 상태인지 확인하고, README에 프로젝트 소개와 본인 기여 내용을 정리해 두세요.
Collaborator인 경우 - 저장소 URL을 기록해 두세요. 본인의 PR과 커밋 기록이 남아 있으므로 기여 내역을 증명할 수 있습니다. 다만 Owner가 저장소를 삭제하면 이 기록도 함께 사라지므로, fork 또는 --mirror로 본인 계정에 복사본을 만들어 두는 것을 권장합니다.

방법	특징
fork	"forked from X" 라벨이 붙고 원본과 연결 유지. 원본이 삭제되면 fork 네트워크가 재구성되어 기존 fork 중 하나가 새 root가 됨
--mirror	원본과 완전히 독립된 저장소로 복사됨

mirror 방법


# 원본 저장소를 mirror clone
# (브랜치, 태그, 커밋 이력 등 Git 데이터 전체 복사)
git clone --mirror https://github.com/owner/repo-name.git

# 내 계정에 비어 있는 새 저장소를 만든 뒤, 거기로 mirror push
cd repo-name.git
git push --mirror https://github.com/my-account/repo-name.git

이 방법은 Git 저장소 자체를 복사하는 방식이므로, 브랜치·태그·커밋 이력은 유지되지만 GitHub의 이슈, Pull Request, 리뷰 기록 같은 플랫폼 데이터까지 그대로 옮겨지지는 않습니다.

반면 fork는 원본과의 연결("forked from X")이 유지되므로, 원본 저장소가 존재하는 한 원본의 PR과 이슈를 통해 본인의 기여 내역을 확인할 수 있습니다.

정리

지금까지 배운 내용을 살펴보겠습니다.

Ch.1 두 가지 협업 방식

개인 저장소 + Collaborator와 Organization을 비교하고, 소규모 팀에는 Collaborator 방식이 적합하다는 결론을 내렸습니다.

Ch.2 실전 셋업

저장소 생성, Collaborator 초대, 브랜치 보호, PR 워크플로우, 팀 규칙 합의까지 실전 체크리스트를 정리했습니다.

이 가이드대로 셋업을 마쳤다면, 이제 팀 프로젝트를 시작할 준비가 된 것입니다. 처음에는 어색할 수 있지만, PR을 통해 코드 리뷰를 주고받는 과정 자체가 협업의 핵심입니다. 몇 번만 경험해 보면 자연스럽게 익숙해집니다.