커스텀 및 커뮤니티 모듈 설치

BMad 설치 프로그램을 사용해 커뮤니티 레지스트리, 서드파티 Git 저장소, 로컬 파일 경로에서 모듈을 추가하세요.

사용 시점

• BMad 레지스트리에서 커뮤니티 기여 모듈을 설치합니다
• 서드파티 Git 저장소(GitHub, GitLab, Bitbucket, 자체 호스팅)에서 모듈을 설치합니다
• BMad 빌더로 로컬에서 개발 중인 모듈을 테스트합니다
• 비공개 또는 자체 호스팅 Git 서버에서 모듈을 설치합니다

필수 조건

Node.js v20.12+와 npx(npm에 포함)가 필요합니다. 커스텀 및 커뮤니티 모듈은 새 설치 중 선택하거나 기존 설치에 추가할 수 있습니다.

커뮤니티 모듈

커뮤니티 모듈은 BMad 플러그인 마켓플레이스에서 선별됩니다. 카테고리별로 구성되고 안전을 위해 승인된 커밋에 고정됩니다.

1. 설치 프로그램 실행

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 플래그를 사용하세요.

npx bmad-method install \
  --directory . \
  --custom-source /path/to/my-module \
  --tools claude-code \
  --yes

--modules 없이 --custom-source를 제공하면 core와 커스텀 모듈만 설치됩니다. 공식 모듈도 포함하려면 --modules를 추가하세요.

npx bmad-method install \
  --directory . \
  --modules bmm \
  --custom-source https://gitlab.com/myorg/my-module \
  --tools claude-code \
  --yes

여러 소스는 쉼표로 구분할 수 있습니다.

--custom-source /path/one,https://github.com/org/repo,/path/two

모듈 발견 방식

설치 프로그램은 소스에서 설치 가능한 모듈을 찾기 위해 두 모드를 사용합니다.

모드	트리거	동작
Discovery	소스에 .claude-plugin/marketplace.json이 있습니다	매니페스트의 모든 플러그인을 나열하고 설치할 항목을 선택하게 합니다
Direct	marketplace.json이 없습니다	디렉터리에서 스킬(SKILL.md가 있는 하위 디렉터리)을 스캔하고 단일 모듈로 해석합니다

Discovery 모드는 게시된 모듈에 일반적입니다. Direct 모드는 로컬 개발 중 스킬 디렉터리를 가리킬 때 편리합니다.

.claude-plugin/ 안내

.claude-plugin/marketplace.json 경로는 여러 AI 도구 설치 프로그램에서 플러그인 발견을 위해 채택한 표준 관례입니다. Claude가 필요하지 않고 Claude API를 사용하지 않으며 어떤 AI 도구를 쓰는지에 영향을 주지 않습니다. 이 파일이 있는 모듈은 관례를 따르는 모든 설치 프로그램에서 발견될 수 있습니다.

로컬 개발 워크플로

BMad 빌더로 모듈을 만들고 있다면 작업 디렉터리에서 직접 설치할 수 있습니다.

npx bmad-method install \
  --directory ~/my-project \
  --custom-source ~/my-module-repo/skills \
  --tools claude-code \
  --yes

로컬 소스는 캐시에 복사되지 않고 경로로 참조됩니다. 모듈 소스를 업데이트하고 다시 설치하면 설치 프로그램이 최신 변경을 가져옵니다.

소스 제거

설치 후 로컬 소스 디렉터리를 삭제해도 _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 빌더를 사용하세요.

1. bmad-module-builder를 실행해 모듈 초기 구조를 생성합니다
2. 여러 BMad 빌더 도구로 스킬, 에이전트, 워크플로를 추가합니다
3. Git 저장소에 게시하거나 폴더 컬렉션을 공유합니다
4. 다른 사용자는 --custom-source <your-repo-url>로 설치합니다

모듈이 발견 모드를 지원하려면 저장소 루트에 .claude-plugin/marketplace.json을 포함하세요(Claude 전용이 아닌 도구 간 관례입니다). marketplace.json 형식은 BMad 빌더 문서를 참고하세요.

먼저 로컬에서 테스트

개발 중에는 Git 저장소에 게시하기 전에 로컬 경로로 모듈을 설치해 빠르게 수정하고 확인하세요.