Claude Code 공식문서 리뷰-Deployment[1] : 엔터프라이즈 배포 개요(Enterprise deployment overview)

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> Deployment 섹션의 내용 중 [Enterprise deployment overview - 엔터프라이즈 배포 개요]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/ko/third-party-integrations

엔터프라이즈 배포 개요 - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다. 

 

회사에서 Claude Code를 도입하려는가?

대규모 팀에서 Claude Code를 사용하려면 단순히 개발자 개인 API 키를 쓰는 것만으로는 부족하다. 보안 정책, 비용 관리, 사용량 추적 등 기업 환경에서 필요한 다양한 요구사항을 충족해야 한다.

이 문서는 이런 분들을 위한 가이드이다.

• 이미 AWS, GCP, Azure를 사용 중인 팀
• 회사 보안 정책(프록시, 방화벽) 준수가 필요한 경우
• 여러 팀의 API 사용량을 중앙에서 관리하고 싶은 경우
• 예산 통제와 감사 로깅이 필요한 경우

엔터프라이즈 배포로 할 수 있는 것들

클라우드 통합	AWS Bedrock, Google Vertex AI, Microsoft Foundry를 통해 기존 인프라와 자연스럽게 연동
보안 준수	회사 프록시, mTLS 인증 등 엔터프라이즈 보안 정책 지원
중앙 관리	LLM 게이트웨이로 사용량 추적, 예산 관리, 감사 로깅을 한 곳에서
비용 최적화	팀별 사용량 모니터링과 예산 책정으로 비용 통제

 

제공업체 비교

글을 작성하다보니 한글 버전의 문서와, 영문 버전의 문서의 갭이 존재하여

이왕이면 영문버전의 글을 번역하는 컨셉으로 본문을 구성해 나가도록 하겠다.

ex) 좌) 영문버전 / 우) 한글버전

 

영문 버전을 기준으로 다시 시작 해보자.

기능	Anthropic	Amazon Bedrock	Google Vertex AI	Microsoft Foundry
리전	지원 국가	다수 AWS 리전	다수 GCP 리전	다수 Azure 리전
프롬프트 캐싱	기본 활성화	기본 활성화	기본 활성화	기본 활성화
인증	API 키	API 키 또는 AWS 자격 증명	GCP 자격 증명	API 키 또는 Entra ID
비용 추적	대시보드	AWS Cost Explorer	GCP Billing	Azure Cost Management
엔터프라이즈 기능	Teams, 사용량 모니터링	IAM 정책, CloudTrail	IAM 역할, Cloud Audit Logs	RBAC 정책, Azure Monitor

어떤 제공업체를 선택해야 할까?

상황 1: "우리는 이미 AWS를 쓰고 있어"

→ Amazon Bedrock을 선택하자!
기존 AWS 계정과 IAM 정책을 그대로 활용할 수 있어서 별도 인증 설정이 필요 없다. CloudTrail로 감사 로그도 자동으로 남고, Cost Explorer로 비용 추적도 간편하다.

상황 2: "구글 클라우드가 우리 메인 인프라야"

→ Google Vertex AI가 최선이다!
GCP IAM으로 권한 관리하고, Cloud Billing으로 비용 보고서 받을 수 있다. 이미 GCP 쓰고 있다면 굳이 다른 플랫폼 배울 필요 없다.

상황 3: "Azure 생태계에 올인했어"

→ Microsoft Foundry를 쓰자!
Entra ID(구 Azure AD)로 SSO 연동하고, Azure Cost Management로 비용 관리할 수 있다. Azure Monitor와 통합되어 모니터링도 편리하다.

상황 4: "클라우드 없이 간단하게 시작하고 싶어"

→ Anthropic 직접 연결이 좋다!
API 키만 발급받으면 바로 시작할 수 있다. 작은 팀이나 PoC 단계라면 이게 가장 빠르다. 나중에 규모가 커지면 클라우드로 전환해도 된다.

 

클라우드 제공업체별 상세 가이드

각 클라우드 제공업체는 Claude API를 자체 플랫폼에 통합하여 제공한다. 이미 사용 중인 인프라가 있다면 그대로 활용할 수 있어서 매우 편리하다.

● Amazon Bedrock

언제 사용하면 좋을까?

• 이미 AWS를 메인 클라우드로 사용 중인 경우
• IAM 정책으로 세밀한 권한 관리가 필요한 경우
• CloudWatch, CloudTrail 같은 AWS 모니터링 도구와 통합하고 싶은 경우

주요 기능

• 인증 옵션: API 키 또는 IAM Role 기반 인증 (IAM 권장)
• 모니터링: CloudWatch로 API 호출 로그, CloudTrail로 감사 추적
• 비용 관리: AWS Cost Explorer로 상세한 비용 분석
• 리전 선택: 데이터 주권이 중요하다면 원하는 AWS 리전 선택 가능

 

● Google Vertex AI

언제 사용하면 좋을까?

• Google Cloud Platform(GCP)을 주로 사용하는 경우
• BigQuery, Dataflow 등 GCP 데이터 도구와 연계하고 싶은 경우
• Google Workspace와 통합된 환경을 원하는 경우

주요 기능

• 인증: GCP 서비스 계정 자격 증명으로 안전한 인증
• 보안 & 규정 준수: GCP의 엔터프라이즈급 보안 정책 활용
• 통합: Vertex AI의 다른 ML 도구들과 자연스러운 연동
• 비용 관리: GCP Billing으로 프로젝트별 비용 추적

 

● Microsoft Foundry

언제 사용하면 좋을까?

• Azure를 기업 표준 클라우드로 사용하는 경우
• Microsoft Entra ID(구 Azure AD)로 SSO를 구현하고 싶은 경우
• Microsoft 365, Teams 등과 통합이 필요한 경우

주요 기능

• 인증 옵션: API 키 또는 Microsoft Entra ID (SSO 가능)
• 결제 통합: Azure 청구서에 Claude 사용료가 함께 청구
• 모니터링: Azure Monitor로 실시간 성능 추적
• 권한 관리: Azure RBAC으로 팀별 접근 제어

팁: 멀티 클라우드는 어떤가?

여러 클라우드를 동시에 쓰는 경우(AWS + GCP 등)라면? 가장 많이 쓰는 플랫폼부터 시작하자. 나중에 LLM 게이트웨이를 도입하면 여러 제공업체를 동시에 관리할 수 있다. 처음부터 복잡하게 갈 필요는 없을 것 같다.

 

기업 인프라 통합

보안이 중요한 기업 환경에서는 모든 외부 통신이 회사 정책을 따라야 한다. Claude Code는 기업 네트워크 환경에서도 안전하게 작동하도록 설계되었다.

엔터프라이즈 네트워크 (프록시 & 방화벽)

이런 상황, 익숙한가?

"우리 회사는 보안 정책상 모든 외부 API 호출이 회사 프록시를 거쳐야 해."
"SSL 인증서를 회사에서 발급한 걸로 써야 하는데..."
"특정 IP 대역에서만 외부 접속이 허용되어 있어."

걱정 말자! Claude Code는 이런 환경을 모두 지원한다:

• HTTP/HTTPS 프록시 지원
  회사 프록시 서버를 통해 모든 API 호출을 라우팅할 수 있다. HTTPS_PROXY 환경 변수만 설정하면 끝!
• mTLS (상호 TLS 인증)
  클라이언트와 서버 양쪽 모두 인증서로 신원을 검증하는 mTLS를 지원한다. 금융권이나 의료 분야처럼 보안이 특히 중요한 곳에서 필수다.
• 커스텀 CA 인증서
  회사에서 발급한 자체 CA 인증서를 사용해야 한다면? 문제없다. Claude Code가 커스텀 인증서를 인식하도록 설정할 수 있다.

더 자세한 설정 방법이 필요한가?
엔터프라이즈 네트워크 구성 가이드 문서를 참조하자. 단계별로 상세히 설명되어 있다.

LLM 게이트웨이 (중앙 집중식 관리)

LLM 게이트웨이가 뭔가?

여러 팀이 Claude를 사용할 때 각자 API 키를 쓰면 관리가 어렵다. 누가 얼마나 썼는지, 예산은 넘지 않는지 파악하기 힘들다. LLM 게이트웨이는 모든 API 호출을 중앙에서 관리하는 일종의 "관문"이다.

게이트웨이를 쓰면 이런 게 가능하다:

사용량 추적	팀별, 프로젝트별로 누가 얼마나 API를 사용했는지 실시간으로 확인할 수 있다. "마케팅팀이 이번 달에 토큰을 너무 많이 썼네?" 같은 분석이 가능해진다.
예산 관리	팀별로 월 예산을 설정하고, 한도를 넘으면 자동으로 차단할 수 있다. "이번 달 예산 $500까지만" 같은 제한을 걸 수 있다.
감사 로깅	누가 언제 어떤 요청을 했는지 모든 기록을 남긴다. 규정 준수(compliance)가 중요한 산업에서 필수다.
중앙 인증 관리	게이트웨이가 클라우드 제공업체 인증을 대신 처리해준다. 개발자는 복잡한 인증 설정을 신경 쓸 필요가 없어진다.
모델 간 전환	필요에 따라 Claude, GPT, Gemini 등 여러 모델을 동적으로 전환할 수 있다. 사용자는 코드 변경 없이 다른 모델을 쓸 수 있다.

⚠️ 언제 게이트웨이를 도입해야 할까?

작은 팀 (5명 이하): 아직 필요 없다. 직접 연결이 더 간단하다.
중간 규모 팀 (10~50명): 고려해볼 시점이다. 비용 관리가 중요해지기 시작한다.
대규모 조직 (50명 이상): 강력 추천! 게이트웨이 없이 관리하기 정말 힘들다.

LLM 게이트웨이 구축 방법
LLM 게이트웨이 배포 가이드에서 실제 구축 방법을 확인하자. 인기 있는 오픈소스 솔루션(LiteLLM, Portkey 등) 설정 방법도 소개한다.

 

구성 개요

핵심 구분

구성 유형	설명	환경 변수
기업 프록시	트래픽 라우팅을 위한 HTTP/HTTPS 프록시	HTTPS_PROXY, HTTP_PROXY
LLM 게이트웨이	인증 처리 및 제공업체 호환 엔드포인트 서비스	ANTHROPIC_BASE_URL, ANTHROPIC_BEDROCK_BASE_URL

참고
두 구성은 함께 사용할 수 있다.

 

구성 예시

이론은 충분하다. 실제로 어떻게 설정하는지 구체적인 예제를 보자. 상황에 맞는 예제를 찾아서 그대로 따라해보자.

 

시나리오 1: AWS 쓰는데 회사 프록시를 거쳐야 하는 경우

상황 설명
AWS Bedrock을 쓰고 싶은데, 회사 보안 정책상 모든 외부 API 호출은 프록시 서버(proxy.company.com:8080)를 거쳐야 한다.

# 1. Bedrock 사용 활성화
export CLAUDE_CODE_USE_BEDROCK=1

# 2. AWS 리전 설정 (회사에서 주로 쓰는 리전)
export AWS_REGION=us-east-1

# 3. 회사 프록시 서버 설정
export HTTPS_PROXY='https://proxy.company.com:8080'

# 이제 Claude Code를 실행하면 프록시를 통해 Bedrock에 연결된다!

동작 확인
설정 후 claude /status 명령으로 프록시가 제대로 설정되었는지 확인하자. "Proxy: https://proxy.company.com:8080" 같은 메시지가 나오면 성공이다!

 

시나리오 2: AWS인데 LLM 게이트웨이로 비용 관리하고 싶은 경우

상황 설명
여러 팀이 Claude를 쓰는데, 팀별 사용량을 추적하고 예산을 관리하고 싶다. 이미 LLM 게이트웨이를 llm-gateway.company.com에 구축했다. 게이트웨이가 AWS 인증을 대신 처리해준다.

# 1. Bedrock 사용 활성화
export CLAUDE_CODE_USE_BEDROCK=1

# 2. LLM 게이트웨이 주소 설정
export ANTHROPIC_BEDROCK_BASE_URL='https://llm-gateway.company.com/bedrock'

# 3. AWS 인증 건너뛰기 (게이트웨이가 대신 처리)
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

# 게이트웨이가 요청을 받아서 사용량을 기록하고 AWS로 전달한다

⚠️ 주의
SKIP_AUTH=1은 게이트웨이가 인증을 대신 처리할 때만 사용하자. 게이트웨이 없이 이 옵션을 켜면 인증 에러가 발생한다!

 

시나리오 3: Azure + 프록시 환경

상황 설명
Microsoft Azure를 쓰고 있고, Entra ID 인증은 이미 설정되어 있다. 회사 프록시도 거쳐야 하는 상황이다.

# 1. Microsoft Foundry 활성화
export CLAUDE_CODE_USE_FOUNDRY=1

# 2. Azure 리소스 이름 설정
export ANTHROPIC_FOUNDRY_RESOURCE=my-company-claude

# 3. Entra ID 인증 사용 (API 키 불필요)
# Entra ID가 이미 설정되어 있다면 API_KEY는 생략 가능

# 4. 회사 프록시 설정
export HTTPS_PROXY='https://proxy.company.com:8080'

# Entra ID로 자동 인증하고, 프록시를 통해 Azure에 연결된다

 

시나리오 4: Google Cloud + 프록시

상황 설명
GCP를 메인 클라우드로 쓰고 있고, 프로젝트 ID는 my-ai-project다. 회사 프록시를 통해 접속해야 한다.

# 1. Vertex AI 활성화
export CLAUDE_CODE_USE_VERTEX=1

# 2. GCP 리전 설정 (데이터 위치가 중요하면 신중히 선택)
export CLOUD_ML_REGION=us-east5

# 3. GCP 프로젝트 ID 설정
export ANTHROPIC_VERTEX_PROJECT_ID=my-ai-project

# 4. 회사 프록시 설정
export HTTPS_PROXY='https://proxy.company.com:8080'

# GCP 서비스 계정 자격 증명으로 인증하고 프록시를 통해 연결된다

💡 GCP 인증 팁
GCP는 서비스 계정 JSON 파일이 필요하다. GOOGLE_APPLICATION_CREDENTIALS 환경 변수로 JSON 파일 경로를 설정하자: export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

 

시나리오 5: Google Cloud + LLM 게이트웨이

상황 설명
GCP를 쓰는데, 중앙 LLM 게이트웨이로 여러 모델을 관리하고 있다. 게이트웨이가 GCP 인증을 처리해준다.

# 1. Vertex AI 활성화
export CLAUDE_CODE_USE_VERTEX=1

# 2. LLM 게이트웨이 주소 설정
export ANTHROPIC_VERTEX_BASE_URL='https://llm-gateway.company.com/vertex'

# 3. GCP 인증 건너뛰기 (게이트웨이가 처리)
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1

# 게이트웨이가 인증과 사용량 추적을 모두 처리한다

환경 변수를 영구적으로 설정하려면?

매번 export 치기 귀찮다면, 셸 설정 파일에 추가하자:

Bash 사용자: ~/.bashrc 또는 ~/.bash_profile
Zsh 사용자: ~/.zshrc

파일 끝에 위 export 명령들을 복사해 넣고 저장한 후, source ~/.zshrc로 적용하면 된다!

 

인증 구성 - 누가 인증을 처리하는가?

인증의 두 가지 패턴

Claude Code는 상황에 따라 두 가지 방식으로 인증할 수 있다: 직접 인증 vs 게이트웨이 대리 인증

패턴 1: Claude Code가 직접 인증 (기본 방식)

개발자 각자가 API 키나 클라우드 자격 증명으로 직접 인증하는 방식이다. 작은 팀이나 개인 개발자에게 적합하다.

어떻게 동작하나?

Anthropic 직접	ANTHROPIC_API_KEY를 사용 → Claude Code가 API 키를 Authorization 헤더에 담아 전송
AWS Bedrock	AWS SDK 자격 증명 사용 (IAM Role, Access Key 등) → Claude Code가 자동으로 AWS Signature V4 서명 생성
Google Vertex	GCP 서비스 계정 자격 증명 사용 → Claude Code가 OAuth 2.0 토큰 자동 획득
Microsoft Foundry	API 키 또는 Entra ID 사용 → Claude Code가 Azure 인증 처리

 

패턴 2: LLM 게이트웨이가 대리 인증 (중앙 관리)

LLM 게이트웨이를 쓰면 개발자는 복잡한 클라우드 인증을 신경 쓸 필요가 없다. 게이트웨이가 모든 인증을 대신 처리해준다.

어떻게 동작하나?

1. 개발자가 Claude Code에 요청
   → Claude Code는 게이트웨이 주소로 요청 전송
2. 게이트웨이가 사용자 식별 (팀 ID, 프로젝트 ID 등)
   → 사용량 추적과 예산 관리에 사용
3. 게이트웨이가 클라우드 제공업체에 인증
   → AWS/GCP/Azure 자격 증명은 게이트웨이만 알고 있음
4. 게이트웨이가 응답을 Claude Code에 전달
   → 로그 기록, 비용 계산 등도 게이트웨이가 처리

⚠️ 중요: SKIP_AUTH 플래그는 언제 쓰나?

LLM 게이트웨이를 사용할 때만 다음 플래그를 설정해야 한다:

• CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
  → 게이트웨이가 AWS 인증 처리
• CLAUDE_CODE_SKIP_VERTEX_AUTH=1
  → 게이트웨이가 GCP 인증 처리
• CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1
  → 게이트웨이가 Azure 인증 처리

💡 이 플래그 없이 게이트웨이만 설정하면 Claude Code가 직접 인증하려다 실패한다!

 

게이트웨이 커스텀 인증 토큰

게이트웨이가 자체 인증 시스템을 쓰는 경우 (예: JWT 토큰), ANTHROPIC_AUTH_TOKEN을 설정할 수 있다.

# 게이트웨이 커스텀 토큰 사용
export ANTHROPIC_AUTH_TOKEN='your-gateway-token'

# Claude Code가 모든 요청에 이 토큰을 포함한다
# Authorization: Bearer your-gateway-token

→ 게이트웨이는 이 토큰으로 사용자/팀을 식별하고, 적절한 클라우드 자격 증명을 사용한다.

 

올바른 배포 구성 선택

직접 제공업체 접근

다음 조직에 적합하다:

• 가장 간단한 설정을 원함
• 기존 AWS 또는 GCP 인프라 보유
• 제공업체 네이티브 모니터링 및 규정 준수 필요

기업 프록시

다음 조직에 적합하다:

• 기존 기업 프록시 요구사항 있음
• 트래픽 모니터링 및 규정 준수 필요
• 모든 트래픽을 특정 네트워크 경로로 라우팅해야 함

LLM 게이트웨이

다음 조직에 적합하다:

• 팀 간 사용량 추적 필요
• 모델 간 동적 전환 원함
• 사용자 정의 요청 한도 또는 예산 필요
• 중앙 집중식 인증 관리 필요

 

문제 해결 & 디버깅

설정이 제대로 되었는지 확인하고, 문제가 생겼을 때 빠르게 해결하는 방법을 알아보자.

1단계: 설정 상태 확인하기

먼저 현재 설정이 제대로 적용되었는지 확인하자:

# Claude Code 상태 확인
claude /status

이 명령으로 확인할 수 있는 것들:

• 사용 중인 제공업체: Anthropic, Bedrock, Vertex, Foundry 중 무엇을 쓰고 있는지
• 프록시 설정: 프록시가 제대로 적용되었는지
• 인증 방식: API 키인지, IAM인지, Entra ID인지
• Base URL: 게이트웨이 주소가 올바른지

💡 예상 출력 예시

Provider: Amazon Bedrock
Region: us-east-1
Proxy: https://proxy.company.com:8080
Authentication: IAM Role
Status: Connected

 

2단계: 상세 로그 보기

문제를 정확히 파악하려면 상세 로그가 필요하다:

# 디버그 모드 활성화
export ANTHROPIC_LOG=debug

# 이제 Claude Code를 실행하면 상세한 로그가 출력된다
claude "간단한 Python 함수 만들어줘"

⚠️ 주의
디버그 모드는 많은 정보를 출력한다. 문제 해결 후에는 꼭 끄자:
unset ANTHROPIC_LOG

흔한 문제와 해결 방법

문제 1: "Authentication failed" 에러

원인:

• API 키가 잘못되었거나 만료됨
• IAM 권한이 부족함 (AWS/GCP/Azure)
• 게이트웨이 설정에서 SKIP_AUTH=1을 빼먹음

해결:

• API 키 재확인: echo $ANTHROPIC_API_KEY
• AWS라면: aws sts get-caller-identity로 IAM 확인
• GCP라면: gcloud auth list로 인증 확인
• 게이트웨이 쓴다면: SKIP_AUTH=1 설정 확인

문제 2: "Connection timeout" 에러

원인:

• 프록시 주소가 틀렸거나 프록시 서버가 다운됨
• 방화벽에서 외부 접속을 차단함
• 네트워크 연결 끊김

해결:

• 프록시 확인: curl -x $HTTPS_PROXY https://api.anthropic.com
• 프록시 없이 테스트: unset HTTPS_PROXY 후 재시도
• IT 팀에 문의하여 방화벽 규칙 확인

문제 3: "Model not found" 에러

원인:

• 선택한 리전에서 해당 모델을 지원하지 않음
• 모델 액세스 권한이 없음 (AWS Bedrock)

해결:

• AWS Bedrock: 콘솔에서 "Model access" 메뉴에서 Claude 모델 활성화
• 다른 리전 시도: export AWS_REGION=us-west-2

문제 4: "SSL certificate verify failed"

원인:

• 회사 자체 CA 인증서를 쓰는데 Claude Code가 인식 못 함
• 프록시가 SSL을 가로채는데 인증서 문제 발생

해결:

• 회사 CA 인증서 경로 설정:
  export SSL_CERT_FILE=/path/to/company-ca.crt
• IT 팀에 요청하여 인증서 받기

디버깅 체크리스트

문제가 생겼을 때 순서대로 확인하자:

1. ☐ claude /status로 현재 설정 확인
2. ☐ echo $환경변수명으로 환경 변수가 제대로 설정되었는지 확인
3. ☐ ANTHROPIC_LOG=debug로 상세 로그 활성화
4. ☐ 프록시 없이 테스트해보기 (프록시 문제인지 확인)
5. ☐ 가장 간단한 설정으로 시작해서 하나씩 추가하기
6. ☐ 공식 문서의 최신 환경 변수 목록 확인
7. ☐ 그래도 안 되면 GitHub Issues나 커뮤니티에 질문하기

 

조직을 위한 실전 모범 사례

기술적 설정도 중요하지만, 팀 전체가 효과적으로 Claude Code를 활용하려면 조직 차원의 가이드라인과 모범 사례가 필요하다.

1. 문서화: CLAUDE.md로 지식 공유하기

CLAUDE.md가 뭔가?

Claude Code가 읽을 수 있는 마크다운 파일이다. 프로젝트 규칙, 코딩 스타일, 아키텍처 설명 등을 넣어두면 Claude가 이를 참고해서 더 정확하고 일관된 코드를 작성한다.

 

계층별로 CLAUDE.md를 배치하자:

조직 전체	위치: ~/.claude/CLAUDE.md (개인 홈 디렉토리) 내용: 회사 코딩 표준 (예: "변수명은 camelCase 사용") 보안 정책 (예: "API 키는 환경 변수로만 관리") 금지 사항 (예: "절대 프로덕션 DB에 직접 접속 금지")
프로젝트별	위치: /project-root/CLAUDE.md 내용: 프로젝트 아키텍처 설명 빌드 & 테스트 명령어 자주 쓰는 개발 패턴 기여 가이드라인

팁
팀의 시니어 개발자가 CLAUDE.md를 작성하고, 신규 팀원은 Claude Code가 이 규칙을 자동으로 따르게 할 수 있다. 온보딩이 훨씬 쉬워진다!

 

2. 원클릭 설치 스크립트 만들기

왜 필요한가?

신규 개발자가 입사했을 때, 복잡한 환경 변수 설정을 일일이 가르치는 건 비효율적이다. 설치 스크립트를 준비해두면 누구나 5분 안에 Claude Code를 쓸 수 있다.

예시 설치 스크립트 (setup-claude.sh):

#!/bin/bash

echo "우리 회사 Claude Code 설정 시작..."

# 1. Claude Code 설치
npm install -g @anthropics/claude-code

# 2. 회사 표준 환경 변수 설정
cat >> ~/.zshrc << 'EOF'
# 우리 회사 Claude Code 설정
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export HTTPS_PROXY='https://proxy.company.com:8080'
EOF

# 3. 회사 전체 CLAUDE.md 다운로드
mkdir -p ~/.claude
curl -o ~/.claude/CLAUDE.md https://internal.company.com/claude-standards.md

echo "설정 완료! 터미널을 재시작하거나 'source ~/.zshrc'를 실행하자."

이 스크립트를 사내 위키나 온보딩 문서에 공유하면 누구나 쉽게 시작할 수 있다.

3. 단계적 도입 전략

처음부터 모든 걸 자동화하려고 하지 말자!

1단계: 간단한 질문으로 시작 (1주차)

• "이 함수가 뭐 하는 거야?"
• "이 에러 메시지 무슨 뜻이야?"
• "테스트는 어떻게 실행해?"

→ 팀원들이 Claude Code와 대화하는 게 편해지도록 유도

2단계: 작은 버그 수정 (2-3주차)

• "이 버튼 클릭 시 색상이 바뀌게 해줘"
• "이 함수에 에러 핸들링 추가해줘"

→ 코드 작성 전에 "먼저 계획 세워줘"라고 요청하는 습관 들이기

3단계: 기능 구현 (4주차 이후)

• "사용자 프로필 페이지를 만들어줘"
• "결제 API를 연동해줘"

→ 코드 리뷰는 여전히 사람이 하되, 반복 작업은 Claude에게 맡기기

4. 보안 정책 강제하기

⚠️ 중요: 개발자가 임의로 변경할 수 없는 정책 설정

회사 보안 정책은 개인이 마음대로 바꾸면 안 된다. 시스템 레벨 설정을 사용하면 개발자가 로컬에서 덮어쓸 수 없다.

관리자가 설정할 곳:

• /etc/claude/config.json (Linux/Mac)
• C:\ProgramData\Claude\config.json (Windows)

예시 보안 정책:

{
  "enforced": {
    "HTTPS_PROXY": "https://proxy.company.com:8080",
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "ANTHROPIC_BEDROCK_BASE_URL": "https://llm-gateway.company.com/bedrock"
  },
  "blocked_commands": [
    "rm -rf /",
    "curl https://malicious.com"
  ]
}

5. MCP로 회사 도구 연동하기

MCP(Model Context Protocol)가 뭔가?

Claude가 외부 도구(Jira, Slack, 사내 위키 등)와 연동할 수 있게 해주는 표준 프로토콜이다. 예를 들어 "Jira에서 내 티켓 목록 보여줘" 같은 명령이 가능해진다.

 

실전 활용 예시:

• 티켓 관리 시스템 연동
  "Jira PROJ-1234 티켓의 요구사항을 읽고 코드를 작성해줘"
• 에러 로그 분석
  "Sentry에서 최근 1시간 에러 로그 가져와서 분석해줘"
• 사내 위키 검색
  "Confluence에서 '결제 API' 문서 찾아서 요약해줘"

 

MCP 설정 공유 방법:

프로젝트 루트에 .mcp.json 파일을 만들고 Git에 커밋하면, 팀 전체가 동일한 MCP 서버를 사용할 수 있다.

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {
        "JIRA_URL": "https://company.atlassian.net"
      }
    }
  }
}

💡 팁
DevOps 팀이 중앙에서 MCP 서버를 설정하고, 개발자는 그냥 가져다 쓰기만 하면 된다. 팀 전체 생산성이 올라간다!

 

다음 단계 - 상황별 가이드

전체 개요를 이해했다면, 이제 실제 환경에 맞는 상세 가이드를 따라가 보자.

💡 어떤 가이드를 먼저 봐야 할까?

현재 팀에서 쓰고 있는 클라우드 플랫폼에 해당하는 문서부터 시작하자. 네트워크 제약이 있다면 엔터프라이즈 네트워크 구성도 함께 봐야 한다.

문서	언제 유용한가?
Amazon Bedrock 설정	이런 경우 필수: AWS를 메인 클라우드로 사용 중 IAM 정책으로 권한 관리하고 싶음 CloudWatch, CloudTrail 같은 AWS 네이티브 도구 활용 핵심 내용: IAM 정책 설정, 리전 선택, Use Case 신청, 비용 추적 설정
Google Vertex AI 구성	이런 경우 필수: GCP를 주요 클라우드 플랫폼으로 사용 BigQuery, Dataflow 등 GCP 도구와 연계 Google Workspace와 통합 필요 핵심 내용: 서비스 계정 설정, GCP IAM 권한, Cloud Billing 연동
Microsoft Foundry 설정	이런 경우 필수: Azure를 기업 표준 클라우드로 채택 Entra ID(Azure AD)로 SSO 구현 Microsoft 365, Teams와 통합 필요 핵심 내용: Entra ID 인증, Azure RBAC 설정, Cost Management 연동
엔터프라이즈 네트워크 구성	이런 경우 필수: 회사 프록시를 통해서만 외부 접속 가능 mTLS 인증이나 커스텀 CA 인증서 사용 특정 IP 대역에서만 접속 허용 핵심 내용: HTTPS_PROXY 설정, mTLS 구성, CA 인증서 등록, 샌드박싱
LLM 게이트웨이 배포	이런 경우 필수: 여러 팀의 API 사용량을 중앙에서 관리 팀별 예산 설정과 사용량 제한 필요 멀티 클라우드 환경에서 통합 관리 핵심 내용: 게이트웨이 아키텍처, 라우팅 규칙, 사용량 추적, 예산 알림
설정 레퍼런스	이런 경우 유용: 모든 환경 변수 목록을 한눈에 보고 싶을 때 특정 설정 옵션의 정확한 값을 확인하고 싶을 때 고급 설정을 커스터마이징하고 싶을 때 핵심 내용: 전체 환경 변수, CLI 옵션, 설정 파일 위치, 우선순위 규칙

추천 학습 경로

1단계: 사용 중인 클라우드 가이드부터 시작 (AWS → Bedrock, GCP → Vertex, Azure → Foundry)
2단계: 회사 네트워크 정책이 있다면 엔터프라이즈 네트워크 구성 참고
3단계: 팀 규모가 크다면 LLM 게이트웨이 배포 검토
4단계: 필요시 설정 레퍼런스에서 상세 옵션 확인