Claude Code 팀 협업 가이드: 인수인계, 리뷰, 권한 경계

Claude Code는 혼자 사용할 때도 조사, 수정, 테스트 작성 속도를 높여 줍니다. 하지만 팀에 도입하면 다른 문제가 드러납니다. 누가 어떤 명령을 승인했는지, Claude가 어떤 파일을 봤는지, 아직 확인하지 않은 리스크가 무엇인지, AI 리뷰가 사람에게 실제로 받아들여졌는지를 남겨야 합니다.

이 글은 2명에서 10명 규모의 개발팀이 Claude Code를 안전하게 운영하기 위한 실전 절차를 정리합니다. 다루는 범위는 팀 인수인계, PR 사전 리뷰, CLAUDE.md 규칙, 권한 경계, 신규 멤버 온보딩, 장애 교대, 커뮤니케이션 실패입니다. 여기서 권한 경계는 “Claude Code가 읽고, 수정하고, 실행할 수 있는 범위”이고, 리뷰 영수증은 “AI 제안을 사람이 어떻게 처리했는지 PR에 남기는 짧은 기록”입니다.

flowchart LR
  A["개발자 요청"] --> B["CLAUDE.md와 규칙"]
  B --> C["Claude Code 작업"]
  C --> D["테스트와 diff 확인"]
  D --> E["리뷰 영수증"]
  E --> F["사람의 PR 리뷰"]

먼저 정할 네 가지 위치

팀 운영은 개인이 좋은 프롬프트를 외우는 방식으로는 안정되지 않습니다. 규칙은 저장소 안의 재사용 가능한 위치에 있어야 합니다.

위치	목적	Git 관리
CLAUDE.md	프로젝트 규칙, 금지사항, 테스트 명령	예
.claude/settings.json	공유 권한, deny 규칙, hooks	예
.claude/settings.local.json	개인 샌드박스 URL, 임시 설정	아니오
.claude/prompts/*.md	인수인계, 리뷰, 조사 템플릿	예

공식 문서는 Claude Code 메모리, 설정, 권한, 보안의 역할을 설명합니다. 내부 글로는 CLAUDE.md 모범 사례, Claude Code hooks 가이드, GitHub Actions 고급 활용을 함께 보면 좋습니다.

사례1: 개발자에서 리뷰어로 인수인계

가장 흔한 실패는 PR에 “Claude가 고쳤습니다”만 남기는 것입니다. 리뷰어에게 필요한 정보는 Claude가 본 파일, 승인된 명령, 실패한 테스트, 사람이 판단해야 할 부분입니다.

.claude/prompts/handoff.md를 만듭니다.

# 팀 인수인계 메모 작성

현재 diff를 읽고 아래 형식으로 인수인계 메모를 작성하세요.

## 목표
- 이번 변경으로 해결하려는 문제:

## 변경 범위
- 수정한 파일:
- 수정하지 않았지만 영향이 있을 수 있는 파일:

## 확인 내용
- 실행한 명령:
- 성공/실패:
- 실패 로그 요약:

## 리뷰어가 볼 점
- 제품 판단:
- 보안:
- 성능:
- 테스트 부족:

## 다음 담당자에게
- 먼저 확인할 것:
- 나중에 해도 되는 것:

diff를 만든 뒤 실행합니다.

claude -p "git diff를 읽고 .claude/prompts/handoff.md 형식으로 팀 인수인계 메모를 작성하세요"

결과를 PR 본문에 붙이면 리뷰어가 위험 지점부터 볼 수 있습니다. 비동기 근무나 시차가 있는 팀에서는 채팅보다 PR에 남는 인수인계가 훨씬 추적하기 쉽습니다.

사례2: AI로 PR 사전 리뷰

Claude Code 리뷰의 목적은 사람을 대체하는 것이 아니라 사전 점검입니다. 명백한 버그, 테스트 누락, 보안 위험, 일관성 없는 변경을 먼저 잡으면 사람은 설계 판단에 집중할 수 있습니다.

.claude/prompts/pr-review.md를 만듭니다.

# PR 사전 리뷰

다음 관점으로 diff를 리뷰하세요.

1. 버그가 될 수 있는 분기, null/undefined, 경계값
2. 권한 검사, 입력 검증, 비밀 정보 노출
3. N+1, 불필요한 재렌더링, 무거운 동기 처리
4. CLAUDE.md 규칙 위반
5. 부족한 테스트 케이스

출력 형식:
- 심각도: 높음 / 중간 / 낮음
- 파일:
- 줄 또는 함수:
- 이유:
- 수정 제안:

추측 기반 지적은 반드시 “확인 필요”라고 표시하세요.

로컬에서는 GitHub CLI와 함께 실행합니다.

gh pr diff 123 | claude -p "$(cat .claude/prompts/pr-review.md)"

GitHub Actions로 자동화할 때는 댓글만 남기고, 병합 판단은 사람이 하도록 둡니다.

name: Claude PR pre-review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  pre-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install tools
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          gh pr diff "$PR_NUMBER" > /tmp/pr.diff
          claude -p "$(cat .claude/prompts/pr-review.md)

          diff:
          $(cat /tmp/pr.diff)" > /tmp/claude-review.md
          gh pr comment "$PR_NUMBER" --body-file /tmp/claude-review.md

공식 일반 워크플로 문서도 리뷰와 테스트 보조 흐름을 다룹니다. 팀 규칙은 분명해야 합니다. AI 댓글은 참고이고, 승인은 사람이 합니다.

사례3: 신규 멤버 온보딩

신규 멤버가 막히는 지점은 문법보다 “어떤 명령이 안전한가”, “업무 규칙은 어디에 있는가”, “처음 읽을 파일은 무엇인가”입니다. Claude Code에게 저장소 안내 초안을 만들게 하면 시작 시간이 줄어듭니다.

claude -p "
이 저장소를 신규 멤버에게 설명하세요.
반드시 포함하세요.
- 주요 디렉터리와 책임
- 로컬 실행, lint, test, build 명령
- 먼저 읽을 3개 파일
- 변경 전에 확인해야 할 업무 규칙
- 자주 하는 실수와 피하는 방법
- 30분 안에 할 수 있는 연습 과제

모르는 내용은 추측하지 말고 확인 필요로 적으세요.
"

출력을 그대로 공개하지 마세요. 경험 많은 멤버가 30분만 투자해 운영 제약, 팀의 과거 결정, 장애 위험을 보강해야 합니다. 큰 조사는 subagent 활용 패턴처럼 탐색과 요약을 나누면 더 안정적입니다.

사례4: 장애 조사와 교대

장애 중에는 Claude Code가 로그 요약과 가설 정리에 도움이 됩니다. 하지만 비밀 정보를 붙여넣거나, 검증되지 않은 가설을 사실처럼 공유하거나, 담당자가 바뀔 때 이미 시도한 내용이 사라질 수 있습니다.

아래 템플릿을 .claude/prompts/incident-handoff.md로 저장합니다.

# 장애 대응 인수인계

## 현상
- 시작 시각:
- 영향 범위:
- 사용자 영향:

## 관측한 사실
- 로그:
- 지표:
- 재현 절차:

## 시도한 것
- 명령:
- 결과:
- 실패한 가설:

## 남은 위험
- 데이터 손상 가능성:
- 보안 영향:
- 롤백 상태:

## 다음 담당자에게
- 먼저 볼 화면/로그:
- 절대 실행하지 말 명령:

Claude Code에 로그를 넣기 전에는 이메일, 접근 토큰, 고객 ID를 마스킹합니다. 공식 보안 문서는 권한 승인과 프롬프트 주입 위험을 설명합니다. 팀은 로그를 채팅 자료가 아니라 운영 데이터로 다뤄야 합니다.

효과적인 CLAUDE.md 규칙

CLAUDE.md에는 팀이 매번 반복해서 설명하는 사실을 넣습니다. 짧고, 구체적이고, 확인 가능해야 합니다.

# Claude Code 프로젝트 지시

## 작업 전
- 수정 전 `git status --short`를 실행한다.
- 기존 사용자 변경을 되돌리지 않는다.
- 제품 동작이 불명확하면 PR에 “확인 필요”라고 쓴다.

## 코드 규칙
- 모든 API 입력은 검증한다.
- DB 쓰기에는 트랜잭션 경계를 명시한다.
- UI 문구를 추가하기 전에 기존 번역 key를 우선 사용한다.

## 테스트
- 로직 변경에는 단위 테스트를 추가한다.
- 버그 수정에는 회귀 테스트 1개를 추가한다.
- 실행하지 못한 테스트는 이유를 남긴다.

## PR
- 변경 내용, 확인 내용, 남은 위험을 쓴다.
- Claude Code 제안은 사람이 확인한 것만 채택한다.

이미 AGENTS.md를 쓰는 저장소라면 중복하지 말고 가져옵니다.

@AGENTS.md

## Claude Code 전용 규칙
- 결제, 인증, 삭제 흐름은 plan mode로 작업 방침을 먼저 제시한다.
- `git push`, 운영 배포, 마이그레이션 실행은 사람이 한다.

settings로 권한 경계 고정

팀 도입에서 가장 위험한 일은 편하다는 이유로 권한을 넓히는 것입니다. deny를 먼저 쓰고, allow는 최소화합니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(git diff *)",
      "Bash(git status *)",
      "Edit(src/**)",
      "Edit(tests/**)"
    ],
    "ask": [
      "Bash(npm install *)",
      "Bash(git commit *)",
      "Write(.github/**)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(**/secrets/**)",
      "Bash(git push --force*)",
      "Bash(rm -rf *)",
      "Bash(npm publish*)"
    ]
  }
}

hooks는 편집 뒤 검사를 실행하거나 위험한 명령을 막는 데 쓸 수 있습니다. 도입 전 공식 hooks reference를 확인하세요.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

이 예시는 프로젝트에 npm run lint가 있을 때만 맞습니다. 큰 monorepo에서는 전체 lint를 매번 실행하지 말고 파일 단위 검사나 CI로 옮기세요.

PR에 리뷰 영수증 남기기

AI 리뷰의 약점은 어떤 제안을 채택했는지 기록이 사라지기 쉽다는 점입니다. PR 템플릿에 다음 항목을 넣습니다.

## Claude Code 리뷰 영수증

- 사용한 프롬프트:
- Claude Code가 본 diff:
- 채택한 제안:
- 채택하지 않은 제안과 이유:
- 사람이 추가로 확인한 점:
- 실행한 테스트:
- 남은 위험:

최종 판단자:

Claude Code를 쓰지 않은 PR은 “사용하지 않음”이라고 쓰면 됩니다. 중요한 것은 AI를 쓴 PR의 투명도가 낮아지지 않는 것입니다.

실패 사례와 대책

실패	영향	대책
CLAUDE.md가 오래됨	낡은 명령과 폐기 API를 사용	실제 실패를 기준으로 매달 갱신
권한이 넓음	비밀 정보와 운영 작업에 가까워짐	deny를 먼저 쓰고 allow를 줄임
AI 리뷰만으로 승인	제품 판단과 책임자가 사라짐	PR 승인은 반드시 사람이 함
말로만 인수인계	다음 날 근거를 추적할 수 없음	PR 또는 Issue에 메모를 붙임
/clear로 맥락 삭제	변경 이유가 사라짐	reset 또는 compact 전에 요약 저장
hooks가 무거움	팀원이 우회하기 시작	파일 단위 hooks나 CI 사용

커뮤니케이션 실패도 자주 일어납니다. “좋게 고쳐줘”는 Claude Code에게 완료 조건을 추측하게 합니다. “이 함수만”, “schema는 건드리지 않기”, “실패한 테스트 로그를 먼저 읽기”처럼 짧고 구체적으로 제한하세요.

최소 팀 체크리스트

• CLAUDE.md에 명령, 금지사항, PR 규칙이 있다
• .claude/settings.json에서 allow, ask, deny를 나눴다
• .claude/settings.local.json을 .gitignore에 넣었다
• 인수인계, PR 리뷰, 장애 교대 프롬프트를 공유했다
• PR 템플릿에 리뷰 영수증을 추가했다
• 최종 판단을 내릴 사람이 명확하다
• 신규 멤버용 30분 연습 과제가 있다

ClaudeCodeLab은 이런 AI 팀 개발 템플릿을 계속 다듬고 있습니다. 내부 도입과 템플릿 정비를 빠르게 시작하고 싶다면 ClaudeCodeLab 제품도 참고하세요.

정리

Claude Code의 팀 활용은 마법 같은 프롬프트를 찾는 일이 아닙니다. 공유된 CLAUDE.md, 좁은 권한 경계, 남는 인수인계, 감사 가능한 리뷰 영수증을 갖추는 일입니다.

개인 생산성만 목표라면 좋은 프롬프트 몇 개로도 효과가 있습니다. 팀에서는 다른 사람이 같은 흐름을 재현할 수 있어야 하고, 실패했을 때 원인을 추적할 수 있어야 하며, Claude Code의 제안과 사람의 판단을 분리해 남겨야 합니다.

Masa가 작은 검증 저장소에서 이 흐름을 적용해 보니, PR 본문에 인수인계 메모와 리뷰 영수증을 넣는 것만으로 리뷰어의 “무엇을 확인했나요?” 질문이 줄었습니다. 반대로 매 편집 후 전체 lint를 실행하는 hook은 너무 느려 CI로 옮기는 편이 현실적이었습니다. 먼저 CLAUDE.md, PR 사전 리뷰 프롬프트, 리뷰 영수증 세 가지부터 시작하세요.