bmalph 실전 가이드 6편 - implement로 Ralph 작업판 만들기

요약#

참고 자료#

• bmalph README 원문 - implement 설명과 생성 파일
• Ralph GitHub 저장소 - 구현 입력물 배경

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

6편에서는 bmalph implement를 실행했을 때 .ralph/@fix_plan.md, .ralph/PROJECT_CONTEXT.md, .ralph/SPECS_INDEX.md가 어떻게 생기는지 실제 검증 결과를 바탕으로 정리합니다.
즉 문서 단계에서 구현 작업판 단계로 넘어가는 편입니다.

하지만 Ralph는 아직 이 문서를 그대로 읽지 않습니다.
Ralph가 직접 따라가는 기준은 .ralph/ 아래에 생성되는 작업판입니다.
즉 6편의 목적은 이 문서들을 Ralph용 입력물로 바꾸는 것입니다.

implement는 실제로 무엇을 할까요?#

공식 README는 implement를 BMAD 산출물을 Ralph 형식으로 바꾸는 단계로 설명합니다.
실제 예제로 검증해 보니 흐름은 아래와 같았습니다.

1. BMAD 문서를 찾습니다
2. 스토리를 읽고 작업판으로 바꿉니다
3. 문서를 .ralph/specs/로 복사합니다
4. 읽기 순서 문서와 프로젝트 맥락 문서를 만듭니다
5. Ralph용 프롬프트와 작업 파일을 준비합니다

즉 implement는 “문서 복사”가 아니라 “반복 구현 준비”입니다.

먼저 무엇이 준비돼 있어야 할까요?#

이번 시리즈 기준으로는 아래 네 문서가 준비돼 있으면 됩니다.

• todo-demo-prd.md
• todo-demo-architecture.md
• todo-demo-epics-stories.md
• todo-demo-readiness.md

실제 검증에서 가장 중요했던 것은 아래 두 가지였습니다.

• PRD에 Vision, Scope, 기능 요구사항, 비기능 요구사항이 있을 것
• 설계 문서에 Tech Stack이 있을 것

이 섹션이 빠진 최소 예제에서는 implement가 경고를 냈고, 채운 뒤 다시 실행하니 경고 없이 통과했습니다.

실제 실행은 이렇게 합니다#

1
bmalph implement

이미 한 번 실행한 적이 있다면 아래처럼 다시 돌릴 수 있습니다.

1
bmalph implement --force

실제 검증에서는 --force를 붙이면 아래 경고와 함께 다시 생성됐습니다.

• PROMPT.md
• PROJECT_CONTEXT.md
• @AGENT.md
• SPECS_INDEX.md

그리고 fix plan 진행 상황은 보존된다고 안내했습니다.

생성된 @fix_plan.md는 어떻게 생길까요?#

implement 뒤에 가장 중요한 파일은 .ralph/@fix_plan.md입니다.
이번 예제에서는 아래처럼 생성됐습니다.

1
### Core todo management
2

3
- [ ] Story 1.1: Add a todo item
4
- [ ] Story 1.2: Toggle todo completion
5
- [ ] Story 1.3: Set todo priority
6
- [ ] Story 1.4: Filter todos by status

실제 파일에는 각 스토리마다 설명과 AC 줄, 원본 문서 위치까지 더 붙었습니다.
즉 Ralph는 여기 체크박스를 기준으로 다음 작업을 고릅니다.

이 구조가 중요한 이유는 단순합니다.
이제부터 Ralph는 “PRD 전체”가 아니라 “체크되지 않은 다음 스토리”를 기준으로 움직입니다.

PROJECT_CONTEXT.md와 SPECS_INDEX.md는 왜 중요할까요?#

이번 예제를 다시 실행해 보니, PRD를 제대로 채운 뒤 생성된 PROJECT_CONTEXT.md에는 아래 내용이 들어갔습니다.

• 프로젝트 목표
• 포함 범위
• 제외 범위
• 비기능 요구사항

즉 PRD의 중요한 요약본이 Ralph용으로 다시 정리된 셈입니다.

SPECS_INDEX.md는 또 다른 역할을 합니다.
이 파일은 어떤 문서를 어떤 순서로 읽으면 되는지 정리한 목록입니다.
실제 생성 결과에서는 설계 문서, 스토리 문서, PRD, 준비 점검 문서 순으로 정리됐습니다.

즉 Ralph는 모든 문서를 매번 통째로 읽는 대신, 필요할 때 이 색인을 참고해 필요한 문서만 읽게 됩니다.

.ralph/ 아래에 생기는 핵심 파일은 무엇일까요?#

이번 예제 기준으로 꼭 봐야 하는 파일은 아래 여섯 개입니다.

• .ralph/@fix_plan.md: 체크박스가 달린 실제 작업판
• .ralph/specs/: BMAD 문서 복사본
• .ralph/PROJECT_CONTEXT.md: 목표와 범위를 요약한 문서
• .ralph/SPECS_INDEX.md: 어떤 문서를 먼저 읽을지 정리한 문서
• .ralph/SPECS_CHANGELOG.md: 이전 실행 대비 문서 변경 사항
• .ralph/PROMPT.md: Ralph가 각 반복에서 따라갈 지침

실제로 .ralph/PROMPT.md에는 “한 번에 하나의 스토리”, “테스트 먼저”, “스토리 체크박스 갱신”, “커밋” 같은 규칙이 들어갔습니다.
즉 7편 run은 이 파일을 바탕으로 돌아갑니다.

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

• implement는 문서를 반복 구현용 작업판으로 바꾸는 단계입니다
• PRD와 설계 문서 섹션이 비어 있으면 사전 경고가 생깁니다
• .ralph/@fix_plan.md가 실제 구현 기준점입니다
• PROJECT_CONTEXT.md와 SPECS_INDEX.md는 Ralph가 문서를 읽는 길잡이입니다
• 다시 실행할 때는 --force를 쓸 수 있습니다

7편에서는 이제 bmalph run을 실제로 시작하고, .ralph/status.json, .ralph/logs/, @fix_plan.md를 기준으로 첫 반복이 어떻게 움직이는지 보겠습니다.