플러그인 시스템 (Plugins)

읽는 시간: 15분 | 난이도: 고급자

Claude Code의 플러그인 시스템을 활용하여 기능을 확장하고 커스텀 통합을 구축하는 방법을 배웁니다.

개요

플러그인은 Claude Code의 기능을 확장하는 모듈형 컴포넌트입니다. 플러그인을 통해 새로운 명령어, 도구, 통합을 추가하고 Claude Code를 프로젝트에 맞게 커스터마이즈할 수 있습니다.

1. 플러그인 기초 (Plugin Basics)

1.1 플러그인이란?

플러그인은 독립적인 기능 모듈입니다:

플러그인 구조:

[Claude Code Core]
    ↓
[Plugin Manager]
    ↓
├── [Plugin 1] - 기능 확장
├── [Plugin 2] - 도구 추가
├── [Plugin 3] - 통합 제공
└── [Plugin N] - 커스텀 로직

1.2 플러그인 유형

플러그인 유형:

1. 명령어 플러그인 (Command Plugins)
   - 새로운 CLI 명령어 추가
   - 커스텀 스킬 구현

2. 도구 플러그인 (Tool Plugins)
   - 새로운 도구 기능 추가
   - 외부 서비스 연동

3. 통합 플러그인 (Integration Plugins)
   - 서드파티 서비스 통합
   - API 연결

4. 테마 플러그인 (Theme Plugins)
   - UI 커스터마이징
   - 색상 테마 변경

5. 언어 플러그인 (Language Plugins)
   - 새로운 언어 지원
   - 언어별 기능 최적화

2. 플러그인 개발 (Plugin Development)

2.1 플러그인 구조

// 플러그인 기본 구조
interface ClaudePlugin {
  // 플러그인 메타데이터
  name: string;
  version: string;
  description: string;
  author: string;

  // 활성화/비활성화
  activate: (context: PluginContext) => void;
  deactivate: (context: PluginContext) => void;

  // 기능 확장
  commands?: Command[];
  tools?: Tool[];
  hooks?: Hook[];
}

// 플러그인 컨텍스트
interface PluginContext {
  // Claude Code API
  api: ClaudeAPI;

  // 설정
  config: PluginConfig;

  // 로거
  logger: Logger;

  // 유틸리티
  utils: PluginUtils;
}

2.2 첫 번째 플러그인

// hello-world-plugin.ts
import { ClaudePlugin, PluginContext } from '@claude-code/plugin';

const HelloWorldPlugin: ClaudePlugin = {
  name: 'hello-world',
  version: '1.0.0',
  description: '간단한 인사 플러그인',
  author: 'Your Name',

  activate(context: PluginContext) {
    context.logger.info('Hello World 플러그인이 활성화되었습니다');

    // 명령어 등록
    context.api.registerCommand({
      name: 'hello',
      description: '세계에 인사하기',
      handler: async (args) => {
        const name = args.name || 'World';
        return `Hello, ${name}!`;
      }
    });
  },

  deactivate(context: PluginContext) {
    context.logger.info('Hello World 플러그인이 비활성화되었습니다');
  }
};

export default HelloWorldPlugin;

2.3 플러그인 매니페스트

{
  "name": "hello-world",
  "version": "1.0.0",
  "description": "간단한 인사 플러그인",
  "main": "dist/index.js",
  "author": "Your Name",
  "license": "MIT",
  "claude": {
    "minVersion": "1.0.0",
    "maxVersion": "2.0.0",
    "permissions": [
      "commands",
      "tools"
    ],
    "dependencies": [],
    "settings": {
      "greeting": {
        "type": "string",
        "default": "Hello",
        "description": "인사말"
      }
    }
  }
}

3. 고급 플러그인 기능 (Advanced Plugin Features)

3.1 도구 추가

// custom-tools-plugin.ts
const CustomToolsPlugin: ClaudePlugin = {
  name: 'custom-tools',
  version: '1.0.0',
  description: '커스텀 도구 플러그인',

  activate(context: PluginContext) {
    // 파일 분석 도구
    context.api.registerTool({
      name: 'analyze_complexity',
      description: '코드 복잡도 분석',
      parameters: {
        filePath: {
          type: 'string',
          required: true,
          description: '분석할 파일 경로'
        }
      },
      handler: async (params) => {
        const content = await context.api.readFile(params.filePath);
        const complexity = calculateComplexity(content);
        return {
          filePath: params.filePath,
          complexity: complexity,
          recommendation: complexity > 10 ? '리팩토링 권장' : '양호'
        };
      }
    });
  }
};

3.2 훅 등록

// hooks-plugin.ts
const HooksPlugin: ClaudePlugin = {
  name: 'custom-hooks',
  version: '1.0.0',
  description: '커스텀 훅 플러그인',

  activate(context: PluginContext) {
    // 파일 저장 전 훅
    context.api.registerHook({
      event: 'pre_file_write',
      handler: async (data) => {
        context.logger.info(`파일 저장: ${data.filePath}`);

        // 자동으로 포맷팅
        if (data.filePath.endsWith('.ts')) {
          const formatted = await formatTypeScript(data.content);
          return { content: formatted };
        }

        return data;
      }
    });

    // 명령 실행 후 훅
    context.api.registerHook({
      event: 'post_command',
      handler: async (data) => {
        if (data.command.startsWith('npm run')) {
          context.logger.info(`npm 명령 완료: ${data.command}`);
          // 성공 메트릭 전송
          await sendMetrics(data);
        }
      }
    });
  }
};

3.3 외부 API 통합

// api-integration-plugin.ts
const APIIntegrationPlugin: ClaudePlugin = {
  name: 'api-integration',
  version: '1.0.0',
  description: '외부 API 통합 플러그인',

  activate(context: PluginContext) {
    const apiKey = context.config.get('api_key');

    context.api.registerTool({
      name: 'call_external_api',
      description: '외부 API 호출',
      parameters: {
        endpoint: {
          type: 'string',
          required: true
        },
        method: {
          type: 'string',
          default: 'GET'
        }
      },
      handler: async (params) => {
        const response = await fetch(params.endpoint, {
          method: params.method,
          headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
          }
        });

        return await response.json();
      }
    });
  }
};

4. 플러그인 배포 (Plugin Distribution)

4.1 NPM에 게시

# 플러그인 빌드
npm run build

# NPM에 게시
npm publish

# 사용자 설치
claude plugin install my-awesome-plugin

4.2 플러그인 저장소

# .claude/plugins/registry.yaml
registry:
  type: "github"
  url: "https://github.com/claude-code-plugins/registry"

plugins:
  - name: "docker-helper"
    repository: "https://github.com/user/docker-helper-plugin"
    version: "1.2.0"

  - name: "aws-integration"
    repository: "https://github.com/user/aws-plugin"
    version: "2.0.1"

5. 플러그인 관리 (Plugin Management)

5.1 플러그인 설치

# NPM에서 설치
claude plugin install @claude-code/docker-helper

# GitHub에서 설치
claude plugin install github:user/repo

# 로컬에서 설치
claude plugin install ./my-plugin

# 특정 버전 설치
claude plugin install my-plugin@1.2.0

5.2 플러그인 관리

# 설치된 플러그인 목록
claude plugin list

# 플러그인 정보 확인
claude plugin info docker-helper

# 플러그인 업데이트
claude plugin update docker-helper

# 모든 플러그인 업데이트
claude plugin update --all

# 플러그인 제거
claude plugin uninstall docker-helper

요약

플러그인 시스템은 Claude Code를 무한히 확장 가능하게 만듭니다.

핵심 개념

1. 플러그인 유형: 명령어, 도구, 통합, 테마, 언어
2. 플러그인 개발: TypeScript 기반 구조
3. 고급 기능: 도구 추가, 훅 등록, API 통합
4. 배포: NPM 또는 커스텀 저장소
5. 관리: 설치, 업데이트, 제거

모범 사례

• 모듈형 설계
• 명확한 API
• 적절한 에러 처리
• 문서화

다음 단계

• CLI Reference - 명령줄 참조
• Troubleshooting - 문제 해결

이 가이드가 도움이 되셨나요?

플러그인 개발에 대한 질문이 있으시면 언제든지 물어보세요!