[2편 - Ralph Loop 설계하기]에 이어, Claude Code를 실제 개발에서 어떻게 활용했는지를 다룹니다. 어떻게 지시했는지, 실수가 발생했을 때 어떻게 대응했는지, 그리고 1,200번 이상의 루프 동안 품질을 유지한 방법을 정리합니다.
역할 분리 — 에이전트 전문화
Claude Code에게 "다 해줘"라고 하면 일관성이 떨어집니다. 이 프로젝트에서는 작업 종류에 따라 전문 에이전트를 분리했습니다.
각 에이전트는 자신이 담당하는 레이어만 구현합니다.
에이전트 | 담당 |
domain-developer | 도메인 모델 TDD 구현 |
application-developer | 유스케이스, 포트 인터페이스 |
adapter-developer | 컨트롤러, 템플릿, API 클라이언트, 스케줄러 |
test-engineer | 통합 테스트, 커버리지 검증 |
build-architect | Gradle 설정, CI/CD |
이 역할은 CLAUDE.md의 하네스 섹션에 정의해두고, Claude가 작업 전에 참고하도록 했습니다.
CLAUDE.md — AI에게 주는 일관된 지침
CLAUDE.md는 프로젝트 루트에 두는 파일입니다. Claude Code는 작업을 시작하기 전에 이 파일을 자동으로 읽습니다.
핵심 규칙을 여기에 적어두면 매 루프마다 같은 스타일로 코드를 작성합니다.
## 개발 규칙
- Double 대신 BigDecimal 사용
- 생성자 대신 정적 팩터리 메서드 (of, from, create)
- set 금지 → 변경은 changeXxx() 메서드
- 주석은 한글, 로그는 영어
- Early return 선호, 중첩 if 금지
- 미사용 import/메서드 주기적으로 제거
Markdown
복사
1,208번의 루프 동안 이 규칙이 지켜진 이유는 매번 사람이 검토해서가 아니라, Claude가 매 루프 시작 시 이 파일을 읽었기 때문입니다.
백로그 항목을 어떻게 작성했나
백로그 항목의 품질이 곧 구현 품질입니다. 항목을 모호하게 쓰면 Claude도 모호하게 구현합니다.
좋지 않은 예시
- [ ] 분석 페이지 지표 추가
Markdown
복사
잘 작성된 예시
- [ ] [BATCH-ANALYSIS-SCORE-RSI] loadScoreScoreStochasticRsi 구현
— 14D RSI에 14D 스토캐스틱 적용, %K/%D 골든/데드크로스 신호 반환
— analysis.html 패널 1개 추가
— 예상 0.5루프
Markdown
복사
항목에는 식별자 태그, 구체적인 동작 설명, 영향 범위, 예상 루프 수를 포함했습니다. Claude는 이 정보를 바탕으로 어디에 무엇을 어떻게 구현할지 스스로 판단했습니다.
컨텍스트 유지 — 세션이 끊겨도 이어가기
Claude Code는 대화 세션이 끊기면 이전 내용을 기억하지 못합니다. 1,200번이 넘는 루프를 진행하면서 이 문제를 해결한 방법은 상태 파일입니다.
PROGRESS.md
완료된 루프를 매번 기록합니다.
루프# | 날짜 | 완료 항목 | 빌드 | 검증 |
1208 | 2026-05-22 | [SEASON-SCORE-ENHANCE] 시즌별 점수 개선 |  | curl OK |
1207 | 2026-05-22 | [SEASON-SCORE-FIX] 시즌별 점수 로직 재설계 | | curl OK |
새 루프를 시작할 때 Claude는 이 파일을 읽고 "1208번까지 완료됐으니 1209번을 시작한다"는 것을 스스로 파악합니다.
MEMORY/ 폴더
세션 간 유지해야 할 결정 사항을 개별 파일로 저장합니다.
# feedback_db_data.md
DB 데이터는 절대 초기화하지 않는다.
Why: 실데이터가 쌓인 운영 DB를 초기화한 적이 있어 복구 불가 손실 발생.
Markdown
복사
Claude가 실수를 반복하거나 잊으면 안 되는 결정이 생길 때마다 이 폴더에 파일을 추가했습니다.
AI가 실수했을 때
Claude Code도 실수를 합니다. 주로 발생한 패턴과 대응 방법입니다.
빌드 실패
빌드가 실패하면 Claude는 에러 로그를 읽고 스스로 수정합니다. 대부분 한두 번의 시도로 해결됩니다. 이 과정도 자동으로 진행되므로 개입이 필요하지 않았습니다.
이미 있는 기능을 다시 구현
간혹 이미 구현된 기능을 중복으로 만드는 경우가 있었습니다. 백로그에 SKIP 태그를 추가해 명시적으로 건너뛰도록 했습니다.
- [x] [BATCH-ANALYSIS-SCORE-TREND-CONSISTENCY](SKIP 이미구현)
→ 다음 배치로 이동
Markdown
복사
규칙을 어긴 코드 작성
BigDecimal 대신 double을 쓰거나, setter를 사용한 경우가 드물게 있었습니다. 이때는 MEMORY/ 폴더에 해당 피드백을 기록했습니다.
# feedback_no_setter.md
setter 대신 changeXxx() 메서드를 사용한다.
Why: 루프 843에서 setter가 혼입되어 값 변경 의도가 불명확해진 사례 발생.
Markdown
복사
다음 루프부터 Claude는 이 파일을 읽고 같은 실수를 반복하지 않았습니다.
브라우저 검증으로 품질 확보
빌드 성공이 곧 완성은 아닙니다. 화면이 제대로 렌더링되는지, JS 에러가 없는지도 확인해야 합니다.
매 루프 끝에 Playwright로 스크린샷을 찍고 JS 에러를 확인했습니다.
JS errors=0 # 루프 합격 기준
Plain Text
복사
이 검증 덕분에 수백 개의 지표를 추가하면서도 조용히 깨진 화면이 누적되지 않았습니다.
배치 처리로 효율 높이기
비슷한 성격의 항목은 2개씩 묶어서 처리했습니다.
[BATCH-ANALYSIS-SCORE-1208a] 시장 심리 게이지
[BATCH-ANALYSIS-SCORE-1208b] 신호 신뢰도 지수
→ 두 항목을 하나의 루프에서 처리
Markdown
복사
루프 횟수를 절반으로 줄이면서도 빌드 단위를 유지할 수 있었습니다. 분석 페이지에 300개 이상의 파생 지표를 추가한 것도 이 방식 덕분입니다.
결론
Claude Code를 잘 활용하기 위해 중요한 것은 세 가지입니다.
•
CLAUDE.md로 코딩 규칙을 고정한다
•
상태 파일로 세션이 끊겨도 컨텍스트가 유지되게 한다
•
백로그 항목을 구체적으로 작성한다
AI에게 모호한 지시를 주면 모호한 결과가 나옵니다. 규칙과 상태를 잘 정의해두면 AI는 그것을 일관되게 따릅니다.
다음 글에서는 자동매매 시스템을 AI와 함께 설계한 과정을 다룰 예정입니다.