bmalph 실전 가이드 2편 - 설치하고 시작하기

요약#

참고 자료#

• bmalph GitHub 저장소 - 전체 구조와 지원 도구 목록
• bmalph README 원문 - init, status, doctor, 지원 단계 설명
• bmalph npm 페이지 - 설치 명령과 배포 정보
• BMAD Method - Getting Started - BMAD 전체 흐름 복습

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

2편에서는 todo-demo 저장소를 만들고 bmalph init으로 초기화한 뒤, status와 doctor로 첫 상태를 확인합니다.
즉 설치 명령만 끝내는 글이 아니라, 실제로 시작 가능한 상태까지 끌고 가는 편입니다.

2편의 목표는 딱 두 가지입니다.

• todo-demo를 실제 작업 가능한 저장소로 만듭니다
• 그 저장소를 bmalph가 관리하는 프로젝트 상태로 바꿉니다

즉 이번 편이 끝나면 _bmad/, .ralph/, bmalph/가 붙고, 다음 편부터는 BMAD 문서를 실제로 만들 수 있게 됩니다.

설치 전에 무엇을 준비하면 될까요?#

공식 README 기준으로 공통 준비물은 단순합니다.

• Node.js¹ 20 이상
• Bash²
• 지원되는 AI 코딩 도구 하나
• Git 저장소와 최소 1회 커밋

여기서 마지막 조건이 생각보다 중요합니다.
실제로 bmalph doctor는 저장소와 커밋 존재 여부를 점검하고, Ralph 반복 구현은 변경 이력을 기준으로 움직입니다.
즉 설치만 되어 있고 커밋이 한 번도 없다면 뒤 단계가 어색해집니다.

공통 설치 명령은 모두 같습니다#

지원 도구가 무엇이든, 가장 먼저 실행하는 설치 명령은 같습니다.

1
npm install -g bmalph

이 명령은 bmalph 실행 파일을 내 컴퓨터에 설치합니다.
하지만 이것만으로는 아직 프로젝트가 준비되지 않습니다.
프로젝트 폴더 안에서 init을 한 번 더 실행해야 합니다.

즉 설치와 시작은 다른 단계입니다.

todo-demo 프로젝트를 먼저 준비합니다#

이번 시리즈는 하나의 예제를 계속 이어 가므로, 먼저 최소한의 프로젝트 바탕을 맞춥니다.
아래 예시는 Node.js 기준으로 가장 작은 형태만 남겼습니다.

1
mkdir todo-demo
2
cd todo-demo
3
git init

package.json

1
{
2
  "name": "todo-demo",
3
  "version": "0.0.1",
4
  "type": "module",
5
  "scripts": {
6
    "test": "node --test"
7
  }
8
}

src/todo.js

1
export function createTodoStore() {
2
  return [];
3
}

test/todo.test.js

1
import test from "node:test";
2
import assert from "node:assert/strict";
3
import { createTodoStore } from "../src/todo.js";
4

5
test("createTodoStore returns an array", () => {
6
  assert.deepEqual(createTodoStore(), []);
7
});

여기까지 만들었다면 첫 기준점을 커밋해 둡니다.

1
git add .
2
git commit -m "chore: scaffold todo demo"

이 커밋은 뒤에서 Ralph가 무엇을 바꾸었는지 비교하는 기준점이 됩니다.

지원 도구별 init 예시는 이렇게 다릅니다#

공식 README는 여러 AI 코딩 도구를 지원합니다.
차이는 설치 명령이 아니라 --platform 값과 설치 뒤 진입 방식에 있습니다.

가장 기본 형태는 아래입니다.

1
bmalph init --name todo-demo

도구를 명확히 알고 있다면 아래처럼 직접 지정할 수 있습니다.

1
bmalph init --name todo-demo --platform claude-code
2
bmalph init --name todo-demo --platform codex
3
bmalph init --name todo-demo --platform opencode
4
bmalph init --name todo-demo --platform cursor
5
bmalph init --name todo-demo --platform windsurf
6
bmalph init --name todo-demo --platform copilot
7
bmalph init --name todo-demo --platform aider

여기서 실무적으로 기억할 점은 하나면 충분합니다.
도구를 이미 정해 두었다면 --platform을 붙이면 되고, 그렇지 않다면 bmalph init --name todo-demo만 먼저 실행해도 됩니다.

즉 2편의 핵심은 “무엇을 선택해야 하는가”가 아니라 “내 도구에서 어떤 값으로 시작하는가”입니다.

지원 도구별 첫 시작 방법은 어떻게 다를까요?#

설치 뒤 첫 진입은 도구마다 조금씩 다릅니다.
이 차이를 알아야 설치가 끝난 뒤 길을 잃지 않습니다.

이번 시리즈에서는 설명 예시를 Codex 기준으로 들기도 하겠지만, 구조 자체는 특정 도구 하나에 묶지 않겠습니다.
Claude Code라면 /analyst처럼, Codex나 OpenCode라면 $analyst처럼, 나머지 도구는 _bmad/COMMANDS.md 기준으로 같은 흐름을 따라가면 됩니다.

init 뒤에 공통으로 생기는 것은 무엇일까요?#

도구마다 진입 방식은 달라도, 프로젝트 안에서 공통으로 생기는 중심 구조는 비슷합니다.

1
project/
2
├── _bmad/
3
├── .ralph/
4
├── bmalph/
5
├── <지침 파일>
6
└── <명령 진입점>

실제로 Codex 기준 예제를 검증해 보니 아래가 생성됐습니다.

• _bmad/
• .ralph/
• bmalph/
• AGENTS.md
• .agents/skills/

각 경로의 역할은 아래처럼 이해하면 됩니다.

• _bmad/: BMAD 문서 작성과 작업 흐름이 들어갑니다
• .ralph/: Ralph 반복 구현에 필요한 파일이 들어갑니다
• bmalph/: 현재 프로젝트 상태를 저장합니다
• 지침 파일: 사용하는 도구가 읽는 안내 문서입니다
• 명령 진입점: 각 도구에서 BMAD를 여는 방식입니다

즉 init은 파일 몇 개를 추가하는 가벼운 작업이 아닙니다.
프로젝트를 “문서 작성 단계와 반복 구현 단계를 함께 다루는 구조”로 바꾸는 작업입니다.

설치 직후 바로 확인할 명령은 두 개면 충분합니다#

처음에는 아래 두 명령만 정확히 기억해도 됩니다.

1
bmalph status --json
2
bmalph doctor --json

이 둘의 역할은 다릅니다.

• status³: 지금 프로젝트가 어느 단계에 있는지 보여 줍니다
• doctor⁴: 설치 구조가 정상인지 점검합니다

프로젝트 밖에서 확인할 때는 -C로 경로를 직접 넘기면 됩니다.

1
bmalph status --json -C /path/to/todo-demo
2
bmalph doctor --json -C /path/to/todo-demo

Codex 기준 검증에서는 status --json이 1단계 분석 상태를 보여 주었고, doctor --json은 구조 점검을 통과했습니다.
즉 이 시점에서 중요한 것은 아직 구현이 아닙니다.
프로젝트가 bmalph 흐름 안으로 제대로 들어왔는지를 확인하는 것입니다.

지금은 아직 없는 파일도 있습니다#

초보자가 가장 자주 착각하는 부분이 여기입니다.
init이 끝났다고 해서 곧바로 Ralph가 실행할 작업판까지 준비되는 것은 아닙니다.

지금 단계에서는 보통 아래 파일이 아직 없습니다.

• .ralph/@fix_plan.md
• .ralph/PROJECT_CONTEXT.md
• .ralph/SPECS_INDEX.md
• .ralph/SPECS_CHANGELOG.md

이 파일들은 BMAD 문서를 만든 뒤 bmalph implement를 실행해야 생깁니다.
즉 지금은 설치와 시작 단계이고, 구현 단계는 아닙니다.

이 기준을 먼저 잡아 두면 6편에서 implement를 이해하기 훨씬 쉬워집니다.

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

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

• bmalph 설치 명령은 공통입니다
• 실제 시작점은 프로젝트 안에서 실행하는 init입니다
• 지원 도구마다 --platform 값과 첫 진입 방식이 다릅니다
• 설치 직후에는 status, doctor를 먼저 확인합니다
• implement, run은 아직 아닙니다

2편의 핵심은 도구를 비교하는 것이 아니라, 지금 쓰는 도구에서 bmalph를 바로 시작하는 방법을 익히는 것입니다.

3편에서는 이제 todo-demo를 막연한 예제가 아니라, 실제로 문서화할 가치가 있는 작은 제품으로 좁혀 가겠습니다.