bmalph 실전 가이드 5편 - 설계 문서와 세부 작업 만들기

요약#

참고 자료#

• BMAD Method - Workflow Map - 설계 단계와 구현 단계 연결
• BMAD Method - Commands - create-architecture, create-epics-stories
• Ralph GitHub 저장소 - 한 번에 하나의 작업만 처리하는 반복 구조
• bmalph README 원문 - implement가 stories를 읽는다는 설명

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

5편에서는 todo-demo-architecture.md, todo-demo-epics-stories.md, todo-demo-readiness.md를 기준으로 Ralph가 읽을 작업 단위를 만듭니다.
즉 PRD를 실제 구현 순서로 잘게 쪼개는 편입니다.

이유는 간단합니다.
PRD는 제품 기준이고, Ralph는 세부 작업 기준으로 움직이기 때문입니다.

그래서 5편에서는 두 가지를 만듭니다.

• 기술 결정을 남기는 설계 문서
• 한 번에 하나씩 구현 가능한 세부 작업 목록

설계 문서에는 무엇이 꼭 들어가야 할까요?#

todo-demo는 작은 프로젝트라서 설계 문서도 길 필요는 없습니다.
다만 사라지면 곤란한 정보는 분명히 있어야 합니다.

실제 예제로 bmalph implement를 돌려 보니, 설계 문서에 Tech Stack이 없을 때 경고가 발생했습니다.
즉 최소한 아래는 넣는 편이 안전합니다.

• 개요
• 기술 스택
• 주요 구성 요소
• 데이터 구조
• 테스트 기준

이번 시리즈에서는 아래 정도로 잡겠습니다.

1
# Todo Demo Architecture
2

3
## Overview
4
작은 Node.js 기반 할 일 예제다.
5

6
## Tech Stack
7
- Runtime: Node.js
8
- Language: JavaScript
9
- Tests: node:test
10

11
## Components
12
- Todo model
13
- Todo store
14
- Filter logic
15
- Priority update logic
16

17
## Quality Gates
18
- `npm test` 통과

중요한 것은 멋있게 쓰는 것이 아니라, Ralph가 코드를 바꿀 때 참고할 기술 기준을 남기는 것입니다.

스토리는 어떻게 쪼개야 할까요?#

여기서 Ralph의 핵심 원칙이 그대로 들어옵니다.
한 번에 하나의 작업만 처리할 수 있어야 합니다.

이번 예제에서 가장 자연스러운 스토리 분해는 아래 네 개입니다.

1
### Story 1.1: Add a todo item
2
> AC: Given a title, when a todo is added, then it receives an id and done is false.
3
> AC: Given an empty list, when a todo is added, then the list contains one item.
4

5
### Story 1.2: Toggle todo completion
6
> AC: Given an existing todo, when completion is toggled, then done changes.
7
> AC: Given a missing id, when completion is toggled, then the function reports failure.
8

9
### Story 1.3: Set todo priority
10
> AC: Given an existing todo, when priority is updated, then the new priority is stored.
11
> AC: Given an invalid priority, when the update is attempted, then the function rejects the value.
12

13
### Story 1.4: Filter todos by status
14
> AC: Given mixed todos, when active filter is used, then only pending todos are returned.
15
> AC: Given mixed todos, when completed filter is used, then only completed todos are returned.

왜 스토리를 더 크게 잡지 않을까요?#

예를 들어 아래처럼 한 줄로 쓰고 싶은 유혹이 생깁니다.

• “핵심 할 일 기능 만들기”

하지만 이건 Ralph에게 너무 큽니다.
추가, 완료 처리, 우선순위, 필터가 모두 섞여 있기 때문입니다.
이렇게 쓰면 테스트도 커지고, 실패했을 때 어느 기준을 놓쳤는지도 흐려집니다.

반대로 1.1부터 1.4까지처럼 자르면 장점이 분명합니다.

• 테스트를 각각 독립적으로 쓸 수 있습니다
• @fix_plan.md 체크박스가 단순해집니다
• 한 번 실패해도 어떤 스토리에서 막혔는지 바로 보입니다

즉 “한 번에 하나의 스토리”는 철학이 아니라 운영 안정성의 문제입니다.

구현 준비 점검 문서는 왜 넣을까요?#

공식 bmalph 흐름에는 Implementation Readiness가 있습니다.
이 문서는 새 기능을 추가하는 문서가 아닙니다.
앞에서 만든 문서들이 서로 모순 없이 맞물리는지 확인하는 마지막 점검표입니다.

todo-demo-readiness.md에는 아래 정도면 충분합니다.

• PRD와 설계 문서의 범위가 같은가
• 스토리가 PRD 요구사항을 빠뜨리지 않았는가
• 테스트 명령이 정해졌는가
• 지금 단계에서 빼기로 한 기능이 스토리에 섞이지 않았는가

이 한 장이 있으면 6편에서 implement를 돌리기 전 마음이 훨씬 편해집니다.

6편으로 넘기기 전에 확인할 기준#

아래 조건이 맞으면 implement로 넘어갈 수 있습니다.

• PRD가 있다
• 설계 문서에 Tech Stack이 있다
• 스토리가 한 번에 하나씩 구현 가능한 크기다
• AC 줄이 동작 기준으로 적혀 있다
• 구현 준비 점검 문서가 있다

이번 시리즈에서는 아래 파일 이름으로 맞추겠습니다.

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

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

• 설계 문서는 기술 기준을 남기는 문서입니다
• 스토리는 한 번에 하나의 작업만 담아야 합니다
• Tech Stack과 AC는 실제로 implement 품질에 영향을 줍니다
• 구현 준비 점검 문서는 마지막 정합성 확인입니다
• 다음 편에서는 이 문서들을 Ralph 작업판으로 변환합니다

6편에서는 이제 bmalph implement를 실제로 실행해 .ralph/@fix_plan.md, .ralph/PROJECT_CONTEXT.md, .ralph/SPECS_INDEX.md가 어떻게 생기는지 직접 확인하겠습니다.