bmalph 실전 가이드 7편 - run으로 첫 작업 구현 흐름 따라가기

요약#

참고 자료#

• bmalph README 원문 - run, driver, troubleshooting
• Ralph GitHub 저장소 - 반복 구현 개념
• Geoffrey Huntley - Ralph - 한 번에 하나의 작업만 처리해야 하는 이유

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

7편에서는 bmalph run이 실제로 어떤 파일을 읽고 어떤 상태 파일과 로그를 남기는지, 시작 전에 무엇을 점검해야 하는지 정리합니다.
즉 첫 반복을 안전하게 시작하는 편입니다.

반대로 말하면, 6편 이전에는 run을 누르면 안 됩니다.
run은 언제나 마지막 버튼입니다.

run 전에 꼭 확인할 다섯 가지#

처음에는 아래 다섯 가지면 충분합니다.

1. Git 저장소인가
2. 최소 1회 커밋이 있는가
3. implement까지 끝나서 .ralph/@fix_plan.md가 있는가
4. 지금 도구가 Ralph를 지원하는 전체 단계 플랫폼인가
5. 테스트 명령이 실제로 돌아가는가

공식 README의 지원 단계 구분을 보면, Ralph 구현 루프는 full 단계 플랫폼에서만 의미가 있습니다.
즉 planning만 지원하는 도구에서는 run을 기대하면 안 됩니다.

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

대시보드 없이 가장 단순하게 시작하려면 아래 명령이면 됩니다.

1
bmalph run --no-dashboard

대시보드까지 보고 싶다면 아래처럼 실행합니다.

1
bmalph run

실제 검증에서는 시작 직후 아래 경로가 바로 안내됐습니다.

• 로그: .ralph/logs/
• 상태 파일: .ralph/status.json

즉 run이 시작되면 가장 먼저 볼 곳은 터미널보다도 이 두 곳입니다.

루프는 어떤 파일을 읽고 움직일까요?#

6편에서 만든 파일들이 여기서 실제로 쓰입니다.

• .ralph/@fix_plan.md: 다음 스토리를 고르는 기준
• .ralph/PROMPT.md: 한 번의 반복에서 따라갈 규칙
• .ralph/PROJECT_CONTEXT.md: 목표와 범위 요약
• .ralph/specs/: 필요할 때 읽는 원본 문서 복사본
• .ralph/@AGENT.md: 빌드와 테스트 방법

실제로 생성된 PROMPT.md를 보면 아래 규칙이 분명했습니다.

• 다음 미완료 스토리를 찾습니다
• 테스트를 먼저 작성합니다
• 한 번에 하나의 스토리만 처리합니다
• 체크박스를 [x]로 바꿉니다
• 커밋 메시지를 남깁니다

즉 Ralph는 “프로젝트 전체를 한 번에 끝내는 도구”가 아니라, “체크되지 않은 다음 스토리를 처리하는 도구”입니다.

첫 반복이 시작되면 무엇이 바뀔까요?#

실제 예제에서 run을 시작하자 바로 .ralph/status.json이 running 상태로 바뀌었습니다.
또 .ralph/logs/ 아래에 실행 로그가 생겼습니다.

이 상태에서 우리가 기대해야 할 흐름은 아래입니다.

1. 첫 미완료 스토리를 읽습니다
2. 관련 코드를 찾습니다
3. 테스트를 만들거나 수정합니다
4. 구현을 바꿉니다
5. 체크박스를 바꿉니다
6. 커밋합니다

즉 첫 성공 기준은 “모든 것이 끝났다”가 아니라, “루프가 첫 스토리를 기준으로 정상 작동하기 시작했다”입니다.

실제 검증에서 바로 드러난 첫 번째 함정#

이 부분은 공식 문서만 읽어서는 놓치기 쉬운 부분입니다.
실제 macOS 환경에서 bmalph run을 실행해 보니, timeout 명령이 없을 때 루프가 즉시 종료됐습니다.

로그에는 아래 의미의 오류가 남았습니다.

• 시스템에 timeout 명령이 없음
• macOS라면 brew install coreutils로 GNU coreutils 설치 필요

이 사실은 .ralph/lib/timeout_utils.sh 설명과 실제 실행 로그에서 함께 확인했습니다.
즉 macOS 사용자는 run 전에 gtimeout 또는 timeout 사용 가능 여부를 같이 보는 편이 안전합니다.

두 번째 함정은 bmalph가 아니라 도구 환경일 수 있습니다#

실제 검증에서는 timeout 문제를 넘긴 뒤 Codex 실행이 시작됐고, 로그와 상태 파일 갱신도 확인했습니다.
다만 그다음부터는 Codex CLI 자체 상태가 불안정하면 루프가 길게 멈추거나, 하위 도구 경고가 튀는 경우가 있었습니다.

이럴 때 중요한 기준은 하나입니다.
bmalph가 모든 하위 도구 문제를 대신 고쳐 주지는 않는다는 점입니다.

즉 아래 순서로 보는 편이 맞습니다.

1. bmalph doctor
2. .ralph/logs/ 확인
3. 필요하면 하위 도구 명령 자체를 단독으로 시험

예를 들어 Codex 환경이라면 codex exec 자체가 정상인지 먼저 보는 식입니다.

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

• run은 언제나 마지막 단계입니다
• 실제 기준 파일은 .ralph/@fix_plan.md와 .ralph/PROMPT.md입니다
• Ralph는 한 번에 하나의 스토리만 처리합니다
• 시작 후에는 .ralph/status.json과 .ralph/logs/를 먼저 봅니다
• 환경 문제가 있으면 bmalph보다 하위 도구 상태를 먼저 확인해야 합니다

8편에서는 이제 status, doctor, check-updates, upgrade, reset, 재실행 전략까지 묶어서 운영과 복구 관점으로 마무리하겠습니다.