프로덕션 플러그인에 요구되는 품질
개인 dotfiles에 두는 플러그인과 공개 마켓플레이스에 출시하는 플러그인은 요구되는 품질 수준이 차원이 다릅니다. 전자는 "내 환경에서만 동작하면 충분하다"로 끝나지만, 후자는 다양한 OS·Node.js 버전·셸·기존 설정과의 공존·온보딩 경험·업그레이드 전략까지 고려해야 합니다.
- 년 4월 현재, Anthropic의 공식 플러그인 마켓플레이스에는 1,800개 이상의 플러그인이 공개되어 있지만, 주간 활성 설치 수가 1,000을 넘는 것은 상위 100개 정도에 불과합니다. 이 차이를 만드는 것은 기능의 화려함이 아니라, 매니페스트 품질·문서화·버전 관리 규율·설정 병합 방식 같은 "겉으로 드러나지 않는 기초"입니다.
표준 리포지토리 구조
플러그인 리포지토리의 표준 구조는 다음과 같습니다.
``` my-claude-plugin/ ├── .claude-plugin/ │ └── plugin.json # 매니페스트 (필수) ├── commands/ # 슬래시 커맨드 │ ├── review.md │ └── deploy.md ├── skills/ # 스킬 │ └── security-audit/ │ └── SKILL.md ├── agents/ # 서브에이전트 정의 │ └── researcher.md ├── hooks/ # 훅 설정 │ └── hooks.json ├── mcp/ # 동봉 MCP 서버 │ ├── server.ts │ └── package.json ├── scripts/ # 설치·마이그레이션 스크립트 │ └── postinstall.sh ├── README.md ├── CHANGELOG.md └── LICENSE ```
gsd-build/get-shit-done이나 wshobson/agents 같은 인기 리포지토리는 거의 이 구조로 수렴되어 있습니다. 특히 `.claude-plugin/plugin.json`을 최상위에 배치하는 관례는, Anthropic CLI의 `plugin add` 커맨드가 이 경로를 고정으로 탐색하기 때문에 사실상 필수 규약입니다.
plugin.json 매니페스트 작성법
plugin.json은 최소한 다음 필드를 가져야 합니다.
```json { "name": "gsd-build", "displayName": "Get Shit Done", "version": "2.4.1", "description": "Stop-hook driven task persistence for Claude Code", "author": { "name": "GSD Team", "url": "https://github.com/gsd-build" }, "license": "MIT", "homepage": "https://github.com/gsd-build/get-shit-done", "repository": "https://github.com/gsd-build/get-shit-done.git", "claudeCode": { "minVersion": "2.8.0" }, "commands": ["commands/"], "skills": ["skills/"], "agents": ["agents/"], "hooks": "hooks/hooks.json", "mcpServers": { "gsd-db": { "command": "node", "args": ["mcp/server.js"] } }, "configSchema": "config.schema.json", "telemetry": { "endpoint": "https://telemetry.gsd.dev/v1" } } ```
`claudeCode.minVersion`은 파괴적 변경이 있을 때마다 반드시 업데이트해야 합니다. 구버전 CLI에서 설치되어 암묵적으로 동작 불량이 발생하는 것이 최악의 UX이기 때문입니다. `configSchema`는 JSON Schema 형식으로 사용자 설정의 유효성 검사를 제공하며, 설정 오류 시 친절한 오류 메시지가 표시되도록 합니다.
시맨틱 버전 관리의 실무
플러그인의 버전 관리는 semver 준수가 기본이지만, "무엇을 파괴적 변경으로 볼 것인가"의 판단은 독자적인 어려움이 있습니다. 슬래시 커맨드 이름 변경, 기존 훅의 matcher 변경, MCP 툴의 inputSchema에서 필수 필드 추가는 모두 파괴적 변경입니다. 반대로 새 커맨드 추가, 기존 커맨드에 옵션 인수 추가, MCP 툴 신규 추가는 마이너 버전으로 처리할 수 있습니다.
CHANGELOG.md는 Keep a Changelog 형식을 강력히 권장합니다. 마켓플레이스 UI가 CHANGELOG.md를 자동 파싱하여 업데이트 화면에 표시하기 때문에, 형식 통일이 실질적인 이익으로 직결됩니다. KGA IT에서는 사내 플러그인을 포함한 모든 프로젝트에서 이 형식을 강제하고 있습니다.
마켓플레이스 배포
- 년 4월 시점에서 주요 배포 경로는 세 가지입니다. 첫 번째는 Anthropic 공식 마켓플레이스(claude.ai/plugins)로, 심사가 있지만 검색 노출이 가장 높습니다. 두 번째는 GitHub 리포지토리에서 직접 설치하는 방식(`claude plugin add github.com/user/repo`)으로, 심사 불필요·즉시 반영이라 OSS 저자에게 인기가 있습니다. 세 번째는 프라이빗 마켓플레이스로, 기업 내부에서 claude-plugin-registry를 호스팅하여 사내 배포하는 형태입니다.
공식 마켓플레이스 심사에서는 셸 커맨드 실행의 타당성, 네트워크 전송 대상 명시, 개인정보 처리 선언, 유료 플러그인의 경우 결제 흐름의 보안이 검토됩니다. 2026년 2월부터 "audit badge" 제도가 도입되어, 정적 분석을 통과한 플러그인에는 초록색 배지가 부여됩니다. 이 배지의 유무에 따라 채택률이 두 배 이상 차이난다는 데이터가 공개되어 있어, 취득을 강력히 권장합니다.
텔레메트리와 관찰 가능성
플러그인 운영에는 "누가 어떻게 사용하고 있는가"를 파악하는 것이 필수입니다. 다만 Claude Code 사용자는 프라이버시 의식이 높아, 불투명한 텔레메트리는 즉시 제거로 이어집니다. 권장 접근법은 "옵트인·익명·집계값만 전송"이라는 세 가지 원칙입니다.
구체적으로는, 최초 실행 시 "익명 사용 통계 전송에 동의하십니까?"라는 프롬프트를 표시하고, Yes인 경우에만 설치 ID와 각 커맨드의 호출 횟수를 일별로 전송합니다. 개별 프롬프트 내용이나 파일 경로는 절대 전송하지 않습니다. wshobson/agents는 이 방식으로 인기 Subagent 정의 순위를 집계하여 월별로 README에 공개하고 있습니다. 이는 "이 플러그인은 건전하게 운영되고 있다"는 신호로도 기능합니다.
파괴적 API 변경에 대한 추적
Claude Code 본체는 2025년 하반기부터 기능 추가 속도가 가속화되어, 마이너 버전에서도 기존 플러그인이 동작하지 않는 경우가 드물게 발생합니다. 2026년 1월 Claude Code 3.0에서 Hook 계약이 변경되어 stdin을 통한 JSON 전달이 필수화되었을 때는, 2주 만에 1,200개 플러그인이 업데이트 대응을 강요받았습니다.
대책은 두 가지입니다. 우선 plugin.json의 `claudeCode.minVersion`을 엄격하게 지정하여, 미대응 CLI에서는 시작되지 않도록 합니다. 다음으로 GitHub Actions에서 claude-code-nightly를 사용한 통합 테스트를 실행하여, 새 버전에서의 동작 확인을 자동화합니다. Anthropic은 2월부터 plugin-compat-matrix를 공개하여, 각 CLI 버전에서의 공식 플러그인 동작 상황을 시각화하고 있습니다. 서드파티도 이 스키마를 따르는 추세입니다.
사용자 설정의 병합 전략
플러그인은 `.claude/settings.json`에 기록하지만, 사용자의 기존 설정을 훼손해서는 안 됩니다. 권장되는 구현은 "JSON Pointer 기반의 패치 적용"입니다. 플러그인 설치 시 차분 패치를 `.claude/plugins/<name>/applied-patch.json`에 저장하고, 제거 시 정확하게 역적용할 수 있도록 합니다.
특히 주의해야 할 것은 permissions 배열의 병합입니다. 사용자의 기존 allow/deny 규칙과 충돌하지 않도록, 플러그인 고유 규칙에는 네임스페이스 접두사(예: `"gsd:*"`)를 붙여 격리하는 것이 관례화되고 있습니다. get-shit-done은 이 방식을 선구적으로 채택하여, 많은 후속 플러그인의 참고 구현이 되었습니다.
공개 후 운영
공개로 끝이 아닙니다. GitHub Issues의 초동 대응 속도, semver 위반이 있었을 때의 즉각적인 patch, 보안 어드바이저리 발행 절차, deprecation notice의 사용자 알림——이러한 운영 품질이 장기적인 채택률을 결정합니다. 인기 플러그인일수록 운영 부담은 높아지고, 메인테이너 증원이나 법인화가 필요해지는 경우도 있습니다.
KGA IT에서는 고객에게 사내 플러그인을 납품할 때, 운영 런북·온콜 체제·분기 리뷰 회의까지를 패키지화하고 있습니다. 플러그인은 결과물이 아닌 프로덕트이며, 프로덕션 공개 순간부터 운영 책임이 발생합니다——이 인식이 프로 품질 플러그인과 취미 플러그인을 나누는 경계선입니다.