Frequently Asked Questions

Frequently asked questions and answers about MoAI-ADK.

Q: What does the version indicator in statusline mean?

The MoAI statusline shows version information with update notifications:

🗿 v2.2.2 ⬆️ v2.2.5

• v2.2.2: Currently installed version
• ⬆️ v2.2.5: New version available for update

When you’re on the latest version, only the version number is displayed:

🗿 v2.2.5

To update: Run moai update and the update notification will disappear.

Q: How do I customize which statusline segments are displayed?

The statusline supports 4 display presets plus custom configuration:

Configure during moai init / moai update -c wizard, or edit .moai/config/sections/statusline.yaml:

statusline:
  preset: compact  # or full, minimal, custom
  segments:
    model: true
    context: true
    output_style: false
    directory: false
    git_status: true
    claude_version: false
    moai_version: false
    git_branch: true

Q: How do I choose a model policy?

MoAI-ADK assigns optimal AI models to each of 28 agents based on your Claude Code subscription plan. This maximizes quality within your plan’s rate limits.

Policy Tier Comparison

Agent Model Assignment by Tier

Manager Agents

Expert Agents

Configuration

# During project initialization
moai init my-project          # Interactive wizard includes model policy selection
 
# Reconfigure existing project
moai update -c                # Re-runs the configuration wizard

Q: “Allow external CLAUDE.md file imports?” warning appears

When opening a project, Claude Code may show a security prompt about external file imports:

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

Why?

• Your project’s .moai/config/sections/ already contains these files
• Project-specific settings take precedence over global settings
• The essential configuration is already embedded in CLAUDE.md text
• Disabling external imports is more secure and doesn’t affect functionality

What are these files?

• quality.yaml: TRUST 5 framework and development methodology settings
• language.yaml: Language preferences (conversation, comments, commits)
• user.yaml: User name (optional, for Co-Authored-By attribution)

Q: What is the difference between TDD and DDD methodologies?

MoAI-ADK v2.5.0+ uses binary methodology selection (TDD or DDD only). The hybrid mode has been removed for clarity and consistency.

Methodology Selection Guide

TDD Methodology (Default)

The default methodology for new projects and feature development. Write tests first, then implement.

For brownfield projects (existing codebases), TDD is enhanced with a pre-RED analysis step: read existing code to understand current behavior before writing tests.

DDD Methodology (Existing Projects with < 10% Coverage)

A methodology for safely refactoring existing projects with minimal test coverage.

ANALYZE   → Analyze existing code and dependencies, identify domain boundaries
PRESERVE  → Write characterization tests, capture current behavior snapshots
IMPROVE   → Improve incrementally under test protection

Methodology Selection Table

Configuration

# Auto-detect during project initialization
moai init my-project          # --mode <ddd|tdd> flag to specify
 
# Manual configuration
# Edit .moai/config/sections/quality.yaml
development_mode: tdd         # or ddd

Q: Why doesn’t my code have @MX tags?

This is completely normal. The @MX tag system is designed to mark only the most dangerous and important code that AI needs to notice first.

Tag Priority

To scan your codebase for @MX tags:

/moai mx --all        # Full scan
/moai mx --dry        # Preview only
/moai mx --priority P1  # Critical only

Have more questions?

• GitHub Discussions  — Questions, ideas, feedback
• Issues  — Bug reports, feature requests
• Discord Community  — Real-time chat, tips sharing