팀을 위한 Claude Code: 공유 CLAUDE.md, Hook, 그리고 AI Drift 방지 (2026)

Claude Code에 관한 모든 튜토리얼은 단 한 명의 개발자를 가정합니다. 하지만 대부분의 소프트웨어는 그런 방식으로 만들어지지 않습니다.

팀 전체가 Claude Code를 사용하기 시작하면, 조용한 문제 하나가 수면 위로 떠오릅니다. 바로 **AI Drift (AI 드리프트)**입니다. 두 명의 개발자가 Claude에게 동일한 모듈에 에러 핸들링 (error handling)을 추가해 달라고 요청했는데, 서로 호환되지 않는 구현 결과가 나옵니다. 한 개발자의 Claude는 모든 곳에 Zod를 사용하는 컨벤션 (convention)을 따르지만, 다른 개발자의 Claude는 그 사실을 모릅니다. 주니어 개발자의 Claude는 시니어 개발자가 지난주에 세운 아키텍처 (architectural) 결정과 상충되는 결정을 내리기도 합니다.

이것은 1인 개발자용 튜토리얼에서는 다루지 않는 문제입니다. 이를 해결하는 방법을 소개합니다.

전체 가이드는 stacknotice.com/blog/claude-code-for-teams-2026에서 확인하세요.

근본 원인: Claude의 컨텍스트 (Context)는 세션별로 존재함

Claude Code는 개발자 간에 메모리 (memory)를 공유하지 않습니다. 동료가 새로운 세션을 열면, 그들의 Claude는 당신이 지난 화요일에 내린 아키텍처 결정, 팀이 지난달에 채택한 컨벤션, 또는 피하기로 합의한 패턴에 대해 전혀 알지 못합니다.

해결책: 공유 컨텍스트를 **명시적이고 버전 관리 (version-controlled)**가 가능하도록 만드세요.

팀용 CLAUDE.md

Claude Code는 여러 위치에서 CLAUDE.md를 읽습니다. 팀의 경우, (레포지토리에 커밋되는) **프로젝트 레벨 (project-level)**의 CLAUDE.md가 핵심입니다:

# Project: TaskApp — AI Conventions

## Architecture decisions (do not deviate without team discussion)
...

이것은 인간을 위한 스타일 가이드 (style guide)가 아닙니다. 이 프로젝트의 모든 Claude 세션이 자동으로 읽어들이는 명령어 세트 (instruction set)입니다. 이를 eslint.config.ts와 동일한 수준의 주의를 기울여 관리하세요.

중요 경로를 위한 모듈 레벨 CLAUDE.md

중요도가 높은 디렉토리에는 CLAUDE.md를 추가하세요:

# src/payments/CLAUDE.md

## CRITICAL — Read before touching any file here
...

공유 PostToolUse Hook: 모든 수정 시 TypeScript 체크

이를 레포지토리의 .claude/settings.json에 커밋하세요:

{
  "hooks": {
    "PostToolUse": [
...

모든 파일 수정은 TypeScript 체크를 트리거합니다. Claude는 오류를 즉시 확인하고 동일한 응답 내에서 이를 수정합니다. 팀 전체적으로, Claude가 생성한 코드라 할지라도 타입 시스템 (Type System)을 깨뜨리는 코드는 그 누구도 머지(Merge)할 수 없습니다.

Two-Claude 리뷰 패턴 (The Two-Claude Review Pattern)

대부분의 개발자는 코드를 작성하기 위해 Claude를 사용합니다. 하지만 Claude를 리뷰 (Review) 용도로도 사용하는 팀은 차원이 다른 버그들을 잡아냅니다.

# 터미널 1 — 작성자 Claude (Writer Claude)
claude "docs/upgrade-flow.md에 따라 구독 업그레이드 흐름을 구현해줘.
진행하면서 테스트도 작성해줘."
...

리뷰어 Claude (Reviewer Claude)는 작성자 Claude의 결정에 어떠한 애착도 없습니다. 객관적으로 리뷰합니다. 실제로 이 방식은 작성자 Claude가 놓친 기능당 2~3개의 실제 이슈를 잡아냅니다.

CLAUDE.md 최신 상태 유지하기

Claude가 스스로 업데이트할 수 있는 섹션을 추가하세요:

## 최근 결정 사항 (Claude가 이 섹션을 업데이트할 수 있음)
- 2026-06-10: 이메일 서비스를 Sendgrid에서 Resend로 전환
- 2026-06-05: 모든 환경 변수에 Zod 채택
...

중요한 세션이 끝날 때마다 다음과 같이 요청하세요: "오늘 우리가 결정한 내용을 CLAUDE.md에 업데이트해줘." 수개월이 지나면, 이는 모든 새로운 세션이 자동으로 상속받는 살아있는 아키텍처 결정 기록 (Architecture Decision Record)이 됩니다.

규칙: 결정 사항 vs 선호도 (Decisions vs Preferences)

결정 사항 (팀 CLAUDE.md — 버전 관리 대상):

• 어떤 ORM을 사용할 것인가
• 에러 핸들링 (Error handling) 패턴
• 파일 명명 규칙 (File naming conventions)
• 특별한 주의가 필요한 민감한 모듈

선호도 (개인 ~/.claude/CLAUDE.md):

• 설명의 상세 수준 (Verbosity)
• 선호하는 응답 형식
• 규칙 내에서의 개인적인 코딩 스타일

모든 것을 팀 파일에 넣게 되면, Claude는 서로 충돌하는 지침을 따르기 시작합니다. 경계를 명확하게 유지하세요.

"모두가 개별적으로 Claude를 사용하는 것"에서 "팀이 함께 Claude를 사용하는 것"으로의 전환은 암묵적인 관습을 명시적인 것으로 만드는 과정입니다. 결정 사항이 CLAUDE.md에 기록되면, 모든 개발자의 AI 세션은 동일한 기준점에서 시작하며, AI 드리프트 (AI Drift)는 멈추게 됩니다.

온보딩 워크플로 (onboarding workflow), 서브에이전트 병렬화 (subagent parallelization), 그리고 팀 체크리스트 (team checklist)를 포함한 전체 가이드는 **stacknotice.com/blog/claude-code-for-teams-2026**에서 확인하실 수 있습니다.