BMAD-METHOD/docs/ko-kr/how-to/install-bmad.md

title	description	sidebar
BMad 설치 방법	로컬 개발, 팀, CI를 위해 BMad를 설치, 업데이트, 고정합니다	order 1

프로젝트에 BMad를 설정하려면 npx bmad-method install을 사용하세요. 하나의 명령으로 최초 설치, 업그레이드, 채널 전환, 스크립트 기반 CI 실행을 처리합니다. 이 페이지에서 그 전체를 다룹니다.

사용 시점

• BMad로 새 프로젝트를 시작합니다
• 기존 설치에 모듈을 추가하거나 제거합니다
• 모듈을 main 브랜치 최신 커밋으로 전환하거나 특정 릴리스에 고정합니다
• CI 파이프라인, Dockerfile, 엔터프라이즈 배포를 위해 설치를 스크립트화합니다

:::note[필수 조건]

• Node.js 20+ (설치 프로그램에 필요)
• Git (외부 모듈 복제용)
• Claude Code 또는 Cursor 같은 AI 도구(지원 도구 목록은 npx bmad-method install --list-tools로 확인)

:::

최초 설치(빠른 경로)

npx bmad-method install

대화형 흐름은 다섯 가지를 묻습니다.

1. 설치 디렉터리(기본값은 현재 작업 디렉터리)
2. 설치할 모듈(core, bmm, bmb, cis, gds, tea 체크박스)
3. "Ready to install (all stable)?" - Yes를 선택하면 모든 외부 모듈의 최신 릴리스 태그를 사용합니다
4. 연동할 AI 도구/IDE(claude-code, cursor 등)
5. 모듈별 설정(이름, 언어, 출력 폴더)

기본값을 받아들이면 선택한 도구에 맞게 설정된 각 모듈의 최신 안정 릴리스가 설치됩니다.

:::tip[최신 사전 릴리스만 원하나요?]

npx bmad-method@next install

core와 bmm의 더 새로운 스냅샷이 포함된 사전 릴리스 설치 프로그램을 실행합니다. 변화는 더 잦지만 개발과 릴리스 사이의 지연이 줄어듭니다. :::

특정 버전 선택

디스크에 무엇이 설치되는지는 두 개의 독립 축으로 제어됩니다.

축 1: 외부 모듈 채널

bmb, cis, gds, tea, 커뮤니티 모듈 등 모든 외부 모듈은 세 채널 중 하나로 설치됩니다.

채널	설치되는 것	누가 선택하나
stable(기본값)	가장 높은 시맨틱 버전 릴리스 태그. v2.0.0-alpha.1 같은 사전 릴리스는 제외됩니다.	대부분의 사용자
next	설치 시점의 main 브랜치 최신 커밋	기여자, 초기 채택자
pinned	지정한 특정 태그	엔터프라이즈 설치, CI 재현성

채널은 모듈마다 정할 수 있습니다. bmb는 next로 두고 cis는 stable로 둘 수 있습니다. 아래 플래그로 자유롭게 섞을 수 있습니다.

축 2: 설치 프로그램 바이너리 버전

bmad-method npm 패키지 자체에는 두 npm 배포 태그(dist-tag)가 있습니다.

명령	받는 것
npx bmad-method install(@latest)	최신 안정 설치 프로그램 릴리스
npx bmad-method@next install	main에 푸시될 때마다 자동 배포되는 최신 사전 릴리스 설치 프로그램

설치 프로그램 바이너리가 core와 bmm 버전을 결정합니다. 이 두 모듈은 별도 저장소에서 복제되지 않고 설치 프로그램 패키지 안에 번들됩니다.

core와 bmm에 자체 채널이 없는 이유

두 모듈은 실행한 설치 프로그램 바이너리에 묶여 있습니다.

• npx bmad-method install → 최신 안정 core 및 bmm
• npx bmad-method@next install → 사전 릴리스 core 및 bmm
• node /path/to/local-checkout/tools/installer/bmad-cli.js install → 로컬 체크아웃의 내용

--pin bmm=v6.3.0과 --next=bmm은 번들 모듈에는 효과가 없고, 시도하면 설치 프로그램이 경고합니다. 향후 릴리스에서 bmm가 설치 프로그램 패키지에서 분리되면 bmb처럼 적절한 채널 선택기를 갖게 됩니다.

기존 설치 업데이트

이미 _bmad/가 있는 디렉터리에서 npx bmad-method install을 실행하면 메뉴가 나타납니다.

실제 메뉴 선택	하는 일
Quick Update	기존 설정으로 설치를 다시 실행합니다. 파일을 새로 고치고, 안정 채널의 패치와 마이너 업그레이드를 적용하며, 메이저 업그레이드는 거부합니다. 빠르고 비대화형입니다.
Modify Install	전체 대화형 흐름입니다. 모듈을 추가/제거하고, 설정을 다시 구성하고, 기존 모듈 채널을 검토하고 전환할 수 있습니다.

업그레이드 프롬프트

Modify가 stable에 설치된 모듈의 새 안정 태그를 감지하면 변경 폭을 분류하고 그에 맞게 묻습니다.

업그레이드 유형	예시	기본값
패치	v1.7.0 → v1.7.1	Y
마이너	v1.7.0 → v1.8.0	Y
메이저	v1.7.0 → v2.0.0	N

메이저 업그레이드는 호환성 깨짐이 예상치 못한 "불안정"으로 나타나는 경우가 많기 때문에 기본값이 N입니다. 프롬프트에는 변경 내용을 읽을 수 있는 GitHub 릴리스 노트 URL이 포함됩니다.

--yes에서는 패치와 마이너 업그레이드가 자동 적용됩니다. 메이저 업그레이드는 고정된 채로 유지됩니다. 비대화형으로 수락하려면 --pin <code>=<new-tag>를 전달하세요.

모듈 채널 전환

대화형: Modify를 선택하고 "Review channel assignments?"에 Yes로 답한 뒤, 각 외부 모듈에서 Keep, Switch to stable, Switch to next, Pin to a tag 중 하나를 선택합니다.

플래그로: 다음 섹션의 레시피가 일반적인 경우를 다룹니다.

Headless CI

플래그 참조

플래그	목적
--yes, -y	모든 프롬프트를 건너뛰고 플래그 값과 기본값을 수락합니다
--directory <path>	이 디렉터리에 설치합니다(기본값: 현재 작업 디렉터리)
--modules <a,b,c>	정확한 모듈 집합입니다. core는 자동 추가됩니다. 증분 목록이 아니므로 유지하려는 모든 것을 나열하세요
--tools <a,b>	IDE/도구 선택입니다. 새 --yes 설치에는 필수입니다. 유효 ID는 --list-tools로 확인하세요
--list-tools	지원되는 모든 도구/IDE ID와 대상 디렉터리를 출력하고 종료합니다
--action <type>	install, update, quick-update. 기본값은 기존 설치 상태에 따라 달라집니다
--custom-source <urls>	Git URL 또는 로컬 경로에서 커스텀 모듈을 설치합니다
--channel <stable|next>	모든 외부 모듈에 적용합니다(--all-stable / --all-next 별칭)
--all-stable	--channel=stable 별칭
--all-next	--channel=next 별칭
--next=<code>	한 모듈을 next 채널에 둡니다. 반복 가능합니다
--pin <code>=<tag>	한 모듈을 특정 태그에 고정합니다. 반복 가능합니다
--set <module>.<key>=<value>	모듈 설정 옵션을 비대화형으로 설정합니다(권장, 모듈 설정 오버라이드 참고). 반복 가능합니다
--list-options [module]	내장 및 로컬 캐시된 공식 모듈의 모든 --set 키를 출력하고 종료합니다. 모듈 코드를 전달하면 범위를 좁힙니다
--user-name, --communication-language, --document-output-language, --output-folder	--set core.<key>=<value>와 동등한 레거시 단축 플래그입니다(계속 지원)

플래그가 겹칠 때 우선순위는 --pin > --next= > --channel / --all-* > 레지스트리 기본값(stable)입니다.

:::note[해결 예시] --all-next --pin cis=v0.2.0은 bmb, gds, tea를 next에 두고 cis를 v0.2.0에 고정합니다. :::

레시피

기본 설치 - 모든 것을 최신 안정 버전으로:

npx bmad-method install --yes --modules bmm,bmb,cis --tools claude-code

엔터프라이즈 고정 - 바이트 단위로 재현 가능:

npx bmad-method install --yes \
  --modules bmm,bmb,cis \
  --pin bmb=v1.7.0 --pin cis=v0.2.0 \
  --tools claude-code

최신 개발판 - 외부 모듈을 main 브랜치 최신 커밋으로:

npx bmad-method install --yes --modules bmm,bmb --all-next --tools claude-code

기존 설치에 모듈 추가(나머지는 유지):

npx bmad-method install --yes --action update \
  --modules bmm,bmb,gds

--tools는 의도적으로 생략했습니다. --action update는 최초 설치 때 설정한 도구를 재사용합니다.

채널 혼합 - bmb는 next, gds는 stable:

npx bmad-method install --yes --action update \
  --modules bmm,bmb,cis,gds \
  --next=bmb

모듈 설정 오버라이드

--set <module>.<key>=<value>는 모듈 설정 옵션을 비대화형으로 설정합니다. 반복 가능하고 앞으로 추가될 모듈에도 같은 방식으로 적용됩니다. 이 플래그는 설치 후 패치로 적용됩니다. 설치 프로그램이 정상 흐름을 먼저 실행한 뒤 --set이 각 값을 _bmad/config.toml(팀 범위) 또는 _bmad/config.user.toml(사용자 범위), 그리고 _bmad/<module>/config.yaml에 갱신 또는 삽입하여 선언된 값이 다음 설치로 이어지게 합니다.

예시 - 명시적 프로젝트 지식과 스킬 수준으로 bmm 설치:

npx bmad-method install --yes \
  --modules bmm \
  --tools claude-code \
  --set bmm.project_knowledge=research \
  --set bmm.user_skill_level=expert

모듈에서 사용할 수 있는 키 찾기:

npx bmad-method install --list-options bmm

--list-options(인자 없음)는 설치 프로그램이 로컬에서 찾을 수 있는 모든 키를 나열합니다. 내장 모듈(core, bmm)과 현재 캐시된 공식 모듈이 포함됩니다. 캐시는 머신별이고 지워질 수 있으므로, 이전에 설치한 공식 모듈도 새 체크아웃이나 임시 CI 작업자에서는 다시 설치되기 전까지 나타나지 않습니다. 커뮤니티 및 커스텀 모듈은 여기서 열거되지 않습니다. 모듈의 module.yaml을 직접 읽어 선언된 키를 확인하세요.

작동 방식:

• 경로 선택. 패치 단계는 먼저 config.user.toml에서 [modules.<module>] <key>(또는 [core] <key>)를 찾고, 있으면 그 파일을 업데이트합니다. 그렇지 않으면 팀 범위 config.toml에 씁니다. 그래서 core.user_name, bmm.user_skill_level 같은 사용자 범위 키는 config.user.toml에, 팀 범위 키는 config.toml에 들어갑니다.
• 그대로 쓰는 값. 값은 제공한 그대로 기록됩니다. result: 템플릿 렌더링은 없습니다. 렌더링된 형태(예: {project-root}/research)를 원하면 명시적으로 전달하세요: --set bmm.project_knowledge='{project-root}/research'.
• 다음 설치로 이어지는 선언된 키. module.yaml에 선언된 키 값은 _bmad/<module>/config.yaml에도 쓰이므로 다음 설치 때 프롬프트 기본값으로 살아남습니다.
• 다음 설치로 이어지지 않는 미선언 키. 모듈 스키마가 선언하지 않은 키 값은 현재 설치의 config.toml에 들어가지만 다음 설치 때 다시 생성되지 않습니다(매니페스트 작성기의 엄격한 스키마 분리 단계가 알 수 없는 키를 떨어뜨립니다). 계속 유지해야 한다면 --set을 다시 전달하거나 _bmad/config.toml을 직접 수정하세요.
• 검증 없음. single-select 값은 허용 선택지와 대조하지 않고, 알 수 없는 키도 거부하지 않습니다. 지정한 값이 그대로 쓰입니다.
• --modules에 없는 모듈. 포함하지 않은 모듈에 값을 설정하면 경고를 출력하고 값은 버려집니다(설치되지 않은 모듈용 파일은 생성되지 않습니다).

레거시 core 단축 플래그(--user-name, --output-folder 등)은 하위 호환성을 위해 계속 동작하고 문서화되어 있지만, --set core.user_name=...과 동등합니다.

:::note[quick-update와 함께 동작] --set은 설치 후 패치이므로 작업 유형과 관계없이 동일하게 적용됩니다. bmad install --action quick-update 또는 기존 설치에서 --yes(기본이 quick-update)로 실행해도 일반 설치처럼 마지막에 중앙 설정 파일을 패치합니다. :::

:::caution[공유 IP의 요청 제한] 익명 GitHub API 호출은 IP당 시간당 60회로 제한됩니다. 한 번의 설치는 안정 태그를 확인하기 위해 외부 모듈마다 API를 한 번 호출합니다. NAT 뒤의 사무실, CI 러너 풀, VPN은 함께 이 한도를 소진할 수 있습니다.

환경 변수에 GITHUB_TOKEN=<personal access token>을 설정하면 계정당 시간당 5000회로 한도가 올라갑니다. 공개 저장소 읽기용 개인 액세스 토큰(PAT)이면 충분하며 범위는 필요 없습니다. :::

설치된 내용

설치 후 _bmad/_config/manifest.yaml은 디스크에 있는 내용을 정확히 기록합니다.

modules:
  - name: bmb
    version: v1.7.0 # 태그 또는 next용 "main"
    channel: stable # stable | next | pinned
    sha: 86033fc9aeae2ca6d52c7cdb675c1f4bf17fc1c1
    source: external
    repoUrl: https://github.com/bmad-code-org/bmad-builder

sha 필드는 git 기반 모듈(외부, 커뮤니티, URL 기반 커스텀)에 기록됩니다. 번들 모듈(core, bmm)과 로컬 경로 커스텀 모듈에는 없습니다. 그 코드는 복제 가능한 참조가 아니라 설치 프로그램 바이너리 또는 파일시스템 상태에 따라 달라집니다.

머신 간 재현성을 위해 같은 --modules 명령을 다시 실행하는 것에 의존하지 마세요. 안정 채널 설치는 설치 시점의 가장 높은 릴리스 태그로 해석되므로 나중에 다시 실행하면 그 사이 릴리스된 버전으로 설치됩니다. manifest.yaml의 기록된 태그를 대상 머신에서 명시적 --pin 플래그로 바꾸세요. 예:

npx bmad-method install --yes --modules bmb,cis \
  --pin bmb=v1.7.0 --pin cis=v0.4.2 --tools claude-code

문제 해결

"Could not resolve stable tag" 또는 "API rate limit exceeded"

GitHub의 익명 시간당 60회 한도에 도달했습니다. GITHUB_TOKEN을 설정하고 다시 시도하세요. 이미 토큰이 있다면 만료되었거나 해당 토큰 자체의 한도에 걸렸을 수 있습니다. 다른 토큰을 시도하거나 시간당 한도가 초기화될 때까지 기다리세요.

"Tag 'vX.Y.Z' not found"

--pin에 전달한 태그가 모듈 저장소에 없습니다. GitHub의 저장소 릴리스 페이지에서 유효한 태그를 확인하세요.

고정 설치가 계속 업그레이드됨

고정 설치는 업그레이드되지 않습니다. Quick Update는 안정 채널의 패치와 마이너만 적용하며 pinned나 next는 건드리지 않습니다. 고정 설치가 바뀌었다면 _bmad/_config/manifest.yaml을 여세요. 명시적으로 플래그로 오버라이드하지 않는 한 channel: pinned와 고정된 version, sha가 실행 간 유지되어야 합니다.

--pin bmm=X가 아무 것도 하지 않음

bmm은 번들 모듈입니다. --pin과 --next=가 적용되지 않습니다. 사전 릴리스 core/bmm을 원하면 npx bmad-method@next install을 사용하거나 bmad-bmm 저장소를 체크아웃하고 설치 프로그램을 로컬에서 실행해 아직 릴리스되지 않은 변경을 받으세요.