플러그인 의존성 버전 제약

기준일: 2026-07-26
공식 기준: Constrain plugin dependency versions

개요

플러그인은 plugin.json 또는 마켓플레이스 항목에 다른 플러그인 의존성을 둘 수 있습니다. 기본은 최신 버전 추적 → 업스트림 릴리스가 예고 없이 의존성을 바꿀 수 있습니다. 버전 제약으로 테스트한 범위에 고정합니다.

의존 플러그인 설치 시 Claude Code가 의존성을 자동 resolve·설치하고 설치 출력 끝에 추가된 의존성을 나열합니다. 나중에 없어지면 /reload-plugins와 백그라운드 auto-update가, 해당 마켓플레이스가 이미 구성된 경우 재설치합니다. claude plugin install 재실행·claude plugin marketplace add도 누락 의존성을 resolve합니다. 미추가 마켓플레이스 의존성은 미해결로 남습니다.

대상: 의존성을 선언하는 플러그인 작성자·마켓 유지보수자. 설치만: Discover plugins. 스키마: Plugins reference.

핵심 개념

개념	설명
미버전 의존성	이름만 — 마켓이 제공하는 버전 추적
제약 의존성	`{ "name", "version": "~2.1.0" }` 등 npm semver 범위
태그 규칙	`{plugin-name}--v{version}` git 태그
범위 교차	여러 플러그인 제약 시 교집합 최고 버전
번들 플러그인	`dependencies`만 있는 매니페스트로 큐레이션 세트 한 번에 설치

상세

왜 제약하는가

예: deploy-kit이 secrets-vault v2.1.0 기준 테스트. 제약 없으면 vault 도구 rename 릴리스 시 auto-update로 전원 깨짐. ~2.1.0이면 최고 2.1.x에 머무르고, deploy 팀이 더 넓은 제약의 새 deploy-kit을 배포할 때 올립니다.

선언

.claude-plugin/plugin.json의 dependencies 배열:

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

필드	설명
`name`	필수. 기본은 선언 플러그인과 같은 마켓에서 resolve
`version`	npm semver 범위 (`~2.1.0`, `^2.0`, `>=1.4`, `=2.1.0`…). 만족하는 최고 태그 버전. pre-release는 `^2.0.0-0` 등 명시 시만
`marketplace`	다른 마켓에서 resolve. 루트 마켓 `marketplace.json`의 `allowCrossMarketplaceDependenciesOn`에 대상이 있어야 함

팀 번들

name + dependencies만으로 표준 세트 패키징:

{
  "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"
  ]
}

비-Anthropic 마켓 auto-update는 기본 off. 새 번들 버전: 마켓 auto-update 켜기, 또는 claude plugin update backend-standard 후 /reload-plugins. 조직 롤아웃: managed settings enabledPlugins.

다른 마켓 의존성

기본 거부(미검토 소스 자동 pull 방지). 루트 마켓(사용자가 설치하는 플러그인이 호스팅된 곳)의 allowlist만 상담, trust chain 없음.

{
  "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 오류. 사용자가 의존성을 먼저 수동 설치하면 allowlist 없이 충족 가능.

릴리스 태그

제약은 마켓 저장소 git 태그 기준. 규칙: {plugin-name}--v{version} (plugin.json version과 일치).

claude plugin tag --push

매니페스트·마켓 항목 version 일치 검증, 플러그인 디렉터리 clean tree, 기존 태그 거부. --push → origin(또는 --remote). 실패해도 로컬 태그는 남음. --dry-run 가능. git tag secrets-vault--v2.1.0 직접도 동등(동기화 책임은 본인).

--v 구분으로 하이픈 포함 플러그인 이름 처리. ~2.1.0 설치 시 secrets-vault--v* 필터 후 최고 만족 버전. 매칭 태그 없으면 dependent 비활성 + available versions 오류.

로컬 폴더 마켓: git 저장소면 태그 동일 (v2.1.196+). 구버전·비-git 폴더는 폴더 현재 내용으로 설치·만족 여부 검사.

해석된 태그 semver는 plugin.json version과 별도 기록(캐시 키에 12자 commit SHA — force-move 태그 시 새 캐시).

npm 마켓 소스: 제약이 fetch 버전을 제어하지 않음(git 태그 해석 전용). 로드 시 검사는 하며 불만족 시 dependency-version-unsatisfied로 dependent 비활성.

제약 상호작용

A	B	결과
`^2.0`	`>=2.1`	최고 2.x ≥2.1.0 하나
`~2.1`	`~3.0`	B 설치 `range-conflict`. A·의존성 유지
`=2.1.0`	없음	2.1.0 고정, auto-update 스킵

auto-update는 모든 설치 플러그인 범위를 만족하는 최고 태그. 만족 태그 없으면 스킵 → /plugin Errors. 마지막 제약 플러그인 제거 시 다음 업데이트부터 마켓 latest 추적.

enable / disable (v2.1.143+)

enable 시 의존성도 같은 scope로 enable (재귀). 성공 메시지에 함께 켠 목록. 실패 조건:

조건	결과
의존성 미설치	enable 실패 + install 명령 제시
조직 정책 차단	차단 의존성 이름
상위 precedence scope에서 `false`	해당 scope enable 또는 `--scope`
모두 OK	플러그인·미활성 의존성에 `true` 기록

defaultEnabled: false여도 명시 true 기록. install로 pull된 의존성도 true.

disable 시 다른 활성 플러그인이 여전히 의존하면 거부 + 올바른 순서 chained disable 명령:

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

orphan prune (v2.1.121+)

auto-installed 의존성은 부모 uninstall 후에도 디스크에 남음.

claude plugin prune

기본 user scope, 확인 후 제거. --scope project|local, --dry-run, -y. 비-TTY는 목록만( -y 없으면 미제거).

claude plugin uninstall deploy-kit --prune

수동 설치 플러그인은 prune 대상 아님. 자동 의존성만.

오류 해결

오류	의미	조치
`dependency-unsatisfied`	미설치 또는 비활성	install / marketplace add / enable
`range-conflict`	범위 교집합 없음·잘못된 semver·너무 복잡	충돌 플러그인 조정·`version` 수정
`dependency-version-unsatisfied`	설치 버전이 범위 밖	`claude plugin install <dep>@<marketplace>` 재해석
`no-matching-tag`	만족 태그 없음	업스트림 태그 또는 범위 완화

claude plugin list --json의 errors 필드. UI 메시지는 코드와 다를 수 있으나 의미는 동일. 문제 플러그인은 해결 전까지 비활성.

체크리스트

의존성에 테스트된 semver 범위를 걸었다
릴리스를 {name}--v{version}으로 태그했다 (claude plugin tag --push)
크로스 마켓이면 루트 allowCrossMarketplaceDependenciesOn을 설정했다
enable/disable·prune 동작을 팀에 안내했다
claude plugin list --json으로 오류를 확인했다

다음 단계

기준일

문서 작성·동기화 기준일: 2026-07-26
원문: https://code.claude.com/docs/en/plugin-dependencies

플러그인 의존성 버전 제약

기준일: 2026-07-26
공식 기준: Constrain plugin dependency versions

개요

대상: 의존성을 선언하는 플러그인 작성자·마켓 유지보수자. 설치만: Discover plugins. 스키마: Plugins reference.

핵심 개념

개념	설명
미버전 의존성	이름만 — 마켓이 제공하는 버전 추적
제약 의존성	`{ "name", "version": "~2.1.0" }` 등 npm semver 범위
태그 규칙	`{plugin-name}--v{version}` git 태그
범위 교차	여러 플러그인 제약 시 교집합 최고 버전
번들 플러그인	`dependencies`만 있는 매니페스트로 큐레이션 세트 한 번에 설치

상세

왜 제약하는가

선언

.claude-plugin/plugin.json의 dependencies 배열:

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

필드	설명
`name`	필수. 기본은 선언 플러그인과 같은 마켓에서 resolve
`version`	npm semver 범위 (`~2.1.0`, `^2.0`, `>=1.4`, `=2.1.0`…). 만족하는 최고 태그 버전. pre-release는 `^2.0.0-0` 등 명시 시만
`marketplace`	다른 마켓에서 resolve. 루트 마켓 `marketplace.json`의 `allowCrossMarketplaceDependenciesOn`에 대상이 있어야 함

팀 번들

name + dependencies만으로 표준 세트 패키징:

{
  "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"
  ]
}

다른 마켓 의존성

기본 거부(미검토 소스 자동 pull 방지). 루트 마켓(사용자가 설치하는 플러그인이 호스팅된 곳)의 allowlist만 상담, trust chain 없음.

{
  "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 오류. 사용자가 의존성을 먼저 수동 설치하면 allowlist 없이 충족 가능.

릴리스 태그

제약은 마켓 저장소 git 태그 기준. 규칙: {plugin-name}--v{version} (plugin.json version과 일치).

claude plugin tag --push

로컬 폴더 마켓: git 저장소면 태그 동일 (v2.1.196+). 구버전·비-git 폴더는 폴더 현재 내용으로 설치·만족 여부 검사.

해석된 태그 semver는 plugin.json version과 별도 기록(캐시 키에 12자 commit SHA — force-move 태그 시 새 캐시).

npm 마켓 소스: 제약이 fetch 버전을 제어하지 않음(git 태그 해석 전용). 로드 시 검사는 하며 불만족 시 dependency-version-unsatisfied로 dependent 비활성.

제약 상호작용

A	B	결과
`^2.0`	`>=2.1`	최고 2.x ≥2.1.0 하나
`~2.1`	`~3.0`	B 설치 `range-conflict`. A·의존성 유지
`=2.1.0`	없음	2.1.0 고정, auto-update 스킵

enable / disable (v2.1.143+)

enable 시 의존성도 같은 scope로 enable (재귀). 성공 메시지에 함께 켠 목록. 실패 조건:

조건	결과
의존성 미설치	enable 실패 + install 명령 제시
조직 정책 차단	차단 의존성 이름
상위 precedence scope에서 `false`	해당 scope enable 또는 `--scope`
모두 OK	플러그인·미활성 의존성에 `true` 기록

defaultEnabled: false여도 명시 true 기록. install로 pull된 의존성도 true.

disable 시 다른 활성 플러그인이 여전히 의존하면 거부 + 올바른 순서 chained disable 명령:

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

orphan prune (v2.1.121+)

auto-installed 의존성은 부모 uninstall 후에도 디스크에 남음.

claude plugin prune

기본 user scope, 확인 후 제거. --scope project|local, --dry-run, -y. 비-TTY는 목록만( -y 없으면 미제거).

claude plugin uninstall deploy-kit --prune

수동 설치 플러그인은 prune 대상 아님. 자동 의존성만.

오류 해결

오류	의미	조치
`dependency-unsatisfied`	미설치 또는 비활성	install / marketplace add / enable
`range-conflict`	범위 교집합 없음·잘못된 semver·너무 복잡	충돌 플러그인 조정·`version` 수정
`dependency-version-unsatisfied`	설치 버전이 범위 밖	`claude plugin install <dep>@<marketplace>` 재해석
`no-matching-tag`	만족 태그 없음	업스트림 태그 또는 범위 완화

claude plugin list --json의 errors 필드. UI 메시지는 코드와 다를 수 있으나 의미는 동일. 문제 플러그인은 해결 전까지 비활성.

체크리스트

의존성에 테스트된 semver 범위를 걸었다
릴리스를 {name}--v{version}으로 태그했다 (claude plugin tag --push)
크로스 마켓이면 루트 allowCrossMarketplaceDependenciesOn을 설정했다
enable/disable·prune 동작을 팀에 안내했다
claude plugin list --json으로 오류를 확인했다

다음 단계

기준일

문서 작성·동기화 기준일: 2026-07-26
원문: https://code.claude.com/docs/en/plugin-dependencies

플러그인 의존성 버전 제약

개요

핵심 개념

상세

왜 제약하는가

선언

팀 번들

다른 마켓 의존성

릴리스 태그

제약 상호작용

enable / disable (v2.1.143+)

orphan prune (v2.1.121+)

오류 해결

체크리스트

다음 단계

기준일

관련 가이드

플러그인 의존성 버전 제약

개요

핵심 개념

상세

왜 제약하는가

선언

팀 번들

다른 마켓 의존성

릴리스 태그

제약 상호작용

enable / disable (v2.1.143+)

orphan prune (v2.1.121+)

오류 해결

체크리스트

다음 단계

기준일

관련 가이드