Ralph Loop 설계하기 — BACKLOG.md와 상태 파일 운영법

이전에 Claude Code로 만든 암호화폐 투자 대시보드에 대해 작성하였습니다. 이번에는 그 프로젝트에서 Ralph Loop를 실제로 설계하고 운영한 방법을 다룹니다. 루프를 어떻게 구성했는지, 상태 파일을 어떻게 관리했는지, 그리고 1,208번의 루프 동안 일관성을 어떻게 유지했는지 정리하도록 하겠습니다.

Ralph Loop의 기본 구조

Ralph Loop는 Claude Code가 자율적으로 반복 작업을 수행하도록 구성하는 패턴입니다. Claude가 "다음에 무엇을 해야 하는지"를 스스로 파악할 수 있도록 상태 파일을 잘 정의해 두는 것이 기본 아이디어입니다.

루프 프롬프트 예시는 아래와 같습니다.

BACKLOG.md의 미완료 항목을 P0 → P1 → P2 순서로 1개씩 구현한다.

루프 프롬프트는 이 한 줄이 전부입니다. Claude는 이 지시를 받으면 BACKLOG.md를 읽고 미완료 항목을 찾아 구현한 뒤, 결과를 PROGRESS.md에 기록하고 다음 루프를 준비합니다.

한 루프가 상태 파일을 어떻게 읽고 쓰는지 그림으로 나타내면 아래와 같습니다.

눌러서 원본 크기로 보기

필요한 맥락이 모두 파일에 남아 있기 때문에, 세션이 끊기거나 새로 시작되어도 다음 루프는 앞 루프가 남긴 기록을 읽고 이어서 작업할 수 있습니다.

상태 파일 구성

루프가 반복되어도 맥락이 유지되려면 상태 파일이 잘 정의되어 있어야 합니다. 이 프로젝트에서 운영한 상태 파일은 세 가지입니다.

BACKLOG.md

구현할 기능 목록을 우선순위별로 관리합니다.

## 우선순위: P0 (데이터 없으면 판단 오류)

- [ ] [NORMALIZATION-DXY] DXY 정규화 범위 재검토 — 현재 90~110 고정값...
- [x] [SP500-TREND] S&P500 점수화 개선 — 완료 루프 41

## 우선순위: P1 (실전 투자에 빠지면 아쉬운 것)

- [ ] [WEEKLY-SCORE-CHART] 주간/월간 점수 차트 — 예상 1루프

항목에는 식별자(태그), 설명, 예상 루프 수를 포함합니다. 완료된 항목은 [x]로 표시하고 완료 루프 번호를 기록합니다.

PROGRESS.md

루프별 완료 이력을 테이블 형태로 기록합니다.

이 파일이 있으면 Claude는 어디까지 구현되었는지를 파악하고, 중복 작업 없이 이어서 진행합니다.

MEMORY/*.md

세션 간 유지해야 할 피드백과 프로젝트 맥락을 개별 파일로 저장합니다.

memory/
├── feedback_db_data.md         # DB 데이터 초기화 금지
├── project_autotrade_focus.md  # 자동매매 위주 개발 전환
└── MEMORY.md                   # 인덱스 파일

각 파일은 아래 형식을 따릅니다.

---
name: DB 데이터 초기화 금지
type: feedback
---

truncate/delete-all/create-drop을 사용하지 않는다.
Why: 실데이터가 쌓인 운영 DB를 초기화한 적이 있어 복구 불가 손실 발생.

CLAUDE.md로 코딩 규칙 고정하기

루프가 수백 번 반복되어도 코드 스타일이 일관되게 유지되려면 CLAUDE.md에 규칙을 명문화해야 합니다. 프로젝트 루트에 CLAUDE.md를 두면 Claude는 매 작업 전에 이 파일을 참고합니다.

## 개발 규칙

- Double 대신 BigDecimal 사용 (부동소수점 오류 방지)
- 생성자 대신 정적 팩터리 메서드 (of, from, create)
- set 금지 → 초기화는 정적 팩터리, 변경은 changeXxx()
- 주석은 한글, 로그는 영어
- Early return 선호, 중첩 if 금지
- 미사용 import/메서드 주기적 제거

이 규칙들은 1,208번의 루프 동안 일관되게 적용되었습니다.

루프 검증 방법

구현 완료 여부를 확인하는 검증 단계는 세 가지입니다.

빌드 검증

./gradlew build

빌드 성공 여부를 PROGRESS.md에 ✅ BUILD OK 또는 ❌ BUILD FAIL로 기록합니다.

curl 검증

주요 API 엔드포인트에 curl 요청을 보내 응답을 확인합니다.

curl -s http://localhost:8080/api/dashboard | jq '.readinessScore'

브라우저 검증

Playwright로 스크린샷을 찍어 화면 렌더링과 JS 에러 여부를 확인합니다.

JS errors=0   # 이 결과가 각 루프의 최종 합격 기준

세 단계의 순서와, 중간에 실패했을 때의 처리를 그림으로 나타내면 아래와 같습니다.

눌러서 원본 크기로 보기

세 단계를 모두 통과해야 그 루프를 완료로 기록합니다. 어느 단계에서 실패하든 실패 내용을 PROGRESS.md에 남기기 때문에, 다음 루프가 그 기록을 읽고 원인부터 확인할 수 있습니다.

루프 운영 팁

1,208번의 루프를 돌리면서 얻은 운영 경험을 정리하면 아래와 같습니다.

P0부터 처리한다

백로그 항목에는 우선순위를 명확히 지정합니다. "데이터 없으면 판단 오류"가 P0, "있으면 편한 것"이 P1, "프로 수준"이 P2입니다. 항상 P0부터 처리해야 기반이 흔들리지 않습니다.

항목 하나를 너무 크게 만들지 않는다

하나의 백로그 항목이 2루프 이상으로 커지면 중간에 컨텍스트가 끊길 위험이 있습니다. "예상 1루프" 단위로 쪼개는 것이 안정적이었습니다.

배치 처리는 2개씩

비슷한 성격의 항목은 2개씩 묶어서 처리합니다. 루프 횟수를 줄이면서도 빌드 단위를 유지할 수 있습니다.

[BATCH-ANALYSIS-SCORE-1208a] 시장 심리 게이지
[BATCH-ANALYSIS-SCORE-1208b] 신호 신뢰도 지수

실패 시 즉시 PROGRESS.md에 기록한다

빌드 실패나 검증 실패가 발생하면 그 내용을 바로 기록합니다. 그래야 다음 루프에서 Claude가 실패 원인을 파악하고 이어서 진행할 수 있습니다.

마무리

오늘은 Ralph Loop의 기본 구조와 BACKLOG.md, PROGRESS.md, MEMORY/ 상태 파일 구성, CLAUDE.md로 코딩 규칙을 고정하는 방법, 루프 검증 방법과 운영 팁에 대해 정리하였습니다. Claude가 언제든 루프를 재개할 수 있도록 상태 파일을 잘 관리해 두면, 수백 번의 루프도 하나의 흐름으로 이어갈 수 있는 것 같습니다. 다음 글에서는 Claude Code를 실제로 어떻게 사용했나에 대해 정리하도록 하겠습니다.