/moai loop

자율 반복 수정 루프 명령어입니다. AI가 스스로 문제를 진단하고, 수정하고, 검증하는 과정을 오류가 모두 해결될 때까지 자동으로 반복합니다. /moai fix가 한 번만 고치는 것과 달리, 이쪽은 완료 조건(0 에러 · 테스트 통과 · 커버리지 85% 이상)을 채울 때까지 계속 돌기 때문에, 오류가 서로 얽혀 있을 때 특히 효과적입니다.

정보

한 줄 요약: /moai loop는 “Ralph Engine” 이라는 자율 수정 엔진입니다. 진단 → 수정 → 검증을 반복하여 코드의 모든 문제를 자동으로 해결합니다.

정보

슬래시 커맨드: Claude Code에서 /moai:loop를 입력하면 이 명령어를 바로 실행할 수 있습니다. /moai만 입력하면 사용 가능한 모든 서브커맨드 목록이 표시됩니다.

코드를 쓰다 보면 타입 오류, 린트 경고, 테스트 실패가 한꺼번에 몰려올 때가 있습니다. 이런 문제를 하나씩 손으로 고치는 대신 /moai loop를 실행하면 AI가 알아서 반복하며 전부 고칩니다.

/moai fix가 딱 한 번만 고치는 것과 달리, /moai loop는 완료 조건을 채울 때까지 계속 돕니다.

이 루프가 v3의 세 가지 핵심 중 하나인 에이전틱 루프 엔지니어링의 대표 사례입니다. 오류마다 사람이 끼어드는 대신 루프가 스스로 진단하고 고치며, 그 과정에서 남은 관찰은 하네스 학습(에이전틱 루프 엔지니어링)의 원료로 쌓입니다. 엔진 구현은 internal/ralph/engine.go에 있습니다. 반복마다 Decide()가 continue / converge / request_review / abort 중 하나를 우선순위 순으로 판정합니다.

/moai loop는 goal 엔진 위의 프리셋입니다. /moai goal "<조건>"이 사용자가 완료 조건을 직접 선언하는 범용 루프라면, /moai loop는 “진단 도구가 찾은 이슈 큐를 다 비울 때까지"라는 조건을 미리 채워 넣은 프리셋입니다.

/moai goal "go test ./... exits 0; 모든 AC가 PASS로 기록"
/moai goal status | clear

끝 상태를 조건식으로 표현할 수 있다면 /moai goal, “도구가 찾는 문제를 전부 없애줘"라면 /moai loop가 맞습니다.

> /moai loop

별도의 인수 없이 실행하면, 현재 프로젝트의 모든 문제를 자동으로 찾아 수정합니다.

반복 횟수를 제한합니다:

# 최대 20회까지 반복
> /moai loop --max 20

주의

무한 루프를 방지하기 위해 기본값은 10회입니다 (ralph.yaml의 loop.max_iterations). 반복 상한 우선순위는 CLI --max 플래그 > ralph.yaml loop.max_iterations > workflow.yaml loop_prevention.max_iterations 순입니다.

기본 스캔 렌즈 (LSP · lint · 테스트 실패 · 리뷰 렌즈 [보안, @MX])에 더해, opt-in 렌즈로 스캔 범위를 넓힙니다:

렌즈가 찾아낸 것만 큐에 담기며, 루프는 스캔된 큐 밖의 “지어낸 개선"에는 절대 손대지 않습니다.

/moai loop는 매 반복 (iteration)마다 다음 과정을 거칩니다.

flowchart TD
    Start["/moai loop 실행"] --> Diag

    subgraph Diag["1단계: 병렬 진단"]
        D1["LSP 진단
타입 오류 검사"]
        D2["AST-grep 진단
구조적 패턴 검사"]
        D3["테스트 실행
실패 테스트 탐지"]
        D4["커버리지 측정
85% 미만 확인"]
    end

    Diag --> Collect["2단계: 이슈 수집"]
    Collect --> Todo["3단계: TODO 생성
수정 작업 목록"]
    Todo --> Fix["4단계: 순차 수정
하나씩 안전하게 수정"]
    Fix --> Verify["5단계: 검증
수정 결과 확인"]
    Verify --> Check{완료 조건
충족?}
    Check -->|아니오| Diag
    Check -->|예| Done["루프 완료 명시"]

4가지 진단 도구가 동시에 실행되어 프로젝트의 모든 문제를 빠르게 파악합니다.

정보

병렬 진단이란? 4가지 진단을 동시에 실행하므로, 순차적으로 하나씩 실행하는 것보다 약 4배 빠릅니다. 이렇게 수집된 문제들은 하나의 목록으로 합쳐집니다.

병렬 진단에서 발견된 모든 문제를 하나의 목록으로 정리합니다.

발견된 이슈 (예시):
  [LSP] src/auth/service.py:42 - "str" 타입에 "int" 할당 불가
  [LSP] src/auth/router.py:15 - "User" 타입 미정의
  [AST] src/utils/helper.py:3 - 사용하지 않는 import "os"
  [TEST] tests/test_auth.py::test_login - AssertionError
  [COV] src/auth/service.py - 커버리지 62% (목표 85%)

모아 둔 이슈를 바탕으로 수정 작업 목록 (TODO) 을 만듭니다. 이때 의존성 순서를 따져 어느 것부터 고칠지 정합니다.

예를 들어 타입 정의가 빠져 있다면, 그 타입을 먼저 추가한 다음 그것을 쓰는 코드를 고칩니다.

TODO 목록의 항목을 하나씩 차례로 고칩니다. 한꺼번에 병렬로 고치면 서로 부딪힐 수 있어, 안전하게 하나씩 처리합니다.

수정이 끝나면 다시 진단을 실행하여 문제가 해결되었는지 확인합니다. 아직 남은 문제가 있으면 1단계로 돌아가 반복합니다.

무한 루프를 막는 안전장치가 두 가지 있습니다. 루프를 끝없이 돌리는 건 토큰 낭비이기도 하니, 이 장치는 안정성과 비용을 함께 지키는 셈입니다.

flowchart TD
    A[반복 실행] --> B{최대 반복
횟수 초과?}
    B -->|예: 상한 도달| C["강제 종료
5-섹션 판정 + 잔여 이슈 영속화"]
    B -->|아니오| D{N회 연속
무진전?}
    D -->|예: 동일 실패 반복| E["정체 감지
사용자 개입 요청"]
    D -->|아니오| F[다음 반복 계속]

주의

정체 상태가 발생하면? AI가 같은 실패 시그니처를 연속으로 해결하지 못하면, 자동으로 중단하고 5-섹션 증거 판정과 함께 사용자에게 개입을 요청합니다. 이 경우 오류 내용을 직접 확인하거나 힌트를 제공해주세요.

/moai loop는 다음 세 가지 조건을 모두 만족하면 루프를 종료합니다.

/moai fix와 /moai loop는 비슷해 보이지만, 핵심적인 차이가 있습니다.

flowchart TD
    subgraph Fix["/moai fix (일회성)"]
        F1[병렬 스캔] --> F2[이슈 수집]
        F2 --> F3[레벨 분류]
        F3 --> F4[수정]
        F4 --> F5[검증]
        F5 --> F6[완료]
    end

    subgraph Loop["/moai loop (반복)"]
        L1[병렬 진단] --> L2[이슈 수집]
        L2 --> L3[TODO 생성]
        L3 --> L4[순차 수정]
        L4 --> L5[검증]
        L5 --> L6{완료?}
        L6 -->|아니오| L1
        L6 -->|예| L7[완료]
    end

정보

선택 가이드: 오류가 몇 개 안 되면 /moai fix로 빠르게 해결하세요. 오류가 많거나 서로 연관된 문제가 있으면 /moai loop가 더 효과적입니다.

/moai loop 명령어의 에이전트 위임 흐름입니다:

flowchart TD
    User["사용자 요청"] --> Orchestrator["MoAI 오케스트레이터"]
    Orchestrator --> ManagerDDD["manager-develop 에이전트"]

    ManagerDDD --> Diagnose["병렬 진단"]
    Diagnose --> LSP["LSP"]
    Diagnose --> AST["AST-grep"]
    Diagnose --> Test["테스트"]
    Diagnose --> Cov["커버리지"]

    LSP --> Todo["TODO 생성"]
    AST --> Todo
    Test --> Todo
    Cov --> Todo

    Todo --> Loop["루프 시작"]

    Loop --> Fix["manager-develop에
수정 위임"]
    Fix --> Predicate{"기계적 완료 술어
(큐 소진 + 진단 clean)?"}
    Predicate -->|아니오| Loop
    Predicate -->|예| FinalPass["Step 1.5
독립 최종 검증"]
    FinalPass --> Done["완료"]

완료 판정: 기계적 술어 + 독립 최종 검증

루프가 성공으로 끝났는지는 기계적 완료 술어로 판정합니다. 이슈 큐가 비었는지, 진단(LSP/AST-grep/테스트/커버리지)이 깨끗한지를 오케스트레이터가 직접 확인합니다. 별도의 감사 에이전트(sync-auditor)가 완료를 판정하지는 않습니다.

술어가 충족되면 성공 종료 경로에서 Step 1.5 독립 최종 검증 (Independent Final Pass)이 돌아갑니다. /moai gate --fresh를 새 컨텍스트에서 돌리거나 read-only 검증 Agent를 띄워, 루프가 제 손으로 제 결과를 채점하지 않도록 최종 상태를 밖에서 확인합니다.

에이전트 역할:

/moai run으로 코드를 구현한 후, 여러 오류가 남아있는 상황을 가정합니다.

# 현재 상태 확인
$ pytest --tb=short
# 3개 테스트 실패
# 커버리지: 71%

# LSP 오류 확인
# 5개 타입 오류, 2개 미정의 참조

# loop 실행
> /moai loop

실행 로그:

[반복 1/10]
  진단: LSP 오류 5개, 테스트 실패 3개, 커버리지 71%
  TODO: 7개 수정 작업 생성
  수정: 타입 오류 5개 해결
  검증: LSP 오류 0개, 테스트 실패 2개, 커버리지 71%

[반복 2/10]
  진단: 테스트 실패 2개, 커버리지 71%
  TODO: 2개 수정 작업 생성
  수정: 테스트 로직 수정 2건
  검증: LSP 오류 0개, 테스트 실패 0개, 커버리지 74%

[반복 3/10]
  진단: 커버리지 74% (목표 85%)
  TODO: 3개 테스트 추가 작업 생성
  수정: 누락된 테스트 케이스 추가
  검증: LSP 오류 0개, 테스트 실패 0개, 커버리지 87%

완료 조건 충족!
  - LSP 오류: 0개
  - 테스트: 모두 통과
  - 커버리지: 87%

DONE

이 예시에서 /moai loop는 3회 반복만에 모든 문제를 해결했습니다. 손으로 했다면 오류를 하나씩 확인하고 고쳐야 했을 일입니다.

--max 플래그로 반복 횟수를 제한하거나, Ctrl+C로 중단할 수 있습니다. 현재 상태가 저장되므로 나중에 다시 시작할 수 있습니다.

--errors 플래그로 오류만 수정하고 경고를 건너뛰거나, --lens 플래그로 스캔 범위를 조정하세요:

# 오류만 수정 (경고 건너뜀)
> /moai loop --errors

# 데드 코드·커버리지 렌즈 추가
> /moai loop --lens clean,coverage

/moai loop는 오류 수정 루프만 담당합니다. /moai는 SPEC 생성부터 구현, 문서화까지 전체 워크플로우를 자동으로 수행합니다.

/moai loop는 진단 도구 (LSP, 테스트, 린터)가 찾은 이슈를 없애는 것이 목표이고, /moai goal은 사용자가 선언한 임의의 완료 조건 (예: “AC-001~AC-010 모두 달성”)을 향해 턴을 이어갑니다. /moai loop는 goal 엔진의 프리셋입니다.

AI가 동일 실패 시그니처를 N회 연속 해결하지 못하면 (정체 감지) 자동으로 중단하고 5-섹션 증거 판정과 함께 사용자에게 개입을 요청합니다. 이 경우 직접 코드를 확인하거나 힌트를 제공해주세요.

• /moai fix - 일회성 자동 수정
• /moai - 완전 자율 자동화
• TRUST 5 품질 시스템
• 도메인 주도 개발