Lab 04: AI 팀 GitHub 협업과 PR 기록

• AI를 활용하는 팀원이 함께 볼 public GitHub 저장소를 fork하고 로컬에 clone합니다.
• 업스트림, 내 작업 공간, 로컬 클론의 관계를 이해합니다.
• AI로 개인 생산성이 높아질수록 협업 기록과 검토 구조가 왜 더 중요해지는지 이해합니다.
• 브랜치, 커밋, PR로 다른 팀원과 다른 에이전트가 이어받을 수 있는 변경 기록을 남깁니다.
• 개인 LLM-Wiki를 사용하는 경우, 팀 프로젝트 맥락과 진행 로그를 함께 남깁니다.
• 팀 저장소와 개인 위키가 서로 다른 역할을 한다는 점을 선택적으로 확인합니다.
• 개인 작업 기준이 있다면 팀 협업에서 어떻게 쓰이는지 연결합니다.

Lab 03에서는 한 사람이 넓은 오너십을 가지고 AI와 일하는 방식을 gstack 관점으로 정리했습니다. 이제 질문은 다시 바뀝니다.

그런 개인들이 여러 명 모이면 어떻게 협업할 것인가?

AI를 잘 쓰는 개인은 예전보다 더 넓은 범위를 맡을 수 있습니다. 하지만 제품과 조직에는 여전히 협업이 필요합니다. 다만 협업의 방식이 바뀝니다.

AI를 활용하면 한 사람이 예전보다 훨씬 많은 코드를 만들고, 더 넓은 범위의 작업을 진행할 수 있습니다. 이 흐름 자체는 강력하지만, 계속 혼자만 작업하면 협업의 방식은 연습되지 않습니다. 팀이 함께 이해하고 검토하고 이어받는 구조를 만들지 못하면, 생성된 결과물은 빠르게 쌓이지만 관리 가능한 자산이 되기 어렵습니다.

그래서 이 Lab에서는 일부러 작은 PR을 만들고, 브랜치와 커밋과 리뷰 기록을 남깁니다. 이 기록은 단순한 절차가 아닙니다. 빠르게 생성된 결과물을 AI Slop으로 흘려보내지 않고, 지속적으로 발전하고 관리되는 공동 산출물로 바꾸기 위한 기본 구조입니다.

각자가 AI 에이전트와 함께 넓은 범위를 처리한다면, 각자가 남긴 결과, 판단, 변경 이유, 검토 포인트가 팀이 이해할 수 있는 기록으로 남아야 합니다.

여기서 GitHub는 개발자만 쓰는 코드 저장소가 아닙니다. AI를 활용하는 여러 사람이 각자의 에이전트와 함께 일할 때, 같은 맥락을 공유하고 검토 가능한 기록을 남기는 협업 공간입니다.

이번 Lab의 목표는 거창한 기능을 만드는 것이 아닙니다. 팀 repo에 작은 변경을 남기고, 그 변경을 PR로 설명하는 것입니다. 개인 LLM-Wiki를 함께 쓰는 경우에는 나의 작업 맥락까지 별도로 기록합니다.

AI를 사용하는 협업에서 GitHub 구조를 이해해야 하는 이유는 명령어를 외우기 위해서가 아닙니다. 누가 기준 기록을 관리하고, 나는 어디에서 작업하고, 내 컴퓨터의 에이전트가 어떤 파일을 수정하고, 그 변경이 어떤 검토 과정을 거쳐 다시 팀의 기록이 되는지를 이해하기 위해서입니다.

이 구조를 알면 AI가 만든 변경을 무작정 덮어쓰지 않고, 작은 단위로 나누어 설명하고 검토할 수 있습니다. 이전보다 많은 코드와 문서가 생성되는 시대일수록 중요한 것은 생성 속도만이 아니라 기록, 검토, 통합 기준입니다.

이번 Lab에서 사용할 GitHub 저장소는 하나입니다. 수업 전체 인원이 같은 공통 저장소에서 각자 작은 변경을 만들고, 브랜치, 커밋, push, PR, review 흐름을 한 번씩 경험합니다.

이번 Lab의 목표는 이 저장소에서 한 사람당 하나의 PR 사이클을 완주하는 것입니다. 팀별 프로젝트 저장소에서도 나중에 같은 방식을 사용하지만, 지금은 공통 저장소 하나에 집중합니다.

개인 LLM-Wiki를 함께 사용하는 경우에는 수업용 GitHub 실습 폴더를 하나 추가합니다. Lab 03에서 정리한 개인 작업 기준이 있더라도, GitHub 협업 실습은 내 위키 안에서 별도 프로젝트 맥락으로 기록합니다. 이 단계는 권장 확장입니다. GitHub repo만으로도 이번 Lab의 핵심 실습은 진행할 수 있습니다.

LLM-Wiki/
└── 10-projects/
    ├── {personal-project}/
    └── {github-practice-or-team-project}/
        ├── README.md
        └── progress.md

10-projects/{github-practice-or-team-project}/README.md에는 아래 항목을 적습니다.

# GitHub 협업 기록

## 사용할 repo
- URL:

## 이 repo에서 무엇을 연습하거나 만드는가
-

## 내가 맡은 역할
-

## 오늘 남길 변경
-

## 개인 작업 기준(있다면)
- 작업 기준:
- 사용할 에이전트:
- 필요한 Skill, Hook, Plugin:

## 에이전트가 먼저 읽을 노트
- [[progress]]

progress.md에는 오늘 작업을 이어갈 수 있게 기록합니다.

# 진행 로그

## YYYY-MM-DD

### 오늘 할 일
- 수업용 공통 repo를 fork하고, 내 fork를 clone한다.
- 브랜치를 만들고 작은 문서 변경을 남긴다.
- PR 설명을 작성한다.

### 확인할 것
- repo URL:
- 내 브랜치 이름:
- PR URL:

AI 에이전트가 GitHub 작업을 도와주려면, 먼저 내가 사용하는 개발 환경에서 GitHub 접근 권한이 준비되어 있어야 합니다. 도구마다 연결 방식은 다르므로 수업에서는 특정 에이전트의 설정 절차를 외우지 않습니다. 대신 아래 원칙만 지킵니다.

기본 확인 명령은 아래 정도면 충분합니다.

gh auth status

GitHub CLI를 처음 설정한다면 GitHub CLI gh auth login 문서를 확인합니다. 토큰을 직접 만들어야 하는 상황이라면 GitHub Personal Access Token 문서를 확인하고, 가능하면 fine-grained token으로 범위를 제한합니다.

에이전트에게는 이렇게 요청할 수 있습니다.

내가 사용하는 에이전트 환경에서 GitHub repo에 접근할 수 있는지 확인해줘.

확인할 것:
1. gh auth status로 GitHub CLI 인증 상태를 확인한다.
2. GitHub CLI가 로그인되어 있지 않으면 어떤 공식 문서를 보면 되는지 알려준다.
3. push나 PR 생성에 필요한 권한이 부족할 수 있는 지점을 알려준다.
4. GitHub token 값은 절대 출력하거나 파일에 저장하지 않는다.

GitHub 작업은 저장소가 여러 위치에 있다는 점부터 이해해야 합니다.

이번 실습은 fork 방식으로 진행합니다. 원본 수업 repo를 직접 수정하지 않고, 먼저 내 GitHub 계정으로 fork한 뒤 내 fork를 clone합니다.

1. nxtcloud-edu/ai-workflow-classroom을 엽니다.
2. GitHub 화면에서 Fork를 누릅니다.
3. Owner를 내 GitHub 계정으로 선택합니다. 예시는 dxm-glen 계정으로 진행합니다.
4. 생성된 내 fork 주소를 확인합니다.

업스트림: https://github.com/nxtcloud-edu/ai-workflow-classroom
내 fork: https://github.com/{github-id}/ai-workflow-classroom

이제 내 fork를 로컬로 clone합니다. origin은 내 fork이고, upstream은 원본 수업 repo입니다.

git clone https://github.com/{github-id}/ai-workflow-classroom.git
cd ai-workflow-classroom
git remote -v
git remote add upstream https://github.com/nxtcloud-edu/ai-workflow-classroom.git
git remote -v
git status

리모트 확인 명령어는 git remote -v입니다. clone 직후에는 보통 origin만 보이고, upstream을 추가한 뒤 다시 실행하면 내 fork와 원본 수업 repo가 함께 보입니다.

작업은 반드시 브랜치에서 시작합니다. 수업용 공통 repo에서는 브랜치 이름에 코호트, 유저명, 사용 에이전트, 작업 내용을 함께 남깁니다. {cohort}에는 수업 또는 기수를 구분하는 값을 넣습니다. 예를 들어 국민대 AI Workflow 수업이라면 kookmin-univ-ai-agent처럼 사용할 수 있습니다.

git fetch upstream
git switch -c {cohort}/{유저명}/{사용에이전트}/add-member-note

이 명령도 직접 외워서 입력하는 것이 목표가 아닙니다. 내가 무엇을 하려는지 이해하고, 에이전트에게 안전하게 확인하고 실행하도록 요청할 수 있어야 합니다.

현재 로컬 repo에서 PR 실습용 브랜치를 만들려고 한다.

목표:
원본 수업 repo의 최신 상태를 가져오고, 내 작업용 브랜치를 만든다.

작업:
1. `git remote -v`로 `origin`과 `upstream`이 올바르게 연결되어 있는지 확인한다.
2. `git status`로 아직 커밋하지 않은 변경이 있는지 확인한다.
3. 변경 중인 파일이 있으면 멈추고 나에게 먼저 보고한다.
4. 문제가 없으면 `git fetch upstream`을 실행한다.
5. 아래 형식으로 새 브랜치를 만든다.
   `{cohort}/{유저명}/{사용에이전트}/add-member-note`
6. `git branch --show-current`로 현재 브랜치를 확인한다.
7. 개인 LLM-Wiki를 사용한다면, 만든 브랜치 이름을 `progress.md`에 기록할 수 있도록 한 줄 요약을 제안한다.

주의:
- 아직 commit, push, PR 생성은 하지 않는다.
- GitHub token이나 인증 정보는 출력하지 않는다.

아래 화면은 에이전트에게 브랜치 생성 작업을 맡기는 예시입니다. 실제 수업에서는 {cohort} 자리에 해당 수업 식별자를 넣습니다.

브랜치는 작업 의도를 분리하는 공간입니다. 이름만 봐도 누가, 어떤 에이전트와, 무엇을 하려는지 알 수 있어야 합니다.

처음 PR은 모든 사람이 같은 형식으로 만들 수 있어야 합니다. 이번에는 자유 기여가 아니라, 각자 자신의 PR 실습 기록 파일을 하나 만듭니다.

fork해서 clone한 뒤에는 각자 자기 GitHub 저장소와 로컬 폴더에서 작업하므로, 그 자체로는 서로 충돌하지 않습니다. 충돌이 생길 수 있는 지점은 여러 PR이 다시 원본 upstream에 합쳐질 때입니다. 그래서 수업용 공통 repo에서는 처음에 자기 파일만 수정합니다. 이렇게 하면 30명에서 50명이 동시에 PR을 올려도 같은 파일을 건드릴 가능성이 낮아집니다.

팀별 프로젝트 repo에서도 나중에는 같은 방식을 사용합니다. 하지만 지금은 모두가 자기 파일 하나만 만들거나 수정해서, upstream 병합 충돌 가능성을 낮춘 상태로 PR 사이클을 한 번 완주하는 데 집중합니다. {cohort}는 브랜치에서 사용한 값과 같게 맞춥니다.

에이전트에게는 아래처럼 요청합니다.

수업용 repo에 내 PR 실습 기록 파일을 만들어줘.

할 일:
1. 현재 브랜치와 `git status`를 확인한다.
2. GitHub ID와 사용 중인 에이전트 이름을 확인한다.
3. `cohorts/{cohort}/members/{github-id}.md` 파일을 만든다.
4. 아래 형식으로 간단히 작성한다.

형식:
# {github-id}의 PR 실습 기록

## 사용한 에이전트
- {agent}

## 이번 실습에서 한 일
- 수업용 repo를 fork/clone하고 PR 실습용 브랜치에서 내 기록 파일을 만들었다.

## 배운 점
- AI와 함께 작업하더라도 브랜치, 커밋, PR로 변경 맥락을 남겨야 협업할 수 있다.

주의:
- 내 파일만 수정한다.
- 민감정보는 쓰지 않는다.
- 작업 후 `git diff`를 보여준다.
- 내가 승인하기 전에는 commit, push, PR은 하지 않는다.

결과 파일은 아래처럼 짧게 남기면 됩니다.

# {github-id}의 PR 실습 기록

## 사용한 에이전트
- {agent}

## 이번 실습에서 한 일
- 수업용 repo를 fork/clone하고 PR 실습용 브랜치에서 내 기록 파일을 만들었다.

## 배운 점
- AI와 함께 작업하더라도 브랜치, 커밋, PR로 변경 맥락을 남겨야 협업할 수 있다.

개인 LLM-Wiki를 함께 사용하는 경우에는 작은 변경을 만든 뒤 progress.md에도 작업 내용을 업데이트합니다. 팀 repo에는 팀이 함께 볼 결과를 남기고, 개인 위키에는 내가 다음 작업을 이어가기 위한 맥락을 남깁니다.

커밋은 변경 내용을 저장하는 단위입니다. 좋은 커밋은 무엇을 바꿨는가뿐 아니라 왜 바꿨는가를 짧게 남깁니다.

git status
git diff
git add <changed-file>
git commit -m "docs: {cohort} {github-id} {agent} 실습 기록 추가"
git push -u origin <branch-name>

에이전트에게 맡길 때는 아래처럼 요청합니다.

방금 만든 내 PR 실습 기록 파일을 커밋하고 내 fork로 push해줘.

할 일:
1. `git status`로 변경 파일을 확인한다.
2. `git diff`로 변경 내용을 검토한다.
3. 변경 파일이 `cohorts/{cohort}/members/{github-id}.md` 하나인지 확인한다.
4. 민감정보가 들어 있지 않은지 확인한다.
5. 문제가 없으면 해당 파일만 `git add`한다.
6. 아래 형식으로 커밋한다.
   `docs: {cohort} {github-id} {agent} 실습 기록 추가`
7. 현재 브랜치를 `origin`에 push한다.

주의:
- `upstream`에는 직접 push하지 않는다.
- 내가 요청하기 전에는 PR을 만들지 않는다.
- 문제가 있으면 commit 전에 멈추고 보고한다.

여기서 origin은 내 fork입니다. push한 뒤 GitHub에서 PR을 만들 때는 내 fork의 브랜치에서 nxtcloud-edu/ai-workflow-classroom의 기준 브랜치로 보내는 PR을 만듭니다.

Fork 기반 협업에는 여러 방식이 있습니다. upstream에 직접 브랜치를 만들 권한이 있는 팀이라면 원본 repo 안에서 브랜치를 만들고 PR을 열 수도 있고, 혼자 쓰는 repo라면 작업 브랜치를 main에 직접 merge할 수도 있습니다.

하지만 이번 워크숍에서는 여러 사람이 같은 upstream repo에 PR을 보내는 상황을 기준으로 삼습니다. 이 경우 내 fork의 main에 먼저 merge하지 않고, 아래 흐름으로 진행합니다.

내 로컬 작업 브랜치
  -> origin의 같은 작업 브랜치로 push
  -> origin 작업 브랜치에서 upstream/main으로 PR
  -> 강의자 또는 maintainer가 upstream에서 review/merge
  -> 이후 내 fork를 upstream 최신 상태로 sync

즉 내 fork는 작업을 준비하고 PR을 보내는 공간입니다. 팀의 공식 기록은 upstream/main에 merge될 때 갱신됩니다. 내 fork의 main은 나중에 upstream/main을 따라가도록 동기화하면 됩니다.

PR은 팀이 변경을 검토할 수 있게 묶은 문맥입니다. AI가 만든 산출물을 그대로 밀어 넣는 것이 아니라, 사람이 검토할 수 있는 설명을 붙입니다.

PR 설명은 아래 형식을 사용합니다.

## 변경 요약
-

## 변경 이유
-

## 검토 포인트
-

## 사용한 에이전트
-

## 개인 LLM-Wiki 기록(선택)
-

## 남은 질문
-

## 확인한 것
- [ ] 민감정보가 없다
- [ ] 출처나 참고 링크가 필요한 곳에 남아 있다
- [ ] 내 파일만 수정했다

GitHub 접근 권한과 gh 설정이 되어 있는 에이전트라면 PR 생성도 맡길 수 있습니다. 다만 PR은 팀 기록으로 남기 때문에, 생성 전에 base, head, 제목, 본문을 먼저 확인받게 합니다.

방금 push한 현재 브랜치로 PR을 만들어줘.

기준:
- base repository: nxtcloud-edu/ai-workflow-classroom
- base branch: main
- head repository: 내 fork(origin)
- head branch: 현재 브랜치
- 제목: docs: {cohort} {github-id} {사용에이전트} 실습 기록 추가

본문에는 아래 항목을 포함해줘.
- 변경 요약
- 사용한 에이전트
- AI에게 맡긴 일
- 사람이 검토한 것
- 개인 LLM-Wiki에 남긴 기록(선택)
- 확인한 것

주의:
- PR을 만들기 전에 base/head, 제목, 본문을 먼저 보여주고 승인을 받는다.
- upstream에는 직접 push하지 않는다.
- PR 생성 후 URL을 보고한다.

개인 LLM-Wiki를 함께 사용하는 경우에는 PR을 만든 뒤 URL을 복사해 progress.md에 남깁니다.

git log --oneline
git revert <commit-hash>

PR은 통과 의례가 아닙니다. AI와 함께 작업할수록 PR 검토는 더 중요해집니다. AI는 요청한 파일 외의 내용을 함께 바꾸거나, 팀의 표현 방식과 맞지 않는 문장, 과한 설명, 불필요한 자동 생성 흔적을 남길 수 있습니다.

다만 이 단계에서 모든 사람이 별도의 자동화까지 직접 만들 필요는 없습니다. 이번 Lab에서는 PR 목록과 diff를 함께 보며, 검토 기준이 어떻게 적용되는지 소개합니다. 개별 프로젝트에서는 필요에 따라 자동화된 리뷰 도구를 추가할 수 있습니다.

수강생은 자기 fork에서 PR을 보냅니다. 하지만 팀의 공식 repo인 upstream에서는 관리자가 모든 PR을 한곳에서 확인합니다. 강의자는 upstream 관리자 계정으로 열린 PR 목록을 확인하고, 필요한 리뷰 코멘트를 남긴 뒤 merge합니다.

리뷰는 말로만 확인하는 절차가 아닙니다. 누가 어떤 기준으로 승인했는지, 어떤 커밋이 언제 upstream에 merge되었는지 기록으로 남습니다.

merge가 끝난 PR은 열린 작업이 아니라 닫힌 기록으로 이동합니다. 수업이 반복될수록 이 목록은 기수별 작업과 리뷰 이력이 쌓이는 공동 기록이 됩니다.

PR merge 후 내 fork와 로컬 최신화하기

PR이 upstream에 merge된 것을 확인하면, 팀의 공식 기록인 upstream/main이 먼저 바뀐 상태입니다. 여기에 관리자가 코호트 안내 파일을 추가하거나, 다른 참여자의 PR이 먼저 merge되면 upstream/main은 내 fork와 로컬보다 더 앞선 상태가 됩니다.

이때 작업 브랜치에서 계속 작업하지 않고, 로컬 main을 upstream 최신 상태로 맞춘 뒤 내 fork의 main도 함께 동기화합니다.

git switch main
git fetch upstream
git merge --ff-only upstream/main
git push origin main

각 명령의 의미는 아래와 같습니다.

에이전트에게 맡길 때는 아래처럼 요청할 수 있습니다.

PR이 upstream에 merge된 것을 확인했다. 내 fork와 로컬 main을 최신 상태로 맞춰줘.

작업:
1. `git status`로 현재 변경 사항이 남아 있는지 확인한다.
2. 변경 사항이 남아 있으면 멈추고 먼저 나에게 보고한다.
3. 깨끗하면 `git switch main`으로 이동한다.
4. `git fetch upstream`으로 원본 수업 repo의 최신 기록을 가져온다.
5. `git merge --ff-only upstream/main`으로 로컬 main을 최신화한다.
6. `git push origin main`으로 내 fork의 main도 최신화한다.
7. `git log --oneline --decorate -5`로 최신 커밋을 보여준다.

주의:
- `--ff-only`가 실패하면 강제로 해결하지 말고 멈춘다.
- 작업 브랜치를 삭제하지 않는다.
- upstream에는 직접 push하지 않는다.

검토 기준은 도구보다 먼저 정해야 합니다. 도구는 기준을 대신 만들어주지 않습니다. 팀이 무엇을 좋은 변경으로 볼지 정해야 에이전트 리뷰도 의미가 생깁니다.

접근 가능한 에이전트에게 리뷰를 맡길 때는 아래처럼 요청할 수 있습니다.

이 PR을 리뷰해줘.

목표:
AI가 만든 변경 중 팀 컨벤션과 맞지 않는 부분을 찾아낸다.

검토 기준:
1. 파일이 정해진 코호트/참여자 경로에 있는지 확인한다.
2. PR 제목과 커밋 메시지에 수업명, 참여자, 사용한 에이전트가 드러나는지 확인한다.
3. 불필요한 자동 생성 문장, 과장 표현, 홍보성 문장을 찾는다.
4. 민감정보나 내부 정보가 포함되어 있지 않은지 확인한다.
5. 출처 없이 단정한 문장이 있는지 확인한다.

출력:
- 반드시 수정해야 할 것
- 수정하면 더 좋아지는 것
- 그대로 둬도 되는 것
- 내가 승인한 항목만 실제 파일에 반영한다

자동화나 외부 서비스를 사용할 때는 권한 범위를 먼저 확인합니다. 특히 private repo, 고객 데이터, 내부 문서가 포함된 저장소라면 어떤 코드와 기록이 외부 서비스에 제공되는지 확인해야 합니다. 리뷰 도구는 보조 수단이고, 최종 승인과 병합 책임은 여전히 사람에게 있습니다.

수정이 필요하다면 기존 기록을 지우는 방식보다, 리뷰 의견에 따라 새 커밋을 추가하는 방식이 좋습니다.

git status
git diff
git add <reviewed-file>
git commit -m "docs: PR 리뷰 반영 및 컨벤션 정리"
git push

협업 기준은 별도의 긴 실습으로 만들지 않습니다. 공용 repo의 README.md, docs/pr-guide.md, docs/team-rules.md를 확인하고, 실제로 올라오는 PR 목록을 함께 보면서 기준이 어떻게 적용되는지 확인합니다.

마지막 단계는 새 기능을 더 만드는 시간이 아닙니다. 지금까지 만든 작업물, 브랜치, 커밋, PR, upstream 동기화 상태를 정리하고, 다음에 에이전트가 이어서 읽을 수 있는 개인 맥락으로 남기는 권장 단계입니다.

GitHub PR 사이클만 수행해도 Lab 04의 필수 실습은 완료됩니다. 개인 LLM-Wiki를 사용하는 사람은 이 단계에서 팀 기록과 개인 기록을 연결해 둡니다.

에이전트에게는 아래처럼 요청할 수 있습니다.

현재 작업물과 Git 상태를 파악해서 개인 LLM-Wiki에 남길 진행 기록 초안을 만들어줘.

대상:
- 팀 repo: 현재 로컬 GitHub repo
- 개인 LLM-Wiki: {LLM-Wiki 경로}
- 기록 파일: 10-projects/{project-name}/progress.md

확인할 것:
1. 현재 브랜치
2. 최근 커밋
3. 내가 수정하거나 추가한 파일
4. PR URL과 merge 여부
5. upstream/main과 origin/main 동기화 여부
6. 다음 작업에서 먼저 읽어야 할 파일

작성할 기록:
- 오늘 팀 repo에 남긴 공식 기록
- 내가 이해한 작업 맥락
- 브랜치, 커밋, PR URL
- 다음에 에이전트에게 먼저 읽힐 파일
- 남은 TODO나 주의할 점

주의:
- 민감정보, 토큰, 개인 인증 정보는 기록하지 않는다.
- GitHub repo의 파일은 수정하지 말고, 개인 LLM-Wiki 기록만 제안한다.
- LLM-Wiki 경로를 모르겠으면 먼저 나에게 물어본다.
- 기록 초안을 보여준 뒤, 내가 승인하면 progress.md에 반영한다.