/moai fix

일회성 자동 수정 명령어입니다. 코드의 오류를 병렬로 스캔한 후 한 번에 수정합니다.

정보

한 줄 요약: /moai fix는 “빠른 청소 도구” 입니다. 코드에 쌓인 린트 오류, 타입 오류를 한 번에 쓸어담아 수정합니다.

정보

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

개발하다 보면 import 정렬이 흐트러지고, 타입이 맞지 않고, 린트 경고가 쌓입니다. 이런 문제를 하나씩 찾아 고치는 대신 /moai fix를 실행하면 AI가 알아서 찾아 고칩니다.

/moai loop와 달리 딱 한 번만 돌기 때문에, 지금 상태를 빠르게 깨끗이 만들고 싶을 때 알맞습니다. 루프 계열에서 보면 /moai fix는 단발 (1회) 프리셋입니다. 반복할 것도 없이 뻔한 오류에 루프를 돌리는 건 토큰 낭비입니다. 일의 크기에 맞는 가장 싼 도구를 고르는 편이 비용을 아낍니다.

> /moai fix

별도의 인수 없이 실행하면, 현재 프로젝트의 오류를 스캔하고 가능한 것을 자동 수정합니다.

수정 없이 어떤 변경이 이루어질지 미리 볼 수 있습니다:

> /moai fix --dry

이 옵션을 사용하면 실제 코드를 수정하지 않고, 발견된 이슈와 예상 변경사항만 표시합니다.

수정할 레벨을 제한합니다:

# Level 1-2만 수정 (포맷팅, 린트)
> /moai fix --level 2

# Level 1만 수정 (포맷팅만)
> /moai fix --level 1

/moai fix는 5단계로 실행됩니다.

flowchart TD
    Start["/moai fix 실행"] --> Scan

    subgraph Scan["1단계: 병렬 스캔"]
        S1["LSP 스캔
타입 오류 검사"]
        S2["AST-grep 스캔
구조적 패턴 검사"]
        S3["Linter 스캔
코드 스타일 검사"]
    end

    Scan --> Collect["2단계: 이슈 수집"]
    Collect --> Classify["3단계: 레벨 분류
(Level 1~4)"]
    Classify --> Fix["4단계: 자동/승인 수정"]
    Fix --> Verify["5단계: 검증"]
    Verify --> Done["완료"]

3가지 도구가 동시에 코드를 스캔합니다.

스캔 결과를 하나의 목록으로 합칩니다.

발견된 이슈 (예시):
  [Level 1] src/api/router.py:3 - import 정렬 필요
  [Level 1] src/models/user.py:15 - 불필요한 공백
  [Level 2] src/utils/helper.py:8 - 사용하지 않는 변수 "temp"
  [Level 2] src/auth/service.py:22 - 불필요한 else 구문
  [Level 3] src/auth/service.py:45 - 누락된 에러 처리
  [Level 4] src/db/connection.py:12 - SQL Injection 가능성

모은 이슈를 위험도에 따라 4단계로 나눕니다. 레벨에 따라 자동으로 고칠지 말지가 갈립니다. 안전한 것은 기계가 처리하고, 위험한 것은 사람의 승인을 받습니다. 자율성과 안전 게이트를 나란히 두는 하네스 설계 원칙이 여기에도 그대로 적용됩니다.

flowchart TD
    Issue[발견된 이슈] --> L1{Level 1?}
    L1 -->|예| Auto1["자동 수정
승인 불필요"]
    L1 -->|아니오| L2{Level 2?}
    L2 -->|예| Auto2["자동 수정
로그만 기록"]
    L2 -->|아니오| L3{Level 3?}
    L3 -->|예| Approve3["사용자 승인 후
수정"]
    L3 -->|아니오| Approve4["사용자 승인 필수
수동 검토 권장"]

코드의 동작에 영향을 주지 않는 형식적인 문제입니다. AI가 자동으로 수정합니다.

실제 수정 예시:

# 수정 전 (Level 1 이슈)
import os
import sys
from pathlib import Path
import json

# 수정 후 (자동 수정)
import json
import os
import sys
from pathlib import Path

코드 품질에 영향을 주는 경미한 문제입니다. AI가 자동으로 수정하고 로그를 남깁니다.

실제 수정 예시:

# 수정 전 (Level 2 이슈)
def get_user(user_id):
    result = db.query(user_id)
    if result:
        return result
    else:           # 불필요한 else
        return None

# 수정 후 (자동 수정)
def get_user(user_id):
    result = db.query(user_id)
    if result:
        return result
    return None

코드의 동작을 변경할 수 있는 문제입니다. 사용자의 승인을 받은 후 수정합니다.

사용자에게 보여주는 내용:

[Level 3] src/auth/service.py:45
  문제: 인증 실패 시 에러 처리가 누락되어 있습니다
  제안: try-except 블록을 추가하여 인증 실패 시 적절한 에러 응답을 반환합니다

  승인하시겠습니까? (y/n)

보안에 영향을 미치는 심각한 문제입니다. 반드시 사용자의 승인이 필요하며, 수동 검토를 권장합니다.

주의

Level 4 이슈가 발견되면 AI가 자동으로 수정하지 않습니다. 보안 취약점은 잘못 수정하면 더 큰 문제를 만들 수 있으므로, 반드시 직접 확인한 후 수정하세요.

정보

선택 가이드:

• “커밋 전에 린트 오류만 빠르게 정리하고 싶다” → /moai fix
• “테스트 실패가 많아서 전부 고치고 싶다” → /moai loop

/moai fix는 단발 (1회) 파이프라인이라, 스캔-수정-검증을 한 바퀴 돌려도 끝나지 않는 이슈가 남을 수 있습니다. 이런 것들이 남습니다:

• Level 4 수동 항목 (보안·아키텍처 — 자동 수정 금지)
• 미해결 오류 (repair 단계에서 고치지 못한 항목)
• Phase 5 회귀 가드 실패 (되돌리지도 보고하지도 못한 회귀)

이런 잔여가 남으면 fix 워크플로우는 이를 .moai/state/loop-verdict-<id>.json에 exit_kind: "one-shot-residue", iterations_used: 1로 영속화합니다. 이 스키마는 /moai loop의 잔여 영속화 스키마와 동일합니다.

보고서는 다시 손볼 여지가 있는 잔여에 대해 /moai loop로 넘어가라고 제안만 합니다. fix 워크플로우가 /moai loop나 다른 서브커맨드를 알아서 부르지는 않습니다. 사용자가 직접 /moai loop로 들어가면 저장해 둔 잔여가 루프의 스캔 큐에 항목으로 들어가고, goal 프리셋 스윕이 이를 비웁니다.

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

flowchart TD
    User["사용자 요청"] --> Orchestrator["MoAI 오케스트레이터"]
    Orchestrator --> Parallel["병렬 스캔"]

    Parallel --> LSP["LSP 스캔"]
    Parallel --> AST["AST-grep 스캔"]
    Parallel --> Linter["Linter 스캔"]

    LSP --> Collect["이슈 수집"]
    AST --> Collect
    Linter --> Collect

    Collect --> Classify["레벨 분류"]
    Classify --> Fix["수정 실행"]

    Fix --> Level12["Level 1-2
자동 수정"]
    Fix --> Level34["Level 3-4
승인 필요"]

    Level12 --> Verify["검증"]
    Level34 --> UserApprove["사용자 승인"]
    UserApprove --> Verify

    Verify --> Complete["완료"]

에이전트 역할:

Level 1 포매터 정리(gofmt/prettier/ruff format 등)는 오케스트레이터가 에이전트를 띄우지 않고 직접 합니다. 수정 결과 확인도 별도 감사 에이전트에 맡기지 않고, 오케스트레이터가 스캐너(LSP/AST-grep/린터)를 다시 돌려 봅니다.

새로운 기능을 구현한 후, 커밋하기 전에 코드를 정리하고 싶은 상황입니다.

# 현재 상태 확인
$ ruff check src/
# 12개 린트 경고 발견

# fix 실행
> /moai fix

실행 로그:

[병렬 스캔]
  LSP: 오류 2개 발견
  AST-grep: 패턴 위반 3개 발견
  Linter: 경고 12개 발견

[이슈 분류]
  Level 1 (포맷팅): 7개 → 자동 수정
  Level 2 (린트): 8개 → 자동 수정
  Level 3 (로직): 2개 → 승인 필요
  Level 4 (보안): 0개

[Level 1-2 자동 수정 완료]
  - import 정렬 5건
  - 후행 공백 제거 2건
  - 사용하지 않는 변수 제거 3건
  - 불필요한 else 제거 2건
  - 타입 힌트 수정 2건
  - 네이밍 규칙 수정 1건

[Level 3 승인 요청]
  이슈 1: src/auth/service.py:45
    문제: 토큰 만료 시 에러 처리 누락
    제안: TokenExpiredError 예외 처리 추가
    → 승인됨: 수정 완료

  이슈 2: src/api/router.py:78
    문제: 입력 값 검증 누락
    제안: Pydantic 모델로 입력 검증 추가
    → 승인됨: 수정 완료

[검증]
  LSP 오류: 0개
  Linter 경고: 0개
  모든 수정이 검증되었습니다.

완료: 17개 이슈 수정됨

네, Level 3-4 이슈는 각각 승인이 필요합니다. 하지만 --dry로 먼저 확인하고, 중요한 것만 승인할 수도 있습니다.

Git으로 되돌릴 수 있습니다. 수정 전에 커밋하거나, git stash로 백업해두는 것이 좋습니다.

/moai fix가 잔여 이슈 (Level 4 수동 항목, 미해결 오류, Phase 5 회귀 가드 실패) 를 남긴 채 끝나면, 남은 항목은 .moai/state/loop-verdict-<id>.json에 exit_kind: "one-shot-residue"로 저장됩니다. 보고서는 다시 손볼 여지가 있는 잔여에 대해 /moai loop로 넘어가라고 제안만 하고 (알아서 부르지는 않습니다), 사용자가 /moai loop로 들어가면 이 잔여가 루프 큐에 스캔 항목으로 들어갑니다.

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

• /moai loop - 반복 수정 루프
• /moai - 완전 자율 자동화
• TRUST 5 품질 시스템