플러그인 종속성 버전 제약

플러그인 종속성에 대한 버전 제약을 선언하고 선별된 플러그인 세트를 하나의 설치 뒤에 번들로 제공합니다.

플러그인은 plugin.json 또는 마켓플레이스 항목에 나열하여 다른 플러그인에 종속될 수 있습니다. 기본적으로 종속성은 최신 사용 가능 버전을 추적하므로 업스트림 릴리스가 경고 없이 플러그인의 종속성을 변경할 수 있습니다. 버전 제약을 사용하면 이동하기로 선택할 때까지 테스트된 버전 범위에서 종속성을 유지할 수 있습니다.

종속성을 선언하는 플러그인을 설치하면 Claude Code가 자동으로 종속성을 해결하고 설치합니다. 단, 마켓플레이스 항목에 command 소스 또는 headersHelper가 있는 종속성은 먼저 직접 설치해야 합니다. 나중에 /reload-plugins, 종속 플러그인의 마켓플레이스 자동 업데이트, 종속 플러그인에서 claude plugin install을 다시 실행, 그리고 claude plugin marketplace add는 각각 같은 규칙에 따라 아직 설치되지 않은 선언된 종속성을 설치합니다. 하나가 미해결 상태로 유지되면 종속성 오류 해결을 참조하세요.

이 가이드는 plugin.json에서 종속성을 선언하는 플러그인 작성자와 릴리스에 태그를 지정하는 마켓플레이스 유지 관리자를 위한 것입니다. 여기서 종속성은 다른 플러그인입니다. 플러그인 자체가 사용하는 npm 및 Bun 패키지는 Node.js 패키지 종속성을 참조하세요. 종속성이 있는 플러그인을 설치하려면 플러그인 검색 및 설치를 참조하세요. 전체 매니페스트 스키마는 플러그인 참조를 참조하세요.

종속성 버전을 제약하는 이유

두 팀이 플러그인을 게시하는 내부 마켓플레이스를 생각해 봅시다. 플랫폼 팀은 비밀 백엔드를 래핑하는 MCP 서버인 secrets-vault를 유지 관리합니다. 배포 팀은 배포 중에 자격 증명을 가져오기 위해 secrets-vault를 호출하는 deploy-kit을 유지 관리합니다.

deploy-kit은 secrets-vault v2.1.0에 대해 테스트됩니다. 버전 제약이 없으면 플랫폼 팀이 MCP 도구의 이름을 바꾸는 릴리스에 태그를 지정할 때마다 자동 업데이트가 모든 엔지니어의 secrets-vault를 새 버전으로 이동하고 deploy-kit이 중단됩니다.

버전 제약을 사용하면 deploy-kit은 ~2.1.0 범위에서 secrets-vault가 필요함을 선언합니다. deploy-kit이 설치된 엔지니어는 가장 높은 일치하는 2.1.x 패치에 머물러 있습니다. 배포 팀은 더 넓은 제약이 있는 새로운 deploy-kit 버전을 게시하여 자신의 일정에 따라 업그레이드합니다.

버전 제약으로 종속성 선언

플러그인의 .claude-plugin/plugin.json의 dependencies 배열에 종속성을 나열합니다.

다음 매니페스트는 하나의 버전 없는 종속성과 하나의 제약된 종속성을 선언합니다:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

항목은 deploy-kit 매니페스트의 "audit-logger"처럼 플러그인 이름만 있는 문자열일 수 있으며, 이는 해당 플러그인의 마켓플레이스가 제공하는 모든 버전에 종속됩니다. 더 많은 제어를 위해 다음 필드가 있는 객체를 사용합니다:

2.0.0-beta.1과 같은 사전 릴리스 버전은 ^2.0.0-0과 같은 사전 릴리스 접미사로 옵트인하지 않는 한 제외됩니다.

팀을 위한 플러그인 번들

필수 name 외에도 플러그인 매니페스트는 dependencies 배열만으로 구성될 수 있습니다. 이를 설치하면 모든 종속성이 함께 설치되므로, 이는 하나의 설치 뒤에 큐레이션된 플러그인 세트를 패키징하는 방법입니다.

예를 들어 플랫폼 팀은 내부 마켓플레이스에 역할별 번들을 게시하여 엔지니어가 각 도구를 별도로 설치하는 대신 하나의 claude plugin install 명령을 실행하도록 할 수 있습니다:

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

backend-standard를 설치하면 네 가지 종속성이 모두 해결되고 설치됩니다.

나중에 표준 세트에 도구를 추가하려면 추가 종속성과 함께 새로운 backend-standard 버전을 게시합니다. 마켓플레이스가 자동 업데이트되지 않으면 엔지니어는 다음 두 가지 방법 중 하나로 새 버전을 받습니다:

• /plugin에서 마켓플레이스의 자동 업데이트를 활성화합니다. 다음 자동 업데이트에서 번들이 새 버전으로 이동하고 추가되는 모든 종속성이 설치됩니다.
• claude plugin update backend-standard를 실행한 후 /reload-plugins를 실행하여 새로 추가된 종속성을 설치합니다.

조직 전체에 번들을 배포하려면 관리 설정의 enabledPlugins에 번들 플러그인을 추가합니다.

다른 마켓플레이스의 플러그인에 종속

기본적으로 Claude Code는 플러그인을 선언하는 플러그인과 다른 마켓플레이스에 있는 종속성을 자동 설치하기를 거부합니다. 이는 한 마켓플레이스가 검토하지 않은 소스의 플러그인을 자동으로 가져오는 것을 방지합니다.

이를 허용하려면 루트 마켓플레이스의 유지 관리자가 대상 마켓플레이스 이름을 marketplace.json의 allowCrossMarketplaceDependenciesOn에 추가합니다. 루트 마켓플레이스는 사용자가 설치하는 플러그인을 호스팅하는 마켓플레이스이며, 해당 허용 목록만 참조되므로 신뢰가 중간 마켓플레이스를 통해 연결되지 않습니다.

다음 marketplace.json은 deploy-kit이 acme-shared의 플러그인에 종속되도록 허용합니다:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

필드가 없거나 대상 마켓플레이스를 포함하지 않으면 설정할 필드의 이름을 지정하는 cross-marketplace 오류로 설치가 실패합니다. 사용자는 여전히 종속성을 수동으로 먼저 설치할 수 있으며, 이는 허용 목록을 변경하지 않고 제약을 만족합니다.

플러그인과 그 종속성을 로컬에서 테스트하기

플러그인을 개발하고 동시에 그 플러그인이 의존하는 플러그인도 개발하는 경우, --plugin-dir을 사용하여 둘 다 로드합니다:

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

종속성의 로컬 복사본은 항목이 마켓플레이스를 지정하는 경우에도 플러그인의 종속성 항목을 만족하므로, 마켓플레이스에서 종속성을 설치할 필요가 없습니다. Claude Code는 로컬 복사본에 대해 버전 제약을 확인하지 않으므로, 로컬 plugin.json에는 version이 필요하지 않습니다. v2.1.242 이전에는 마켓플레이스를 지정하는 종속성 항목이 로컬 복사본과 일치하지 않았으며, Claude Code는 로드 시 플러그인을 비활성화했습니다.

두 플러그인이 하나의 상위 폴더에 있는 경우, 해당 폴더를 --plugin-dir에 한 번만 전달할 수 있습니다. 폴더 자체가 플러그인이 아닌 경우, Claude Code는 .claude-plugin/plugin.json을 가진 각 하위 폴더를 로드합니다. Claude Code v2.1.265 이상이 필요합니다.

마켓플레이스에서 종속성을 설치하지 않은 경우, 로컬 복사본이 사라지면 플러그인 로드가 중지됩니다:

• 로컬 복사본을 비활성화한 경우: Claude Code는 다음 플러그인 로드 시 플러그인을 비활성화합니다. 마켓플레이스를 지정하는 종속성 항목의 경우, Claude Code는 Dependency "<name>@inline" is disabled — enable it or remove the dependency를 보고합니다. 단순 이름 항목의 경우, 종속성을 단순 이름으로 보고합니다. <name>@inline은 Claude Code가 모든 --plugin-dir 및 --plugin-url 플러그인을 식별하는 방식입니다.
• 종속성의 --plugin-dir 플래그 없이 세션을 시작한 경우: Claude Code는 종속성이 설치되지 않았다고 보고합니다. 플래그를 다시 전달하거나 마켓플레이스에서 종속성을 설치합니다.

버전 해석을 위한 태그 플러그인 릴리스

Claude Code는 의존성을 호스팅하는 저장소의 git 태그에 대해 버전 제약을 해석합니다. github, url, git-subdir 플러그인 소스의 경우 플러그인 자체 저장소이거나, 마켓플레이스가 상대 경로로 참조하는 플러그인의 경우 마켓플레이스 저장소입니다. Claude Code가 의존성의 사용 가능한 버전을 찾으려면 업스트림 플러그인의 릴리스가 특정 명명 규칙을 사용하여 태그되어야 합니다.

각 릴리스를 {plugin-name}--v{version}으로 태그하십시오. 여기서 {version}은 해당 커밋의 plugin.json에 있는 version 필드와 일치합니다. 플러그인 디렉터리에서 다음을 실행하십시오:

claude plugin tag --push

claude plugin tag 명령은 플러그인의 매니페스트와 포함된 마켓플레이스 항목에서 태그 이름을 파생합니다. 태그를 생성하기 전에 플러그인 내용을 검증하고, plugin.json과 마켓플레이스 항목이 버전에 동의하는지 확인하고, 플러그인 디렉터리 아래의 깨끗한 작업 트리를 요구하며, 태그가 이미 존재하면 거부합니다.

• --push는 태그를 origin 원격으로 푸시하므로 저장소에 구성된 origin 원격이 필요합니다. --remote를 전달하여 다른 원격으로 푸시하십시오.
• 푸시가 실패하면 태그는 여전히 로컬로 생성되고 명령은 오류와 함께 종료됩니다.
• --push를 사용하면 성공적인 실행은 Created tag secrets-vault--v2.1.0 및 Pushed to origin으로 끝나며, 마지막 줄은 푸시한 원격의 이름을 지정합니다. --push 없이는 명령이 대신 실행할 git push 명령을 인쇄합니다.
• --dry-run은 생성하지 않고 태그될 내용을 인쇄합니다.

git tag secrets-vault--v2.1.0을 직접 실행하는 것은 plugin.json과 마켓플레이스 항목을 직접 동기화 상태로 유지하면 동등합니다.

플러그인 이름 접두사를 사용하면 하나의 마켓플레이스 저장소가 독립적인 버전 라인을 가진 여러 플러그인을 호스팅할 수 있습니다. --v 구분자는 전체 플러그인 이름에 대한 접두사 일치로 파싱되므로 하이픈을 포함하는 플러그인 이름이 올바르게 처리됩니다.

{ "name": "secrets-vault", "version": "~2.1.0" }을 선언하는 플러그인을 설치할 때 Claude Code는 secrets-vault를 호스팅하는 저장소의 태그를 나열하고, secrets-vault--v로 시작하는 태그로 필터링하고, ~2.1.0을 만족하는 최고 버전을 가져옵니다. 플러그인 자체 저장소의 태그가 범위를 만족하지 않으면 설치는 Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0으로 실패하며, 이는 의존성을 마켓플레이스와 함께 이름 지정합니다. 일치하는 태그가 없는 상대 경로 플러그인의 경우 Claude Code는 마켓플레이스의 현재 복사본을 대신 설치하고 플러그인이 로드될 때 제약을 확인합니다.

마켓플레이스가 상대 경로로 참조하는 플러그인의 경우, 로컬 폴더 경로로 추가된 마켓플레이스는 폴더가 git 저장소일 때 동일한 방식으로 태그를 해석합니다. 이는 Claude Code v2.1.196 이상이 필요합니다. 두 가지 경우에 Claude Code는 폴더의 현재 내용에서 의존성을 설치합니다:

• 이전 버전은 로컬 폴더 마켓플레이스에서 태그를 읽지 않으므로 제약된 의존성은 해당 복사본이 범위를 만족할 때만 로드됩니다.
• git 저장소가 아닌 로컬 폴더는 버전에 관계없이 태그가 없습니다.

해석된 태그의 semver는 plugin.json의 version과 별도로 기록되므로 제약 확인은 plugin.json이 해당 커밋에서 오래된 값을 가지고 있더라도 실제로 가져온 태그를 사용합니다. 태그 해석 설치의 캐시 디렉터리 이름에는 12자 커밋-SHA 접미사가 포함되므로 유지 관리자가 태그를 다른 커밋으로 강제 이동하면 다음 설치는 오래된 내용을 재사용하는 대신 새로운 캐시 디렉터리를 가져옵니다.

제약이 상호 작용하는 방식

여러 설치된 플러그인이 동일한 종속성을 제약하면 Claude Code는 해당 범위를 교차하고 모든 범위를 만족하는 가장 높은 버전으로 종속성을 해결합니다. 아래 표는 일반적인 조합이 어떻게 해결되는지 보여줍니다.

자동 업데이트는 마켓플레이스의 최신 버전이 아닌 모든 설치된 플러그인의 범위를 만족하는 가장 높은 git 태그에서 제약된 종속성을 가져오므로, 종속성은 허용된 범위 내에서 계속 업데이트를 받습니다. 모든 범위를 만족하는 태그가 없으면 자동 업데이트는 해당 종속성을 건너뛰고 /plugin 오류 탭에서 건너뛴 내용을 나열하며 제약 플러그인의 이름을 지정합니다.

종속성을 제약하는 마지막 플러그인을 제거하면 종속성은 더 이상 유지되지 않으며 다음 업데이트에서 마켓플레이스 항목 추적을 재개합니다.

플러그인 종속성 활성화 또는 비활성화

이 섹션은 마켓플레이스에서 설치한 플러그인을 다룹니다. --plugin-dir로 로드한 복사본의 경우 플러그인 및 해당 종속성을 로컬에서 테스트를 참조하십시오.

플러그인을 활성화하면 이에 종속된 플러그인도 활성화되며, 다른 활성화된 플러그인이 여전히 필요로 하면 플러그인을 비활성화할 수 없습니다.

플러그인을 활성화하면 Claude Code는 동일한 범위에서 해당 종속성도 활성화합니다. 종속성에 자체 종속성이 있으면 Claude Code는 이들도 활성화합니다. 성공 메시지는 명명한 플러그인과 함께 활성화된 다른 항목을 나열합니다. 종속성을 활성화할 수 없으면 명령이 거부되고 무엇이 차단하고 있는지, 어떻게 해결할지 알려줍니다:

이는 종속성이 매니페스트에서 defaultEnabled: false를 설정하는 경우에도 적용됩니다. Claude Code는 이에 대해 명시적 true를 쓰기 때문입니다. 설치 시에도 동일하게 적용됩니다. 활성화된 플러그인을 만족시키기 위해 가져온 종속성은 자체 기본값에 관계없이 true로 설치됩니다.

플러그인을 비활성화하면 다른 활성화된 플러그인이 여전히 이에 종속되면 Claude Code가 거부합니다. 오류는 이에 종속된 플러그인의 이름을 지정하고 올바른 순서로 비활성화하는 연쇄 명령을 제공하며, 요청한 것으로 끝납니다.

예를 들어 deploy-kit이 secrets-vault에 종속되면 secrets-vault만 비활성화하면 다음과 유사한 출력으로 실패합니다:

secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

오류에서 연쇄 명령을 복사하여 한 단계에서 전체 집합을 비활성화합니다.

고아 자동 설치 종속성 제거

자동 설치된 종속성은 이를 설치한 플러그인이 제거된 후에도 디스크에 남아 있으며, 종속 플러그인을 다시 설치하거나 종속성을 직접 계속 사용하려는 경우를 대비합니다. 이를 정리하려면 claude plugin prune을 실행하여 더 이상 설치된 플러그인이 필요로 하지 않는 자동 설치된 종속성을 나열하고 확인 프롬프트 후 제거합니다.

claude plugin prune

제거 대상이 없으면 명령은 Nothing to prune을 이유와 함께 출력하고 종료합니다. 이는 새로 설치한 경우의 예상된 출력이며 오류가 아닙니다.

기본적으로 prune은 사용자 범위에서 작동하며 제거하기 전에 확인을 요청합니다:

• --scope project 또는 --scope local은 다른 범위를 대상으로 합니다.
• --dry-run은 아무것도 변경하지 않고 제거될 항목을 나열합니다.
• -y는 확인 프롬프트를 건너뜁니다. stdin 또는 stdout이 터미널이 아닐 때 prune은 고아를 나열하고 -y를 전달하지 않는 한 제거하지 않고 종료합니다.

제거의 일부로 prune하려면 claude plugin uninstall에 --prune을 전달합니다. 명명된 플러그인을 제거한 후 Claude Code는 이제 고아가 된 자동 설치된 종속성을 검사하고 제거합니다. 직접 설치한 플러그인은 절대 prune되지 않으며, 다른 플러그인의 dependencies 배열을 통해 자동으로 설치된 플러그인만 prune됩니다.

동일한 확인 동작이 적용됩니다. stdin 또는 stdout이 터미널이 아닐 때 제거는 여전히 완료되지만 prune 단계는 고아를 나열하고 -y를 전달하지 않는 한 제거하지 않습니다.

예를 들어 deploy-kit을 제거하고 이를 남기는 종속성을 정리하려면:

claude plugin uninstall deploy-kit --prune

종속성 오류 해결

종속성 문제는 claude plugin list 및 /plugin 인터페이스에 표시되며, 이 표의 리터럴 코드가 아닌 설명적 오류 메시지로 나타납니다. Claude Code는 오류를 해결할 때까지 영향을 받는 플러그인을 비활성화합니다. 아래 표에는 가장 일반적인 오류와 해결 방법이 나열되어 있습니다.

이러한 오류를 프로그래밍 방식으로 확인하려면 claude plugin list --json을 실행합니다. 문제가 있는 플러그인에는 이를 나열하는 errors 필드가 포함됩니다. 정상적으로 로드된 플러그인은 이 필드를 생략합니다.

참고 항목

• 플러그인 생성: 기술, 에이전트 및 훅으로 플러그인 빌드
• 플러그인 마켓플레이스 생성 및 배포: 팀을 위한 플러그인 호스팅
• 플러그인 참조: 전체 plugin.json 스키마
• 버전 관리: 플러그인의 자체 버전이 어떻게 해결되고 캐시 키로 사용되는지