4-5인 개발팀, Claude Code를 팀 단위로 굴리는 법

"Claude Code 좋다는 건 알겠는데, 팀에서 어떻게 써야 하나요?"

최근 여러 개발팀을 만나면서 가장 많이 받은 질문입니다. 개인이 Claude Code를 쓰는 건 쉽습니다. 터미널에서 claude를 실행하고, 원하는 걸 시키면 됩니다. 문제는 팀입니다. 4-5명이 같은 프로젝트에서 Claude Code를 쓰기 시작하면, 각자 다른 프롬프트를 쓰고, 다른 규칙으로 코드를 생성하고, 서로 다른 결과물을 만들어냅니다. 한 사람이 Claude에게 "ESLint 규칙을 따라줘"라고 매번 말하고, 다른 사람은 그걸 빼먹어서 PR에서 충돌이 납니다.

현업 개발자에게 들어보니, Claude Code를 팀에 도입한 지 한 달쯤 되면 대부분 같은 벽에 부딪힌다고 합니다. "개인 생산성은 올랐는데, 팀 전체의 코드 품질은 오히려 들쭉날쭉해졌다"는 겁니다. Anthropic 공식 문서에도 이런 구절이 있습니다. "가장 성공적인 팀은 Claude를 코드 생성기가 아닌 사고 파트너로 다룹니다." 그런데 사고 파트너도 팀원마다 다르게 훈련시키면 혼란만 커집니다.

이 글에서는 4-5명 규모 팀이 Claude Code를 표준화해서 생산성을 올리는 방법을 정리합니다. 설정 파일의 역할부터 워크플로우 통일, 비용 관리까지 바로 적용할 수 있는 수준으로 썼습니다.

1. 워크스페이스 설계: .claude/ 디렉토리가 팀의 두뇌입니다

Claude Code를 팀에서 쓰려면, 가장 먼저 해야 할 일이 있습니다. .claude/ 디렉토리를 Git에 커밋하는 겁니다. 이 디렉토리가 팀 전체에서 Claude Code를 표준화하는 유일한 방법입니다. 개인 노트북에만 존재하는 설정은 팀 자산이 아닙니다.

팀 프로젝트의 .claude/ 디렉토리는 다음과 같은 구조를 가집니다.

복사
.claude/
  CLAUDE.md              # 프로젝트 전체 컨텍스트
  settings.json          # 팀 공유 설정 (Git 커밋 대상)
  settings.local.json    # 개인 설정 (gitignored)
  rules/                 # 자동 로드 규칙
    frontend/
      react.md
      styles.md
    backend/
      api.md
      database.md
    general.md
  skills/                # 팀 공유 스킬
    review/SKILL.md
    deploy/SKILL.md
    tdd/SKILL.md
  agents/                # 서브에이전트 정의
    code-reviewer.md
    security-checker.md
  hooks/                 # 자동화 훅
    protect-files.sh
    auto-format.sh

각 디렉토리의 역할을 명확히 구분해야 합니다. 이걸 두루뭉술하게 섞어 놓으면, 나중에 유지보수가 안 됩니다. 정리하면 이렇습니다.

rules/는 가장 상위의 거버넌스 계층입니다. 회사 내 공통 보안 정책이나 모든 프로젝트, 작업에 적용되는 전역 컨벤션을 정의합니다. "모든 API 엔드포인트에 입력 유효성 검사를 포함할 것", "console.log 대신 구조화된 로거를 사용할 것" 같은 규칙이 여기 들어갑니다. rules/ 디렉토리의 .md 파일은 세션 시작 시 자동으로 로드됩니다. 별도 호출이 필요 없다는 뜻입니다.

skills/는 반복되는 단위 작업을 워크플로우로 정의합니다. "코드 리뷰 프로세스", "TDD 사이클", "배포 절차"처럼 여러 단계로 구성된 작업을 스킬로 만들어 놓으면, 팀원 누구나 /review나 /deploy를 입력해서 동일한 절차를 밟을 수 있습니다.

agents/는 특정 전문 영역을 독립된 컨텍스트에서 맡아 처리하는 전문가를 정의합니다. "보안 검토 전문가", "성능 분석가" 같은 역할을 가진 에이전트를 만들어 놓으면, 메인 대화 컨텍스트를 오염시키지 않으면서 전문적인 분석 작업을 위임할 수 있습니다.

CLAUDE.md는 이 프로젝트의 구체적인 맥락과 원칙을 담습니다. 폴더 구조, 문서 저장 위치, 기술 스택, 사용 라이브러리 버전, 네이밍 규칙 등 AI가 이 프로젝트에서 작업하기 위해 알아야 하는 모든 가이드라인이 여기 있습니다.

CLAUDE.md의 계층 구조

CLAUDE.md 파일은 한 개가 아닙니다. Claude Code는 계층적으로 여러 CLAUDE.md를 로드합니다. 더 구체적인 지시사항이 포괄적인 지시사항보다 우선합니다.

실전에서 이걸 어떻게 쓰느냐면, 루트 CLAUDE.md에는 프로젝트 공통 사항(커밋 메시지 형식, PR 템플릿, 코딩 표준)을 넣고, packages/frontend/CLAUDE.md에는 React 컴포넌트 패턴이나 스타일 규칙을, packages/backend/CLAUDE.md에는 API 설계 원칙이나 데이터베이스 규칙을 넣습니다.

Expo 웹 팀의 사례가 인상적입니다. 이 팀은 Claude Code를 한 달간 사용한 후 이런 이야기를 했습니다. "CLAUDE.md 파일을 다듬다 보니, Claude를 위한 문서가 아니라 새 팀원 온보딩에도 유용한 살아 있는 문서가 되어 있었습니다." 코드베이스가 실제로 어떻게 작동하는지를 반영하는 문서가 자연스럽게 만들어진 겁니다.

한 가지 주의할 점이 있습니다. Anthropic 공식 문서에서는 CLAUDE.md를 500줄 이내로 유지하라고 권장합니다. 상세한 워크플로우 지시사항은 스킬로 옮기고, CLAUDE.md에는 프로젝트 핵심 맥락만 담아야 합니다. CLAUDE.md가 비대해지면 Claude의 컨텍스트 윈도우를 불필요하게 소모합니다.

조건부 규칙으로 정밀하게 제어하기

rules/ 디렉토리의 규칙 파일은 YAML 프론트매터의 paths 필드를 사용해서, 특정 파일 패턴에만 적용되도록 만들 수 있습니다.

복사
---
paths:
  - "src/api/**/*.ts"
  - "src/models/**/*.ts"
---

백엔드 API 작업 시 다음 규칙을 따르세요.

- RESTful 명명 규칙을 사용합니다.
- 모든 엔드포인트에 요청 유효성 검사를 포함합니다.
- 에러 응답은 {code, message, details} 형식을 따릅니다.
- 데이터베이스 쿼리에는 반드시 인덱스 힌트를 고려합니다.

이렇게 하면 프론트엔드 코드를 수정할 때는 이 규칙이 로드되지 않고, 백엔드 API 코드를 건드릴 때만 자동으로 적용됩니다. 5명이 각각 프론트엔드와 백엔드를 오가면서 작업할 때, 이 조건부 규칙이 없으면 매번 "지금 백엔드 작업 중이니까 이 규칙을 따라줘"라고 프롬프트에 넣어야 합니다. 조건부 규칙은 그 수고를 없앱니다.

2. 스킬 설계: 팀의 워크플로우를 코드화하기

스킬은 Claude Code에서 쓸모가 많은 만큼 관리하기도 까다로운 기능입니다. 스킬을 잘 설계하면 팀의 반복 작업이 표준화되고, 잘못 설계하면 스킬이 폭발적으로 늘어나서 오히려 혼란만 생깁니다.

스킬의 동작 원리

스킬은 점진적 공개 아키텍처를 사용합니다. 세션이 시작되면 Claude는 스킬의 메타데이터(약 100토큰)만 로드합니다. 사용자가 해당 스킬을 호출하면 그때 전체 지시사항(5,000토큰 이내 권장)이 로드되고요. 스킬에 참조 자료가 번들되어 있다면, 필요할 때만 추가로 로드합니다. 이 설계 덕분에 10개, 20개의 스킬을 등록해 놓아도 컨텍스트 윈도우를 압도하지 않습니다.

스킬의 SKILL.md 파일은 다음과 같은 프론트매터를 가질 수 있습니다.

복사
---
name: code-review
description: PR 코드 리뷰를 수행합니다
allowed-tools: Read, Grep, Glob, Bash(git diff *)
model: sonnet
---

## 코드 리뷰 절차

1. 변경된 파일 목록을 확인합니다.
2. 각 파일의 diff를 읽고 다음을 검토합니다.
   - 보안 취약점 (OWASP Top 10)
   - 성능 이슈 (N+1 쿼리, 불필요한 렌더링)
   - 코드 스멜 (매직 넘버, 중복 코드)
   - 테스트 커버리지
3. 발견된 이슈를 심각도별로 분류합니다.
4. 개선 제안과 함께 리뷰 결과를 정리합니다.

allowed-tools로 스킬이 사용할 수 있는 도구를 제한할 수 있습니다. 코드 리뷰 스킬에 Write 권한을 주지 않으면, 리뷰 중에 실수로 코드를 수정하는 일을 막을 수 있습니다. model을 지정하면 해당 스킬을 실행할 때 사용할 모델을 고정합니다. 비용에 민감한 팀이라면, 단순 작업에는 Sonnet을, 복잡한 아키텍처 분석에만 Opus를 지정하는 식으로 쓸 수 있습니다.

스킬 폭발 문제와 통합 전략

주변 개발자에게 들어보니, 스킬 관리에서 가장 흔한 실수는 작업 단위를 너무 잘게 쪼개는 것이라고 합니다. 예를 들어 배포 관련 작업에서 "스테이징 배포", "프로덕션 배포", "롤백", "배포 상태 확인"을 각각 별도 스킬로 만들면, 금방 스킬이 20개, 30개로 불어납니다.

좋은 추상화로 통합하면 됩니다. 위 네 가지 스킬을 하나의 "deploy" 스킬로 통합하고, 세부 절차는 스킬 내부에서 분기하도록 설계합니다. 기존의 세부 작업 명세는 /reference 폴더 아래에 참조 자료로 두면 됩니다.

복사
.claude/skills/
  deploy/
    SKILL.md              # 통합된 배포 스킬
    reference/
      staging-checklist.md
      production-runbook.md
      rollback-procedure.md

스킬을 통합할 때 핵심은, 필요한 정보를 필요한 시점에 꺼내 쓰도록 설계하는 겁니다. SKILL.md에 세부사항을 전부 넣으면 5,000토큰을 훌쩍 넘기거든요. 핵심 분기 로직만 SKILL.md에 넣고, 각 분기에서 필요한 상세 절차는 reference/ 폴더를 참조하도록 설계해야 합니다.

스킬의 호출 제어

팀 환경에서 꼭 알아야 할 설정이 disable-model-invocation입니다.

복사
---
name: deploy
description: 프로덕션 배포를 실행합니다
disable-model-invocation: true
---

이 설정을 켜면, Claude가 판단에 따라 자동으로 이 스킬을 호출하는 것을 막습니다. 사용자가 명시적으로 /deploy를 입력해야만 실행됩니다. 배포, 데이터 마이그레이션, 프로덕션 DB 조회처럼 부작용이 있는 작업에는 반드시 이 설정을 켜야 합니다.

반대로, user-invocable: false 설정을 쓰면 사용자는 직접 호출할 수 없고 Claude만 판단에 따라 호출할 수 있습니다. 레거시 시스템 컨텍스트나 배경 지식을 담은 스킬에 적합합니다. "이 프로젝트의 레거시 결제 시스템은 이런 구조이고 이런 제약이 있다"는 정보를 스킬로 만들어 놓으면, Claude가 관련 작업을 할 때 알아서 참조합니다.

skill-semver로 스킬 버전 관리

팀에서 스킬을 공유하면서 빠지기 쉬운 함정이 있습니다. 누군가 스킬을 수정했는데, 그 변경이 언제, 왜 이루어졌는지 추적할 수 없는 상황입니다. skill-semver 플러그인은 이 문제를 해결합니다.

복사
claude mcp add-json skill-semver '{"type":"stdio","command":"npx","args":["-y","skill-semver"]}'

설치하면 SKILL.md가 수정될 때마다 자동으로 백업이 생기고, 시맨틱 버저닝(MAJOR.MINOR.PATCH)이 적용됩니다. 변경 로그도 자동 생성됩니다.

복사
deploy/
  SKILL.md              # 현재 버전 (v2.1.0)
  CHANGELOG.md          # 변경 이력
  releases/
    v1.0.0_2026-01-15_SKILL.md
    v2.0.0_2026-02-01_SKILL.md
    v2.1.0_2026-02-20_SKILL.md

다만 skill-semver는 아직 초기 단계의 커뮤니티 도구입니다. 프로덕션 워크플로우에 바로 적용하기 전에, 리포지토리의 활동 상태와 이슈를 확인하는 것을 권장합니다. 외부 도구에 의존하고 싶지 않다면, Git 자체만으로도 스킬 이력을 충분히 추적할 수 있습니다. SKILL.md가 .claude/skills/ 아래에 있으므로, git log --follow .claude/skills/deploy/SKILL.md 같은 명령으로 변경 이력을 볼 수 있고, 의미 있는 변경마다 커밋 메시지에 버전을 명시하는 것만으로도 실용적인 관리가 됩니다.

어떤 방법을 쓰든, 스킬이 팀 자산인 이상 버전 관리는 선택이 아닙니다. 특히 배포 스킬이나 DB 마이그레이션 스킬처럼 프로덕션에 영향을 주는 워크플로우는, 누가 언제 어떤 변경을 했는지 반드시 추적해야 합니다.

3. 서브에이전트와 에이전트 팀: 협업의 두 가지 레벨

Claude Code에서 팀 작업을 분담하는 방법은 두 가지가 있습니다. 서브에이전트와 에이전트 팀입니다. 이 둘의 차이를 알아야 상황에 맞게 쓸 수 있습니다.

서브에이전트: 전문가에게 위임하기

서브에이전트는 .claude/agents/ 디렉토리에 마크다운 파일로 정의합니다. 메인 Claude 세션이 필요에 따라 이 에이전트를 호출하면, 서브에이전트는 자체 컨텍스트 윈도우에서 자체 도구 세트로 작업을 수행하고, 결과만 메인 세션에 돌려줍니다.

왜 이게 중요하냐면, 메인 대화의 컨텍스트를 보호할 수 있기 때문입니다. 예를 들어 100개 파일의 보안 취약점을 검사하는 작업을 메인 세션에서 직접 하면, 파일을 읽는 것만으로 컨텍스트 윈도우가 꽉 차버립니다. 서브에이전트에게 위임하면, 서브에이전트가 자기 컨텍스트에서 100개 파일을 읽고 분석한 다음, "이 파일의 이 줄에 SQL 인젝션 위험이 있고, 이 파일에 XSS 취약점이 있다"는 요약만 돌려줍니다. 메인 세션의 컨텍스트는 깨끗하게 유지됩니다.

실전에서 효과적인 서브에이전트 구성 예시입니다.

복사
<!-- .claude/agents/security-reviewer.md -->
# 보안 리뷰 에이전트

당신은 OWASP Top 10에 정통한 보안 전문가입니다.

## 검토 항목
- SQL 인젝션: 파라미터화되지 않은 쿼리
- XSS: 이스케이프 처리되지 않은 사용자 입력 출력
- 인증/인가: 엔드포인트별 권한 검증 누락
- 민감 정보 노출: 하드코딩된 시크릿, 로그에 포함된 개인정보

## 출력 형식
각 발견 사항을 다음 형식으로 보고합니다.
- 파일 경로와 라인 번호
- 취약점 유형
- 심각도 (Critical / High / Medium / Low)
- 수정 제안 (코드 포함)

이 에이전트를 정의해 놓으면, 팀원 누구나 "보안 리뷰 에이전트로 이 PR을 검토해 줘"라고 요청할 수 있고, 동일한 기준으로 보안 검토가 이루어집니다.

에이전트 팀: 여러 Claude가 함께 일하기

에이전트 팀은 서브에이전트보다 한 단계 위의 협업 방식입니다. 현재는 실험적 기능이지만, 복잡한 작업에서 강력한 효과를 보입니다.

서브에이전트는 메인 세션 -> 서브에이전트 -> 결과 반환의 단방향 구조입니다. 에이전트 팀은 다릅니다. 팀 리드가 여러 동료 에이전트를 생성하고, 이 동료들은 공유 작업 목록과 메일박스 시스템을 통해 서로 직접 소통합니다. 서브에이전트가 "지시받고 보고하는" 관계라면, 에이전트 팀은 "함께 논의하고 협업하는" 관계입니다.

다음 그림은 두 구조의 차이를 보여줍니다.

서브에이전트는 메인 세션이 작업을 위임하고 결과를 받는 단방향 구조입니다. 에이전트 팀은 팀 리드가 작업을 분배한 뒤, 동료 에이전트들이 메일박스와 공유 작업 목록을 통해 서로 소통하는 양방향 협업 구조입니다.

활성화는 settings.json에 다음을 추가합니다.

복사
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

실전에서 효과적인 시나리오를 하나 살펴보겠습니다. PR 리뷰를 세 명의 전문가에게 동시에 맡기는 경우입니다.

복사
에이전트 팀을 만들어 PR #142를 리뷰해 주세요.

- 보안 리뷰어: OWASP 기준으로 취약점을 검토합니다
- 성능 리뷰어: 쿼리 성능, 메모리 사용, 불필요한 렌더링을 검토합니다
- 테스트 리뷰어: 테스트 커버리지와 엣지 케이스 누락을 검토합니다

각자 리뷰하고 발견 사항을 정리해 주세요.

세 리뷰어가 병렬로 작업하면서, 발견한 내용을 메일박스를 통해 공유합니다. 보안 리뷰어가 "이 엔드포인트에 인증이 빠져 있다"고 발견하면, 테스트 리뷰어에게 "이 엔드포인트의 인증 테스트가 있는지도 확인해 달라"고 메시지를 보낼 수 있습니다.

에이전트 팀이 실제로 어떻게 돌아가는지 좀 더 들어가 보겠습니다. 팀 리드 에이전트가 생성되면, 이 리드가 동료 에이전트를 spawn합니다. 각 동료는 독립된 Claude 세션으로 실행되며, 자기 자신의 컨텍스트 윈도우와 도구 세트를 갖습니다. 핵심은 공유 작업 목록과 메일박스 시스템입니다. 공유 작업 목록은 팀 리드가 작업을 분배하고 진행 상황을 추적하는 데 사용하며, 메일박스는 동료 간 비동기 메시지를 주고받는 채널입니다. 동료 A가 작업 중 발견한 사항을 동료 B에게 알려야 할 때, 메일박스에 메시지를 남기면 B가 다음 턴에서 이를 확인하고 반영합니다.

현재 이 기능은 실험적 단계이므로 API가 변경될 수 있습니다. Anthropic 공식 문서(agent-teams)에 따르면, 에이전트 팀의 최적 규모는 3-5명의 동료이고, 동료당 5-6개의 작업을 유지하는 것이 효율적입니다. 그 이상으로 늘리면 조율 비용이 작업 효율을 잡아먹습니다.

주의할 점이 있습니다. 에이전트 팀은 일반 세션 대비 약 7배의 토큰을 소모합니다. 단순한 작업에 에이전트 팀을 쓰는 건 낭비입니다. "결과만 필요한 집중 작업"에는 서브에이전트를, "논의와 협업이 필요한 복잡한 작업"에만 에이전트 팀을 사용해야 합니다.

4. 안전망 구축: 훅, 권한, MCP로 팀을 보호하기

5명이 Claude Code를 쓰면, 5명 모두가 실수할 가능성이 있습니다. Claude에게 rm -rf를 시키거나, main 브랜치에 직접 push하거나, .env 파일을 커밋하거나. "조심해"라고 말하는 것만으로는 부족합니다. 시스템으로 막아야 합니다.

훅: "프롬프트는 제안이고, 훅은 보장입니다"

이 문장이 Anthropic 공식 문서에 있습니다. 정확한 표현입니다. CLAUDE.md에 "main 브랜치에 push하지 마세요"라고 적어 놓아도, Claude가 100% 그걸 따른다고 보장할 수 없습니다. 훅은 다릅니다. 도구가 실행되기 전에 셸 스크립트로 검증하고, 조건에 맞지 않으면 실행 자체를 차단합니다.

다음 그림은 훅이 도구 호출을 어떻게 제어하는지 보여줍니다.

Claude Code가 도구를 호출하면 PreToolUse 훅이 먼저 셸 스크립트로 검증합니다. 통과하면(exit 0) 도구가 실행되고, 차단하면(exit 2) 실행 자체가 막힙니다. 도구 실행 후에는 PostToolUse 훅이 자동 포맷팅 같은 후처리를 수행합니다.

팀에서 반드시 설정해야 할 훅 패턴 세 가지입니다.

첫째, 보호 파일 수정 차단입니다.

복사
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

복사
#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" "yarn.lock" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "BLOCKED: $FILE_PATH is protected. This file should not be modified by AI." >&2
    exit 2
  fi
done
exit 0

exit 2를 반환하면 해당 도구 호출이 차단됩니다. .env 파일이나 lock 파일을 Claude가 수정하는 것을 원천 차단할 수 있습니다.

둘째, 위험한 명령어 차단입니다. Trail of Bits의 설정에서 가져온 패턴입니다. rm -rf 대신 trash 명령어를 제안하고, main 브랜치 직접 push를 차단해서 feature 브랜치 워크플로우를 강제합니다.

셋째, 코드 자동 포맷팅입니다.

복사
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-format.sh"
          }
        ]
      }
    ]
  }
}

복사
#!/bin/bash
# .claude/hooks/auto-format.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$FILE_PATH" =~ \.(ts|tsx|js|jsx|css|scss)$ ]]; then
  npx prettier --write "$FILE_PATH" 2>/dev/null
fi
exit 0

Claude가 파일을 수정한 직후, JS/TS/CSS 파일에 한해 자동으로 Prettier가 실행됩니다. 파일 확장자를 체크하기 때문에 마크다운이나 JSON 파일이 의도치 않게 변형되는 일을 막을 수 있습니다. 팀의 Prettier 설정에 따라 대상 확장자를 조정하면 됩니다. 팀원 5명이 각각 Claude에게 코드를 생성시켜도, 포맷은 항상 일관되게 유지됩니다.

권한 설정: 4단계 계층 구조

Claude Code는 4단계 계층적 설정 시스템을 사용합니다.

팀 리드가 .claude/settings.json에 공통 권한 규칙을 설정하면, 모든 팀원에게 적용됩니다.

복사
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(npm test *)",
      "Bash(npm run lint *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git push origin main *)",
      "Bash(DROP TABLE *)",
      "Bash(curl * | bash)"
    ]
  }
}

settings.local.json은 gitignore되므로, 각 개발자가 자신만의 추가 설정을 유지할 수 있습니다. 숙련된 팀원은 AcceptEdits 모드로 파일 수정을 자동 승인하고, 신규 팀원은 기본 모드에서 모든 수정을 확인하는 식으로 운영할 수 있습니다.

MCP 서버: 팀 공유 도구 확장

MCP(Model Context Protocol)는 Claude Code의 기능을 외부 도구와 연결하는 표준입니다. 프로젝트 루트의 .mcp.json 파일을 Git에 커밋하면, 팀 전체가 동일한 도구에 접근할 수 있습니다.

복사
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sentry"],
      "env": {
        "SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}"
      }
    }
  }
}

이렇게 설정하면 팀원 누구나 Claude에게 "이 PR의 리뷰 코멘트를 확인해 줘", "최근 Sentry 에러를 분석해 줘", "이 쿼리의 실행 계획을 확인해 줘"라고 요청할 수 있습니다. 별도 설정 없이요.

한 가지 주의할 점은, 각 MCP 서버가 유휴 상태에서도 컨텍스트에 도구 정의를 추가한다는 것입니다. MCP 서버를 10개 붙여 놓으면 컨텍스트 윈도우의 상당 부분을 도구 정의가 차지합니다. Anthropic 공식 문서에 따르면, MCP 도구 설명이 컨텍스트 윈도우의 10%를 초과하면 자동으로 도구 검색 모드로 전환됩니다. 필요한 서버만 활성화하고, CLI 도구(gh, aws, sentry-cli)로 되는 일이면 MCP보다 CLI를 쓰는 편이 비용이 적게 듭니다.

5. 실전 팀 워크플로우: 일하는 방식을 바꾸기

여기까지 설정을 마쳤으면, 이제 팀이 실제로 Claude Code를 어떻게 활용할지 구체적인 패턴을 살펴보겠습니다.

Writer/Reviewer 패턴

Claude Code를 가장 효과적으로 쓰는 패턴 중 하나입니다. 한 팀원이 Claude와 함께 코드를 작성하면, 다른 팀원이 새로운 Claude 세션에서 그 코드를 리뷰합니다.

왜 새로운 세션이어야 하냐면, Claude는 자기가 방금 작성한 코드에 편향이 있기 때문입니다. 같은 세션에서 "방금 쓴 코드를 리뷰해 줘"라고 하면, 자기가 쓴 코드의 문제를 잘 찾지 못합니다. 새로운 컨텍스트에서 보면 "이 함수는 에러 핸들링이 빠져 있네요", "이 쿼리는 인덱스를 타지 않을 수 있습니다" 같은 피드백이 나옵니다.

이 패턴을 더 발전시킨 것이 TDD 워크플로우입니다. A 팀원이 Claude와 함께 테스트를 먼저 작성하고, B 팀원이 다른 Claude 세션에서 테스트를 통과하는 구현 코드를 작성합니다. 테스트가 정직하다는 것을 알기 때문에, 구현 코드의 품질을 테스트가 보장합니다.

GitHub Actions 연동: CI/CD에 Claude 녹이기

Claude Code GitHub Actions를 사용하면, PR이나 이슈에서 @claude를 멘션하는 것만으로 AI 자동화를 트리거할 수 있습니다.

PR이 열리면 Claude가 자동으로 변경 사항을 분석하고 개선을 제안합니다. 이슈에 @claude 이 버그를 수정해 줘라고 코멘트하면, Claude가 코드를 분석하고 수정 PR을 올립니다. 보안 리뷰 전용 Action도 있어서, 모든 PR에 대해 자동으로 보안 취약점 스캔을 돌릴 수 있습니다.

5명 팀에서 이걸 활용하면, 코드 리뷰의 첫 번째 패스를 Claude가 자동으로 처리하고, 사람은 Claude가 놓친 비즈니스 로직 검증이나 아키텍처 판단에 집중할 수 있습니다.

온보딩 가속화

새 팀원이 합류했을 때, 가장 시간이 많이 걸리는 것은 코드베이스를 파악하는 일입니다. Claude Code가 이 과정을 크게 단축합니다.

새 팀원이 레포를 클론하고 claude를 실행하면, CLAUDE.md에 정의된 프로젝트 구조, 기술 스택, 핵심 규칙이 자동으로 로드됩니다. "이 프로젝트의 인증 흐름을 설명해 줘", "이 API 엔드포인트가 호출하는 서비스 레이어를 추적해 줘"라고 물으면, Claude가 코드를 읽고 설명합니다.

Anthropic 내부에서도 이 방식이 효과적이었다고 합니다. 새 팀에 로테이션하는 엔지니어가 동료 상담 없이 낯선 코드베이스를 빠르게 탐색하고, 의미 있는 기여를 시작할 수 있게 되었다는 겁니다.

여기서 핵심은, CLAUDE.md와 rules/가 잘 정리되어 있어야 한다는 것입니다. Claude가 참조할 문서가 부실하면, 새 팀원에게 주는 답변도 부실해집니다. 결국 팀의 문서화 수준이 AI 활용 수준을 결정합니다.

6. 비용과 컨텍스트 관리: 현실적인 운영 전략

팀에서 Claude Code를 운영하면 비용 문제를 피할 수 없습니다. 개인이 쓸 때는 월 $20-200 정도로 관리되지만, 5명이 쓰면 상황이 달라집니다.

비용 현실

Anthropic의 비용 관리 문서(Manage costs effectively)에 따르면, Claude Code 사용자의 일 평균 비용은 개발자당 약 $6이고, 90%의 사용자는 일 $12 미만을 씁니다. 5명 팀 기준으로 월 환산하면, $900-$1,800 정도가 일반적인 범위입니다.

요금제 선택지를 정리하면 이렇습니다.

API 방식(BYOK)으로 쓸 수도 있습니다. 이 경우 사용한 만큼만 지불하므로, 사용량이 불규칙한 팀에 유리합니다. 다만 API 방식은 토큰 사용량을 직접 모니터링해야 하는 부담이 있습니다.

5인 팀의 TPM/RPM 현실

1-5명 규모 팀의 경우, 사용자당 TPM(분당 토큰)은 200k-300k, RPM(분당 요청)은 5-7이 권장됩니다. 이 수치는 "5명이 동시에 Claude Code를 사용해도 응답 지연 없이 작업할 수 있는" 수준입니다.

팀 규모가 커질수록 사용자당 할당량이 줄어드는데, 이는 대규모 조직에서 동시 사용자 비율이 낮아지기 때문입니다. 5명 팀에서는 거의 전원이 동시에 사용하는 경우가 많으므로, 넉넉한 할당량을 확보하는 것이 좋습니다.

비용 최적화 6가지 전략

첫째, 작업 간 /clear를 사용합니다. 관련 없는 작업으로 전환할 때 새로 시작하면, 이전 컨텍스트의 불필요한 토큰 소모를 막을 수 있습니다.

둘째, 모델을 작업에 맞게 선택합니다. 대부분의 코딩 작업은 Sonnet으로 충분합니다. Opus는 복잡한 아키텍처 결정이나 대규모 리팩토링에만 사용합니다. 스킬의 프론트매터에서 model: sonnet을 지정하면 해당 스킬 실행 시 자동으로 Sonnet을 사용합니다.

셋째, 서브에이전트로 대량 작업을 위임합니다. 100개 파일의 테스트 실행, 문서 수집, 로그 분석 같은 작업을 서브에이전트에게 맡기면, 메인 컨텍스트는 깨끗하게 유지되고 비용도 절약됩니다.

넷째, CLAUDE.md를 간결하게 유지합니다. 500줄 이내가 권장입니다. 특정 워크플로우의 상세 지시사항은 스킬로 옮기세요.

다섯째, 구체적으로 프롬프트를 작성합니다. "이 코드베이스를 개선해 줘" 대신 "auth.ts의 로그인 함수에 입력 유효성 검사를 추가해 줘"라고 요청하면, Claude가 읽어야 할 파일 수가 줄어들고 토큰 소모도 줄어듭니다.

여섯째, 확장 사고 토큰을 조절합니다. 간단한 작업에서는 MAX_THINKING_TOKENS=8000으로 줄이거나 비활성화할 수 있습니다.

컨텍스트 윈도우 관리

Claude Code의 모든 최적화는 하나의 제약에 기반합니다. 컨텍스트 윈도우는 빠르게 채워지고, 채워질수록 성능이 저하됩니다. 메시지, 파일 내용, 명령 출력 전부가 컨텍스트에 쌓입니다.

Anthropic의 모범 사례 문서(Best Practices for Claude Code)에서 이런 이야기를 합니다. 컨텍스트를 여유 있게 유지하는 세션이, 100%까지 밀어붙이는 세션보다 더 좋은 코드를 만든다고요. 출력량은 적지만, 프로덕션에 실제로 올릴 수 있는 코드 비율이 높습니다. 컨텍스트에 여유가 있어야 복잡한 리팩토링이나 엣지 케이스를 제대로 추론할 수 있기 때문입니다.

Claude Code 상태 표시줄에 컨텍스트 채움 표시기가 있습니다. 60%를 넘으면 새 세션을 시작하는 게 좋습니다. /context 명령으로 현재 상태를 확인할 수 있습니다.

Claude Code Team Collaboration Guide의 멀티 세션 전략에 따르면, 대규모 프로젝트에서 3개의 병렬 세션을 기능 영역별로 나누면 전체 코드베이스를 커버하면서도 어떤 세션도 포화시키지 않습니다. 세션별로 담당 디렉토리를 지정하고, 각 세션이 자기 영역만 깊이 파고드는 방식입니다.

마무리

글의 처음으로 돌아가 보겠습니다. "Claude Code를 팀에서 어떻게 쓰나요?"라는 질문에 대한 답은, 결국 "프로세스를 먼저 정의하세요"입니다. 어떤 도구든 사용법을 모르면 개인 생산성 도구에 그칩니다. 프로세스를 정의하고, 그 프로세스를 .claude/ 디렉토리에 코드화하면, Claude Code는 팀 전체의 작업 방식을 표준화하는 인프라가 됩니다.

Claude Code Team Collaboration Guide에 따르면, 5명 규모 팀이 CLAUDE.md, rules/, skills/ 설정을 표준화한 후 주당 약 12시간을 절약했다고 합니다. 팀원당 하루 약 30분입니다. 이 30분은 "Claude가 코드를 더 빨리 생성해서" 생긴 시간이 아닙니다. "같은 실수를 반복하지 않고, 같은 질문을 다시 하지 않고, 같은 설정을 매번 입력하지 않아서" 생긴 시간입니다. 다만 이 수치는 해당 가이드의 사례이고, 팀마다 체감은 다를 겁니다.

한 가지 솔직히 말하면, 도입 초기에는 오히려 속도가 느려지는 시기가 있습니다. CLAUDE.md를 처음 작성하는 데 반나절이 걸리고, rules/ 파일을 다듬는 데 또 시간이 들고, 팀원들이 새로운 워크플로우에 적응하는 기간도 필요합니다. 현업 개발자에게 들어보니, 대략 2주 정도 지나야 "이제 없으면 불편하다"는 느낌이 온다고 합니다.

그래서 한 번에 전부 도입하려 하면 안 됩니다. 주변 팀에서 효과를 본 점진적 도입 순서는 이렇습니다. 첫째 주에는 CLAUDE.md 한 개와 rules/ 파일 두세 개를 Git에 커밋합니다. 이것만으로도 팀원 모두가 같은 기준으로 Claude Code를 사용하기 시작합니다. 둘째 주에는 팀에서 가장 반복적인 작업 하나를 스킬로 만듭니다. 코드 리뷰나 테스트 실행 같은 것이 좋습니다. 셋째 주에는 보호 파일 훅과 권한 설정을 추가합니다. 안전망이 생기면 팀원들이 Claude를 더 적극적으로 활용하게 됩니다. 넷째 주부터는 팀의 필요에 따라 서브에이전트, MCP, 추가 스킬을 하나씩 확장합니다.

핵심은, 이 모든 게 Git에 커밋되어 팀 자산으로 남는다는 겁니다. 팀원이 바뀌어도, 프로젝트가 이어져도, .claude/ 디렉토리가 팀의 두뇌로 계속 작동합니다.

---

참고 자료

• Orchestrate teams of Claude Code sessions - 에이전트 팀 공식 문서
• Extend Claude with skills - 스킬 공식 문서
• Manage costs effectively - 비용 관리 공식 문서
• Automate workflows with hooks - 훅 가이드 공식 문서
• Configure permissions - 권한 설정 공식 문서
• Best Practices for Claude Code - 모범 사례 공식 문서
• How Anthropic teams use Claude Code - Anthropic 내부 팀 사용 사례
• What our web team learned using Claude Code for a month (Expo) - Expo 팀 한 달 경험
• Trail of Bits Claude Code Config - 보안 기업의 팀 설정 사례
• skill-semver - 스킬 버전 관리 도구
• Claude Code Team Collaboration Guide - 팀 협업 가이드 (22파트)
• My Skill Makes Claude Code GREAT At TDD - TDD 스킬 사례
• Claude Code GitHub Actions - GitHub Actions 공식 문서
• Connect Claude Code to tools via MCP - MCP 공식 문서
• Claude Code Rules Directory: Modular Instructions That Scale - 규칙 디렉토리 가이드