bmad-setup 1.4.0 → 1.5.1

package/README.md

@@ -1,90 +1,119 @@
 # BMAD Framework Submodule
 
-![Version](https://img.shields.io/badge/version-1.3.1-blue.svg)
+![Version](https://img.shields.io/badge/version-1.5.0-blue.svg)
+![npm](https://img.shields.io/npm/v/bmad-setup.svg)
 ![BMAD](https://img.shields.io/badge/BMAD-6.0.0--beta.8-orange.svg)
 ![License](https://img.shields.io/badge/license-MIT-green.svg)
-![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-purple.svg)
+![Claude Code](https://img.shields.io/badge/Claude%20Code-only-purple.svg)
 
-BMAD-METHOD - 범용 AI 에이전트 프레임워크
+BMAD 프레임워크를 Git Submodule로 관리하여 **팀별, 프로젝트별로 간편하게 커스터마이징**할 수 있는 세팅 도구입니다.
 
-소프트웨어 개발 전체 라이프사이클을 위한 프롬프트 & 컨텍스트 엔지니어링 프레임워크입니다. 전문화된 에이전트(Analyst, PM, Architect, Dev, Test Architect)와 워크플로우, 지식 베이스를 제공합니다.
+한 줄 설치(`npx bmad-setup`)로 에이전트, 워크플로우, 지식 베이스를 프로젝트에 즉시 적용하고, 필요한 모듈만 골라 사용할 수 있습니다.
 
-| 항목               | 버전              |
-| ------------------ | ----------------- |
-| Submodule Version  | v1.3.1            |
-| BMAD Framework     | 6.0.0-beta.8      |
+> **Claude Code 전용** — 슬래시 커맨드 및 에이전트 시스템이 Claude Code의 커맨드 구조에 맞춰 설계되어 있습니다.
 
-> [Changelog](./CHANGELOG.md) 에서 변경 이력을 확인하세요.
+| 항목              | 버전         |
+| ----------------- | ------------ |
+| Submodule Version | v1.5.0       |
+| BMAD Framework    | 6.0.0-beta.8 |
+
+> [Changelog](./CHANGELOG.md)에서 변경 이력을 확인하세요.
 
 ---
 
-## Git Submodule이란?
+## BMAD Method란?
 
-Git을 처음 접하시거나 Submodule이 생소하신 분들을 위한 설명입니다.
+**BMAD(Breakthrough Method of Agile AI-Driven Development)** 는 AI 기반 소프트웨어 개발을 위한 오픈소스 프레임워크입니다.
 
-### 기본 개념
+아이디어 기획부터 구현까지 전체 개발 과정을 **전문화된 AI 에이전트**와 **가이드 워크플로우**로 지원하며, 프로젝트 복잡도에 맞춘 적응형 접근 방식을 제공합니다.
 
-**Submodule**은 하나의 Git 저장소 안에 다른 Git 저장소를 포함시키는 기능입니다.
+- **전문 에이전트** — Analyst, PM, Architect, Dev, Test Architect 등 역할별 AI 에이전트
+- **가이드 워크플로우** — 단계별 개발 프로세스로 일관된 품질 확보
+- **적응형 계획** — 버그 수정부터 엔터프라이즈 플랫폼까지 프로젝트 규모에 맞게 동적 조정
 
-일반적인 폴더와 달리:
+> 공식 문서: [https://docs.bmad-method.org](https://docs.bmad-method.org/)
 
-- 실제 파일 전체가 아닌 **참조(포인터)**만 저장됩니다
-- `.gitmodules` 파일에 원격 저장소 URL이 기록됩니다
-- 특정 커밋(SHA)을 가리키므로 버전 고정이 가능합니다
+---
 
-### 비유로 이해하기
+## 왜 이 서브모듈을 사용하나요?
 
-**일반 폴더 복사** = 책 전체를 복사해서 가져옴
-**Submodule** = 도서관 책의 위치(서가 번호)만 메모해둠
+BMAD 프레임워크 원본은 범용으로 설계되어 있습니다. 이 서브모듈은 그것을 **우리 팀의 실정에 맞게 가져다 쓰는 방법**을 제공합니다.
 
-따라서:
+### 팀/프로젝트별 커스터마이징
 
-- 메인 프로젝트는 가볍게 유지됩니다
-- BMAD 업데이트는 원본 저장소에서 한 번만 하면 됩니다
-- 여러 프로젝트에서 동일한 BMAD를 공유할 수 있습니다
+- **모듈 선택** — 필요한 모듈(소프트웨어 개발, 테스트, 데이터 분석 등)만 골라 사용
+- **에이전트 커스텀** — 팀 컨벤션, 기술 스택, 도메인 용어를 에이전트에 반영
+- **워크플로우 조정** — 팀의 개발 프로세스에 맞게 워크플로우를 추가/수정
+- **메모리 템플릿** — 프로젝트별 컨텍스트(서비스 정보, 퍼널, 지표 등)를 사전 설정
 
----
+### Submodule 방식의 이점
 
-## 왜 Submodule을 사용하나요?
+| 구분      | 직접 복사                 | Submodule 사용            |
+| --------- | ------------------------- | ------------------------- |
+| PR 크기   | 300개 이상 파일 변경      | 2개 파일만 변경           |
+| 업데이트  | 각 프로젝트마다 수동 복사 | `git pull` 한 번으로 해결 |
+| 버전 관리 | 어떤 버전인지 추적 어려움 | 커밋 SHA로 정확한 버전 추적 |
+| 설치      | 수동 복사                 | `npx bmad-setup` 한 줄    |
 
-### 장점
+프레임워크 원본이 업데이트되더라도, 커스터마이징한 설정은 프로젝트에 그대로 유지됩니다.
 
-| 구분        | 직접 복사                   | Submodule 사용              |
-| ----------- | --------------------------- | --------------------------- |
-| PR 크기     | 300개 이상 파일 변경        | 2개 파일만 변경             |
-| 업데이트    | 각 프로젝트마다 수동 복사   | `git pull` 한 번으로 해결   |
-| 버전 관리   | 어떤 버전인지 추적 어려움   | 커밋 SHA로 정확한 버전 추적 |
-| 디스크 용량 | 프로젝트마다 전체 파일 중복 | 참조만 저장                 |
-| 설치 자동화 | 불가능                      | `npm install`로 자동 초기화 |
+---
 
-### 단점 및 주의사항
+## 제공 모듈
 
-- 초기 학습 곡선이 있습니다
-- `git clone` 시 `--recurse-submodules` 옵션을 잊으면 빈 폴더가 됩니다
-- Submodule 내부 변경사항은 별도로 커밋/푸시해야 합니다
+| 모듈   | 설명                     | 주요 에이전트/워크플로우                  |
+| ------ | ------------------------ | ---------------------------------------- |
+| `core` | 핵심 기능                | bmad-master, brainstorming, party-mode   |
+| `bmm`  | 소프트웨어 개발          | analyst, architect, dev, pm, sm, ux      |
+| `bmb`  | 모듈 빌더                | agent-builder, workflow-builder          |
+| `gds`  | 게임 개발                | game-designer, game-dev, game-qa         |
+| `tea`  | 테스트 아키텍처          | test-engineer-architect                  |
+| `cis`  | 크리에이티브 & 혁신 전략 | design-thinking, innovation, storytelling |
+| `dae`  | 데이터 분석 (커스텀)     | data-analyst, Amplitude 연동             |
 
 ---
 
-## 언제 이 프레임워크를 사용하나요?
+## 빠른 시작
+
+### 설치
+
+```bash
+npx bmad-setup
+```
+
+자동으로 수행되는 작업:
 
-### 적합한 경우
+1. `bmad-submodule` Git Submodule 추가 및 초기화
+2. `.gitmodules`에 `ignore = dirty` 설정
+3. `install.sh` 실행 (심볼릭 링크 생성)
+4. `.gitignore`에 BMAD 항목 추가
+5. `package.json`에 postinstall / bmad:install / bmad:uninstall 스크립트 추가
 
-- **AI 기반 개발 워크플로우**를 구축하려는 팀
-- **Claude Code** 또는 **Cursor** 등 AI 도구를 활용하는 프로젝트
-- 여러 프로젝트에서 **일관된 AI 프롬프트/에이전트**를 사용하고 싶을 때
-- **소프트웨어 개발 전체 과정**(기획 → 설계 → 개발 → 테스트)에 AI를 적용하려는 경우
+> 이미 설치된 항목은 자동으로 스킵됩니다 (멱등성 보장).
+
+### 업데이트
+
+```bash
+npx bmad-setup --update
+```
 
-### 제공하는 모듈
+Submodule을 최신 버전으로 pull하고 심볼릭 링크를 갱신합니다.
 
-| 모듈   | 설명                      | 주요 에이전트/워크플로우                    |
-| ------ | ------------------------- | ------------------------------------------- |
-| `core` | 핵심 기능                 | bmad-master, brainstorming, party-mode      |
-| `bmm`  | 소프트웨어 개발           | analyst, architect, dev, pm, sm, ux         |
-| `bmb`  | 모듈 빌더                 | agent-builder, workflow-builder             |
-| `gds`  | 게임 개발 (구 bmgd)       | game-designer, game-dev, game-qa            |
-| `tea`  | 테스트 아키텍처           | test-engineer-architect                     |
-| `cis`  | 크리에이티브 & 혁신 전략  | design-thinking, innovation, storytelling   |
-| `dae`  | 데이터 분석 (커스텀)      | data-analyst, Amplitude 연동                |
+### 동작 확인
+
+```bash
+claude
+```
+
+Claude Code 실행 후 `/bmad-`를 입력하면 사용 가능한 커맨드 목록이 자동완성됩니다.
+
+```bash
+# 예시: 에이전트 실행
+/bmad-agent-bmm-dev            # 개발자 에이전트
+/bmad-agent-bmm-architect      # 아키텍트 에이전트
+/bmad-agent-bmad-master        # 마스터 에이전트
+/bmad-agent-dae-data-analyst   # 데이터 분석가
+```
 
 ---
 
@@ -94,7 +123,7 @@ Git을 처음 접하시거나 Submodule이 생소하신 분들을 위한 설명
 bmad-submodule/
 ├── .claude/
 │   └── commands/
-│       ├── bmad-agent-*.md     # 에이전트 슬래시 커맨드 (플랫 구조)
+│       ├── bmad-agent-*.md     # 에이전트 슬래시 커맨드
 │       ├── bmad-bmm-*.md       # BMM 워크플로우 커맨드
 │       ├── bmad-bmb-*.md       # BMB 빌더 커맨드
 │       ├── bmad-gds-*.md       # GDS 게임 개발 커맨드
@@ -119,61 +148,32 @@ bmad-submodule/
 
 ---
 
-## 설치 가이드
+## 수동 설치
 
-### 빠른 설치 (권장)
+`npx bmad-setup` 대신 직접 설치하려면 아래 단계를 따르세요.
 
-프로젝트 루트 디렉토리에서 한 줄로 설치:
+### 1단계: Submodule 추가
 
 ```bash
-npx bmad-setup
-```
-
-이 명령어는 다음을 자동으로 수행합니다:
-
-1. `bmad-submodule` Git Submodule 추가 및 초기화
-2. `.gitmodules`에 `ignore = dirty` 설정
-3. `install.sh` 실행 (심볼릭 링크 생성)
-4. `.gitignore`에 BMAD 항목 추가
-5. `package.json`에 postinstall / bmad:install / bmad:uninstall 스크립트 추가
-
-> 이미 설치된 항목은 자동으로 스킵됩니다 (멱등성 보장).
-
----
-
-### 수동 설치
-
-아래는 수동으로 단계별 설치하는 방법입니다.
-
-#### 1단계: Submodule 추가
-
-프로젝트 루트 디렉토리에서 실행:
-
-```bash
-# Submodule 추가
 git submodule add https://github.com/OhSeungWan/bmad-submodule.git bmad-submodule
-
-# Submodule 초기화 및 파일 다운로드
 git submodule init
 git submodule update
-
-# dirty 상태 무시 설정 (아래 '설정 파일 설명' 참조)
 git config -f .gitmodules submodule.bmad-submodule.ignore dirty
 ```
 
-#### 2단계: 심볼릭 링크 생성
+### 2단계: 심볼릭 링크 생성
 
 ```bash
 ./bmad-submodule/install.sh
 ```
 
-이 스크립트는 다음 심볼릭 링크를 생성합니다:
+생성되는 링크:
 
-- `프로젝트/.claude/commands/bmad-*.md` → `bmad-submodule/.claude/commands/bmad-*.md`
-- `프로젝트/.claude/commands/commit.md` → `bmad-submodule/.claude/commands/commit.md`
-- `프로젝트/_bmad` → `bmad-submodule/_bmad`
+- `.claude/commands/bmad-*.md` → `bmad-submodule/.claude/commands/bmad-*.md`
+- `.claude/commands/commit.md` → `bmad-submodule/.claude/commands/commit.md`
+- `_bmad` → `bmad-submodule/_bmad`
 
-#### 3단계: package.json 설정 (권장)
+### 3단계: package.json 설정 (권장)
 
 팀원들의 자동 설치를 위해 추가:
 
@@ -187,27 +187,13 @@ git config -f .gitmodules submodule.bmad-submodule.ignore dirty
 }
 ```
 
-**각 스크립트 설명:**
-
 | 스크립트         | 실행 시점        | 동작                                  |
 | ---------------- | ---------------- | ------------------------------------- |
 | `postinstall`    | `npm install` 후 | Submodule 초기화 + 최신화 + 링크 생성 |
 | `bmad:install`   | 수동 실행        | 심볼릭 링크만 생성                    |
 | `bmad:uninstall` | 수동 실행        | 심볼릭 링크 제거                      |
 
-**postinstall 명령어 분석:**
-
-```bash
-[ -z "$CI" ]                              # CI 환경이 아닐 때만 실행
-&& git submodule update --init --recursive # Submodule 초기화 및 업데이트
-&& git -C bmad-submodule pull origin master # 최신 버전으로 업데이트
-&& ./bmad-submodule/install.sh            # 심볼릭 링크 생성
-|| true                                   # 실패해도 npm install은 계속 진행
-```
-
-#### 4단계: .gitignore 추가
-
-루트 프로젝트의 `.gitignore`에 추가:
+### 4단계: .gitignore 추가
 
 ```
 # BMAD 심볼릭 링크 (실제 파일은 submodule에 있음)
@@ -217,52 +203,9 @@ _bmad
 
 ---
 
-## 설정 파일 상세 설명
-
-### .gitmodules
-
-Submodule 정보가 저장되는 파일입니다. `git submodule add` 실행 시 자동 생성됩니다.
-
-```ini
-[submodule "bmad-submodule"]
-    path = bmad-submodule
-    url = https://github.com/OhSeungWan/bmad-submodule.git
-    ignore = dirty
-```
-
-| 항목     | 설명                                          |
-| -------- | --------------------------------------------- |
-| `path`   | Submodule이 위치할 로컬 경로                  |
-| `url`    | Submodule의 원격 저장소 URL                   |
-| `ignore` | `dirty` = 내부 변경사항을 git status에서 무시 |
-
-### ignore = dirty 설정
-
-**왜 필요한가요?**
-
-VSCode 등 에디터가 파일을 열면 자동으로:
-
-- 줄 끝 공백 제거
-- 파일 끝 빈 줄 추가
-- 탭→스페이스 변환
-
-이런 자동 변경으로 인해 `git status`에서 `bmad-submodule (modified content)`가 표시됩니다.
-
-**해결 방법:**
-
-```bash
-# dirty 상태 무시 설정
-git config -f .gitmodules submodule.bmad-submodule.ignore dirty
-
-# 이미 발생한 변경사항 되돌리기
-git submodule foreach --recursive git checkout .
-```
-
----
-
-## Submodule과 함께 Clone
+## 팀원 온보딩
 
-### 새 팀원이 프로젝트를 받을 때
+새 팀원이 프로젝트를 받을 때:
 
 ```bash
 # 방법 1: 한 번에 (권장)
@@ -274,167 +217,16 @@ cd <your-repo>
 git submodule update --init --recursive
 ```
 
-**주의:** `--recurse-submodules` 없이 clone하면 `bmad-submodule` 폴더가 비어있습니다!
-
----
-
-## Submodule 업데이트
-
-BMAD에 새 기능이 추가되었을 때:
-
-```bash
-# 1. Submodule 디렉토리로 이동
-cd bmad-submodule
-
-# 2. 최신 버전 가져오기
-git pull origin master
-
-# 3. 심볼릭 링크 재생성 (새 파일이 추가된 경우)
-./install.sh
+> `--recurse-submodules` 없이 clone하면 `bmad-submodule` 폴더가 비어있습니다.
 
-# 4. 루트로 돌아가서 변경사항 커밋
-cd ..
-git add bmad-submodule
-git commit -m "chore: update bmad-submodule"
-git push
-```
-
----
-
-## 스크립트 상세 설명
-
-### install.sh
-
-```bash
-./bmad-submodule/install.sh
-```
-
-**동작:**
-
-1. 기존 심볼릭 링크/폴더가 있으면 삭제
-2. 루트 프로젝트에 `.claude/commands` 디렉토리 생성
-3. 심볼릭 링크 생성:
-   - `.claude/commands/bmad` → submodule의 `.claude/commands/bmad`
-   - `_bmad` → submodule의 `_bmad`
-
-**언제 실행하나요?**
-
-- 최초 설치 시
-- Submodule 업데이트 후 (새 파일이 추가된 경우)
-- 심볼릭 링크가 깨진 경우
-
-### uninstall.sh
-
-```bash
-./bmad-submodule/uninstall.sh
-```
-
-**동작:**
-
-1. 심볼릭 링크인 경우: 바로 삭제
-2. 일반 디렉토리인 경우: 확인 후 삭제
-
-**언제 실행하나요?**
-
-- BMAD 사용을 중단할 때
-- 심볼릭 링크 대신 직접 파일을 관리하고 싶을 때
-
----
-
-## 동작 확인
-
-설치가 완료되면 BMAD 에이전트가 정상적으로 작동하는지 확인합니다.
-
-### 1. Claude Code 실행
-
-프로젝트 루트 디렉토리에서 Claude Code를 실행합니다:
-
-```bash
-claude
-```
-
-### 2. 슬래시 커맨드 확인
-
-Claude Code 내에서 `/bmad-`를 입력하면 사용 가능한 커맨드 목록이 자동완성됩니다.
-
-### 3. 에이전트 실행 테스트
-
-예시로 Data Analyst 에이전트를 실행해봅니다:
-
-```
-/bmad-agent-dae-data-analyst
-```
-
-**정상 실행 시 출력 예시:**
-
-```
-안녕하세요, 렌트리 개발팀님! 📊
-
-저는 재만이에요 - 여러분의 데이터 분석 파트너입니다.
-
-----
-현재 서비스 컨텍스트
-
-아직 서비스 정보가 설정되지 않았어요. [SC] 서비스 컨텍스트 설정을 통해
-렌트리 서비스의 퍼널과 핵심 지표를 학습하면 더 정확한 분석을 도와드릴 수 있어요!
-
-----
-메뉴
-
-| #   | 명령어 | 설명                                   |
-| --- | ------ | -------------------------------------- |
-| 1   | [MH]   | 메뉴 도움말 다시 표시                  |
-| 2   | [CH]   | 에이전트와 자유롭게 대화하기           |
-| 3   | [QA]   | 빠른 데이터 분석 - 질문에 답하기       |
-| 4   | [FA]   | 퍼널 분석 - 전환율, 병목, 이탈 분석    |
-| 5   | [ED]   | 실험 설계 - A/B 테스트 계획 수립       |
-| 6   | [ER]   | 실험 결과 분석 - 테스트 결과 해석      |
-| 7   | [IA]   | 영향도 분석 - 기능 변경 영향 예측      |
-| 8   | [RM]   | 위험 모니터링 - 이상 징후 감지         |
-| 9   | [SC]   | 서비스 컨텍스트 설정 - 퍼널, 지표 학습 |
-| 10  | [GR]   | 리포트 생성 - 분석 결과 문서화         |
-| 11  | [DA]   | 에이전트 종료                          |
-
-----
-번호나 명령어를 입력해주세요. 무엇을 도와드릴까요?
-```
-
-위와 같이 에이전트 메뉴가 표시되면 설치가 정상적으로 완료된 것입니다.
-
-### 4. 다른 에이전트/워크플로우 테스트
-
-모듈별로 다양한 에이전트와 워크플로우를 테스트해볼 수 있습니다:
-
-```bash
-# BMM (소프트웨어 개발)
-/bmad-agent-bmm-dev            # 개발자 에이전트
-/bmad-agent-bmm-architect      # 아키텍트 에이전트
-
-# Core (핵심)
-/bmad-agent-bmad-master        # 마스터 에이전트
-/bmad-brainstorming            # 브레인스토밍
-
-# DAE (데이터 분석)
-/bmad-agent-dae-data-analyst   # 데이터 분석가
-/bmad-dae-data-analysis        # 데이터 분석 워크플로우
-```
-
-### 5. 설치 실패 시 체크리스트
-
-에이전트가 실행되지 않으면 다음을 확인하세요:
-
-| 확인 항목                   | 명령어                         |
-| --------------------------- | ------------------------------ |
-| Submodule이 초기화되었는가? | `ls bmad-submodule/`           |
-| 심볼릭 링크가 생성되었는가? | `ls -la .claude/commands/bmad` |
-| _bmad 링크가 생성되었는가?  | `ls -la _bmad`                 |
-| install.sh를 실행했는가?    | `./bmad-submodule/install.sh`  |
+`package.json`에 postinstall이 설정되어 있다면, `npm install`만으로 자동 초기화됩니다.
 
 ---
 
 ## 문제 해결
 
-### "bmad-submodule 폴더가 비어있어요"
+<details>
+<summary><b>bmad-submodule 폴더가 비어있어요</b></summary>
 
 Submodule이 초기화되지 않은 상태입니다.
 
@@ -442,41 +234,44 @@ Submodule이 초기화되지 않은 상태입니다.
 git submodule update --init --recursive
 ```
 
-### "git status에서 bmad-submodule (modified content)가 보여요"
+</details>
+
+<details>
+<summary><b>git status에서 bmad-submodule (modified content)가 보여요</b></summary>
 
-에디터 자동 포맷팅 때문입니다.
+에디터 자동 포맷팅(줄 끝 공백 제거, 탭→스페이스 등) 때문입니다.
 
 ```bash
-# 설정으로 방지
 git config -f .gitmodules submodule.bmad-submodule.ignore dirty
-
-# 현재 변경사항 되돌리기
 git submodule foreach --recursive git checkout .
 ```
 
-### "심볼릭 링크가 작동하지 않아요"
+</details>
+
+<details>
+<summary><b>심볼릭 링크가 작동하지 않아요</b></summary>
 
 Windows에서는 관리자 권한이 필요할 수 있습니다.
 
 ```bash
-# 심볼릭 링크 재생성
 ./bmad-submodule/install.sh
-
-# 링크 확인
 ls -la .claude/commands/bmad
 ls -la _bmad
 ```
 
-### Submodule 완전 재설치
+</details>
+
+<details>
+<summary><b>완전 재설치</b></summary>
 
 문제가 지속되면 깨끗하게 다시 시작:
 
 ```bash
-# 1. 변경사항 리셋
+# 1. 리셋
 git reset HEAD -- .gitmodules bmad-submodule 2>/dev/null || true
 git checkout HEAD -- .gitmodules 2>/dev/null || true
 
-# 2. Submodule 완전 제거
+# 2. 제거
 git submodule deinit -f bmad-submodule 2>/dev/null || true
 git rm -f bmad-submodule 2>/dev/null || true
 rm -rf bmad-submodule
@@ -489,29 +284,24 @@ git add .gitmodules
 # 4. 다시 추가
 git submodule add https://github.com/OhSeungWan/bmad-submodule.git bmad-submodule
 git config -f .gitmodules submodule.bmad-submodule.ignore dirty
-
-# 5. 확인
-ls -la bmad-submodule/
-git submodule status
 ```
 
-gitignore 에서 관련 폴더 제거 (특정 클로드 버전에서 gitignore 에 추가된 파일을 클로드가 인식 못할 수도 있음)
+> .gitignore에서 관련 폴더를 제거했는지도 확인하세요. 특정 Claude 버전에서 .gitignore에 추가된 파일을 인식하지 못할 수 있습니다.
 
----
-
-## 자주 묻는 질문
+</details>
 
-### Q: Submodule 내부에서 직접 수정해도 되나요?
-
-A: 가능하지만 권장하지 않습니다. 수정사항은 bmad-submodule 저장소에 별도로 커밋/푸시해야 합니다. 팀 프로젝트라면 원본 저장소에 PR을 보내세요.
+---
 
-### Q: 특정 버전의 BMAD를 고정하고 싶어요
+## FAQ
 
-A: Submodule은 특정 커밋을 가리키므로 기본적으로 버전이 고정됩니다. `git pull`을 하지 않으면 해당 버전이 유지됩니다.
+**Q: Submodule 내부에서 직접 수정해도 되나요?**
+가능하지만 권장하지 않습니다. 수정사항은 bmad-submodule 저장소에 별도로 커밋/푸시해야 합니다. 팀 프로젝트라면 원본 저장소에 PR을 보내세요.
 
-### Q: CI/CD에서는 어떻게 하나요?
+**Q: 특정 버전의 BMAD를 고정하고 싶어요**
+Submodule은 특정 커밋을 가리키므로 기본적으로 버전이 고정됩니다. `git pull`을 하지 않으면 해당 버전이 유지됩니다.
 
-A: postinstall 스크립트에 `[ -z "$CI" ]` 조건이 있어 CI 환경에서는 스킵됩니다. CI에서 BMAD가 필요하다면 이 조건을 제거하세요.
+**Q: CI/CD에서는 어떻게 하나요?**
+postinstall 스크립트에 `[ -z "$CI" ]` 조건이 있어 CI 환경에서는 스킵됩니다. CI에서 BMAD가 필요하다면 이 조건을 제거하세요.
 
 ---
 

package/bin/cli.js

@@ -10,8 +10,11 @@ const VERSION = require('../package.json').version;
 const REPO_URL = 'https://github.com/OhSeungWan/bmad-submodule.git';
 const SUBMODULE_DIR = 'bmad-submodule';
 
+const args = process.argv.slice(2);
+const isUpdate = args.includes('--update') || args.includes('-u');
+
 const log = (icon, msg) => console.log(`${icon} ${msg}`);
-const logStep = (n, msg) => log(`[${n}/6]`, msg);
+const logStep = (n, total, msg) => log(`[${n}/${total}]`, msg);
 
 function run(cmd, opts = {}) {
   return execSync(cmd, { stdio: 'inherit', ...opts });
@@ -31,7 +34,6 @@ function runSafe(cmd, stepName) {
 
 // --- --help / --version ---
 function handleFlags() {
-  const args = process.argv.slice(2);
   if (args.includes('--version') || args.includes('-v')) {
     console.log(VERSION);
     process.exit(0);
@@ -43,17 +45,23 @@ bmad-setup v${VERSION}
 BMAD Framework 서브모듈을 한 줄로 설치합니다.
 
 Usage:
-  npx bmad-setup          전체 설치 실행
-  npx bmad-setup --help   도움말 표시
-  npx bmad-setup --version 버전 표시
+  npx bmad-setup            전체 설치 실행
+  npx bmad-setup --update   서브모듈 최신화 + 심링크 재생성
+  npx bmad-setup --help     도움말 표시
+  npx bmad-setup --version  버전 표시
 
-Steps:
+Install steps:
   1. git submodule add (bmad-submodule)
   2. git submodule init & update
   3. .gitmodules ignore=dirty 설정
   4. install.sh 실행 (심볼릭 링크)
   5. .gitignore 패치
   6. package.json 스크립트 패치
+
+Update steps (--update):
+  1. git submodule update --init --recursive
+  2. git -C bmad-submodule pull origin master
+  3. install.sh 재실행 (심링크 갱신)
 `);
     process.exit(0);
   }
@@ -79,9 +87,40 @@ function validateGitRepo() {
   }
 }
 
+// --- Update mode ---
+function updateSubmodule() {
+  logStep(1, 3, 'Submodule 동기화');
+  if (!fs.existsSync(SUBMODULE_DIR)) {
+    log('  \u274c', `${SUBMODULE_DIR}/ 디렉토리가 없습니다. 먼저 \`npx bmad-setup\`으로 설치하세요.`);
+    process.exit(1);
+  }
+  runSafe('git submodule update --init --recursive', 'Submodule 동기화');
+  log('  \u2714', 'Submodule 동기화 완료');
+  return 'done';
+}
+
+function pullLatest() {
+  logStep(2, 3, 'Submodule 최신화 (pull origin master)');
+  runSafe(`git -C ${SUBMODULE_DIR} pull origin master`, 'Submodule pull');
+  log('  \u2714', '최신 버전으로 업데이트 완료');
+  return 'done';
+}
+
+function reinstallSymlinks() {
+  logStep(3, 3, 'install.sh 재실행 (심링크 갱신)');
+  const scriptPath = `./${SUBMODULE_DIR}/install.sh`;
+  if (!fs.existsSync(scriptPath)) {
+    log('  \u26a0', `${scriptPath} 파일을 찾을 수 없습니다. 스킵합니다.`);
+    return 'skipped';
+  }
+  runSafe(`bash ${scriptPath}`, 'install.sh 실행');
+  log('  \u2714', '심링크 갱신 완료');
+  return 'done';
+}
+
 // --- Step 1: Submodule 추가 ---
 function addSubmodule() {
-  logStep(1, 'Submodule 추가');
+  logStep(1, 6, 'Submodule 추가');
   if (fs.existsSync(SUBMODULE_DIR)) {
     log('  \u2714', `${SUBMODULE_DIR}/ 이미 존재합니다. 스킵합니다.`);
     return 'skipped';
@@ -93,7 +132,7 @@ function addSubmodule() {
 
 // --- Step 2: Submodule 초기화 ---
 function initSubmodule() {
-  logStep(2, 'Submodule 초기화');
+  logStep(2, 6, 'Submodule 초기화');
   runSafe('git submodule init && git submodule update', 'Submodule 초기화');
   log('  \u2714', '초기화 완료');
   return 'done';
@@ -101,7 +140,7 @@ function initSubmodule() {
 
 // --- Step 3: dirty ignore 설정 ---
 function configureDirtyIgnore() {
-  logStep(3, 'dirty ignore 설정');
+  logStep(3, 6, 'dirty ignore 설정');
   runSafe(
     `git config -f .gitmodules submodule.${SUBMODULE_DIR}.ignore dirty`,
     'dirty ignore 설정',
@@ -112,7 +151,7 @@ function configureDirtyIgnore() {
 
 // --- Step 4: install.sh 실행 ---
 function runInstallScript() {
-  logStep(4, 'install.sh 실행 (심볼릭 링크 생성)');
+  logStep(4, 6, 'install.sh 실행 (심볼릭 링크 생성)');
   const scriptPath = `./${SUBMODULE_DIR}/install.sh`;
   if (!fs.existsSync(scriptPath)) {
     log('  \u26a0', `${scriptPath} 파일을 찾을 수 없습니다. 스킵합니다.`);
@@ -125,7 +164,7 @@ function runInstallScript() {
 
 // --- Step 5: .gitignore 패치 ---
 function patchGitignore() {
-  logStep(5, '.gitignore 패치');
+  logStep(5, 6, '.gitignore 패치');
 
   const MARKER_START = '# BMAD symlinks (auto-generated)';
   const MARKER_END = '# End BMAD';
@@ -159,7 +198,7 @@ function patchGitignore() {
 
 // --- Step 6: package.json 패치 ---
 function patchPackageJson() {
-  logStep(6, 'package.json 패치');
+  logStep(6, 6, 'package.json 패치');
 
   const pkgPath = 'package.json';
   if (!fs.existsSync(pkgPath)) {
@@ -221,12 +260,26 @@ function patchPackageJson() {
 function main() {
   handleFlags();
 
+  validateGitRepo();
+
+  if (isUpdate) {
+    console.log('');
+    console.log('=== BMAD Submodule Update ===');
+    console.log('');
+
+    const steps = [
+      { key: 'sync', label: 'Submodule 동기화', fn: updateSubmodule },
+      { key: 'pull', label: 'Submodule 최신화', fn: pullLatest },
+      { key: 'reinstall', label: '심링크 갱신', fn: reinstallSymlinks },
+    ];
+
+    return runSteps(steps, 'BMAD 업데이트가 완료되었습니다!');
+  }
+
   console.log('');
   console.log('=== BMAD Submodule Setup ===');
   console.log('');
 
-  validateGitRepo();
-
   const steps = [
     { key: 'submodule', label: 'Submodule 추가', fn: addSubmodule },
     { key: 'init', label: 'Submodule 초기화', fn: initSubmodule },
@@ -236,6 +289,10 @@ function main() {
     { key: 'packageJson', label: 'package.json 패치', fn: patchPackageJson },
   ];
 
+  runSteps(steps, 'BMAD 설치가 완료되었습니다!');
+}
+
+function runSteps(steps, doneMessage) {
   const results = {};
   for (const step of steps) {
     try {
@@ -247,7 +304,7 @@ function main() {
   }
 
   console.log('');
-  console.log('=== Setup Summary ===');
+  console.log('=== Summary ===');
   console.log('');
 
   for (const step of steps) {
@@ -262,7 +319,7 @@ function main() {
     log('\u26a0', '일부 단계가 실패했습니다. 위 로그를 확인하세요.');
     process.exit(1);
   } else {
-    log('\ud83d\ude80', 'BMAD 설치가 완료되었습니다!');
+    log('\ud83d\ude80', doneMessage);
   }
   console.log('');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-setup",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "BMAD Framework submodule installer - one command setup",
   "bin": {
     "bmad-setup": "bin/cli.js"