팀 협업과 운영 베스트 프랙티스

Claude Code는 개인 도구로 시작하지만, 진짜 가치는 팀 전체가 일관된 방식으로 사용할 때 나옵니다. "Claude가 알아서 한다"는 기대와 달리, 팀 환경에서 가장 자주 발생하는 문제는 "Claude가 팀원마다 다른 방식으로 코드를 작성해서 일관성이 무너진다"는 것입니다. 이 강에서는 팀 전체가 Claude Code를 활용하는 운영 시스템을 설계합니다.

팀 CLAUDE.md 공동 소유

CLAUDE.md는 팀의 살아있는 문서입니다. 한 사람이 작성하는 것이 아니라 팀이 함께 관리해야 합니다.

# 팀 CLAUDE.md 운영 원칙
1. 코드 리뷰와 같은 프로세스로 관리 — PR로만 수정
2. 새 패턴 발견 시 즉시 추가 — "나중에"는 없음
3. 오래된 규칙은 삭제 — 지키지 않는 규칙은 없는 것만 못함
4. 팀 회의에서 분기 1회 검토

# CLAUDE.md PR 예시
feat(claude): 결제 모듈 패턴 추가

결제 관련 Server Action 위치와 에러 처리 패턴 명시.
Toss Payments 연동 예시 포함.

+## 결제 모듈
+- Server Action: app/actions/payment.ts
+- Webhook: app/api/webhook/tosspayments/route.ts
+- 에러 코드는 반드시 한국어 메시지로 변환

신규 팀원 온보딩 자동화

# .claude/commands/onboarding.md
신규 팀원 온보딩을 도와줘.

1. 프로젝트 구조 설명
   - 주요 디렉토리와 역할
   - 핵심 파일 5개 소개

2. 로컬 환경 설정 확인
   - Node.js 버전 확인
   - npm install 완료 여부
   - .env.local 필요 키 목록 안내 (.env.example 기준)

3. 첫 번째 작업 추천
   - 현재 GitHub Issues에서 'good first issue' 라벨 찾기
   - 난이도 낮은 이슈 1개 추천

4. 코딩 규칙 퀴즈
   "Server Action에서 관리자 인증은 어떻게 해야 할까요?"
   → 정답: getAdminInfo() 호출 (CLAUDE.md 기준)

팀 설정 파일 계층 관리

# 3계층 설정 구조
# 1. 팀 공유 (git 커밋)
.claude/settings.json      # 팀 공통 권한·훅·MCP 설정
.claude/commands/          # 팀 공통 슬래시 명령
CLAUDE.md                  # 팀 공통 컨텍스트

# 2. 개인 설정 (gitignore)
.claude/settings.local.json  # 개인 MCP 토큰, 개인 권한
.env.local                   # 개인 API 키

# 3. 전역 개인 설정 (모든 프로젝트)
~/.claude/settings.json    # 개인 전역 기본값
~/.claude/commands/        # 개인 전역 슬래시 명령

# .gitignore에 추가
.claude/settings.local.json

팀 코딩 표준 자동 강제

# .claude/settings.json — 팀 표준 자동 적용
{
  "permissions": {
    "allow": [
      "Bash(npm run test*)",
      "Bash(npm run lint*)",
      "Bash(npx tsc*)",
      "Bash(git diff*)",
      "Bash(git log*)"
    ],
    "deny": [
      "Bash(git push origin main*)",
      "Bash(git push --force*)",
      "Bash(rm -rf*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ '$FILE' == *.ts || '$FILE' == *.tsx ]]; then npx eslint '$FILE' --max-warnings 0 --quiet 2>&1 | tail -3; fi"
          }
        ]
      }
    ]
  }
}

팀 Claude Code 활용 지표

# 월간 회고에서 측정할 지표
- PR당 Claude Code 사용 세션 수
- 자동화 슬래시 명령 사용 빈도
- /review 사용 후 사람 리뷰 코멘트 감소율
- 빌드 실패율 변화 (Hooks 도입 전후)

# 팀 레트로 질문
"Claude Code가 가장 도움됐던 작업은?"
"Claude Code를 쓰다가 실수한 경험은?"
"팀 CLAUDE.md에 추가해야 할 규칙은?"

Claude Code 팀 도입 로드맵

1주차: 개인 설치·기본 사용법 공유 (이 과정 1~3강)
2주차: 팀 CLAUDE.md 초안 작성 (기존 코딩 규칙 이전)
3주차: 공통 슬래시 명령 3개 구축 (/review, /pre-pr, /onboarding)
4주차: settings.json Hooks 적용 (저장 시 ESLint 자동)
2개월: GitHub Actions AI 리뷰 적용
3개월: 팀 전체 워크플로우 정착, CLAUDE.md 첫 번째 분기 검토

팀 Claude Code 운영의 핵심은 "AI가 알아서 팀 규칙을 지키게 만드는 것"입니다. 개인이 규칙을 기억하지 않아도, CLAUDE.md와 settings.json이 기억합니다. 팀원이 바뀌어도, 새 팀원이 입사해도, 규칙이 코드화되어 있으면 일관성이 유지됩니다. 이것이 이 과정에서 배운 모든 기법을 팀에 확장하는 최종 목표입니다.

핵심 정리

팀 CLAUDE.md는 PR로만 수정 — 팀 코딩 규칙의 단일 진실 공급원, 분기 1회 정기 검토
설정 3계층: 팀 공유(git 커밋) + 개인(gitignore) + 전역(홈 디렉토리) — 토큰·시크릿은 절대 공유 설정에 포함 금지
도입 로드맵 6주 — 개인 설치 → CLAUDE.md → 슬래시 명령 → Hooks → CI 리뷰 → 정착의 단계적 확장

관련 검색어 · 클로드 코드 팀 협업 · AI 개발 팀 도입 · Claude Code 팀 설정 · 클로드 코드 완벽 마스터 · AI 개발 워크플로우 팀