메인 콘텐츠로 건너뛰기
플러그인은 plugin.json 또는 마켓플레이스 항목에 나열하여 다른 플러그인에 종속될 수 있습니다. 기본적으로 종속성은 최신 사용 가능 버전을 추적하므로 업스트림 릴리스가 경고 없이 플러그인의 종속성을 변경할 수 있습니다. 버전 제약을 사용하면 이동하기로 선택할 때까지 테스트된 버전 범위에서 종속성을 유지할 수 있습니다. 종속성을 선언하는 플러그인을 설치하면 Claude Code가 자동으로 종속성을 해결하고 설치하며 설치 출력의 끝에 추가된 종속성을 나열합니다. 이 가이드는 plugin.json에서 종속성을 선언하는 플러그인 작성자와 릴리스에 태그를 지정하는 마켓플레이스 유지 관리자를 위한 것입니다. 종속성이 있는 플러그인을 설치하려면 플러그인 검색 및 설치를 참조하세요. 전체 매니페스트 스키마는 플러그인 참조를 참조하세요.
종속성 버전 제약에는 Claude Code v2.1.110 이상이 필요합니다.

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

두 팀이 플러그인을 게시하는 내부 마켓플레이스를 생각해 봅시다. 플랫폼 팀은 비밀 백엔드를 래핑하는 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 배열에 종속성을 나열합니다. 각 항목은 플러그인 이름 또는 버전 제약이 있는 객체입니다. 다음 매니페스트는 하나의 버전 없는 종속성과 하나의 제약된 종속성을 선언합니다:
.claude-plugin/plugin.json
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
항목은 위의 예에서 "audit-logger"처럼 플러그인 이름만 있는 문자열일 수 있으며, 이는 해당 플러그인의 마켓플레이스가 제공하는 모든 버전에 종속됩니다. 더 많은 제어를 위해 다음 필드가 있는 객체를 사용합니다:
필드유형설명
namestring플러그인 이름입니다. 선언 플러그인과 동일한 마켓플레이스 내에서 해결됩니다. 필수입니다.
versionstring~2.1.0, ^2.0, >=1.4 또는 =2.1.0과 같은 semver 범위입니다. 종속성은 이 범위를 만족하는 가장 높은 태그된 버전에서 가져옵니다.
marketplacestringname을 해결할 다른 마켓플레이스입니다. 교차 마켓플레이스 종속성은 대상 마켓플레이스가 루트 마켓플레이스의 marketplace.json에서 allowCrossMarketplaceDependenciesOn에 나열되지 않는 한 차단됩니다.
version 필드는 캐럿, 틸드, 하이픈 및 비교자 범위를 포함하여 Node의 semver 패키지에서 지원하는 모든 표현식을 허용합니다. ^2.0.0-0과 같은 사전 릴리스 접미사로 옵트인하지 않는 한 2.0.0-beta.1과 같은 사전 릴리스 버전은 제외됩니다.

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

기본적으로 Claude Code는 플러그인을 선언하는 플러그인과 다른 마켓플레이스에 있는 종속성을 자동 설치하기를 거부합니다. 이는 한 마켓플레이스가 검토하지 않은 소스의 플러그인을 자동으로 가져오는 것을 방지합니다. 이를 허용하려면 루트 마켓플레이스의 유지 관리자가 대상 마켓플레이스 이름을 marketplace.json의 allowCrossMarketplaceDependenciesOn에 추가합니다. 루트 마켓플레이스는 사용자가 설치하는 플러그인을 호스팅하는 마켓플레이스이며, 해당 허용 목록만 참조되므로 신뢰가 중간 마켓플레이스를 통해 연결되지 않습니다. 다음 marketplace.json은 deploy-kit이 acme-shared의 플러그인에 종속되도록 허용합니다:
.claude-plugin/marketplace.json
{
  "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 오류로 설치가 실패합니다. 사용자는 여전히 종속성을 수동으로 먼저 설치할 수 있으며, 이는 허용 목록을 변경하지 않고 제약을 만족합니다.

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

버전 제약은 마켓플레이스 저장소의 git 태그에 대해 해결됩니다. Claude Code가 종속성의 사용 가능한 버전을 찾으려면 업스트림 플러그인의 릴리스가 특정 명명 규칙을 사용하여 태그되어야 합니다. 각 릴리스를 {plugin-name}--v{version}으로 태그하며, 여기서 {version}은 해당 커밋의 plugin.json의 version 필드와 일치합니다. 
git tag secrets-vault--v2.1.0
git push origin secrets-vault--v2.1.0
플러그인 이름 접두사를 사용하면 하나의 마켓플레이스 저장소가 독립적인 버전 라인을 가진 여러 플러그인을 호스팅할 수 있습니다. --v 구분자는 전체 플러그인 이름에 대한 접두사 일치로 구문 분석되므로 하이픈을 포함하는 플러그인 이름이 올바르게 처리됩니다. { "name": "secrets-vault", "version": "~2.1.0" }을 선언하는 플러그인을 설치하면 Claude Code는 마켓플레이스의 태그를 나열하고, secrets-vault--v로 시작하는 태그로 필터링하고, ~2.1.0을 만족하는 가장 높은 버전을 가져옵니다. 일치하는 태그가 없으면 종속 플러그인은 사용 가능한 버전을 나열하는 오류로 비활성화됩니다.
npm 마켓플레이스 소스의 경우 태그 기반 해결이 git 지원 소스에만 적용되므로 제약이 가져온 버전을 제어하지 않습니다. 제약은 여전히 로드 시간에 확인되며, 설치된 버전이 이를 만족하지 않으면 종속 플러그인은 dependency-version-unsatisfied로 비활성화됩니다.

​
제약이 상호 작용하는 방식

여러 설치된 플러그인이 동일한 종속성을 제약하면 Claude Code는 해당 범위를 교차하고 모든 범위를 만족하는 가장 높은 버전으로 종속성을 해결합니다. 아래 표는 일반적인 조합이 어떻게 해결되는지 보여줍니다.
플러그인 A 필요플러그인 B 필요결과
^2.0>=2.12.1.0 이상의 가장 높은 2.x 태그에서 하나의 설치입니다. 두 플러그인 모두 로드됩니다.
~2.1~3.0플러그인 B 설치가 range-conflict로 실패합니다. 플러그인 A와 종속성은 그대로 유지됩니다.
=2.1.0none종속성은 2.1.0에 머물러 있습니다. 플러그인 A가 설치된 동안 자동 업데이트는 최신 버전을 건너뜁니다.
자동 업데이트는 업데이트를 적용하기 전에 모든 설치된 플러그인의 범위에 대해 각 제약된 종속성을 확인합니다. 마켓플레이스가 종속성을 범위 외의 버전으로 이동하면 업데이트를 건너뛰고 건너뛴 메시지는 제약 플러그인의 이름을 지정합니다. 종속성을 제약하는 마지막 플러그인을 제거하면 종속성은 더 이상 유지되지 않으며 다음 업데이트에서 마켓플레이스 항목 추적을 재개합니다.

​
종속성 오류 해결

종속성 문제는 claude plugin list, /plugin 인터페이스 및 /doctor에 표시됩니다. 영향을 받는 플러그인은 오류를 해결할 때까지 비활성화됩니다. 가장 일반적인 오류와 해결 방법은 아래에 나열되어 있습니다.
오류의미해결 방법
range-conflict종속성의 버전 요구 사항을 결합할 수 없습니다. 오류 메시지는 원인의 이름을 지정합니다: 모든 범위를 만족하는 버전이 없거나, 범위가 유효한 semver 구문이 아니거나, 결합된 범위가 너무 복잡하여 교차할 수 없습니다.충돌하는 플러그인 중 하나를 제거하거나 업데이트하고, 유효하지 않은 version 문자열을 수정하고, 긴 || 체인을 단순화하거나, 업스트림 작성자에게 제약을 넓히도록 요청합니다.
dependency-version-unsatisfied설치된 종속성의 버전이 이 플러그인의 선언된 범위를 벗어났습니다.claude plugin install <dependency>@<marketplace>를 실행하여 모든 현재 제약에 대해 종속성을 다시 해결합니다.
no-matching-tag종속성의 저장소에 범위를 만족하는 {name}--v* 태그가 없습니다.업스트림이 위의 규칙을 사용하여 릴리스에 태그를 지정했는지 확인하거나 범위를 완화합니다.
이러한 오류를 프로그래밍 방식으로 확인하려면 claude plugin list --json을 실행하고 각 플러그인의 errors 필드를 읽습니다.

​
참고 항목