182 lines
7.6 KiB
Markdown
182 lines
7.6 KiB
Markdown
---
|
|
title: '커스텀 및 커뮤니티 모듈 설치'
|
|
description: 커뮤니티 레지스트리, Git 저장소, 로컬 경로에서 서드파티 모듈을 설치합니다
|
|
sidebar:
|
|
order: 3
|
|
---
|
|
|
|
BMad 설치 프로그램을 사용해 커뮤니티 레지스트리, 서드파티 Git 저장소, 로컬 파일 경로에서 모듈을 추가하세요.
|
|
|
|
## 사용 시점
|
|
|
|
- BMad 레지스트리에서 커뮤니티 기여 모듈을 설치합니다
|
|
- 서드파티 Git 저장소(GitHub, GitLab, Bitbucket, 자체 호스팅)에서 모듈을 설치합니다
|
|
- BMad 빌더로 로컬에서 개발 중인 모듈을 테스트합니다
|
|
- 비공개 또는 자체 호스팅 Git 서버에서 모듈을 설치합니다
|
|
|
|
:::note[필수 조건]
|
|
[Node.js](https://nodejs.org) v20+와 `npx`(npm에 포함)가 필요합니다. 커스텀 및 커뮤니티 모듈은 새 설치 중 선택하거나 기존 설치에 추가할 수 있습니다.
|
|
:::
|
|
|
|
## 커뮤니티 모듈
|
|
|
|
커뮤니티 모듈은 [BMad 플러그인 마켓플레이스](https://github.com/bmad-code-org/bmad-plugins-marketplace)에서 선별됩니다. 카테고리별로 구성되고 안전을 위해 승인된 커밋에 고정됩니다.
|
|
|
|
### 1. 설치 프로그램 실행
|
|
|
|
```bash
|
|
npx bmad-method install
|
|
```
|
|
|
|
### 2. 커뮤니티 카탈로그 둘러보기
|
|
|
|
공식 모듈을 선택한 뒤 설치 프로그램이 묻습니다.
|
|
|
|
```
|
|
Would you like to browse community modules?
|
|
```
|
|
|
|
카탈로그 브라우저로 들어가려면 **Yes**를 선택하세요. 할 수 있는 일은 다음과 같습니다.
|
|
|
|
- 카테고리별 탐색
|
|
- 추천 모듈 보기
|
|
- 사용 가능한 모든 모듈 보기
|
|
- 키워드로 검색
|
|
|
|
### 3. 모듈 선택
|
|
|
|
어떤 카테고리에서든 모듈을 선택하세요. 설치 프로그램은 설명, 버전, 신뢰 등급을 보여줍니다. 이미 설치된 모듈은 업데이트 대상으로 미리 체크됩니다.
|
|
|
|
### 4. 설치 계속
|
|
|
|
커뮤니티 모듈을 선택하면 설치 프로그램은 커스텀 소스, 도구/IDE 설정, 나머지 설치 흐름으로 이어집니다.
|
|
|
|
## 커스텀 소스(Git URL과 로컬 경로)
|
|
|
|
커스텀 모듈은 어떤 Git 저장소나 로컬 디렉터리에서든 올 수 있습니다. 설치 프로그램은 소스를 해석하고 모듈 구조를 분석한 뒤 다른 모듈 옆에 설치합니다.
|
|
|
|
### 대화형 설치
|
|
|
|
설치 중 커뮤니티 모듈 단계 이후 설치 프로그램이 묻습니다.
|
|
|
|
```
|
|
Would you like to install from a custom source (Git URL or local path)?
|
|
```
|
|
|
|
**Yes**를 선택한 뒤 소스를 제공합니다.
|
|
|
|
| 입력 유형 | 예시 |
|
|
| --- | --- |
|
|
| HTTPS URL(모든 호스트) | `https://github.com/org/repo` |
|
|
| HTTP URL(모든 호스트) | `http://host/org/repo` |
|
|
| 하위 디렉터리가 있는 HTTPS URL | `https://github.com/org/repo/tree/main/my-module` |
|
|
| SSH URL | `git@github.com:org/repo.git` |
|
|
| 로컬 경로 | `/Users/me/projects/my-module` |
|
|
| 틸드가 있는 로컬 경로 | `~/projects/my-module` |
|
|
|
|
설치 프로그램은 저장소를 복제(URL인 경우)하거나 디스크에서 직접 읽은 뒤(로컬 경로인 경우), 발견된 모듈을 선택할 수 있게 보여줍니다.
|
|
|
|
### 비대화형 설치
|
|
|
|
명령줄에서 커스텀 모듈을 설치하려면 `--custom-source` 플래그를 사용하세요.
|
|
|
|
```bash
|
|
npx bmad-method install \
|
|
--directory . \
|
|
--custom-source /path/to/my-module \
|
|
--tools claude-code \
|
|
--yes
|
|
```
|
|
|
|
`--modules` 없이 `--custom-source`를 제공하면 core와 커스텀 모듈만 설치됩니다. 공식 모듈도 포함하려면 `--modules`를 추가하세요.
|
|
|
|
```bash
|
|
npx bmad-method install \
|
|
--directory . \
|
|
--modules bmm \
|
|
--custom-source https://gitlab.com/myorg/my-module \
|
|
--tools claude-code \
|
|
--yes
|
|
```
|
|
|
|
여러 소스는 쉼표로 구분할 수 있습니다.
|
|
|
|
```bash
|
|
--custom-source /path/one,https://github.com/org/repo,/path/two
|
|
```
|
|
|
|
## 모듈 발견 방식
|
|
|
|
설치 프로그램은 소스에서 설치 가능한 모듈을 찾기 위해 두 모드를 사용합니다.
|
|
|
|
| 모드 | 트리거 | 동작 |
|
|
| --- | --- | --- |
|
|
| `Discovery` | 소스에 `.claude-plugin/marketplace.json`이 있습니다 | 매니페스트의 모든 플러그인을 나열하고 설치할 항목을 선택하게 합니다 |
|
|
| `Direct` | marketplace.json이 없습니다 | 디렉터리에서 스킬(`SKILL.md`가 있는 하위 디렉터리)을 스캔하고 단일 모듈로 해석합니다 |
|
|
|
|
`Discovery` 모드는 게시된 모듈에 일반적입니다. `Direct` 모드는 로컬 개발 중 스킬 디렉터리를 가리킬 때 편리합니다.
|
|
|
|
:::note[`.claude-plugin/`에 대해]
|
|
`.claude-plugin/marketplace.json` 경로는 여러 AI 도구 설치 프로그램에서 플러그인 발견을 위해 채택한 표준 관례입니다. Claude가 필요하지 않고 Claude API를 사용하지 않으며 어떤 AI 도구를 쓰는지에 영향을 주지 않습니다. 이 파일이 있는 모듈은 관례를 따르는 모든 설치 프로그램에서 발견될 수 있습니다.
|
|
:::
|
|
|
|
## 로컬 개발 워크플로
|
|
|
|
[BMad 빌더](https://github.com/bmad-code-org/bmad-builder)로 모듈을 만들고 있다면 작업 디렉터리에서 직접 설치할 수 있습니다.
|
|
|
|
```bash
|
|
npx bmad-method install \
|
|
--directory ~/my-project \
|
|
--custom-source ~/my-module-repo/skills \
|
|
--tools claude-code \
|
|
--yes
|
|
```
|
|
|
|
로컬 소스는 캐시에 복사되지 않고 경로로 참조됩니다. 모듈 소스를 업데이트하고 다시 설치하면 설치 프로그램이 최신 변경을 가져옵니다.
|
|
|
|
:::caution[소스 제거]
|
|
설치 후 로컬 소스 디렉터리를 삭제해도 `_bmad/`에 설치된 모듈 파일은 보존됩니다. 소스 경로가 복원될 때까지 업데이트 중 해당 모듈은 건너뜁니다.
|
|
:::
|
|
|
|
## 얻는 결과
|
|
|
|
설치 후 커스텀 모듈은 공식 모듈과 함께 `_bmad/`에 나타납니다.
|
|
|
|
```
|
|
your-project/
|
|
├── _bmad/
|
|
│ ├── core/ # 내장 core 모듈
|
|
│ ├── bmm/ # 공식 모듈(선택한 경우)
|
|
│ ├── my-module/ # 커스텀 모듈
|
|
│ │ ├── my-skill/
|
|
│ │ │ └── SKILL.md
|
|
│ │ └── module-help.csv
|
|
│ └── _config/
|
|
│ └── manifest.yaml # 모든 모듈, 버전, 소스를 추적
|
|
└── ...
|
|
```
|
|
|
|
매니페스트는 각 커스텀 모듈의 소스(Git 소스는 `repoUrl`, 로컬 소스는 `localPath`)를 기록하여 `Quick Update`가 소스를 다시 찾을 수 있게 합니다.
|
|
|
|
## 커스텀 모듈 업데이트
|
|
|
|
커스텀 모듈도 일반 업데이트 흐름에 참여합니다.
|
|
|
|
- **Quick Update**(`--action quick-update`): 모든 모듈을 원래 소스에서 새로 고칩니다. Git 기반 모듈은 다시 가져오고 로컬 모듈은 소스 경로에서 다시 읽힙니다.
|
|
- **전체 업데이트**: 모듈 선택을 다시 실행해 커스텀 모듈을 추가하거나 제거할 수 있습니다.
|
|
|
|
## 직접 모듈 만들기
|
|
|
|
다른 사람이 설치할 수 있는 모듈을 만들려면 [BMad 빌더](https://github.com/bmad-code-org/bmad-builder)를 사용하세요.
|
|
|
|
1. `bmad-module-builder`를 실행해 모듈 초기 구조를 생성합니다
|
|
2. 여러 BMad 빌더 도구로 스킬, 에이전트, 워크플로를 추가합니다
|
|
3. Git 저장소에 게시하거나 폴더 컬렉션을 공유합니다
|
|
4. 다른 사용자는 `--custom-source <your-repo-url>`로 설치합니다
|
|
|
|
모듈이 발견 모드를 지원하려면 저장소 루트에 `.claude-plugin/marketplace.json`을 포함하세요(Claude 전용이 아닌 도구 간 관례입니다). marketplace.json 형식은 [BMad 빌더 문서](https://github.com/bmad-code-org/bmad-builder)를 참고하세요.
|
|
|
|
:::tip[먼저 로컬에서 테스트]
|
|
개발 중에는 Git 저장소에 게시하기 전에 로컬 경로로 모듈을 설치해 빠르게 반복하세요.
|
|
:::
|