bmalph 실전 가이드 1편 - 왜 bmalph인가

요약#

참고 자료#

• BMAD Method - Getting Started - BMAD 전체 시작 흐름
• BMAD Method - Workflow Map - 단계별 문서 흐름
• bmalph GitHub 저장소 - bmalph 전체 구조와 명령
• bmalph README 원문 - init, implement, run의 역할
• Ralph GitHub 저장소 - Ralph 반복 구현 구조
• Geoffrey Huntley - Ralph - Ralph가 왜 한 번에 하나의 작업만 처리해야 하는지 설명한 글

왜 이런 도구가 또 필요할까요?#

bmalph는 BMAD 문서를 Ralph 구현 루프로 넘기는 연결 도구입니다.
이 시리즈는 공식 프로젝트가 아니라, Moodturn이 공식 문서와 실제 검증을 바탕으로 정리한 비공식 실전 가이드입니다.

하지만 실제 작업은 그렇게 깔끔하게 이어지지 않습니다.
처음에는 요구사항이 또렷해도, 시간이 지나면 눈앞의 코드 수정이 더 중요해집니다.
그러면 왜 이런 기능을 넣기로 했는지, 어디까지 만들면 끝난 것인지, 다음에 무엇을 해야 하는지가 흐려집니다.

BMAD 공식 문서가 강조하는 것도 바로 이 지점입니다.
한 대화에 모든 것을 밀어 넣지 말고, 단계마다 문서를 만들고, 그 문서를 다음 단계의 기준으로 넘기라는 것입니다.

즉 문제는 “AI가 코드를 못 짠다”가 아닙니다.
문서와 구현 사이를 오래 안정적으로 이어 가기 어렵다는 점입니다.

BMAD는 무엇을 맡고, Ralph는 무엇을 맡을까요?#

이 구분을 먼저 잡아야 bmalph도 이해됩니다.

BMAD는 앞쪽 일을 맡습니다.
무엇을 만들지, 누구를 위한 것인지, 어떤 구조로 만들지, 어떤 세부 작업으로 나눌지를 문서로 정리합니다.

공식 문서 기준으로 보면 BMAD는 아래 흐름을 중심으로 설명됩니다.

• 분석 단계: 아이디어를 좁히고 근거를 모읍니다
• 기획 단계: 요구사항 문서를 만듭니다
• 설계 단계: 기술 결정과 세부 작업을 정리합니다
• 구현 단계: 세부 작업을 하나씩 구현합니다

그런데 bmalph 공식 README는 BMAD의 앞 세 단계와 Ralph의 구현 반복을 함께 묶어 보여 줍니다.
여기서 Ralph는 “세부 작업 하나를 고르고, 구현하고, 검사하고, 다음 작업으로 넘어가는 반복 실행”을 맡습니다.

즉 이렇게 이해하면 가장 쉽습니다.

• BMAD: 무엇을 만들지와 어떻게 나눌지를 문서로 정합니다
• Ralph: 정리된 세부 작업을 실제 코드 변경으로 밀어 갑니다
• bmalph: 둘을 한 프로젝트 안에서 이어 줍니다

왜 BMAD만으로 끝내지 않을까요?#

이 질문이 1편의 핵심입니다.

BMAD만으로도 문서를 만들고 구현을 시작할 수는 있습니다.
실제로 BMAD 공식 문서에도 구현 단계가 있습니다.

하지만 bmalph가 필요한 이유는 문서를 실제 반복 구현 체계로 넘기는 데 있습니다.
bmalph README는 이 도구를 init, implement, run 세 축으로 설명합니다.

• init: BMAD와 Ralph를 프로젝트에 붙입니다
• implement: BMAD 문서를 Ralph가 읽는 작업판으로 바꿉니다
• run: Ralph 반복 구현을 시작합니다

즉 bmalph는 새로운 기획 방법을 하나 더 만드는 도구가 아닙니다.
이미 만든 문서를 구현 순서로 바꾸고, 그 구현을 반복 실행으로 이어 주는 운영 도구입니다.

이 점이 이해되면, 왜 bmalph가 “BMAD의 경쟁자”가 아니라 “BMAD의 다음 연결 고리”인지도 자연스럽게 보입니다.

Ralph는 왜 따로 알아야 할까요?#

Ralph는 단순히 “자동 코딩”이라고 부르면 오해가 생깁니다.
Ralph 쪽 문서는 반복 실행이 잘 되려면 몇 가지 조건이 꼭 필요하다고 설명합니다.

가장 중요한 기준은 세 가지입니다.

• 한 번에 하나의 세부 작업만 처리할 것
• 매 반복은 새 대화처럼 가볍게 시작할 것
• 테스트와 점검이 빠르게 돌아올 것

이 원칙이 중요한 이유는 간단합니다.
한 번에 너무 많은 일을 시키면 문맥이 흐려지고, 검사 장치가 약하면 잘못된 코드가 계속 쌓입니다.
그래서 Ralph는 “엄청 똑똑한 한 번의 답”보다 “작은 작업을 여러 번 안정적으로 끝내는 방식”에 가깝습니다.

bmalph 실전 가이드를 따로 만드는 이유도 여기에 있습니다.
독자는 BMAD 문서를 잘 만드는 법뿐 아니라, 그 문서가 실제로 어떤 반복 구현 구조로 이어지는지까지 알아야 하기 때문입니다.

이번 시리즈에서 만들 예제는 무엇일까요?#

이번 시리즈에서는 todo-demo⁴를 만듭니다.
아주 흔한 예제처럼 보이지만, 일부러 조금만 더 현실적인 범위로 잡겠습니다.

이번 예제의 목표는 아래 네 가지입니다.

• 할 일을 추가합니다
• 할 일을 완료 처리합니다
• 우선순위를 정합니다
• 상태에 따라 목록을 걸러서 봅니다

이 정도 규모가 좋은 이유는 분명합니다.
너무 작아서 문서가 필요 없지도 않고, 너무 커서 초보자가 중간에 지치지도 않습니다.
즉 BMAD 문서화와 Ralph 반복 구현을 모두 보여 주기에 딱 좋은 크기입니다.

이 시리즈에서는 이 todo-demo가 1편에서 개요로 시작해, 8편에서 운영과 복구까지 이어지게 됩니다.
즉 매 편이 따로 노는 글이 아니라, 하나의 작은 제품을 끝까지 따라가는 글이 됩니다.

이 시리즈는 어떤 순서로 읽게 될까요?#

이번 시리즈는 8편으로 갑니다.
길어 보일 수 있지만, 오히려 이 정도로 끊어야 초보자가 중간 점프 없이 따라올 수 있습니다.

중요한 점은 6편에서 갑자기 데모가 시작되지 않는다는 것입니다.
1편부터 같은 예제를 이어 가기 때문에, 6편의 implement와 7편의 run도 앞 문서의 연장선으로 자연스럽게 이어집니다.

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

이 글에서 먼저 머리에 남아야 할 기준은 아래 다섯 가지입니다.

• BMAD는 문서를 만드는 쪽입니다
• Ralph는 세부 작업을 하나씩 구현하는 쪽입니다
• bmalph는 둘을 이어 주는 운영 도구입니다
• 이번 시리즈는 todo-demo를 처음부터 끝까지 따라가는 구조입니다
• 다음 편부터는 개념 설명이 아니라 실제 설치와 초기화로 들어갑니다

bmalph를 이해하는 가장 쉬운 방법은 “새 방법론”으로 보는 것이 아니라, BMAD 문서를 Ralph 반복 구현으로 넘기는 연결 도구로 보는 것입니다.

2편에서는 이제 실제로 todo-demo 폴더를 만들고, bmalph를 설치하고, init, status, doctor까지 따라가겠습니다.