현재 인기 있는 CLAUDE.md 가이드만 해도 적어도 한두 개 이상 돌아다닌다. Builder.io가 하나를 발표했고, ClaudeFast는 완전한 키트를 제공한다. Dometrain, Gradually AI, scotthavird, Claude for Designers까지 — 모두가 자기 템플릿을 내놓고 있다.

모두 훌륭하다. 그리고 모두 개인 개발자와 스타트업을 겨냥하고 있다.

여러 저장소, 규정 준수 요구사항, Azure 인프라, 공유 MCP 서버, 그리고 똑같은 블로그 글을 읽지 않은 개발자들까지 포함된 기업 팀 전반에 Claude Code를 도입한다면, 이런 템플릿은 도착지가 아니라 출발점이다.

이 가이드에서는 그 템플릿들이 놓치는 것과, 여러분의 팀이 실제로 필요로 하는 것을 짚어본다.

한눈에 보기

CLAUDE.md는 Claude Code의 프로젝트 설정 파일로, 매 세션마다 가장 먼저 읽히는 핵심 파일입니다. 커뮤니티는 이미 견고한 기본 원칙(짧게 유지, 정체성을 먼저, 명령어와 주의사항을 문서화)에 수렴했습니다. 하지만 기업 팀에는 더 많은 것이 필요합니다. 민감한 모듈을 위한 보안 경계, 다중 저장소 규칙 배포, MCP 서버 선언, 규정 준수 가이드라인, 그리고 모델이 지시사항을 기억하는 데 의존하지 않는 훅 기반 강제 적용입니다. 이 가이드는 인기 템플릿이 잘 처리하는 부분과 놓치는 부분을 짚고, 오늘 당장 저장소에 적용할 수 있는 프로덕션급 기업 템플릿을 제공합니다.

CLAUDE.md가 실제로 무엇인지

Claude Code가 처음이라면 요약하자면 이렇다. CLAUDE.md는 저장소 루트에 있는 마크다운 파일로, Claude가 매 세션 시작 시 읽는다. 프로젝트가 무엇인지, 무엇이 어디 있는지, 어떤 명령을 실행할지, 어떤 규칙을 따를지를 Claude에게 알려준다.

전체 프로젝트 구조(CLAUDE.md, 스킬, 훅, 문서, 로컬 오버라이드)는 The Anatomy of a Claude Code Project에서 다루었다. 기초가 필요하다면 먼저 그 글을 읽어 보라.

이해해야 할 핵심은 이것이다. CLAUDE.md는 프롬프트가 아니라 설정 파일이다. 이 차이는 중요하다. 프롬프트는 일회성이다. 설정은 모든 상호작용, 모든 세션, 팀의 모든 개발자에 걸쳐 지속된다.

모두가 동의하는 표준 구조

Builder.io의 모듈식 접근, ClaudeFast의 풀패키지 키트, scotthavird의 GitHub 스타터, Dometrain의 .NET 중심 가이드, Gradually AI의 토큰 인식형 접근까지 모든 주요 템플릿을 검토한 결과, 커뮤니티는 몇 가지 보편적 원칙에 수렴했다.

  1. 500줄 이내로 유지한다. 컨텍스트 토큰은 유한하다. 파일이 비대하면 성능이 떨어진다.
  2. 프로젝트 정체성을 먼저 쓴다. 한 문장으로 이 시스템이 무엇을 하는지 설명하라.
  3. 정확한 명령을 문서화한다. 빌드, 테스트, 린트, 배포. Claude는 이를 그대로 사용한다.
  4. 주의사항을 기록한다. 이상한 부분, 즉 인증 관련 특이점, 금지된 파일, 우회 패턴 등이다.
  5. 관심사를 분리한다. 무거운 문서는 메인 파일이 아니라 .claude/rules/나 @imported 파일에 둔다.
  6. 유기적으로 키운다. 지시사항을 반복하게 될 때 규칙을 추가하라. 미리 추가하지 마라.

디렉터리 구조도 마찬가지로 정리되었다.

project/
├── CLAUDE.md                    # Identity, commands, rules (short)
├── .claude/
│   ├── settings.json            # Hooks, permissions
│   ├── commands/                # Slash commands
│   └── rules/                   # Auto-loaded rule files
└── docs/                        # @imported on demand

이 구조는 견고하다. Builder.io의 Steve Sewell이 CLAUDE.md를 간결하게 유지하기 위한 @imports 패턴을 널리 알렸다. Boris Cherny는 PR 코멘트에 @claude를 태그해 리뷰 워크플로의 일부로 규칙을 업데이트하는 방법을 보여주었다. ClaudeFast는 18개의 사전 구성 에이전트 정의와 20개 이상의 스킬 모듈로 이를 더 밀어붙였다.

모두 훌륭한 성과다. 하지만 Azure 랜딩 존과 규정 준수 팀이 목을 조르는 상황에서 4개 저장소에 15명의 개발자가 있을 때 어떤 일이 벌어지는지는 다루지 않는다.

기업 팀이 다르게 필요로 하는 것

보안 경계

개인 개발자 템플릿은 자기 자신으로부터 보호할 것이 없기 때문에 접근 제어를 고려하지 않는다. 기업 저장소에는 Claude가 매우 신중하게 접근해야 하거나 아예 손대지 말아야 할 인증 모듈, 결제 로직, IaC(코드로서의 인프라), 비밀 관리가 있다.

날카로운 경계에는 로컬 CLAUDE.md 파일이 필요하다.

src/auth/CLAUDE.md
src/billing/CLAUDE.md
infra/terraform/CLAUDE.md

각 파일에는 모듈별 제약을 담는다. 토큰 교체는 마이그레이션을 업데이트하지 않으면 수정하지 말 것, 연결 문자열을 하드코딩하지 말 것, Terraform 변경 사항을 커밋하기 전에 반드시 규정 준수 검사를 실행할 것. Claude는 해당 디렉터리에서 작업할 때 이 파일을 자동으로 불러온다.

다중 저장소 규칙 배포

CLAUDE.md의 계층(사용자 수준 ~/.claude/CLAUDE.md, 프로젝트 수준, 하위 디렉터리 수준)은 강력하지만 조직 전체에서 이를 어떻게 관리할지에 대해서는 아무도 이야기하지 않는다. 30개 저장소가 있으면 모든 프로젝트에 복사-붙여넣기할 필요가 없는 공유 표준이 있어야 한다.

잘 작동하는 패턴은 이렇다. 조직의 기본 규칙을 담은 중앙 claude-standards 저장소를 유지한다. 그런 다음 CI/CD로 배포한다. 즉, 파이프라인 단계가 공유 .claude/rules/ 파일을 각 저장소에 동기화한다. 원한다면 Git 서브모듈을 써도 된다. 핵심은 Azure 명명 규칙, 보안 기준, 규정 준수 규칙을 한 번 작성하고 모든 곳에서 상속받게 하는 것이다.

MCP 서버 구성

Model Context Protocol 서버는 Claude에게 외부 도구(구성 요소 라이브러리, 문서 검색, 배포 API, Jira)에 대한 접근을 제공한다. Dometrain이 Shadcn 예제로 이를 잠깐 다루었지만, 기업 팀은 내부 패키지 레지스트리, Azure 리소스 API, 정책 엔진 등 여러 MCP 서버를 운영한다.

CLAUDE.md에는 어떤 MCP 서버가 사용 가능하고 각각 무엇을 위한 것인지 선언되어 있어야, Claude가 언제 외부 컨텍스트를 찾고 언제 로컬 파일을 사용할지 알 수 있다.

강제 적용을 위한 훅

이것이 핵심이다. 모든 템플릿은 Claude에게 “이 규칙을 따르라"고 말한다. 기업 팀은 모델이 기억하는 것에 의존할 수 없다. 결정론적 강제 적어가 필요하다.

Claude Code 훅(.claude/settings.json)은 특정 작업 전후에 자동으로 실행된다. 매번 반드시 일어나야 할 일에 훅을 사용하라.

  • 모든 파일 편집 후 코드 포맷
  • 인프라 변경 시 보안 린트 실행
  • 보호된 디렉터리 쓰기 차단
  • 커밋 전 규정 준수 검사 실행

프롬프트는 제안이다. 훅은 보장이다. “Claude가 대체로 우리 표준을 따른다"와 “Claude가 항상 우리 표준을 따른다"의 차이가 바로 훅이다.

코드로서의 규정 준수 규칙

규제 대상 산업이라면 CLAUDE.md 규칙 파일에 규정 준수 요구사항을 직접 인코딩해야 한다. 로그 문에 PII를 넣지 않는다. 인증 없는 퍼블릭 엔드포인트를 만들지 않는다. 승인된 Azure 지역 외부에서 리소스를 프로비저닝하지 않는다. 이것은 스타일 취향이 아니라 감사 요구사항이며, 매 세션마다 자동 로드되는 .claude/rules/compliance.md에 속한다.

기업용 CLAUDE.md 템플릿

다음은 Terraform 기반 Azure 인프라, .NET 또는 Node.js 애플리케이션 계층, Intune으로 관리되는 엔드포인트를 운영하는 기업 팀을 위한 프로덕션 준비 템플릿이다.

# Project: ContosoCloud Platform

Enterprise SaaS platform — .NET 8 APIs, React frontend, Azure landing zone.
Managed by the Platform Engineering team at Contoso.

## Commands

- Build: `dotnet build src/ContosoCloud.sln`
- Test: `dotnet test --no-build --verbosity normal`
- Lint: `dotnet format --verify-no-changes && npx eslint src/web/`
- Deploy (staging): `az deployment group create -g rg-contoso-staging -f infra/main.bicep`
- Terraform plan: `cd infra/terraform && terraform plan -var-file=env/staging.tfvars`

## Architecture

- `src/api/` — .NET 8 Web API (Clean Architecture)
- `src/web/` — React 18 + TypeScript frontend
- `infra/bicep/` — Azure Bicep templates (landing zone)
- `infra/terraform/` — Terraform modules (networking, DNS)
- `scripts/` — CI/CD pipeline scripts
- `.claude/rules/` — Auto-loaded team standards

## Rules

- Never hardcode secrets. Use Azure Key Vault references.
- All API endpoints require authentication. No anonymous access.
- Follow Azure naming convention: `{resource}-{project}-{env}-{region}`
- Terraform changes require `terraform plan` output in PR description.
- No `any` types in TypeScript. No `dynamic` in C# unless justified.

## MCP Servers

- `azure-docs` — Search Azure documentation (use for service limits, SKU details)
- `component-lib` — Internal React component library (check before building new UI)
- `jira` — Project tracking (reference ticket numbers in commits)

## Gotchas

- Auth uses MSAL with custom token cache — see `src/api/Auth/CLAUDE.md`
- Database migrations are EF Core — never modify generated migration files
- The staging Key Vault has a different access policy than prod — check before assuming
- Bicep modules in `infra/bicep/modules/` are shared across 3 teams — coordinate changes

@docs/architecture.md
@docs/adr/
@docs/runbooks/incident-response.md

이와 함께 코드 스타일, 보안 정책, 규정 준수를 위한 .claude/rules/ 파일을 구성한다.

.claude/rules/
├── code-style.md          # Formatting, naming, patterns
├── security.md            # Auth requirements, secret handling, input validation
├── compliance.md          # Data residency, PII handling, audit logging
├── azure-conventions.md   # Naming, tagging, resource group structure
└── terraform.md           # Module patterns, state management, plan requirements

그리고 .claude/settings.json의 훅으로 타협 불가능한 규칙을 강제한다.

{
  "hooks": {
    "postFileEdit": [
      { "command": "dotnet format src/ContosoCloud.sln --include ${file}" },
      { "command": "npx eslint --fix ${file}" }
    ],
    "preCommit": [
      { "command": "dotnet test --no-build" },
      { "command": "scripts/compliance-check.sh" }
    ]
  }
}

흔히 하는 실수

모든 것을 한 파일에 쏟아붓기. 루트 CLAUDE.md는 백과사전이 아니라 목차여야 한다. 500줄이 넘으면 컨텍스트 토큰을 낭비하며 Claude가 지시사항을 놓치기 시작한다.

훅 없이 프롬프트에만 의존. 기록할 가치가 있는 규칙이라면 강제할 가치도 있다. 훅은 구성 비용이 적고 잊힐 일이 없다.

계층을 무시. 모든 템플릿이 루트 수준 CLAUDE.md를 보여준다. 하위 디렉터리 오버라이드나 사용자 수준 기본값을 다루는 곳은 거의 없다. 기업 팀은 세 계층이 함께 작동해야 한다.

템플릿을 다듬지 않고 복사-붙여넣기. Builder.io의 ShopFront 예제는 Next.js 전자상거래 앱에는 훌륭하다. Azure 랜딩 존 저장소에는 다른 지시사항이 필요하다. /init로 시작한 뒤 과감히 잘라내라.

팀 소유권 부재. 한 사람이 CLAUDE.md를 작성하고 아무도 유지 보수하지 않으면 썩어간다. 규칙 파일의 소유권을 해당 부서에 맡겨라. 보안 팀이 security.md를, 플랫폼 팀이 azure-conventions.md를 소유한다. 이를 코드처럼 다루어 풀 리퀘스트를 거치게 하라.

FAQ

아래 FAQ 섹션을 참조하세요. 기업 팀으로부터 CLAUDE.md에 대해 가장 자주 받는 질문을 다룹니다.

팀을 빠르게 준비시키기

“Claude Code를 사용하는 개발자"에서 “대규모로 Claude Code를 배포하는 팀"으로 가는 간극은 구조다. 템플릿은 시작점을 제공한다. 기업 패턴(보안 경계, 분산 규칙, 훅 강제 적용, 규정 준수 통합)이 프로덕션까지 데려다 준다.

Big Hat Group은 기업 팀이 이런 인프라를 구축하도록 돕는다. IT 팀을 위한 Claude Code 및 AI 에이전트 교육을 운영하고, 컨설팅 실무는 이 글에서 설명한 패턴(다중 저장소 CLAUDE.md 전략, MCP 서버 통합, OpenClaw 배포, 규정 준수 팀이 AI 보조 개발에 안심하도록 만드는 거버넌스 프레임워크)을 전문으로 다룬다.

팀이 실험 단계를 넘어 Claude Code를 실무에 투입할 준비가 되었다면, 문의해 주세요.

Kevin Kaminski는 Microsoft MVP이자 Big Hat Group의 Principal로, 기업 팀이 AI 에이전트, Windows 365, 최신 관리 솔루션을 배포하도록 돕습니다.