개인이 작성하는 CLAUDE.md와 팀에서 운용하는 CLAUDE.md는 구조부터 업데이트 흐름까지 근본적으로 다른 것이었습니다.

개인용은 잘 작동하고 있는데, 팀에 전개하자마자 "사람마다 출력이 제각각이다", "누군가의 변경으로 다른 사람의 동작이 망가진다"와 같은 문제가 발생합니다. 이 기사에서는 팀 운용에서 실제로 시도하여 효과가 있었던 5가지 설계 패턴을 소개합니다.

레이어 분리형으로 설정 충돌을 방지한다 -
역할 기반형·페이즈 연동형으로 문맥에 맞는 지시를 구분하여 내린다 -
Git 연동형·템플릿 상속형으로 운용을 자동화·표준화한다

이것들을 조합함으로써 팀원 전원이 일관된 품질로 Claude Code를 활용할 수 있게 됩니다.

— 글로벌 (사용자 단위) ~/.claude/CLAUDE.md

— 프로젝트 단위 (Git 리포지토리에 커밋 가능) 프로젝트 루트/CLAUDE.md

— 서브 디렉토리 단위로 추가 지시 임의 디렉토리/CLAUDE.md

이 메커니즘을 이해한 후, 팀 운용 설계로 넘어가겠습니다.

개인용 CLAUDE.md가 파탄 나는 이유는 명확합니다. "자신에게만 통하는 암묵지"가 그대로 적혀 있기 때문입니다.

전형적인 파탄 패턴을 예로 들겠습니다.

개인용은 "나 혼자만 사용한다"는 전제로 최적화되어 있습니다. 팀으로 가져오려면 책임의 분리와 업데이트 규칙에 대한 합의가 필요합니다.

가장 기본적이면서 중요한 패턴입니다. Claude Code가 제공하는 3가지 스코프를 명확하게 구분하여 사용합니다.

Global (개인) — .gitignore로 관리 대상 제외. 각자 자유롭게 설정.

# ~/.claude/CLAUDE.md
- 일본어로 응답해 주세요
- 설명은 간결하게, 코드 예제를 우선해 주세요

Project (팀 공유) — Git에 커밋하고, PR (Pull Request)로 리뷰.

# /project-root/CLAUDE.md
## 기술 스택
- 언어: TypeScript 5.x (strict mode)
...

Personal (개인 로컬) — .gitignore에 추가하여 관리 대상 제외.

# /project-root/.claude/CLAUDE.local.md
- 현재 태스크: 사용자 인증 기능 구현
- 관련 파일: src/features/auth/ 하위를 중심으로 작업 중

• Project 층은 팀 리드 또는 테크 리드가 관리자 - 변경은 반드시 PR을 거침 (후술할 패턴 4와 조합)
• .claude/CLAUDE.local.md는 .gitignore에 추가해 둘 것

팀 내에 여러 기술 영역이 있는 경우, 디렉토리 단위로 CLAUDE.md를 배치하여 지시를 분기시킵니다.

project-root/
├── CLAUDE.md # 공통 규칙
├── frontend/
...

frontend/CLAUDE.md:

## 프론트엔드 고유 규칙
- 컴포넌트는 Atomic Design을 따른다
- 스타일링은 Tailwind CSS만 사용 (CSS Modules 금지)
...

backend/CLAUDE.md:

## 백엔드 고유 규칙
- API는 RESTful 설계 (OpenAPI 3.1 준수)
- 유효성 검사는 Zod로 구현
...

Claude Code는 현재 디렉토리에서 상위 디렉토리로 향해 CLAUDE.md를 탐색하기 때문에, 작업 디렉토리에 따라 자동으로 적절한 지시가 적용됩니다. 프론트엔드 담당자가 백엔드 규칙에 휘둘리는 일이 없어집니다.

개발 단계에 따라 Claude Code에 요구하는 역할은 달라집니다. 이를 명시적으로 전환하는 패턴입니다.

단계별로 별도의 파일을 준비하고, 심볼릭 링크(Symbolic Link)나 스크립트로 전환합니다.

project-root/
├── .claude/
│ ├── phases/
...

switch-phase.sh:

#!/bin/bash
PHASE=${1:-implement}
cp ".claude/phases/${PHASE}.md" CLAUDE.md
...

실제로는 스크립트로 전환하는 것보다 CLAUDE.md 내에 페이즈(Phase) 섹션을 나열하고, "현재 페이즈: 구현"이라고 한 줄을 수정하는 것이 더 간편합니다. Claude Code는 문맥을 이해할 수 있으므로, "현재 페이즈에 해당하는 섹션을 따르세요"라는 지시만으로도 충분히 기능합니다.

## 현재 페이즈: 구현
### 설계 페이즈의 규칙
(생략 — 이 페이즈에서는 참고용으로만 사용)
...

CLAUDE.md의 변경이 "어느샌가" 이루어지면 팀 전체의 출력 품질이 조용히 붕괴됩니다. 이를 방지하는 것이 Git 연동형입니다.

1. CI에서 CLAUDE.md의 변경을 감지하여 라벨을 붙임

# .github/workflows/claude-md-review.yml
name: CLAUDE.md Change Detection
on: [pull_request]
...

2. CODEOWNERS를 통해 특정 멤버의 승인을 필수화함

# .github/CODEOWNERS
CLAUDE.md @tech-lead @ai-champion
**/CLAUDE.md @tech-lead @ai-champion

3. PR 템플릿에 CLAUDE.md 변경 이유를 기재하는 칸을 마련함

## CLAUDE.md 변경 (해당하는 경우)
- [ ] 변경 이유를 기재함
- [ ] 기존 규칙과 모순이 없음을 확인함
...

CLAUDE.md는 팀원 전체의 AI 출력을 좌우하는 설정 파일입니다. 운영 환경의 설정 파일(.env나 terraform.tfvars)과 동일한 중요도로 관리해야 합니다.

여러 프로젝트나 팀이 동일 조직 내에 있는 경우, 조직 공통 베이스 템플릿을 준비하고 각 팀이 이를 오버라이드(Override)하는 구성입니다.

조직 템플릿을 별도의 리포지토리(Repository) 또는 패키지로 관리합니다.

org-claude-template (조직 공통):

# 조직 공통 규칙 (반드시 준수)
## 보안
- 시크릿(Secret) 정보를 코드에 포함하지 말 것
...

각 팀의 CLAUDE.md:

# 팀 A CLAUDE.md
## 조직 공통 규칙
<!-- org-claude-template v2.1 적용 -->
...

• 조직 템플릿이 업데이트되면 각 팀에 통지 (Slack Bot 등)
• 각 팀은 자사 팀의 CLAUDE.md에 반영하는 PR을 생성
• 조직 템플릿의 버전을 명기하여 추적 가능하게 관리

시행착오 끝에 저희 팀(백엔드 5명 + 프론트엔드 3명)은 패턴 1 + 패턴 2 + 패턴 4의 조합으로 정착했습니다.

project-root/
├── CLAUDE.md # 공통 규칙 (기술 스택 · 금지 사항)
├── .claude/
...

스프린트 회고 시 다음 사항을 확인하고 있습니다.

• 사용되지 않는 규칙은 없는가

• 모순되는 규칙이 추가되지 않았는가

• Claude Code의 출력에서 반복적으로 수동 수정하고 있는 부분이 있는가 (→ 규칙 추가 후보)

• 행수가 상한을 초과하지 않았는가

• 레이어 분리(Layer Separation)가 최우선: Global / Project / Personal의 3개 계층을 명확히 나누고, Git 관리 경계를 설정하는 것이 팀 운용의 출발점입니다 -
  컨텍스트 전환(Context Switching)을 체계화하기: 역할(Role)이나 페이즈(Phase)에 따른 지시 방식의 차별화를 디렉토리 구성이나 섹션 설계로 구현하면, Claude Code의 출력 정밀도가 안정화됩니다 -
  CLAUDE.md는 인프라 설정과 동일하게 관리하기: PR 리뷰 필수, CODEOWNERS 설정, 정기적인 점검(Inventory)이라는 3종 세트를 통해 팀 전체의 AI 출력 품질을 보호할 수 있습니다