bmalph 실전 가이드 8편 - 운영, 복구, 반복 실행

요약#

참고 자료#

• bmalph README 원문 - CLI reference와 troubleshooting
• BMAD Method - Workflow Map - planning 산출물 구조

지금 todo-demo는 어디까지 왔을까요?#

8편에서는 status, doctor, check-updates, upgrade, reset을 언제 쓰는지와, implement와 run을 다시 이어 가는 운영 흐름을 정리합니다.
즉 한 번 시작한 bmalph 프로젝트를 끝까지 굴리는 편입니다.

이제부터 중요한 것은 “어떻게 시작할까”보다 “막혔을 때 어떻게 다시 이어 갈까”입니다.
그래서 마지막 편은 운영과 복구에 집중합니다.

status는 언제 봐야 할까요?#

status는 지금 프로젝트가 어디쯤 와 있는지 보여 줍니다.
처음에는 아래 네 타이밍만 기억하면 충분합니다.

• init 직후
• planning 문서를 만든 직후
• implement 직전과 직후
• run 전에 마지막 확인할 때

1
bmalph status
2
bmalph status --json

실제 예제에서도 status --json은 단계 이름과 다음 행동을 보여 줬습니다.
implement 뒤에는 구현 단계로 바뀌고, 다음 행동으로 bmalph run을 안내했습니다.

즉 status는 “지금 어디서 막혔는가”를 보는 명령입니다.

doctor는 무엇을 점검할까요?#

doctor는 설치 구조와 기본 전제 조건을 점검합니다.

1
bmalph doctor
2
bmalph doctor --json

실제 Codex 예제에서는 아래 항목이 통과했습니다.

• Node.js 버전
• bash 사용 가능 여부
• git 저장소와 커밋 존재 여부
• _bmad/, .ralph/, bmalph/ 구조
• 도구별 스킬 또는 명령 파일 존재 여부

중요한 점은 여기서 끝이 아니라는 것입니다.
실제 검증에서는 doctor --json이 통과했지만, run에서는 macOS의 timeout 부재 때문에 루프가 바로 실패했습니다.

즉 doctor는 첫 번째 문턱이지, 마지막 보증은 아닙니다.

check-updates와 upgrade는 언제 쓸까요?#

bmalph는 BMAD와 Ralph를 묶어 배포하기 때문에, 시간이 지나면 묶인 버전이 뒤처질 수 있습니다.
이럴 때는 아래 두 명령이 있습니다.

1
bmalph check-updates
2
bmalph upgrade --dry-run
3
bmalph upgrade

권장 순서는 단순합니다.

1. 먼저 check-updates로 상태를 봅니다
2. upgrade --dry-run으로 바뀔 내용을 미리 봅니다
3. 괜찮으면 upgrade를 실행합니다

이 순서를 지키면 갑자기 문서나 스크립트가 크게 바뀌는 것을 줄일 수 있습니다.

reset은 언제 써야 할까요?#

프로젝트 구조가 너무 꼬였거나, 처음부터 다시 붙이는 편이 빠를 때가 있습니다.
그럴 때는 아래 명령을 씁니다.

1
bmalph reset --dry-run
2
bmalph reset

실전에서는 항상 --dry-run부터 보는 편이 좋습니다.
지워질 범위를 먼저 확인한 뒤 실제 초기화를 하는 것이 안전합니다.

공식 README 기준으로 이 명령은 bmalph가 만든 구조를 제거하는 역할입니다.
즉 저장소 전체를 지우는 명령이 아니라, bmalph가 관리하던 구조를 정리하는 명령으로 이해하면 됩니다.

기존 BMAD 프로젝트에 붙일 때는 무엇이 바뀔까요?#

이 부분도 공식 README에 분명히 나옵니다.
이미 _bmad/가 있는 프로젝트에 bmalph init을 다시 쓰면, _bmad/ 프레임워크 파일은 bmalph 관리 버전으로 바뀔 수 있습니다.
대신 _bmad-output/처럼 사용자가 만든 기획 산출물은 건드리지 않는 방향으로 설명돼 있습니다.

즉 기존 BMAD 프로젝트에 붙일 때는 아래 순서가 안전합니다.

1. 먼저 커밋합니다
2. bmalph init으로 붙입니다
3. _bmad/ 차이를 검토합니다
4. _bmad-output/는 그대로 남아 있는지 확인합니다

이렇게 보면 bmalph는 “기존 기획을 버리고 다시 쓰는 도구”가 아니라, “기존 문서를 Ralph 단계까지 연결하는 도구”에 가깝습니다.

반복 실행은 어떤 흐름으로 이해하면 될까요?#

bmalph는 한 번만 쓰고 끝나는 도구가 아닙니다.
공식 README도 아래 반복 흐름을 설명합니다.

1. BMAD로 새 문서를 추가하거나 수정합니다
2. bmalph implement를 다시 실행합니다
3. bmalph run으로 Ralph 루프를 다시 돌립니다

중요한 점은 implement를 다시 돌려도 완료된 작업이 무조건 처음부터 사라지는 방식이 아니라는 점입니다.
공식 설명에는 이미 끝난 스토리를 보존하고, 새 스토리를 보태는 방향이 나옵니다.

즉 bmalph는 “한 번 계획하고 끝”이 아니라, “문서를 고치고 다시 구현 루프로 넘기는 반복 작업”을 전제로 합니다.

막혔을 때 점검 순서는 어떻게 가져가면 좋을까요?#

실전에서는 아래 순서가 가장 안전합니다.

1. bmalph status --json
2. bmalph doctor --json
3. .ralph/logs/ 확인
4. 하위 도구 명령 자체 확인
5. 필요하면 implement --force
6. 그래도 꼬였으면 reset --dry-run 검토

이 순서를 권하는 이유는 명확합니다.

• 먼저 단계와 구조를 확인합니다
• 그다음 실제 로그를 봅니다
• 마지막에야 다시 생성하거나 초기화합니다

즉 바로 지우고 다시 시작하는 것보다, 지금 상태를 읽는 습관이 먼저입니다.

시리즈 전체를 한 번에 다시 보면#

이번 todo-demo 흐름은 아래처럼 끝납니다.

1. 왜 bmalph가 필요한지 이해합니다
2. 저장소를 만들고 init으로 구조를 붙입니다
3. 분석 단계로 범위를 줄입니다
4. PRD와 화면 흐름을 정리합니다
5. 설계 문서와 세부 작업을 만듭니다
6. implement로 Ralph 작업판을 생성합니다
7. run으로 반복 구현을 시작합니다
8. 상태 확인, 복구, 반복 실행까지 익힙니다

즉 bmalph의 핵심은 명령 세 개를 외우는 것이 아닙니다.
문서를 만들고, 그 문서를 반복 구현으로 넘기고, 막혔을 때 다시 이어 가는 흐름 전체를 다루는 것입니다.

8편에서 꼭 가져가야 할 기준#

• bmalph는 설치 도구이면서 운영 도구입니다
• status와 doctor는 가장 먼저 보는 명령입니다
• doctor가 통과해도 런타임 문제는 따로 생길 수 있습니다
• implement, run, implement 재실행이 반복 흐름입니다
• 기존 BMAD 프로젝트에도 bmalph를 얹을 수 있습니다

여기까지 오면 이제 todo-demo 예제를 따라 하는 수준을 넘어, bmalph를 실제 작업 흐름에 어디에 끼워 넣어야 하는지 감이 잡히기 시작합니다.
다음에는 같은 구조를 더 큰 프로젝트로 옮기거나, 반대로 작은 작업에서는 어디까지 생략할지를 판단하면 됩니다.