GitHub협업 가이드

01GitHub 말을 일상어로 번역하기

GitHub는 어렵다기보다 낯선 말이 많습니다. 아래 단어만 알아도 AI에게 일을 맡기고 팀원과 이야기하는 데 큰 문제가 없습니다.

02팀 프로젝트의 기본 흐름

소규모 팀이나 수업 프로젝트에서는 한 레포에 팀원을 초대하고, 각자 branch를 만든 뒤 PR로 합치는 방식이 자연스럽습니다. GitHub 공식 문서도 이 방식을 작은 팀과 조직의 private project에 흔한 모델로 설명합니다.

03처음 한 번만 하는 설정

GitHub 계정, Git, GitHub CLI가 준비되어야 합니다. 이 문서는 CLI 기준이므로 gh 명령어를 사용합니다.

GitHub CLI 로그인

gh auth login --web
gh auth status

Git 사용자 이름과 이메일 확인

git config --global user.name
git config --global user.email

값이 비어 있으면 아래처럼 설정합니다. 이메일은 GitHub 계정 이메일 또는 GitHub의 private noreply 이메일을 사용해도 됩니다.

git config --global user.name "내 GitHub 이름"
git config --global user.email "내이메일@example.com"

AI에게 환경 점검시키기

이 컴퓨터에서 GitHub 협업을 할 준비가 되었는지 확인해줘.
다음 항목을 검사하고, 부족한 것이 있으면 설치/설정 방법을 초보자도 이해할 수 있게 안내해줘.

확인할 것:
1. git 설치 여부와 버전
2. gh(GitHub CLI) 설치 여부와 버전
3. gh auth status 로그인 여부
4. git user.name / user.email 설정 여부
5. 현재 작업 폴더 위치

주의:
- 내 GitHub 인증 코드, 토큰, 비밀번호는 절대 대신 입력하지 마.
- 실제 변경 명령을 실행하기 전에는 어떤 명령을 실행할지 먼저 보여줘.

04프로젝트를 내 컴퓨터로 가져오기

팀원이 이미 GitHub 레포를 만들고 여러분을 collaborator로 초대했다면, 초대 수락 후 clone부터 시작합니다.

1. 레포 주소를 받습니다.

   예: github.com/team-name/project-name 또는 OWNER/REPO

2. GitHub CLI로 clone합니다.

   내 컴퓨터에 프로젝트 폴더가 생깁니다.

3. 설치와 실행은 프로젝트마다 다릅니다.

   README.md, package.json, pyproject.toml 같은 파일을 AI에게 읽히면 빠릅니다.

gh repo clone OWNER/REPO
cd REPO

이 저장소를 처음 보는 사람에게 설명하듯이 구조를 파악해줘.

원하는 출력:
1. 이 프로젝트가 무엇을 하는지 한 문단 요약
2. 중요한 폴더와 파일 목록
3. 로컬에서 실행하는 명령어
4. 테스트 또는 빌드 명령어
5. 내가 함부로 건드리면 위험한 파일

아직 파일을 수정하지 말고, 읽고 설명만 해줘.

README와 설정 파일을 보고 이 프로젝트를 로컬에서 실행해줘.

진행 방식:
1. 먼저 실행할 명령어 목록을 보여줘.
2. 내가 승인하면 설치와 실행을 진행해.
3. 개발 서버가 켜지면 접속 URL을 알려줘.
4. 오류가 나면 오류 원인과 해결 후보를 쉬운 말로 설명해줘.

05일감은 issue로 작게 쪼개기

바이브코딩에서 가장 흔한 실패는 AI에게 너무 큰 일을 한 번에 던지는 것입니다. GitHub issue는 "이번에 딱 무엇을 할지" 정하는 장치입니다.

CLI로 issue 만들기

gh issue create \
  --title "로그인 화면의 오류 메시지를 더 이해하기 쉽게 바꾸기" \
  --body "목표: 로그인 실패 시 사용자가 다음 행동을 알 수 있게 문구를 수정한다.

완료 조건:
- 비밀번호 오류와 네트워크 오류 문구가 구분된다.
- 모바일 화면에서 문구가 버튼과 겹치지 않는다.
- 관련 스크린샷을 PR에 첨부한다."

다음 아이디어를 GitHub issue로 쪼개줘.

아이디어:
[여기에 만들고 싶은 기능이나 개선 내용을 붙여넣기]

출력 형식:
1. issue 제목
2. 배경
3. 작업 범위
4. 완료 조건
5. 건드릴 가능성이 있는 파일
6. 너무 커 보이면 더 작은 issue로 나누기

비개발자도 이해할 수 있는 말로 써줘.

06AI와 branch에서 작업하기

AI에게 코드를 맡길 때도 작업 공간은 branch입니다. branch 이름은 짧고 설명적으로 짓습니다. 예: fix-login-error-copy, feat-profile-card, docs-github-guide

작업 전 최신 상태로 맞추기

git switch main
git pull
git switch -c fix-login-error-copy

AI에게 일을 시키는 기본 프롬프트

현재 branch에서 issue #[번호] 작업을 진행해줘.

작업 목표:
[무엇을 바꿀지 적기]

제약:
- issue 범위를 벗어난 리팩터링은 하지 마.
- 관련 없는 파일 포맷팅은 하지 마.
- 비밀키, 토큰, .env 파일은 읽거나 출력하지 마.
- 큰 변경이 필요하면 먼저 나에게 이유를 설명하고 승인받아.

진행 방식:
1. 먼저 수정할 파일과 작업 계획을 5줄 이내로 말해줘.
2. 내가 승인하면 수정해.
3. 수정 후 git diff 요약과 확인 방법을 알려줘.

작업 중간에 AI를 멈추고 확인시키기

지금까지 변경한 내용을 멈추고 점검해줘.

출력:
1. 변경된 파일 목록
2. 각 파일에서 바뀐 이유
3. issue 범위를 벗어난 변경이 있는지
4. 내가 브라우저에서 확인해야 할 화면 또는 동작
5. 다음으로 할 일

아직 commit하지 마.

07커밋과 푸시

commit은 팀원에게 보여주는 작업 저장 지점입니다. AI가 많은 파일을 바꿨다면 더더욱 관련 변경만 골라서 commit해야 합니다.

변경 확인

git status
git diff

AI에게 commit 전 검토시키기

git status와 git diff를 바탕으로 commit 전에 검토해줘.

출력:
1. 이번 변경 요약
2. 관련 없는 변경이 섞였는지
3. 위험하거나 되돌려야 할 변경 후보
4. 실행해야 할 테스트/빌드 명령
5. 추천 commit 메시지 3개

아직 git add나 commit은 하지 마.

commit과 push

git add 파일경로1 파일경로2
git commit -m "fix: clarify login error message"
git push -u origin fix-login-error-copy

이번 issue와 관련된 변경만 stage하고 commit해줘.

조건:
- 먼저 git status와 git diff를 확인해.
- 관련 없는 파일이 있으면 stage하지 말고 나에게 물어봐.
- commit 메시지는 "type: 짧은 설명" 형식으로 제안하고, 내가 승인하면 commit해.
- commit 후 push까지 진행해.

추천 type:
feat, fix, docs, style, refactor, test, chore

08Pull Request 만들기

PR은 결과물 자랑이 아니라 검토 요청서입니다. 팀원이 빠르게 이해하도록 "왜, 무엇을, 어떻게 확인하면 되는지"를 씁니다.

CLI로 PR 만들기

gh pr create \
  --base main \
  --head fix-login-error-copy \
  --title "fix: clarify login error message" \
  --body "## 요약
- 로그인 실패 메시지를 상황별로 구분했습니다.
- 모바일 화면에서 문구가 버튼과 겹치지 않도록 간격을 조정했습니다.

## 확인 방법
- 잘못된 비밀번호로 로그인 시도
- 네트워크를 끄고 로그인 시도
- 모바일 폭에서 오류 문구 확인

Closes #12"

AI에게 PR 본문 초안 만들게 하기

현재 branch의 변경사항으로 GitHub PR 제목과 본문 초안을 만들어줘.

참고할 것:
- git log main..HEAD
- git diff main...HEAD
- 연결된 issue가 있으면 issue 내용

본문 형식:
## 요약
- 

## 변경한 이유
- 

## 확인 방법
- [ ] 

## 스크린샷 또는 결과
- 필요하면 어떤 화면을 캡처해야 하는지 알려줘.

## 리뷰어에게 묻고 싶은 점
- 

주의:
- 과장하지 말고 실제 변경한 내용만 써.
- 내가 실행하지 않은 테스트를 실행했다고 쓰지 마.

09리뷰 받고 수정하기

리뷰는 혼나는 과정이 아니라 main에 들어가기 전에 서로 확인하는 과정입니다. PR의 Conversation, Commits, Checks, Files changed 탭을 차례로 보면 상황을 이해하기 쉽습니다.

리뷰 댓글을 AI에게 정리시키기

PR 리뷰 댓글을 보고 수정 계획을 세워줘.

입력:
[리뷰 댓글을 붙여넣기]

출력:
1. 반드시 수정해야 하는 항목
2. 질문에 답하면 되는 항목
3. 수정할 파일 후보
4. 각 항목의 위험도
5. 내가 리뷰어에게 답글로 남길 문장 초안

아직 코드는 수정하지 마.

수정 후 다시 push

git status
git add 파일경로
git commit -m "fix: address review feedback"
git push

main 최신 변경 반영하기

git switch main
git pull
git switch 내-작업-브랜치
git merge main

10fork는 언제 쓰나

fork는 팀 내부 협업의 기본값이 아닙니다. 보통 권한이 없는 외부 프로젝트에 기여하거나, 원본과 독립된 실험 공간이 필요할 때 씁니다.

fork 방식 명령 예시

gh repo fork OWNER/REPO --clone --remote
cd REPO
git switch -c fix-small-typo

# 작업 후
git add .
git commit -m "docs: fix typo"
git push -u origin fix-small-typo
gh pr create --repo OWNER/REPO --base main --head 내아이디:fix-small-typo

11바이브코더 협업 규칙

AI를 쓰면 속도는 빨라지지만, 변경 범위가 커지고 의도를 놓치기 쉽습니다. 아래 규칙은 팀 프로젝트에서 사고를 줄이는 기본선입니다.

PR 올리기 전 체크리스트

• 현재 branch가 main이 아니다.
• issue 또는 작업 목표가 PR 본문에 연결되어 있다.
• 관련 없는 파일 변경이 섞이지 않았다.
• 직접 실행, 화면 확인, 빌드, 테스트 중 하나 이상을 했다.
• 리뷰어가 볼 수 있게 확인 방법을 적었다.
• AI가 만든 변경 중 이해하지 못한 부분을 질문했다.

12자주 막히는 상황

막혔을 때는 에러 메시지를 지우지 말고 그대로 복사해서 AI에게 설명을 요청합니다.

현재 운영체제에 GitHub CLI(gh)를 설치하는 방법을 안내해줘.
가능하면 공식 설치 방법을 기준으로 하고, 설치 후 gh --version과 gh auth status 확인까지 도와줘.

pwd
ls
cd REPO

git push가 실패했습니다. 아래 에러를 읽고 원인을 설명해줘.

[에러 메시지 붙여넣기]

원하는 출력:
1. 원인
2. 안전한 해결 순서
3. 실행할 명령어
4. 작업 내용이 사라질 위험이 있는 명령어가 있다면 경고

merge conflict가 났습니다.

먼저 충돌 파일 목록을 확인하고, 각 충돌 블록에서 양쪽 변경이 무엇을 의미하는지 비개발자도 이해하게 설명해줘.
내가 어떤 쪽을 선택할지 결정할 수 있게 선택지를 제시해줘.

주의:
- 내가 선택하기 전에는 파일을 수정하지 마.
- 해결 후에는 어떤 테스트를 해야 하는지 알려줘.

이번 변경이 너무 커졌습니다. git diff를 보고 변경을 분류해줘.

분류:
1. issue와 직접 관련 있는 변경
2. 관련은 있지만 별도 PR로 빼는 게 좋은 변경
3. 되돌리는 게 좋은 변경

각 분류별 파일 목록과 이유를 알려줘.
아직 되돌리거나 commit하지 마.

작업을 되돌리고 싶습니다.

먼저 현재 상태를 확인해줘:
- git status
- git log --oneline -5
- git diff

그 다음 내 상황이 commit 전인지, commit 후인지, push 후인지 구분해서 가장 안전한 되돌리기 방법을 설명해줘.
작업이 사라지는 명령은 실행하기 전에 반드시 나에게 확인받아.

13참고 문서

이 자료는 아래 공식 문서를 기준으로 협업 흐름을 일반 수업용으로 다시 설명했습니다.

• GitHub Docs: GitHub flow
• GitHub Docs: About collaborative development models
• GitHub Docs: About pull requests
• GitHub Docs: Helping others review your changes
• GitHub Docs: Creating an issue
• GitHub CLI Manual: gh auth login
• GitHub CLI Manual: gh repo clone
• GitHub CLI Manual: gh pr create