자주 묻는 질문

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

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

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

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

• 터미널에서 moai plan을 실행하면 동작하지 않습니다 — /moai plan은 Claude Code 안에서만 유효합니다.
• moai init은 프로젝트를 설정하는 터미널 명령이고, Claude Code 안에서는 /moai project로 프로젝트 문서를 생성합니다.

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을 참조하세요.

v3.2부터 에이전트별 모델 정책은 더 이상 고를 것이 없습니다. 서브에이전트는 메인 세션의 모델과 추론 깊이를 그대로 따릅니다 — 서브에이전트를 부를 때 model도 effort도 넘기지 않으며, MoAI 에이전트 정의는 어느 쪽도 선언하지 않습니다. 남은 것은 세션 수준 선택 하나입니다. moai profile setup의 세션 모델 정책은 이 프로필로 실행하는 Claude 세션의 기본 추론 강도(추론 강도를 따로 고르지 않았을 때 적용)를 정합니다.

주의

왜 중요한가요? effort를 낮추면 모델 클래스보다는 주로 추론 깊이가 낮아집니다. 오래 이어지는 에이전틱 작업에서는 Opus의 low effort가 어떤 effort의 Sonnet보다도 점수가 높고 작업당 비용도 낮습니다. 청구액을 좌우하는 것은 토큰당 단가가 아니라, 모델이 작업을 끝낼 때까지 밟은 스텝 수이기 때문입니다. 이 경제 운용의 자리가 이제 세션 effort이며, 예전 버전의 에이전트별 배정표는 물러났습니다.

v3.1까지 MoAI-ADK는 프로필 매트릭스로 13개 카탈로그 에이전트 각각에 {model, effort}를 배정했고, 티어가 그 열을 골랐습니다. 이 장치는 SPEC-AGENT-MODEL-INHERIT-001에서 물러났습니다 — 부름에 model 인자가 붙은 경우가 1%에도 못 미친다는 실측이 나왔고, 배정의 자리는 세션 자신으로 옮겨졌습니다. 예전의 --model-policy, --profile, --high, --medium-alias, --low 플래그는 경고만 내고 아무 효과가 없는 지원 종료 스텁으로 남아 있습니다.

# 세션 모델 정책 설정 (세션 모델 정책 질문)
moai profile setup

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

정보

기본 effort 폴백은 medium 입니다. moai profile setup에서 바꾸거나, /effort나 ultrathink로 세션 effort를 그때그때 조절하세요 — 이후의 서브에이전트 부름은 전부 그 값을 따릅니다.

프로젝트를 열 때 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 커뮤니티 — 실시간 소통, 팁 공유