/moai

/moai는 자연어로 던진 요청 하나로 SPEC 생성부터 구현, 문서화까지 전 과정을 잇는 완전 자율 자동화 명령어입니다. 사용자가 “무엇을 만들고 싶은지"를 말하면, MoAI가 plan → run → sync 파이프라인을 스스로 돌려 결과물을 내놓습니다. 파이프라인 중간에는 plan-auditor 감사와 구현 착수 승인 같은 휴먼 게이트가 있어, 자율이라고 해서 무방비로 끝까지 달리는 것은 아닙니다. 따라서 “기능 하나를 통째로 맡기고 싶을 때” 가장 먼저 떠올리는 명령어입니다.

정보

한 줄 요약: /moai는 “완전 자율 자동화” 명령어입니다. 사용자는 원하는 기능을 자연어로 설명하기만 하면, MoAI가 SPEC 생성부터 구현, 문서화까지 모든 과정을 자동으로 수행합니다.

플랫폼 기초

플랫폼 계층의 배경 설명은 세션 관리에 있습니다. MoAI-ADK 기준 설명은 이 문서입니다.

정보

슬래시 커맨드 지원: MoAI의 모든 서브커맨드는 스킬로 래핑되어 있어, /moai만 입력하면 사용 가능한 서브커맨드 목록이 표시됩니다. 각 서브커맨드는 /moai:fix, /moai:loop, /moai:review 등의 형식으로 바로 실행할 수도 있습니다.

/moai는 MoAI-ADK의 완전 자율 자동화 워크플로우 명령어입니다. 하위 명령어를 따로 실행할 필요 없이, 명령 한 번으로 개발 과정 전체가 이어집니다:

1. SPEC 생성 (manager-spec)
2. DDD/TDD 구현 (manager-develop — quality.yaml의 development_mode에 따라)
3. 문서 동기화 (manager-docs)

v3부터 /moai의 기본 라우팅은 Analyze-First, 즉 언어에 얽매이지 않는 의도 분석입니다. 영어 키워드를 맞춰 보는 것이 아니라 요청의 의미를 분류하므로, 어떤 conversation_language로 요청해도 같은 품질로 라우팅됩니다.

라우팅은 다음 순서로 진행됩니다:

1. 의도 분석: 사용자 요청의 의도를 분류 (입력 언어와 무관)
2. 컨텍스트 충분성 확인: 불충분하면 Socratic 인터뷰로 명확화
3. 실행 계획 구성: 스킬 / 에이전트 / 동적 워크플로우 체인 선택
4. 오케스트레이션 모드 선택 (Phase 4): 4-모드 카탈로그 (direct / serial / fanout / sweep; agent-team은 명시적 요청 전용 실험적 각주) 중 자율 선택

즉 /moai "로그인 버그 고쳐줘"처럼 서브커맨드 없이 자연어만 입력해도, 의도 분석을 거쳐 알맞은 워크플로우 (수정이면 fix 계열, 신규 기능이면 plan→run→sync 파이프라인)로 연결됩니다.

기본 파이프라인은 네 개의 명명된 게이트를 순서대로 통과합니다:

1. Plan-audit 게이트 (plan-auditor): SPEC 계획 산출물을 따로 감사하고, FAIL이나 INCONCLUSIVE면 중단
2. 구현 착수 승인 (plan→run 휴먼 게이트): 파이프라인에 진입할 때마다 정확히 1회, 점수와 무관하게 항상 사용자 승인을 받음
3. Phase 4 모드 선택 (4-모드 카탈로그): 구현 착수 승인 이후 자율 선택, progress.md에 기록
4. Sync-audit 게이트 (sync-auditor): 동기화 결과를 4차원으로 평가하고, FAIL이나 INCONCLUSIVE면 체인 중단

# 기본 사용법
> /moai "구현하고 싶은 기능 설명"

# 브랜치와 함께
> /moai "기능 설명" --branch

# 루프 모드 활성화
> /moai "기능 설명" --loop

# 기존 SPEC 재개
> /moai --resume SPEC-AUTH-001

구현이 끝나면 반복 수정을 자동으로 돌려 남은 오류를 모두 고칩니다:

> /moai "JWT 인증 시스템" --loop

이 옵션을 사용하면:

1. SPEC 생성
2. DDD 구현
3. 자동 루프 실행 (LSP 오류, 테스트 실패, 커버리지 부족 해결)
4. 문서 동기화
5. PR 생성

정보

--loop 옵션은 구현 후 정리 작업까지 자동으로 처리하므로 손이 갈 일이 크게 줄어듭니다.

플래그 없이 실행하면 MoAI가 작업 규모를 보고 오케스트레이션 모드를 자동 선택합니다. 모드는 동시 스폰 수를 축으로 하는 4개 카탈로그(direct / serial / fanout / sweep)입니다:

자동 선택 기준 (플래그 없을 때):

• 영향 도메인 >= 3개 → fanout (병렬 실행)
• 수정 파일 >= 10개 → fanout (병렬 실행)
• 복잡도 점수 >= 7 → fanout (병렬 실행)
• 그 외 → serial (순차 실행, 기본 폴백)

정보

Agent Teams — 실험적 재허용: v3.0.0에 은퇴했던 Agent Teams는 실험적 표면으로 재허용되었습니다. 명시적 --team 요청이 네이티브 teammate 런타임을 선택하며, 자동 선택은 없습니다. 은퇴 시절 --team을 강제하면 MODE_TEAM_UNAVAILABLE을 알리며 하위 에이전트 모드로 폴백했고, 이 센티널은 문서화된 역사로 남아 있습니다. Tier L 조정은 manager-lead이, 병렬 조사는 fanout과 sweep이 담당합니다.

병렬 실행은 에이전트마다 독립 컨텍스트 윈도우를 쓰므로 토큰을 그만큼 더 씁니다. 도메인 하나짜리 단순한 작업이라면 --solo (순차)가 더 경제적입니다. 규모를 보고 자동으로 고르는 방식이 기본값인 이유입니다.

/moai가 내부적으로 수행하는 전체 과정입니다:

flowchart TD
    A["명령어 실행
/moai '기능 설명'"] --> B{--resume?}
    B -->|예| C["SPEC 로드
이어서 작업"]
    B -->|아니오| D["Phase 0
병렬 탐색"]

    subgraph D["Phase 0: 병렬 탐색 (15-30초)"]
        D1["Explore 하위 에이전트
코드베이스 분석"]
        D2["Research 하위 에이전트
외부 문서 조사"]
        D3["Quality 하위 에이전트
품질 기준선 확인"]
    end

    D --> E{"단일 도메인?"}
    E -->|예| F["전문가 에이전트에
직접 위임"]
    E -->|아니오| G["Phase 1 계속"]

    C --> G["Phase 1
SPEC 생성"]
    G --> H["manager-spec 호출"]
    H --> I["GEARS 형식 SPEC 생성"]
    I --> J[".moai/specs/SPEC-XXX/spec.md"]

    J --> K["Phase 2
DDD 구현"]

    K --> L["manager-develop 호출
DDD/TDD 순환 (quality.yaml에 따라)"]
    L --> M{"구현 완료?"}
    M -->|아니오| L
    M -->|예| N{"--loop?"}

    N -->|예| O["자동 루프 실행"]
    O --> P["모든 문제 해결"]
    N -->|아니오| P

    P --> Q["Phase 3
문서 동기화"]

    Q --> R["manager-docs 호출
문서 생성"]
    R --> S{"--pr?"}
    S -->|예| T["PR 생성"]
    S -->|아니오| U["완료 신호"]
    T --> U

핵심 포인트:

• Phase 0 (병렬 탐색): 세 에이전트가 동시에 실행되어 2-3배 속도 향상
• 단일 도메인 라우팅: 단순 작업은 전문가 에이전트에 곧바로 넘겨 SPEC 단계를 건너뜀
• 완료 신호: 작업이 끝나면 완료 보고서에 그 사실을 분명히 적음

세 에이전트가 동시에 실행되어 프로젝트 맥락을 빠르게 파악합니다:

속도 향상: 병렬 실행으로 순차 실행 대비 2-3배 빠름 (15-30초 vs 45-90초)

단일 도메인 라우팅:

• 단일 도메인 작업 (예: “SQL 최적화”): SPEC 생성 없이 전문가 에이전트에 직접 위임
• 다중 도메인 작업: 전체 워크플로우 진행

manager-spec 하위 에이전트가 GEARS 형식 SPEC 문서를 생성합니다:

• .moai/specs/SPEC-XXX/spec.md
• GEARS 형식 요구사항
• Given-When-Then 인수 기준
• conversation_language로 작성된 콘텐츠

정보

GEARS 형식이 현재 SPEC 요구사항의 정식 형식입니다. 예전 문서·구성에서 보이는 EARS는 레거시 명칭이며, GEARS로 대체되었습니다.

manager-develop 하위 에이전트가 SPEC을 기반으로 구현을 수행합니다:

• DDD 순환: ANALYZE-PRESERVE-IMPROVE (기존 코드 리팩토링)
• TDD 순환: RED-GREEN-REFACTOR (새 기능 개발)
• 도메인 컨텍스트 자동 주입 (백엔드, 프론트엔드, 보안, 데이터베이스 등)

quality.yaml development_mode 설정:

• development_mode: ddd → DDD 순환 사용 (기존 코드 개선)
• development_mode: tdd → TDD 순환 사용 (새 기능 개발, 기본값)

루프 동작 (–loop 또는 loop.enabled가 true일 때):

문제가 존재 AND 반복 < 최대값:
  1. 진단 실행 (LSP 오류, 테스트 실패, 커버리지)
  2. manager-develop에 수정 위임
  3. 수정 결과 검증
  4. 완료 조건 충족 여부 확인
  5. 완료 문장 감지 시 루프 종료

manager-docs 하위 에이전트가 구현과 문서를 동기화합니다:

• API 문서 생성
• README 업데이트
• CHANGELOG 추가
• 성공 시 작업 완료를 명시

[HARD] TodoWrite 도구 필수: 모든 작업 추적에 TodoWrite를 써야 합니다

• 이슈 발견 시: TodoWrite (pending 상태)
• 작업 시작 전: TodoWrite (in_progress 상태)
• 작업 완료 후: TodoWrite (completed 상태)
• TODO 목록을 텍스트로 출력 금지

모든 워크플로우 단계가 무사히 끝나면, MoAI는 완료 보고서(배너/서술형)에 작업이 끝났음을 분명히 적습니다.

MoAI-ADK가 비용을 줄이는 장치 중 하나입니다. llm.yaml 설정에 따라 단계마다 Claude와 GLM을 자동으로 갈라 씁니다. 전략과 계획은 Claude가 맡고, 물량이 많은 구현은 값싼 GLM에 넘기는 식으로 섞어 쓸 수 있습니다.

1단계: 명령어 실행

> /moai "JWT 기반 사용자 인증 시스템: 회원가입, 로그인, 토큰 갱신" --loop --pr

정보

파이프라인은 워크트리를 만들지 않습니다. 격리된 워크트리에서 작업하려면 moai cc -w <이름>으로 먼저 진입한 뒤 그 안에서 명령을 실행하세요.

2단계: Phase 0 - 병렬 탐색

[병렬 탐색 시작]
  Explore 하위 에이전트: src/auth/ 분석 중...
  Research 하위 에이전트: JWT best practices 조사 중...
  Quality 하위 에이전트: 테스트 커버리지 32% 확인...

[탐색 완료 - 23초]
  발견 파일: 4개
  권장 라이브러리: PyJWT, bcrypt
  기준선: LSP 0 오류, 커버리지 32%

3단계: Phase 1 - SPEC 생성

[manager-spec 호출]
  SPEC ID: SPEC-AUTH-001
  요구사항: 5개 (GEARS 형식)
  인수 기준: 3개 시나리오

  사용자 승인: 완료

4단계: Phase 2 - DDD 구현

[manager-spec]
  작업 분해: 7개 태스크
  전략 계획 완료

[manager-develop]
  ANALYZE: 코드 구조 분석 완료
  PRESERVE: 특성화 테스트 12개 작성
  IMPROVE: 7개 태스크 구현 완료

[sync-auditor]
  TRUST 5: 다섯 가지 요소 모두 통과
  커버리지: 89%
  상태: PASS

5단계: 자동 루프 (–loop)

[루프 시작 - 반복 1/100]
  진단: 타입 오류 2개 발견
  수정: manager-develop 하위 에이전트에 위임
  검증: 모든 오류 해결됨

[루프 종료 - 1회 반복]
  완료 조건 충족!

6단계: Phase 3 - 문서 동기화

[manager-docs]
  API 문서: docs/api/auth.md 생성
  README: 사용법 섹션 업데이트
  CHANGELOG: v1.1.0 항목 추가
  SPEC-AUTH-001: ACTIVE → COMPLETED

7단계: 완료

[완료]
  SPEC: SPEC-AUTH-001
  커밋: 7개
  테스트: 36/36 통과
  커버리지: 89%
  PR: #42 생성 (Draft → Ready)

  → 완료 보고서(Completion Report) 배너로 작업 완료를 명시

구현 후 자동으로 모든 오류를 수정하고 싶을 때 사용합니다. 특히 대규모 리팩토링 후 정리 작업에 유용합니다.

단일 도메인 작업 (예: “SQL 쿼리 최적화”)은 SPEC 생성 없이 해당 도메인 전문가 에이전트에 직접 위임하여 시간을 절약합니다.

네. Analyze-First 라우팅은 언어 독립적 의도 분석이므로, 한국어·일본어·중국어 등 어떤 언어로 요청해도 동일하게 동작합니다.

• /moai plan - SPEC 생성 상세
• /moai run - DDD 구현 상세
• /moai sync - 문서 동기화 상세
• /moai loop - 반복 수정 루프 상세
• /moai fix - 일회성 자동 수정 상세