• 팀에서 CLAUDE.md를 공유·관리할 때의 설계 패턴
• 「개인 규칙」과 「팀 규칙」을 분리하는 방법
• CLAUDE.md의 비대화를 방지하는 유지보수 전략
• 신규 멤버가 즉시 전력이 되는 CLAUDE.md 작성법
• 코드 리뷰 지적이 절반으로 줄어든 구체적인 설정 예시

개인적으로 CLAUDE.md를 정비한 후, 팀에 전개하려다 난관에 부딪혔다는 이야기를 자주 듣습니다.

• 「자신의 규칙을 그대로 팀에 강요하여 반발을 샀다」
• 「모두가 제멋대로 추가해서 500행이 되었다」
• 「신규 멤버가 무엇을 믿어야 할지 모르게 되었다」

이 기사에서는 팀에서 CLAUDE.md를 운영하여 코드 리뷰(Code Review)의 지적이 반감된 실례를 바탕으로 설계 패턴을 정리합니다.

팀 운영의 기본은 「누가 작성한 규칙인가」를 명확히 나누는 것입니다.

~/.claude/CLAUDE.md ← 개인 설정 (git 관리하지 않음)
.claude/CLAUDE.md ← 프로젝트 공통 (.git 관리)
CLAUDE.md ← 리포지토리 루트 (최우선)

Claude는 위에서부터 순서대로 읽으며, 아래에 있는 파일이 우선됩니다.

우선순위 (높음)
↑
CLAUDE.md (프로젝트 루트)
...

여기에는 「왜 그렇게 하는가」를 작성합니다

# 프로젝트명 — Claude Code 설정
## 이 프로젝트에 대하여
Next.js 14 + TypeScript 기반의 B2B SaaS.
...

「왜」가 포함된 규칙은 Claude가 본질을 이해하고 응용할 수 있습니다. 「~금지」라고만 적으면 유사한 케이스에서 판단을 그르칩니다.

## 기술 스택 (Tech Stack)
- 프론트엔드: Next.js 14 App Router, Tailwind CSS
- 백엔드: Node.js 18, Prisma, PostgreSQL
...

## 개인 설정 (팀에는 적용하지 않음)
- 설명은 일본어로
- 코드 주석은 영어로
...

# CLAUDE.md (붕괴 버전 · 500행)
## TypeScript 규칙
(50행)
...

Claude의 컨텍스트(Context)가 소비되어 중요한 규칙이 무시됩니다.

✅ 대책: @include를 통한 분할 관리

# CLAUDE.md (60행 이내)
## 절대 규칙 (5개까지)
- any 타입 금지
...

.claude/rules/
├── typescript.md (TypeScript 고유 규칙)
├── react.md (React 컴포넌트 규칙)
...

- 스타일은 Tailwind만 사용
- Prisma 직접 쿼리 금지
- 에러 핸들링(Error Handling)은 반드시 포함

Claude가 예외 케이스에서 판단하지 못하고 매번 확인을 요청해 옵니다.

## 스타일: Tailwind만 사용
결정일: 2025-10
이유: styled-components와 혼재되어 번들 사이즈(Bundle Size)가 2배가 됨.
...

6개월 후에는 「왜 이 규칙이 있었지?」 하는 것들이 늘어납니다.

## 규칙 점검
최종 확인: 2026-05-01
다음 확인: 2026-08-01
...

신규 멤버가 첫날부터 Claude를 올바르게 사용할 수 있도록 하는 섹션을 추가합니다:

## 새로 참여하신 분들께
### 이 프로젝트의 Claude 사용법
1. 코드를 작성하기 전에 반드시 기존 구현을 확인하도록 함
...

실제로 효과가 있었던 CLAUDE.md 설정 패턴입니다:

## 코딩 규칙
- TypeScript의 any 금지
- 주석을 작성할 것
...

## 코드 리뷰에서 반복적으로 지적되는 사항
### 타입 정의
- `any`는 `unknown` + type guard로 변경
...

「지적되는 사항」으로 작성하면, Claude가 스스로 체크하고 수정해 줍니다.

새로운 규칙 추가
↓
1. 팀 내 합의 (Slack/PR에서 논의)
...

CLAUDE.md는 "쓰면 끝"이 아니라 "팀의 암묵지 (Tacit Knowledge)를 축적하는 문서"입니다. 코드 리뷰에서 같은 지적이 반복된다면, 그것은 CLAUDE.md에 작성해야 한다는 신호입니다.

Q. CLAUDE.md의 변경 사항은 즉시 반영되나요?

A. Claude Desktop을 재시작하지 않아도 다음 턴 (Turn)부터 반영됩니다. 큰 변경이 있을 때는 만약을 위해 재시작을 권장합니다.

Q. CLAUDE.md를 .gitignore에 넣어야 하나요?

A. 팀 규칙은 git 관리 (Git Management)를 권장합니다. 개인 설정은 ~/.claude/CLAUDE.md에 작성하여 git 관리 대상에서 제외하는 것이 베스트 프랙티스 (Best Practice)입니다.

Q. 규칙이 너무 많아서 Claude가 무시하기 시작했습니다

A. 60행을 초과하면 @include를 사용하여 분할하십시오. 또한 "절대 규칙"을 5개 이내로 압축하고, 나머지는 참조 형식으로 만들면 우선순위가 명확해집니다.

Q. 팀 멤버마다 Claude의 동작이 다른 이유는 무엇인가요?

A. ~/.claude/CLAUDE.md의 개인 설정이 영향을 미치고 있기 때문입니다. 공통으로 적용하고 싶은 규칙은 리포지토리 (Repository)의 CLAUDE.md에 작성해 주세요.