팀의 Claude Code 환경을 통일하는 법: Private Plugin 설계부터 배포까지

"우리 팀 Claude 설정, 어떻게 관리하고 있나요?"

 

 

Claude Code를 팀 단위로 도입하면 곧 이 문제를 만나게 된다. 누군가는 auto-formatter Hook을 쓰고, 누군가는 안 쓴다. 커밋 메시지 스타일은 사람마다 다르다. 새로 합류한 팀원은 어떤 설정을 해야 하는지 아무도 알려주지 않는다.

이 글은 테크 리드와 팀 리더를 위한 실전 가이드다. Private Plugin을 설계하고 MCP 서버까지 포함시켜, 팀원 누구나 한 번의 명령으로 동일한 환경을 갖출 수 있는 시스템을 만드는 방법을 다룬다.

---

왜 Plugin으로 관리해야 하는가

팀 설정을 공유하는 방법은 여러 가지지만, 대부분 결국 이렇게 되는 듯 하다.

방법	문제
Slack으로 파일 공유	버전 관리 불가, 업데이트 전달 어려움
위키에 설정 문서화	직접 따라 해야 해서 실수가 생긴다
레포에 .claude/ 커밋	프로젝트마다 중복, 전사 적용 불가

 

 

Plugin 방식은 이 문제를 한 번에 해결한다.

• 한 줄 설치: /plugin install our-org/dev-tools
• 버전 관리: Git 태그로 업데이트 추적
• 자동 갱신: 팀원 환경이 항상 최신 상태
• MCP 포함: 서버 설정까지 함께 배포

---

Step 1. Plugin 저장소 구조 설계

GitHub에 Private Repository를 만들고 아래 구조로 설계

our-company/claude-dev-tools/          ← private repo
│
├── .claude-plugin/
│   └── plugin.json                    ← 플러그인 메니페스트
│
├── skills/
│   ├── commit.md                      ← /dev-tools:commit
│   ├── pr-review.md                   ← /dev-tools:pr-review
│   ├── deploy.md                      ← /dev-tools:deploy
│   └── debug.md                       ← /dev-tools:debug
│
├── agents/
│   └── code-reviewer.md               ← 코드 리뷰 전담 에이전트
│
├── hooks/
│   └── hooks.json                     ← 자동화 훅 모음
│
├── servers/
│   └── internal-api-server            ← MCP 서버 바이너리
│
└── .mcp.json                          ← MCP 서버 설정

---

Step 2. plugin.json 작성

{
  "name": "dev-tools",
  "version": "1.2.0",
  "description": "Our company's standard Claude Code configuration",
  "skills": "skills/",
  "agents": "agents/",
  "hooks": "hooks/hooks.json",
  "mcpServers": {
    "internal-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/internal-api-server",
      "args": ["--env", "production"],
      "env": {
        "API_BASE_URL": "${INTERNAL_API_URL}",
        "API_TOKEN": "${INTERNAL_API_TOKEN}"
      }
    }
  }
}

${CLAUDE_PLUGIN_ROOT}는 플러그인이 설치된 절대 경로로 자동 치환된다.
이때 API 키 등 민감한 값은 반드시 ${ENV_VAR} 형식으로 분리해야 한다. 

---

Step 3. 핵심 Skills 작성

팀 컨벤션을 Skills로 인코딩하는 것이 핵심이다. 문서에는 써있지만 아무도 안 읽는 규칙을 Claude가 자동으로 따르게 만든다.

 

skills/commit.md

---
name: commit
description: 팀 컨벤션에 맞는 커밋 메시지 자동 생성
---

# 커밋 메시지 작성 규칙

## 형식
`<type>(<scope>): <subject>` (한국어)

## type 종류
- feat: 새 기능
- fix: 버그 수정
- refactor: 리팩토링
- docs: 문서 변경
- chore: 설정/빌드 변경

## 절차
1. `git diff --staged` 로 변경사항 분석
2. 위 형식에 맞는 커밋 메시지 초안 작성
3. 사용자에게 확인 후 커밋 실행

 

 

skills/pr-review.md

---
name: pr-review
description: PR 코드 리뷰 체크리스트 기반 검토
---

# PR 리뷰 기준

다음 항목을 순서대로 검토하고 결과를 보고하라:

1. **기능 정확성**: 요구사항을 올바르게 구현했는가
2. **보안**: SQL Injection, XSS, 민감 정보 노출 위험은 없는가
3. **성능**: N+1 쿼리, 불필요한 렌더링 등 성능 문제는 없는가
4. **테스트**: 핵심 로직에 테스트가 존재하는가
5. **타입 안전성**: any 타입 남용, 타입 단언 과다 사용은 없는가

각 항목별로 통과 / 주의 / 수정 필요로 분류하라.

---

Step 4. Hooks 설정

hooks/hooks.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(echo \"$STDIN\" | jq -r '.tool_input.file_path // empty'); if [[ \"$FILE\" =~ \\.(ts|tsx|js|jsx)$ ]]; then npx prettier --write \"$FILE\" 2>/dev/null; fi"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/protect-sensitive-files.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code가 응답을 기다립니다\" with title \"Claude Code\"' 2>/dev/null || notify-send 'Claude Code' '응답을 기다립니다' 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

macOS와 Linux를 모두 지원하기 위해 || true로 오류를 무시한다.

---

Step 5. MCP 서버 포함하기

팀 내부 API나 사내 툴에 Claude가 직접 접근해야 한다면 MCP 서버를 플러그인에 번들하면 된다.

.mcp.json

{
  "internal-db": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--read-only"],
    "env": {
      "DATABASE_URL": "${INTERNAL_DATABASE_URL}"
    }
  },
  "jira": {
    "command": "npx",
    "args": ["-y", "@company/mcp-jira"],
    "env": {
      "JIRA_BASE_URL": "${JIRA_BASE_URL}",
      "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
    }
  }
}

MCP 서버는 플러그인 활성화 시 자동으로 시작된다. 팀원은 별도로 /mcp 설정을 할 필요가 없다. 이것이 Plugin에 MCP를 포함시키는 가장 큰 이유다.

---

Step 6. 팀 프로젝트에 자동 안내 설정

각 레포의 .claude/settings.json에 아래를 추가한다. 팀원이 레포를 clone하면 Claude Code가 플러그인 설치를 자동으로 안내한다.

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "our-company/claude-dev-tools"
      }
    }
  },
  "enabledPlugins": {
    "dev-tools@company-tools": true
  }
}

---

Step 7. 팀원 온보딩

설정이 완료되면 새 팀원의 온보딩은 이렇게 간단해진다.

# 1. GitHub 인증 (이미 되어 있으면 스킵)
gh auth login

# 2. 레포 clone
git clone https://github.com/our-company/our-project.git

# 3. Claude Code 실행 시 플러그인 설치 안내 자동 표시
claude
# → /dev-tools:commit, /dev-tools:pr-review 등 즉시 사용 가능

 

 

환경변수는 각자의 .zshrc 또는 .bashrc에 추가한다.

export INTERNAL_API_URL="https://api.our-company.internal"
export INTERNAL_API_TOKEN="your-token-here"
export JIRA_BASE_URL="https://our-company.atlassian.net"
export JIRA_API_TOKEN="your-jira-token"

팀 비밀값은 1Password나 AWS Secrets Manager 같은 시크릿 관리 도구로 배포하는 것이 바람직하다.

---

Enterprise 환경: 마켓플레이스 강제 설정

Claude for Teams/Enterprise를 사용 중이라면 관리자 수준에서 승인된 플러그인 소스만 허용할 수 있다.

// 관리자 Managed Settings (claude.ai 어드민 패널)
{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "our-company/claude-dev-tools"
    }
  ]
}

설정	효과
미설정	누구나 아무 마켓플레이스 추가 가능
[] 빈 배열	외부 마켓플레이스 추가 완전 차단
레포 목록 지정	지정된 소스만 허용

이 설정은 프로젝트 설정으로 우회할 수 없다. 보안이 중요한 팀에서는 적극적으로 활용해볼 만하다.

---

운영 시 주의사항

버전 관리

# plugin.json의 version을 올리고 Git 태그
git tag v1.3.0
git push origin v1.3.0

 

팀원들은 다음 Claude Code 시작 시 업데이트 알림을 받는다.

 

플러그인 디렉토리 외부 파일 참조 불가

${CLAUDE_PLUGIN_ROOT}/../shared-utils 같은 경로는 동작하지 않는다. 공유 스크립트가 필요하다면 플러그인 레포 안에 포함시키거나 심볼릭 링크를 활용해야 한다.

---

마치며

Claude Code의 Plugin 시스템은 단순한 개인 설정 도구를 넘어, 팀의 개발 문화와 컨벤션을 코드로 인코딩하는 수단이다.

• 코드 리뷰 기준 → 문서가 아닌 Skill로
• 포매팅 규칙 → 구두 약속이 아닌 Hook으로
• 사내 시스템 접근 → 개인 설정이 아닌 MCP로

팀 모두가 동일한 환경에서 시작하고, 설정이 코드와 함께 버전 관리되며, 새 팀원도 하루 안에 온보딩이 완료된다. 한번 구조를 잡아두면 그 다음부터는 계속 쌓이는 자산이 된다.