자주 묻는 질문

MoAI-ADK 를 처음 쓰면서 자주 겪는 혼동 포인트를 모았습니다. 대부분은 “두 가지를 헷갈렸다” 에서 출발합니다 — 터미널 명령과 슬래시 명령을 바꿔 쓰거나, statusline 표시의 의미를 잘못 읽거나, 설정 파일이 어디에 저장되는지 몰라 헤매는 식입니다. 이 페이지는 그런 첫 질문들을 한자리에 둡니다.

각 질문은 독립적으로 읽어도 이해되도록 답을 썼습니다. 위에서부터 순서대로 읽지 않아도 됩니다 — 필요한 질문으로 바로 건너뛰세요. 더 깊은 배경이 필요한 답에는 관련 페이지 링크를 달아 두었습니다.

MoAI-ADK 의 설계는 “세 가지 핵심(토크노믹스 · 에이전틱 루프 엔지니어링 · 에이전틱 하네스)이 하나의 계통 안에서만 작동한다” 는 전제 위에 서 있습니다. 이 아래의 질문들도 결국 이 세 가지 중 하나로 돌아갑니다 — 비용 통제는 토크노믹스의 결과이고, 설정 보존과 학습 축적은 루프 엔지니어링의 재료이며, 품질 게이트는 하네스가 책임지는 영역입니다.

완전히 다른 두 가지입니다. 가장 흔한 혼동이니 먼저 짚고 갑니다.

• 터미널에서 moai plan을 실행하면 동작하지 않습니다 — /moai plan은 Claude Code 안에서만 유효합니다.
• Claude Code에서 /moai init을 입력해도 동작하지 않습니다 — moai init은 터미널 명령입니다.

MoAI statusline은 버전 정보와 업데이트 알림을 함께 표시합니다:

🗿 v3.1.2 -> 🗿 v3.1.3

• 🗿 v3.1.2: 현재 설치된 버전
• -> 🗿 v3.1.3: 업데이트 가능한 새 버전 (ASCII 화살표 ->로 이어집니다)

최신 버전을 사용 중일 때는 버전 번호만 표시됩니다:

🗿 v3.1.3

업데이트 방법: moai update 실행 시 업데이트 알림이 사라집니다.

정보

참고: Claude Code의 빌트인 버전 표시(🔅 v2.1.172)와는 다릅니다. MoAI 표시는 MoAI-ADK 버전을 추적하며, Claude Code는 자체 버전을 별도로 표시합니다.

statusline은 세그먼트 단위로 켜고 끌 수 있습니다. 각 세그먼트를 따로 토글해 원하는 정보만 남기세요. 디스플레이 프리셋은 따로 없고, 테마와 세그먼트 두 가지만으로 구성합니다.

moai init 또는 moai update -c 마법사에서 설정하거나, .moai/config/sections/statusline.yaml을 직접 편집합니다:

statusline:
  segments:
    model: true
    context: true
    output_style: false
    directory: false
    git_status: true
    claude_version: false
    moai_version: false
    git_branch: true

segments: 블록이 없으면 기본적으로 모든 세그먼트가 활성화됩니다.

정보

자세한 내용은 SPEC-STATUSLINE-001을 참조하세요.

MoAI-ADK는 Claude Code 구독 요금제에 맞춰 에이전트에 최적의 AI 모델을 할당합니다. 요금제의 사용량 한도 안에서 품질을 최대한 끌어올리는 토크노믹스 장치입니다.

주의

왜 중요한가요? 티어를 낮춘다는 것은 모델 클래스가 아니라 추론 깊이를 낮춘다는 뜻입니다. 오래 이어지는 에이전틱 작업에서는 Opus의 low effort가 어떤 effort의 Sonnet보다도 점수가 높고 작업당 비용도 낮습니다. 청구액을 좌우하는 것은 토큰당 단가가 아니라, 모델이 작업을 끝낼 때까지 밟은 스텝 수이기 때문입니다. 그래서 low는 Opus 안에서 아끼고, 여러 스텝을 밟다 실패할 일이 없는 단발성 행 (manager-git, Explore) 에서만 Sonnet을 씁니다.

11개 에이전트 카탈로그 (10 MoAI 커스텀 + 1 Anthropic 빌트인 Explore) 가운데 MoAI 커스텀 에이전트는 티어에 따라 모델이 정해집니다. 과거의 12개 보관 에이전트 (archived agents) 는 쓸 수 없습니다.

빌트인 Explore는 모든 열에서 sonnet / low로 해석됩니다. 디스크에 고정해 둘 에이전트 파일이 없어서, 호출하는 시점에 이 기본값이 적용됩니다.

# 프로젝트 초기화 시
moai init my-project          # 대화형 마법사에서 모델 정책 선택

# 기존 프로젝트 재설정
moai update -c                # 설정 마법사 재실행

정보

기본 티어는 medium 입니다. moai update -c로 설정 마법사를 다시 실행하여 변경할 수 있습니다.

프로젝트를 열 때 Claude Code가 외부 파일 import 관련 보안 프롬프트를 띄울 수 있습니다:

External imports:
  /Users/<user>/.moai/config/sections/quality.yaml
  /Users/<user>/.moai/config/sections/user.yaml
  /Users/<user>/.moai/config/sections/language.yaml

정보

권장 조치: “No, disable external imports” 를 선택하세요.

이유:

• 프로젝트의 .moai/config/sections/에 이미 이 파일들이 존재합니다
• 프로젝트별 설정이 전역 설정보다 우선 적용됩니다
• 필수 설정은 이미 CLAUDE.md 텍스트에 포함되어 있습니다
• 외부 import를 꺼 두는 편이 더 안전하고, 기능에도 아무 영향이 없습니다

파일 설명:

• quality.yaml: TRUST 5 프레임워크 및 개발 방법론 설정
• language.yaml: 언어 설정 (대화, 코멘트, 커밋)
• user.yaml: 사용자 이름 (선택 사항, Co-Authored-By 표시용)

MoAI-ADK v2.5.0+는 방법론을 TDD 또는 DDD 둘 중 하나로만 고릅니다. 명확성과 일관성을 위해 하이브리드 모드는 없앴습니다.

TDD는 테스트를 먼저 쓰고 그 테스트를 통과시키는 순서라 신규 개발에 맞고, DDD는 기존 동작을 특성 테스트로 붙잡아 둔 뒤 조금씩 손보는 순서라 테스트가 거의 없는 코드에 맞습니다. 각 사이클의 단계별 절차는 SPEC 기반 개발과 DDD에서 다룹니다.

# 프로젝트 초기화 시 자동 감지
moai init my-project          # --mode <ddd|tdd> 플래그로 지정 가능

# 수동 설정
# .moai/config/sections/quality.yaml 편집
development_mode: tdd         # 또는 ddd

아주 정상입니다. @MX 태그 시스템은 AI가 먼저 살펴야 할 가장 위험하고 중요한 코드에만 표시를 남기도록 만들었습니다.

코드베이스를 @MX 태그로 스캔하려면:

/moai mx --all        # 전체 스캔
/moai mx --dry        # 미리보기
/moai mx --priority P1  # 치명적 항목만

• GitHub Issues — 질문, 아이디어, 버그 리포트, 기능 요청
• Discord 커뮤니티 — 실시간 소통, 팁 공유