팀 협업 워크플로우: 3~5명 팀 프로젝트에서 Claude Code 함께 쓰기

한 줄 요약

CLAUDE.md로 팀 규칙을 공유하고, Git worktree로 충돌 없이 병렬 개발하며, 주간 회고와 표준화된 배포 프로세스로 팀 전체의 Claude Code 활용 수준을 함께 높인다.

대상 독자

3~5명 팀 프로젝트에서 팀장을 맡아 협업 체계를 잡아야 하는 학생
"각자 Claude Code를 다르게 쓰다 보니 코드 스타일이 제각각"인 팀의 팀원
Git 충돌로 인한 야근을 없애고 싶은 개발자
팀원들이 Claude Code 사용법을 몰라 혼자만 쓰고 있는 상황의 학생

핵심 워크플로우

팀 협업의 4가지 축

1. CLAUDE.md      → 팀 규칙·컨벤션 공유 (1회 설정, 지속 유지)
2. Git Worktree   → 충돌 없는 병렬 개발 (매 기능마다)
3. 주간 회고(retro) → 팀 속도·품질 개선 (매주 반복)
4. 배포 표준화    → setup-deploy + land-and-deploy (일관된 배포)

단계 1 — CLAUDE.md로 팀 규칙 공유 (1회 설정)

팀 프로젝트 시작 시 팀장이 CLAUDE.md를 작성해 레포에 커밋한다. 이후 팀원이 Claude Code를 실행하면 이 파일을 자동으로 읽어 동일한 규칙이 적용된다.

bash

# 프로젝트 루트에 CLAUDE.md 생성
claude

> 다음 팀 규칙을 CLAUDE.md로 정리해줘:
> - 언어: 한국어 주석, 영어 변수명
> - 스타일: TypeScript strict, any 금지, 2 spaces
> - 스택: Next.js 15 App Router, Supabase, Tailwind CSS, shadcn/ui
> - 브랜치 전략: main(보호), develop, feature/[이름]-[기능]
> - 커밋 메시지: 한국어 Conventional Commits (feat/fix/chore/docs)
> - PR: 머지 전 리뷰어 1명 승인 필수
> - 금지: console.log 프로덕션 코드, CSS 하드코딩 색상, magic number

생성된 CLAUDE.md 핵심 섹션 예시:

markdown

# 동아리 게시판 팀 프로젝트 규칙

## 기술 스택
- Next.js 15 (App Router, Server Component 우선)
- TypeScript 5 (strict mode, any 금지)
- Supabase (SSR 클라이언트 패턴 사용)
- Tailwind CSS + shadcn/ui (className 유틸리티만 사용)

## 코드 컨벤션
- 들여쓰기: 2 spaces
- 변수/함수: camelCase
- 컴포넌트: PascalCase
- 상수: UPPER_SNAKE_CASE
- 파일명: camelCase.ts, PascalCase.tsx

## 브랜치 전략
- main: 프로덕션 (직접 push 금지)
- develop: 통합 테스트
- feature/[이름]-[기능]: 개인 개발 브랜치
  예: feature/minsu-notice-crud

## 커밋 메시지 (한국어)
- feat: 새 기능
- fix: 버그 수정
- refactor: 리팩토링 (기능 변화 없음)
- docs: 문서
- chore: 빌드·설정

## 금지 사항
- any 타입
- console.log (프로덕션 코드)
- 하드코딩 색상값 (#fff, rgb(...))
- main 브랜치 직접 push

단계 2 — Git Worktree로 충돌 없는 병렬 개발 (using-git-worktrees)

각 팀원이 동시에 다른 기능을 개발할 때 Git worktree를 사용하면 브랜치 전환 없이 독립된 작업 디렉토리에서 개발할 수 있다.

bash

# 팀장이 기능별 worktree 설정 안내
> /skill using-git-worktrees
> 4명 팀이 동시에 다음 기능을 개발할 수 있도록 worktree를 설정해줘:
> - 민수: 공지 CRUD
> - 지수: 댓글 기능
> - 준혁: 파일 첨부
> - 태리: 인증 페이지

워크트리 설정 명령어:

bash

# develop 브랜치에서 각 기능 브랜치 생성
git checkout develop

# 각 팀원의 feature 브랜치 + worktree 생성
git worktree add ../club-board-notice feature/minsu-notice-crud
git worktree add ../club-board-comment feature/jisu-comment
git worktree add ../club-board-upload feature/junhyuk-file-upload
git worktree add ../club-board-auth feature/taeri-auth-page

# 각 팀원은 자신의 worktree 디렉토리에서 작업
cd ../club-board-notice
claude
> 공지 CRUD 기능을 구현해줘. (CLAUDE.md 규칙 자동 적용)

Worktree의 장점:

각 기능 브랜치가 독립된 디렉토리 → git stash 불필요
동시에 여러 Claude Code 세션 실행 가능
한 기능의 빌드 에러가 다른 기능 개발에 영향 없음
베이스 브랜치와 비교가 쉬움 (git diff develop...HEAD)

Worktree 상태 확인:

bash

git worktree list
# 출력 예시:
# /c/Users/team/club-board          abc1234  [develop]
# /c/Users/team/club-board-notice   def5678  [feature/minsu-notice-crud]
# /c/Users/team/club-board-comment  ghi9012  [feature/jisu-comment]

단계 3 — 체크포인트로 세션 이어받기 (checkpoint)

팀원 간에 세션을 이어받거나, 다음 날 작업을 재개할 때 checkpoint 스킬을 사용한다.

bash

# 퇴근 전 체크포인트 저장
> /skill checkpoint
> 오늘 작업한 내용을 체크포인트로 저장해줘:
> - 완료: 공지 목록 GET API, NoticeCard 컴포넌트 기본 구조
> - 진행 중: 공지 상세 페이지 (app/notices/[id]/page.tsx 50% 완성)
> - 내일 할 일: 댓글 API + 공지 삭제 권한 체크
> - 막힌 부분: Supabase join 쿼리 타입이 안 맞음

checkpoint 스킬이 생성하는 세션 요약:

markdown

## 세션 체크포인트 - 2026-04-12

### 완료 항목
- [x] GET /api/notices (페이지네이션 포함)
- [x] NoticeCard 컴포넌트 (타입 안전, 날짜 포맷 포함)

### 진행 중
- [ ] app/notices/[id]/page.tsx — Supabase join 쿼리 타입 문제
  현재 코드: `supabase.from('notices').select('*, users(name)')`
  문제: 반환 타입에서 users가 배열로 추론됨

### 내일 할 일
1. join 쿼리 타입 수정 (supabase-js v2 타입 생성 재실행)
2. DELETE /api/notices/[id] (작성자 권한 확인 포함)
3. 댓글 API 시작

### 팀원 인계 사항
- `lib/supabase/types.ts`를 `pnpm supabase gen types` 후 업데이트 필요
- `.env.local`의 SUPABASE_SERVICE_ROLE_KEY 확인 필요

단계 4 — 주간 회고 (retro)

매주 금요일 또는 스프린트 종료 시 팀 전체가 retro 스킬로 회고를 진행한다.

bash

> /skill retro
> 이번 주 팀 회고를 진행해줘.
>
> 이번 주 완료한 작업:
> - 공지 CRUD API 완성
> - 댓글 기능 60% 완성
> - Vercel 스테이징 배포 성공
>
> 발생한 문제:
> - 목요일 merge conflict로 2시간 낭비
> - 빌드 에러가 main에 머지됨 (CI가 없어서 발견 못함)
> - 공지 삭제 권한 체크 누락 (QA에서 발견)
>
> 팀 분위기:
> - 진도는 잘 나가고 있음
> - 코드 리뷰 시간이 너무 오래 걸림 (평균 1.5시간)

retro 스킬이 생성하는 회고 보고서:

markdown

## 주간 회고 - 2026-04-08 ~ 04-12

### Well (잘된 것)
- Vercel 스테이징 배포 첫 성공 → CI 기반 구축 완료
- 공지 CRUD API 예정보다 하루 빨리 완성

### Problem (문제)
1. **Merge Conflict** (심각도: 높음)
   원인: develop 브랜치 동기화 없이 3일간 독립 개발
   → 해결책: 매일 아침 `git rebase develop` 실행 규칙 추가

2. **CI 없는 main 머지** (심각도: 높음)
   원인: GitHub Actions 없이 수동 머지
   → 해결책: 다음 주까지 `pnpm build` CI 파이프라인 추가

3. **권한 체크 누락** (심각도: 중간)
   원인: CRUD 구현 시 인증 테스트 생략
   → 해결책: API 라우트 PR 체크리스트에 "인증 테스트" 항목 추가

### Try (다음 주 시도)
- [ ] GitHub Actions CI 파이프라인 추가 (빌드 + 타입 체크)
- [ ] 매일 아침 standup 5분 + develop rebase
- [ ] PR 크기 제한: 파일 10개 이하

단계 5 — 배포 프로세스 표준화 (setup-deploy + land-and-deploy)

팀 프로젝트에서 배포는 한 명이 전담하지 않고 누구나 할 수 있게 표준화한다.

bash

# 최초 배포 환경 설정 (팀장, 1회)
> /skill setup-deploy
> Vercel + GitHub Actions로 자동 배포 파이프라인을 설정해줘.
> - main 브랜치 push → 프로덕션 자동 배포
> - develop 브랜치 push → 스테이징 자동 배포
> - PR 생성 → Preview 배포 URL 자동 생성
> 환경변수 목록도 Vercel 대시보드 등록 가이드와 함께 만들어줘.

bash

# 배포 실행 (팀원 누구나)
> /skill land-and-deploy
> develop → main 머지 후 프로덕션 배포 체크리스트를 실행해줘.
> 배포 전 확인: pnpm build 성공, 스테이징 smoke test 통과
> 배포 후 확인: 주요 페이지 응답 200, 공지 CRUD 동작 확인

표준화된 배포 체크리스트 (setup-deploy 산출물):

markdown

## 프로덕션 배포 체크리스트

### 배포 전 (필수)
- [ ] `pnpm build` 로컬 성공
- [ ] `pnpm tsc --noEmit` 타입 에러 없음
- [ ] 스테이징 URL smoke test 통과
- [ ] 팀원 1명 이상 PR 승인
- [ ] 환경변수 변경 사항 Vercel에 반영

### 배포 실행
```bash
git checkout main
git merge develop --no-ff -m "chore: develop → main 머지 (배포)"
git push origin main
# GitHub Actions 자동 배포 트리거

배포 후 (10분 내)

[ ] Vercel 배포 로그 에러 없음 확인
[ ] https://club-board.vercel.app/notices → 200 응답
[ ] 로그인 → 공지 작성 → 댓글 → 로그아웃 smoke test
[ ] Supabase 대시보드 Active Connections 정상 범위


---

## 실전 시나리오

**상황**: 4명 팀 (민수, 지수, 준혁, 태리)의 역할 분담, 브랜치 전략, 주간 리뷰 사이클

### 팀 구성 및 역할 분담

| 팀원 | 역할 | 담당 기능 | Worktree 경로 |
|---|---|---|---|
| 민수 (팀장) | 풀스택 | 공지 CRUD + 배포 | `../club-board-notice` |
| 지수 | 프론트 | 댓글 + 파일 UI | `../club-board-comment` |
| 준혁 | 백엔드 | 파일 API + 스토리지 | `../club-board-upload` |
| 태리 | 풀스택 | 인증 + 권한 | `../club-board-auth` |

### 1주차: 기반 세팅

```bash
# 민수 (팀장) — 킥오프 세션
claude

# 1. CLAUDE.md 작성
> 팀 규칙 CLAUDE.md를 생성해줘. (위 내용 참조)

# 2. 초기 프로젝트 스캐폴딩
> /skill setup-deploy
> Vercel + Supabase + Next.js 15 초기 배포 환경을 설정해줘.

# 3. 팀원용 개발 가이드 작성
> CONTRIBUTING.md를 만들어줘.
> 내용: 로컬 설정 방법, Worktree 사용법, PR 절차, 커밋 규칙

2주차: 병렬 개발

bash

# 각 팀원이 자신의 worktree에서 독립 개발

# 민수 워크트리에서
cd ../club-board-notice
claude
> /skill executing-plans
> PLAN.md의 공지 CRUD 항목을 순서대로 구현해줘.

# 지수 워크트리에서 (동시에)
cd ../club-board-comment
claude
> 댓글 API와 CommentList 컴포넌트를 구현해줘.
> CLAUDE.md의 TypeScript strict 규칙을 엄격히 따라줘.

# 준혁 워크트리에서 (동시에)
cd ../club-board-upload
claude
> Supabase Storage를 사용한 파일 업로드 API를 구현해줘.
> 허용 파일 타입: PDF, 이미지 (최대 10MB)

매주 금요일: 주간 리뷰 사이클

bash

# 팀 전체 세션 (팀원 중 1명이 대표로 실행)
claude

# 1. 이번 주 완료/미완료 점검
> /skill retro
> 이번 주 팀 작업 현황과 문제점을 회고해줘. [현황 입력]

# 2. 다음 주 계획 재조정
> /skill writing-plans
> 회고 결과를 반영해서 다음 주 PLAN.md를 업데이트해줘.

# 3. develop → main 머지 여부 결정
> /skill ship
> 현재 develop 브랜치가 배포 가능한지 점검해줘.

마감 전주: 최종 스프린트

bash

# D-7: 전체 기능 통합 테스트
> /skill verification-before-completion
> 각 기능 브랜치를 develop에 머지한 후 전체 통합 테스트를 실행해줘.
> 예상 충돌 지점: lib/supabase/types.ts, tailwind.config.ts

# D-3: 스테이징 배포
> /skill ship
> 스테이징 배포 체크리스트를 실행해줘.

# D-1: 프로덕션 배포
> /skill land-and-deploy
> 프로덕션 배포 체크리스트를 실행해줘.

# D-0: 발표 자료
> /skill document-release
> 팀원 기여도 섹션을 포함한 발표용 문서를 만들어줘.

용도	스킬	타이밍
팀 규칙 설정	`CLAUDE.md 작성`	프로젝트 시작 (1회)
병렬 개발	`using-git-worktrees`	기능 개발마다
세션 인계	`checkpoint`	퇴근 전 / 세션 종료 시
주간 회고	`retro`	매주 금요일
배포 설정	`setup-deploy`	최초 배포 설정 (1회)
배포 실행	`land-and-deploy`	매 배포마다
종합 점검	`review`	PR 머지 전

주의사항

자주 하는 실수

CLAUDE.md를 팀원에게 안 알림: 파일만 만들고 팀원에게 "Claude Code 열면 이 파일 자동으로 적용된다"고 알려주지 않으면 팀원들이 여전히 각자의 규칙으로 코드를 작성한다.
Worktree 사용하다가 베이스 브랜치와 너무 멀어짐: worktree에서 3일 이상 작업하면 develop과 diff가 커진다. 매일 아침 git rebase develop을 의무화한다.
배포 권한을 팀장만 가짐: "민수만 배포할 줄 안다"는 상황은 팀장 부재 시 배포 불가 상태를 만든다. setup-deploy로 배포 가이드를 만들어 팀원 모두가 배포할 수 있게 한다.
회고를 건너뜀: "바쁘니까 retro 이번 주는 패스"가 쌓이면 팀 문제가 누적된다. 금요일 5분 회고라도 반드시 진행한다.
checkpoint 없이 긴 세션 진행: 2시간 이상 Claude Code 세션을 진행하면 컨텍스트 창이 길어져 응답 품질이 떨어진다. 1시간마다 checkpoint를 저장하고 새 세션에서 이어간다.

팁

PR 크기를 10개 파일 이하로 제한: 큰 PR은 리뷰가 느리고 충돌이 많다. 기능을 작게 나눠 PR을 자주 올린다.
Worktree 정리 자동화: 기능 완성 후 git worktree remove ../club-board-notice로 정리하지 않으면 디스크가 낭비된다. 머지 완료 후 즉시 정리한다.
팀 CLAUDE.md 버전 관리: 팀 규칙이 바뀌면 CLAUDE.md를 업데이트하고 커밋에 chore: CLAUDE.md 팀 규칙 업데이트 메시지를 남긴다. 팀원들이 변경 이력을 추적할 수 있다.
Claude Code를 "쌍둥이 리뷰어"로: 팀원이 Claude Code를 독립적으로 쓰다 보면 각자 다른 패턴을 익힌다. 주간 회고에서 "이 스킬을 이렇게 썼더니 좋았다"는 사례를 공유하면 팀 전체 활용 수준이 올라간다.

항목	내용
원본 URL	https://docs.anthropic.com/en/docs/claude-code
라이선스	CC BY 4.0
해설 작성일	2026-04-12
작성자	Claude-Code-Study 프로젝트

팀 협업 워크플로우: 3~5명 팀 프로젝트에서 Claude Code 함께 쓰기 ​

한 줄 요약 ​

대상 독자 ​

핵심 워크플로우 ​

팀 협업의 4가지 축 ​

단계 1 — CLAUDE.md로 팀 규칙 공유 (1회 설정) ​

단계 2 — Git Worktree로 충돌 없는 병렬 개발 (using-git-worktrees) ​

단계 3 — 체크포인트로 세션 이어받기 (checkpoint) ​

단계 4 — 주간 회고 (retro) ​

단계 5 — 배포 프로세스 표준화 (setup-deploy + land-and-deploy) ​

배포 후 (10분 내) ​

2주차: 병렬 개발 ​

매주 금요일: 주간 리뷰 사이클 ​

마감 전주: 최종 스프린트 ​

추천 스킬 조합 ​

주의사항 ​

자주 하는 실수 ​

팁 ​

팀 협업 워크플로우: 3~5명 팀 프로젝트에서 Claude Code 함께 쓰기

한 줄 요약

대상 독자

핵심 워크플로우

팀 협업의 4가지 축

단계 1 — CLAUDE.md로 팀 규칙 공유 (1회 설정)

단계 2 — Git Worktree로 충돌 없는 병렬 개발 (using-git-worktrees)

단계 3 — 체크포인트로 세션 이어받기 (checkpoint)

단계 4 — 주간 회고 (retro)

단계 5 — 배포 프로세스 표준화 (setup-deploy + land-and-deploy)

배포 후 (10분 내)

2주차: 병렬 개발

매주 금요일: 주간 리뷰 사이클

마감 전주: 최종 스프린트

추천 스킬 조합

주의사항

자주 하는 실수

팁