plugin-dependencies.md +0 −267 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# 플러그인 종속성 버전 제약
6
7> 플러그인 종속성에 대한 버전 제약을 선언하고 선별된 플러그인 세트를 하나의 설치 뒤에 번들로 제공합니다.
8
9플러그인은 `plugin.json` 또는 마켓플레이스 항목에 나열하여 다른 플러그인에 종속될 수 있습니다. 기본적으로 종속성은 최신 사용 가능 버전을 추적하므로 업스트림 릴리스가 경고 없이 플러그인의 종속성을 변경할 수 있습니다. 버전 제약을 사용하면 이동하기로 선택할 때까지 테스트된 버전 범위에서 종속성을 유지할 수 있습니다.
10
11종속성을 선언하는 플러그인을 설치하면 Claude Code가 자동으로 종속성을 해결하고 설치합니다. 단, 마켓플레이스 항목에 [`command` 소스](/docs/ko/plugin-marketplaces#how-users-accept-the-command) 또는 [`headersHelper`](/docs/ko/plugin-marketplaces#how-users-accept-a-headershelper-command)가 있는 종속성은 먼저 직접 설치해야 합니다. 나중에 `/reload-plugins`, 종속 플러그인의 마켓플레이스 자동 업데이트, 종속 플러그인에서 `claude plugin install`을 다시 실행, 그리고 `claude plugin marketplace add`는 각각 같은 규칙에 따라 아직 설치되지 않은 선언된 종속성을 설치합니다. 하나가 미해결 상태로 유지되면 [종속성 오류 해결](#resolve-dependency-errors)을 참조하세요.
12
13이 가이드는 `plugin.json`에서 종속성을 선언하는 플러그인 작성자와 릴리스에 태그를 지정하는 마켓플레이스 유지 관리자를 위한 것입니다. 여기서 종속성은 다른 플러그인입니다. 플러그인 자체가 사용하는 npm 및 Bun 패키지는 [Node.js 패키지 종속성](/docs/ko/plugins-reference#node-js-package-dependencies)을 참조하세요. 종속성이 있는 플러그인을 설치하려면 [플러그인 검색 및 설치](/docs/ko/discover-plugins)를 참조하세요. 전체 매니페스트 스키마는 [플러그인 참조](/docs/ko/plugins-reference)를 참조하세요.
14
15<h2 id="why-constrain-dependency-versions">
16 종속성 버전을 제약하는 이유
17</h2>
18
19두 팀이 플러그인을 게시하는 내부 마켓플레이스를 생각해 봅시다. 플랫폼 팀은 비밀 백엔드를 래핑하는 MCP 서버인 `secrets-vault`를 유지 관리합니다. 배포 팀은 배포 중에 자격 증명을 가져오기 위해 `secrets-vault`를 호출하는 `deploy-kit`을 유지 관리합니다.
20
21`deploy-kit`은 `secrets-vault` v2.1.0에 대해 테스트됩니다. 버전 제약이 없으면 플랫폼 팀이 MCP 도구의 이름을 바꾸는 릴리스에 태그를 지정할 때마다 자동 업데이트가 모든 엔지니어의 `secrets-vault`를 새 버전으로 이동하고 `deploy-kit`이 중단됩니다.
22
23버전 제약을 사용하면 `deploy-kit`은 `~2.1.0` 범위에서 `secrets-vault`가 필요함을 선언합니다. `deploy-kit`이 설치된 엔지니어는 가장 높은 일치하는 `2.1.x` 패치에 머물러 있습니다. 배포 팀은 더 넓은 제약이 있는 새로운 `deploy-kit` 버전을 게시하여 자신의 일정에 따라 업그레이드합니다.
24
25<h2 id="declare-a-dependency-with-a-version-constraint">
26 버전 제약으로 종속성 선언
27</h2>
28
29플러그인의 `.claude-plugin/plugin.json`의 `dependencies` 배열에 종속성을 나열합니다.
30
31다음 매니페스트는 하나의 버전 없는 종속성과 하나의 제약된 종속성을 선언합니다:
32
33```json .claude-plugin/plugin.json theme={null}
34{
35 "name": "deploy-kit",
36 "version": "3.1.0",
37 "dependencies": [
38 "audit-logger",
39 { "name": "secrets-vault", "version": "~2.1.0" }
40 ]
41}
42```
43
44항목은 `deploy-kit` 매니페스트의 `"audit-logger"`처럼 플러그인 이름만 있는 문자열일 수 있으며, 이는 해당 플러그인의 마켓플레이스가 제공하는 모든 버전에 종속됩니다. 더 많은 제어를 위해 다음 필드가 있는 객체를 사용합니다:
45
46| 필드 | 유형 | 설명 |
47| :------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
48| `name` | string | 플러그인 이름입니다. 선언 플러그인과 동일한 마켓플레이스 내에서 해결됩니다. 필수입니다. |
49| `version` | string | `~2.1.0`, `^2.0`, `>=1.4` 또는 `=2.1.0`과 같은 [semver 범위](https://github.com/npm/node-semver#ranges)입니다. 종속성은 이 범위를 만족하는 가장 높은 태그된 버전에서 가져옵니다. |
50| `marketplace` | string | `name`을 해결할 다른 마켓플레이스입니다. 교차 마켓플레이스 종속성은 대상 마켓플레이스가 루트 마켓플레이스의 `marketplace.json`에서 [`allowCrossMarketplaceDependenciesOn`](#depend-on-a-plugin-from-another-marketplace)에 나열되지 않는 한 차단됩니다. |
51
52`2.0.0-beta.1`과 같은 사전 릴리스 버전은 `^2.0.0-0`과 같은 사전 릴리스 접미사로 옵트인하지 않는 한 제외됩니다.
53
54<h2 id="bundle-plugins-for-a-team">
55 팀을 위한 플러그인 번들
56</h2>
57
58필수 `name` 외에도 플러그인 매니페스트는 `dependencies` 배열만으로 구성될 수 있습니다. 이를 설치하면 모든 종속성이 함께 설치되므로, 이는 하나의 설치 뒤에 큐레이션된 플러그인 세트를 패키징하는 방법입니다.
59
60예를 들어 플랫폼 팀은 내부 마켓플레이스에 역할별 번들을 게시하여 엔지니어가 각 도구를 별도로 설치하는 대신 하나의 `claude plugin install` 명령을 실행하도록 할 수 있습니다:
61
62```json .claude-plugin/plugin.json theme={null}
63{
64 "name": "backend-standard",
65 "version": "1.0.0",
66 "description": "Standard plugin set for backend engineers",
67 "dependencies": [
68 "secrets-vault",
69 "deploy-kit",
70 { "name": "db-migrate", "version": "^3.0" },
71 "oncall-runbook"
72 ]
73}
74```
75
76`backend-standard`를 설치하면 네 가지 종속성이 모두 해결되고 설치됩니다.
77
78나중에 표준 세트에 도구를 추가하려면 추가 종속성과 함께 새로운 `backend-standard` 버전을 게시합니다. 마켓플레이스가 [자동 업데이트](/docs/ko/discover-plugins#configure-auto-updates)되지 않으면 엔지니어는 다음 두 가지 방법 중 하나로 새 버전을 받습니다:
79
80* `/plugin`에서 마켓플레이스의 자동 업데이트를 활성화합니다. 다음 자동 업데이트에서 번들이 새 버전으로 이동하고 추가되는 모든 종속성이 설치됩니다.
81* `claude plugin update backend-standard`를 실행한 후 `/reload-plugins`를 실행하여 새로 추가된 종속성을 설치합니다.
82
83조직 전체에 번들을 배포하려면 [관리 설정](/docs/ko/settings-reference#enabledplugins)의 `enabledPlugins`에 번들 플러그인을 추가합니다.
84
85<h2 id="depend-on-a-plugin-from-another-marketplace">
86 다른 마켓플레이스의 플러그인에 종속
87</h2>
88
89기본적으로 Claude Code는 플러그인을 선언하는 플러그인과 다른 마켓플레이스에 있는 종속성을 자동 설치하기를 거부합니다. 이는 한 마켓플레이스가 검토하지 않은 소스의 플러그인을 자동으로 가져오는 것을 방지합니다.
90
91이를 허용하려면 루트 마켓플레이스의 유지 관리자가 대상 마켓플레이스 이름을 `marketplace.json`의 `allowCrossMarketplaceDependenciesOn`에 추가합니다. 루트 마켓플레이스는 사용자가 설치하는 플러그인을 호스팅하는 마켓플레이스이며, 해당 허용 목록만 참조되므로 신뢰가 중간 마켓플레이스를 통해 연결되지 않습니다.
92
93다음 `marketplace.json`은 `deploy-kit`이 `acme-shared`의 플러그인에 종속되도록 허용합니다:
94
95```json .claude-plugin/marketplace.json theme={null}
96{
97 "name": "acme-tools",
98 "owner": { "name": "Acme" },
99 "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
100 "plugins": [
101 {
102 "name": "deploy-kit",
103 "source": "./deploy-kit",
104 "dependencies": [
105 { "name": "audit-logger", "marketplace": "acme-shared" }
106 ]
107 }
108 ]
109}
110```
111
112필드가 없거나 대상 마켓플레이스를 포함하지 않으면 설정할 필드의 이름을 지정하는 `cross-marketplace` 오류로 설치가 실패합니다. 사용자는 여전히 종속성을 수동으로 먼저 설치할 수 있으며, 이는 허용 목록을 변경하지 않고 제약을 만족합니다.
113
114<h2 id="test-a-plugin-and-its-dependency-locally">
115 플러그인과 그 종속성을 로컬에서 테스트하기
116</h2>
117
118플러그인을 개발하고 동시에 그 플러그인이 의존하는 플러그인도 개발하는 경우, `--plugin-dir`을 사용하여 둘 다 로드합니다:
119
120```bash theme={null}
121claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin
122```
123
124종속성의 로컬 복사본은 항목이 마켓플레이스를 지정하는 경우에도 플러그인의 종속성 항목을 만족하므로, 마켓플레이스에서 종속성을 설치할 필요가 없습니다. Claude Code는 로컬 복사본에 대해 [버전 제약](#declare-a-dependency-with-a-version-constraint)을 확인하지 않으므로, 로컬 `plugin.json`에는 `version`이 필요하지 않습니다. v2.1.242 이전에는 마켓플레이스를 지정하는 종속성 항목이 로컬 복사본과 일치하지 않았으며, Claude Code는 로드 시 플러그인을 비활성화했습니다.
125
126두 플러그인이 하나의 상위 폴더에 있는 경우, 해당 폴더를 `--plugin-dir`에 한 번만 전달할 수 있습니다. 폴더 자체가 플러그인이 아닌 경우, Claude Code는 `.claude-plugin/plugin.json`을 가진 각 하위 폴더를 로드합니다. Claude Code v2.1.265 이상이 필요합니다.
127
128마켓플레이스에서 종속성을 설치하지 않은 경우, 로컬 복사본이 사라지면 플러그인 로드가 중지됩니다:
129
130* **로컬 복사본을 비활성화한 경우**: Claude Code는 다음 플러그인 로드 시 플러그인을 비활성화합니다. 마켓플레이스를 지정하는 종속성 항목의 경우, Claude Code는 `Dependency "<name>@inline" is disabled — enable it or remove the dependency`를 보고합니다. 단순 이름 항목의 경우, 종속성을 단순 이름으로 보고합니다. `<name>@inline`은 Claude Code가 모든 `--plugin-dir` 및 `--plugin-url` 플러그인을 식별하는 방식입니다.
131* **종속성의 `--plugin-dir` 플래그 없이 세션을 시작한 경우**: Claude Code는 종속성이 설치되지 않았다고 보고합니다. 플래그를 다시 전달하거나 마켓플레이스에서 종속성을 설치합니다.
132
133<h2 id="tag-plugin-releases-for-version-resolution">
134 버전 해석을 위한 태그 플러그인 릴리스
135</h2>
136
137Claude Code는 의존성을 호스팅하는 저장소의 git 태그에 대해 버전 제약을 해석합니다. `github`, `url`, `git-subdir` [플러그인 소스](/docs/ko/plugin-marketplaces#plugin-sources)의 경우 플러그인 자체 저장소이거나, 마켓플레이스가 상대 경로로 참조하는 플러그인의 경우 마켓플레이스 저장소입니다. Claude Code가 의존성의 사용 가능한 버전을 찾으려면 업스트림 플러그인의 릴리스가 특정 명명 규칙을 사용하여 태그되어야 합니다.
138
139각 릴리스를 `{plugin-name}--v{version}`으로 태그하십시오. 여기서 `{version}`은 해당 커밋의 `plugin.json`에 있는 `version` 필드와 일치합니다. 플러그인 디렉터리에서 다음을 실행하십시오:
140
141```bash theme={null}
142claude plugin tag --push
143```
144
145`claude plugin tag` 명령은 플러그인의 매니페스트와 포함된 마켓플레이스 항목에서 태그 이름을 파생합니다. 태그를 생성하기 전에 플러그인 내용을 검증하고, `plugin.json`과 마켓플레이스 항목이 버전에 동의하는지 확인하고, 플러그인 디렉터리 아래의 깨끗한 작업 트리를 요구하며, 태그가 이미 존재하면 거부합니다.
146
147* `--push`는 태그를 `origin` 원격으로 푸시하므로 저장소에 구성된 `origin` 원격이 필요합니다. `--remote`를 전달하여 다른 원격으로 푸시하십시오.
148* 푸시가 실패하면 태그는 여전히 로컬로 생성되고 명령은 오류와 함께 종료됩니다.
149* `--push`를 사용하면 성공적인 실행은 `Created tag secrets-vault--v2.1.0` 및 `Pushed to origin`으로 끝나며, 마지막 줄은 푸시한 원격의 이름을 지정합니다. `--push` 없이는 명령이 대신 실행할 `git push` 명령을 인쇄합니다.
150* `--dry-run`은 생성하지 않고 태그될 내용을 인쇄합니다.
151
152`git tag secrets-vault--v2.1.0`을 직접 실행하는 것은 `plugin.json`과 마켓플레이스 항목을 직접 동기화 상태로 유지하면 동등합니다.
153
154플러그인 이름 접두사를 사용하면 하나의 마켓플레이스 저장소가 독립적인 버전 라인을 가진 여러 플러그인을 호스팅할 수 있습니다. `--v` 구분자는 전체 플러그인 이름에 대한 접두사 일치로 파싱되므로 하이픈을 포함하는 플러그인 이름이 올바르게 처리됩니다.
155
156`{ "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는 마켓플레이스의 현재 복사본을 대신 설치하고 플러그인이 로드될 때 제약을 확인합니다.
157
158마켓플레이스가 상대 경로로 참조하는 플러그인의 경우, 로컬 폴더 경로로 추가된 마켓플레이스는 폴더가 git 저장소일 때 동일한 방식으로 태그를 해석합니다. 이는 Claude Code v2.1.196 이상이 필요합니다. 두 가지 경우에 Claude Code는 폴더의 현재 내용에서 의존성을 설치합니다:
159
160* 이전 버전은 로컬 폴더 마켓플레이스에서 태그를 읽지 않으므로 제약된 의존성은 해당 복사본이 범위를 만족할 때만 로드됩니다.
161* git 저장소가 아닌 로컬 폴더는 버전에 관계없이 태그가 없습니다.
162
163해석된 태그의 semver는 `plugin.json`의 `version`과 별도로 기록되므로 제약 확인은 `plugin.json`이 해당 커밋에서 오래된 값을 가지고 있더라도 실제로 가져온 태그를 사용합니다. 태그 해석 설치의 캐시 디렉터리 이름에는 12자 커밋-SHA 접미사가 포함되므로 유지 관리자가 태그를 다른 커밋으로 강제 이동하면 다음 설치는 오래된 내용을 재사용하는 대신 새로운 캐시 디렉터리를 가져옵니다.
164
165<Note>
166 `npm`, `archive`, 또는 `command` [플러그인 소스](/docs/ko/plugin-marketplaces#plugin-sources)를 가진 의존성의 경우, 태그 기반 해석이 git 지원 소스에만 적용되므로 제약이 어떤 버전을 가져올지 제어하지 않습니다. 제약은 여전히 로드 시간에 확인되며, 설치된 버전이 제약을 만족하지 않으면 종속 플러그인은 `dependency-version-unsatisfied`로 비활성화됩니다. `command` 소스의 경우 Claude Code는 의존성의 `plugin.json`에서 버전을 확인하고 콘텐츠 해시 접미사를 무시합니다. `plugin.json`이 버전을 설정하지 않는 의존성은 제약을 만족하지 않으므로 제약하기 전에 버전을 설정하십시오.
167
168 Claude Code는 `command` 소스를 가진 의존성을 직접 설치하지 않으므로 사용자는 [먼저 설치합니다](/docs/ko/plugin-marketplaces#how-users-accept-the-command). Claude Code는 의존성의 마켓플레이스 항목에서 `headersHelper`를 실행하지 않으므로 사용자는 [먼저 해당 플러그인을 설치합니다](/docs/ko/plugin-marketplaces#how-users-accept-a-headershelper-command).
169</Note>
170
171<h2 id="how-constraints-interact">
172 제약이 상호 작용하는 방식
173</h2>
174
175여러 설치된 플러그인이 동일한 종속성을 제약하면 Claude Code는 해당 범위를 교차하고 모든 범위를 만족하는 가장 높은 버전으로 종속성을 해결합니다. 아래 표는 일반적인 조합이 어떻게 해결되는지 보여줍니다.
176
177| 플러그인 A 필요 | 플러그인 B 필요 | 결과 |
178| :-------- | :-------- | :------------------------------------------------------------ |
179| `^2.0` | `>=2.1` | `2.1.0` 이상의 가장 높은 `2.x` 태그에서 하나의 설치입니다. 두 플러그인 모두 로드됩니다. |
180| `~2.1` | `~3.0` | 플러그인 B 설치가 `range-conflict`로 실패합니다. 플러그인 A와 종속성은 그대로 유지됩니다. |
181| `=2.1.0` | none | 종속성은 `2.1.0`에 머물러 있습니다. 플러그인 A가 설치된 동안 자동 업데이트는 최신 버전을 건너뜁니다. |
182
183자동 업데이트는 마켓플레이스의 최신 버전이 아닌 모든 설치된 플러그인의 범위를 만족하는 가장 높은 git 태그에서 제약된 종속성을 가져오므로, 종속성은 허용된 범위 내에서 계속 업데이트를 받습니다. 모든 범위를 만족하는 태그가 없으면 자동 업데이트는 해당 종속성을 건너뛰고 `/plugin` 오류 탭에서 건너뛴 내용을 나열하며 제약 플러그인의 이름을 지정합니다.
184
185종속성을 제약하는 마지막 플러그인을 제거하면 종속성은 더 이상 유지되지 않으며 다음 업데이트에서 마켓플레이스 항목 추적을 재개합니다.
186
187<h2 id="enable-or-disable-a-plugin-with-dependencies">
188 플러그인 종속성 활성화 또는 비활성화
189</h2>
190
191이 섹션은 마켓플레이스에서 설치한 플러그인을 다룹니다. `--plugin-dir`로 로드한 복사본의 경우 [플러그인 및 해당 종속성을 로컬에서 테스트](#test-a-plugin-and-its-dependency-locally)를 참조하십시오.
192
193플러그인을 활성화하면 이에 종속된 플러그인도 활성화되며, 다른 활성화된 플러그인이 여전히 필요로 하면 플러그인을 비활성화할 수 없습니다.
194
195플러그인을 활성화하면 Claude Code는 동일한 범위에서 해당 종속성도 활성화합니다. 종속성에 자체 종속성이 있으면 Claude Code는 이들도 활성화합니다. 성공 메시지는 명명한 플러그인과 함께 활성화된 다른 항목을 나열합니다. 종속성을 활성화할 수 없으면 명령이 거부되고 무엇이 차단하고 있는지, 어떻게 해결할지 알려줍니다:
196
197| 조건 | 결과 |
198| :--------------------------------------- | :--------------------------------------------------------- |
199| 종속성이 설치되지 않음 | 활성화가 실패하고 누락된 각 종속성에 대해 `claude plugin install` 명령을 인쇄합니다. |
200| 종속성이 조직의 플러그인 정책에 의해 차단됨 | 활성화가 실패하고 차단된 종속성의 이름을 지정합니다. |
201| 종속성이 대상 범위보다 우선 순위가 높은 범위에서 `false`로 설정됨 | 활성화가 실패합니다. 해당 범위에서 종속성을 활성화하거나 `--scope`를 전달하여 거기에 쓰기합니다. |
202| 모든 종속성이 설치되고 허용됨 | 활성화가 성공하고 대상 범위에서 아직 활성화되지 않은 플러그인과 각 종속성에 대해 `true`를 씁니다. |
203
204이는 종속성이 매니페스트에서 [`defaultEnabled: false`](/docs/ko/plugins-reference#default-enablement)를 설정하는 경우에도 적용됩니다. Claude Code는 이에 대해 명시적 `true`를 쓰기 때문입니다. 설치 시에도 동일하게 적용됩니다. 활성화된 플러그인을 만족시키기 위해 가져온 종속성은 자체 기본값에 관계없이 `true`로 설치됩니다.
205
206플러그인을 비활성화하면 다른 활성화된 플러그인이 여전히 이에 종속되면 Claude Code가 거부합니다. 오류는 이에 종속된 플러그인의 이름을 지정하고 올바른 순서로 비활성화하는 연쇄 명령을 제공하며, 요청한 것으로 끝납니다.
207
208예를 들어 `deploy-kit`이 `secrets-vault`에 종속되면 `secrets-vault`만 비활성화하면 다음과 유사한 출력으로 실패합니다:
209
210```text theme={null}
211secrets-vault is still required by deploy-kit. Disable that plugin first, or
212disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools
213```
214
215오류에서 연쇄 명령을 복사하여 한 단계에서 전체 집합을 비활성화합니다.
216
217<h2 id="remove-orphaned-auto-installed-dependencies">
218 고아 자동 설치 종속성 제거
219</h2>
220
221자동 설치된 종속성은 이를 설치한 플러그인이 제거된 후에도 디스크에 남아 있으며, 종속 플러그인을 다시 설치하거나 종속성을 직접 계속 사용하려는 경우를 대비합니다. 이를 정리하려면 `claude plugin prune`을 실행하여 더 이상 설치된 플러그인이 필요로 하지 않는 자동 설치된 종속성을 나열하고 확인 프롬프트 후 제거합니다.
222
223```bash theme={null}
224claude plugin prune
225```
226
227제거 대상이 없으면 명령은 `Nothing to prune`을 이유와 함께 출력하고 종료합니다. 이는 새로 설치한 경우의 예상된 출력이며 오류가 아닙니다.
228
229기본적으로 prune은 사용자 범위에서 작동하며 제거하기 전에 확인을 요청합니다:
230
231* `--scope project` 또는 `--scope local`은 다른 범위를 대상으로 합니다.
232* `--dry-run`은 아무것도 변경하지 않고 제거될 항목을 나열합니다.
233* `-y`는 확인 프롬프트를 건너뜁니다. stdin 또는 stdout이 터미널이 아닐 때 prune은 고아를 나열하고 `-y`를 전달하지 않는 한 제거하지 않고 종료합니다.
234
235제거의 일부로 prune하려면 `claude plugin uninstall`에 `--prune`을 전달합니다. 명명된 플러그인을 제거한 후 Claude Code는 이제 고아가 된 자동 설치된 종속성을 검사하고 제거합니다. 직접 설치한 플러그인은 절대 prune되지 않으며, 다른 플러그인의 `dependencies` 배열을 통해 자동으로 설치된 플러그인만 prune됩니다.
236
237동일한 확인 동작이 적용됩니다. stdin 또는 stdout이 터미널이 아닐 때 제거는 여전히 완료되지만 prune 단계는 고아를 나열하고 `-y`를 전달하지 않는 한 제거하지 않습니다.
238
239예를 들어 `deploy-kit`을 제거하고 이를 남기는 종속성을 정리하려면:
240
241```bash theme={null}
242claude plugin uninstall deploy-kit --prune
243```
244
245<h2 id="resolve-dependency-errors">
246 종속성 오류 해결
247</h2>
248
249종속성 문제는 `claude plugin list` 및 `/plugin` 인터페이스에 표시되며, 이 표의 리터럴 코드가 아닌 설명적 오류 메시지로 나타납니다. Claude Code는 오류를 해결할 때까지 영향을 받는 플러그인을 비활성화합니다. 아래 표에는 가장 일반적인 오류와 해결 방법이 나열되어 있습니다.
250
251| 오류 | 의미 | 해결 방법 |
252| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
253| `dependency-unsatisfied` | 선언된 종속성이 설치되지 않았거나 설치되었지만 비활성화되어 있습니다. | 오류 메시지에 표시된 `claude plugin install` 명령을 실행합니다. 종속성의 마켓플레이스가 아직 구성되지 않은 경우 `claude plugin marketplace add`로 추가하면 Claude Code가 종속성을 자동으로 해결합니다. 종속성이 비활성화된 경우 활성화합니다. |
254| `range-conflict` | 종속성의 버전 요구 사항을 결합할 수 없습니다. 오류 메시지는 원인의 이름을 지정합니다: 모든 범위를 만족하는 버전이 없거나, 범위가 유효한 semver 구문이 아니거나, 결합된 범위가 너무 복잡하여 교차할 수 없습니다. | 충돌하는 플러그인 중 하나를 제거하거나 업데이트하고, 유효하지 않은 `version` 문자열을 수정하고, 긴 `\|\|` 체인을 단순화하거나, 업스트림 작성자에게 제약을 넓히도록 요청합니다. |
255| `dependency-version-unsatisfied` | 설치된 종속성의 버전이 이 플러그인의 선언된 범위를 벗어났습니다. | `claude plugin install <dependency>@<marketplace>`를 실행하여 모든 현재 제약에 대해 종속성을 다시 해결합니다. |
256| `no-matching-tag` | 종속성의 저장소에 범위를 만족하는 `{name}--v*` 태그가 없습니다. | 업스트림이 위의 규칙을 사용하여 릴리스에 태그를 지정했는지 확인하거나 범위를 완화합니다. |
257
258이러한 오류를 프로그래밍 방식으로 확인하려면 `claude plugin list --json`을 실행합니다. 문제가 있는 플러그인에는 이를 나열하는 `errors` 필드가 포함됩니다. 정상적으로 로드된 플러그인은 이 필드를 생략합니다.
259
260<h2 id="see-also">
261 참고 항목
262</h2>
263
264* [플러그인 생성](/docs/ko/plugins): 기술, 에이전트 및 훅으로 플러그인 빌드
265* [플러그인 마켓플레이스 생성 및 배포](/docs/ko/plugin-marketplaces): 팀을 위한 플러그인 호스팅
266* [플러그인 참조](/docs/ko/plugins-reference#plugin-manifest-schema): 전체 `plugin.json` 스키마
267* [버전 관리](/docs/ko/plugins-reference#version-management): 플러그인의 자체 버전이 어떻게 해결되고 캐시 키로 사용되는지