MoAI-ADK란?

MoAI-ADK는 Claude Code를 위한 고성능 AI 개발 환경입니다. 28개의 전문 AI 에이전트와 52개의 스킬이 협력하여 품질 높은 코드를 생산합니다. 새 프로젝트와 기능 개발에는 TDD (기본값), 테스트 커버리지가 낮은 기존 프로젝트에는 DDD를 자동으로 적용하며, Sub-Agent와 Agent Teams 이중 실행 모드를 지원합니다.

Go로 작성된 단일 바이너리 — 의존성 없이 모든 플랫폼에서 즉시 실행됩니다.

MoAI-ADK 소개

MoAI 는 “모두의 AI” (MoAI - Everybody’s AI) 를 의미합니다. ADK 는 Agentic Development Kit의 약자로, AI 에이전트가 개발 과정을 주도하는 도구 모음을 뜻합니다.

MoAI-ADK는 Claude Code 내에서 에이전트들이 상호 작용을 통해 에이전트 코딩을 수행할 수 있도록 하는 Agentic Development Kit입니다. 마치 AI 개발팀이 협업하여 프로젝트를 완성하듯, MoAI-ADK의 AI 에이전트들이 각자의 전문 분야에서 개발 작업을 수행하며 상호 협력합니다.

왜 MoAI-ADK인가?

Python에서 Go로의 완전 재작성

Python 기반 MoAI-ADK (~73,000줄)를 Go로 완전히 재작성했습니다.

핵심 수치

• 34,220줄 Go 코드, 32개 패키지
• 85-100% 테스트 커버리지
• 28개 전문 AI 에이전트 + 52개 스킬
• 18개 프로그래밍 언어 지원
• 16개 Claude Code Hook 이벤트

바이브코딩의 문제점

바이브코딩 (Vibe Coding) 이란 AI와 자연스럽게 대화하며 코드를 작성하는 방식입니다. “이런 기능 만들어줘”라고 말하면 AI가 코드를 생성합니다. 직관적이고 빠르지만, 실무에서는 심각한 문제가 발생합니다.

실무에서 겪는 구체적인 문제들:

MoAI-ADK의 해결책

시스템 요구사항

필수 조건:

• 모든 플랫폼에 Git 설치 필요
• Windows 사용자: Git for Windows  필수 (Git Bash 포함)
  • 최상의 경험을 위해 WSL (Windows Subsystem for Linux) 사용 권장
  • PowerShell 7.x 이상은 대안으로 지원
  • 레거시 Windows PowerShell 5.x와 cmd.exe는 지원하지 않음

빠른 시작

1. 설치

macOS / Linux / WSL

curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash

Windows (PowerShell 7.x+)

권장: 위의 Linux 설치 명령어로 WSL을 사용하면 최상의 경험을 제공합니다.

irm https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.ps1 | iex

Git for Windows 가 먼저 설치되어 있어야 합니다.

소스에서 빌드 (Go 1.26+)

git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk && make build

사전 빌드된 바이너리는 Releases  페이지에서 다운로드할 수 있습니다.

2. 프로젝트 초기화

moai init my-project

대화형 마법사가 언어, 프레임워크, 방법론을 자동 감지한 후 Claude Code 통합 파일을 생성합니다.

3. Claude Code에서 개발 시작

# Claude Code 실행 후
/moai project                            # 프로젝트 문서 생성 (product.md, structure.md, tech.md)
/moai plan "사용자 인증 추가"              # SPEC 문서 생성
/moai run SPEC-AUTH-001                   # DDD/TDD 구현
/moai sync SPEC-AUTH-001                  # 문서 동기화 및 PR 생성

핵심 철학

이 철학은 세 가지 원칙으로 구체화됩니다:

1. 명세 우선 (SPEC-First): 코드를 작성하기 전에 무엇을 만들지 문서로 명확히 정의합니다
2. 안전한 개선 (DDD/TDD): 기존 코드의 동작을 보존하면서 점진적으로 개선합니다
3. 자동 품질 검증 (TRUST 5): 5가지 품질 원칙으로 모든 코드를 자동 검증합니다

MoAI 개발 방법론

MoAI-ADK는 프로젝트 상태에 따라 최적의 개발 방법론을 자동으로 선택합니다.

TDD 방법론 (기본값)

새 프로젝트와 기능 개발의 기본 방법론입니다. 테스트를 먼저 작성하고, 그 다음 구현합니다.

브라운필드 프로젝트 (기존 코드베이스) 의 경우, TDD에 pre-RED 분석 단계가 추가됩니다: 테스트 작성 전에 기존 코드를 읽어 현재 동작을 이해합니다.

DDD 방법론 (기존 프로젝트, 10% 미만 커버리지)

테스트 커버리지가 낮은 기존 프로젝트를 안전하게 리팩토링하기 위한 방법론입니다.

ANALYZE   → 기존 코드와 의존성 분석, 도메인 경계 식별
PRESERVE  → 특성화 테스트 작성, 현재 동작 스냅샷 캡처
IMPROVE   → 테스트 보호 하에 점진적 개선. /simplify가 IMPROVE 완료 후 자동 실행됩니다.

Harness Engineering 아키텍처

MoAI-ADK는 Harness Engineering 패러다임을 구현합니다 — 직접 코드를 작성하는 것이 아니라, AI 에이전트가 일할 환경을 설계하는 접근입니다.

자동 품질 및 스케일아웃 레이어

MoAI-ADK v2.6.0+는 MoAI가 자율적으로 호출하는 두 가지 Claude Code 네이티브 스킬을 통합합니다 — 플래그나 수동 명령 없이 작동합니다.

/simplify — 자동 품질 패스

병렬 에이전트를 사용하여 변경된 코드의 재사용 기회, 품질 이슈, 효율성, CLAUDE.md 준수를 검토한 후 자동 수정합니다. MoAI가 모든 구현 사이클 후 직접 호출합니다.

/batch — 병렬 스케일아웃

격리된 git worktree에서 수십 개의 에이전트를 생성하여 대규모 병렬 작업을 수행합니다. 각 에이전트가 테스트를 실행하고 결과를 보고하면 MoAI가 병합합니다. 워크플로우별 자동 트리거:

AI 에이전트 오케스트레이션

MoAI는 전략적 오케스트레이터입니다. 직접 코드를 작성하지 않고, 28개의 전문 에이전트에 작업을 위임합니다.

에이전트 카테고리

52개 스킬 (Progressive Disclosure)

3레벨 Progressive Disclosure 시스템으로 토큰 효율적으로 관리됩니다:

MoAI 워크플로우

Plan → Run → Sync 파이프라인

MoAI의 핵심 워크플로우는 3단계로 구성됩니다:

실제 사용 예시:

# 1. Plan: 요구사항 정의
> /moai plan "JWT 기반 사용자 인증 기능 구현"
 
# 2. Run: DDD/TDD 방식으로 구현
> /moai run SPEC-AUTH-001
 
# 3. Sync: 문서 생성 및 PR
> /moai sync SPEC-AUTH-001

실행 모드 선택 게이트

Plan 단계에서 Run 단계로 전환할 때, MoAI는 자동으로 현재 실행 환경 (cc/glm/cg) 을 감지하고 사용자가 확인하거나 변경할 수 있는 선택 UI를 표시합니다.

이 게이트는 환경 상태에 관계없이 올바른 실행 모드가 사용되도록 보장하여 구현 중 모드 불일치를 방지합니다.

/moai 서브커맨드

모든 서브커맨드는 Claude Code 내에서 /moai <서브커맨드>로 실행합니다.

핵심 워크플로우

품질 및 테스트

문서 및 코드베이스

기본 워크플로우

실행 모드 플래그

에이전트가 워크플로우 실행 중 어떻게 배치될지 제어합니다:

--team은 3가지 실행 환경을 지원합니다:

자율 개발 루프 (Ralph Engine)

LSP 진단과 AST-grep을 결합한 자율 오류 수정 엔진입니다:

/moai fix       # 단일 패스: 스캔 → 분류 → 수정 → 검증
/moai loop      # 반복 수정: 완료 마커 감지까지 반복 (최대 100회)

Ralph Engine 작동 방식:

1. 병렬 스캔: LSP 진단 + AST-grep + 린터를 동시에 실행
2. 자동 분류: 레벨 1 (자동 수정) 부터 레벨 4 (사용자 개입) 까지 오류 분류
3. 수렴 감지: 동일한 오류가 반복되면 대안 전략 적용
4. 완료 기준: 0 오류, 0 타입 오류, 85%+ 커버리지

추천 워크플로우 체인

새 기능 개발:

/moai plan → /moai run SPEC-XXX → /moai sync SPEC-XXX

버그 수정:

/moai fix (또는 /moai loop) → /moai review → /moai sync

리팩토링:

/moai plan → /moai clean → /moai run SPEC-XXX → /moai review → /moai coverage → /moai codemaps

문서 업데이트:

/moai codemaps → /moai sync

TRUST 5 품질 프레임워크

모든 코드 변경은 5가지 품질 기준으로 검증됩니다:

@MX 태그 시스템

MoAI-ADK는 AI 에이전트 간 컨텍스트, 불변량, 위험 영역을 전달하기 위해 @MX 코드 수준 주석 시스템을 사용합니다.

@MX 태그 시스템은 가장 위험하고 중요한 코드만 표시하도록 설계되었습니다. 대부분의 코드에는 태그가 필요하지 않으며, 이는 정상적인 설계입니다.

# 전체 코드베이스 스캔
/moai mx --all
 
# 미리보기 (파일 수정 없음)
/moai mx --dry
 
# 우선순위별 스캔
/moai mx --priority P1

모델 정책 (토큰 최적화)

MoAI-ADK는 Claude Code 구독 요금제에 맞춰 28개 에이전트에 최적의 AI 모델을 할당합니다. 요금제의 사용량 제한 내에서 품질을 극대화합니다.

설정 방법

# 프로젝트 초기화 시
moai init my-project          # 대화형 마법사에서 모델 정책 선택
 
# 기존 프로젝트 재설정
moai update                   # 각 설정 단계에 대한 대화형 프롬프트

이중 실행 모드

MoAI-ADK는 Claude Code가 지원하는 Sub-Agent와 Agent Teams 두 가지 실행 모드를 모두 제공합니다.

Agent Teams 모드 (기본값)

MoAI-ADK는 프로젝트 복잡도를 자동으로 분석하여 최적의 실행 모드를 선택합니다:

Agent Teams 모드는 병렬 팀 기반 개발을 사용합니다:

• 여러 에이전트가 동시에 작업하고 공유 작업 목록으로 협업
• TeamCreate, SendMessage, TaskList를 통한 실시간 조율
• 대규모 기능 개발, 멀티 도메인 작업에 적합

/moai plan "대규모 기능"          # 자동: researcher + analyst + architect 병렬
/moai run SPEC-XXX                # 자동: backend-dev + frontend-dev + tester 병렬
/moai run SPEC-XXX --team         # Agent Teams 모드 강제

CG 모드 (Claude + GLM 하이브리드)

CG 모드는 Leader가 Claude API를, Workers가 GLM API를 사용하는 하이브리드 모드입니다. tmux 세션 수준 환경 변수 격리를 통해 구현됩니다.

┌─────────────────────────────────────────────────────────────┐
│  LEADER (현재 tmux 패인, Claude API)                         │
│  - /moai --team 실행 시 워크플로우 오케스트레이션             │
│  - plan, quality, sync 단계 처리                             │
│  - GLM 환경 없음 → Claude API 사용                           │
└──────────────────────┬──────────────────────────────────────┘
                       │ Agent Teams (새 tmux 패인)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  TEAMMATES (새 tmux 패인, GLM API)                           │
│  - tmux 세션 환경 상속 → GLM API 사용                        │
│  - run 단계에서 구현 작업 실행                                │
│  - SendMessage로 리더와 통신                                  │
└─────────────────────────────────────────────────────────────┘

# 1. GLM API 키 저장 (한 번만)
moai glm sk-your-glm-api-key
 
# 2. CG 모드 활성화
moai cg
 
# 3. 같은 패인에서 Claude Code 시작 (중요!)
claude
 
# 4. 팀 워크플로우 실행
/moai --team "작업 설명"

Sub-Agent 모드 (--solo)

기존 Claude Code의 Task() API를 활용한 순차적 에이전트 위임 방식입니다.

• 하나의 전문 에이전트에게 작업을 위임하고 결과를 받음
• 단계별로 Manager → Expert → Quality 순서로 진행
• 단순하고 예측 가능한 워크플로우에 적합

/moai run SPEC-AUTH-001 --solo    # Sub-Agent 모드 강제

CLI 명령어

Task 메트릭 로깅

MoAI-ADK는 개발 세션 중 Task 도구 메트릭을 자동으로 캡처합니다:

• 위치: .moai/logs/task-metrics.jsonl
• 캡처 메트릭: 토큰 사용량, 도구 호출, 소요 시간, 에이전트 타입
• 목적: 세션 분석, 성능 최적화, 비용 추적

Task 도구 완료 시 PostToolUse 훅이 메트릭을 로깅합니다. 이 데이터를 사용하여 에이전트 효율성을 분석하고 토큰 소비를 최적화하세요.

프로젝트 구조

MoAI-ADK를 설치하면 프로젝트에 다음과 같은 구조가 생성됩니다.

my-project/
├── CLAUDE.md                  # MoAI의 실행 지침서
├── .claude/
│   ├── agents/moai/           # 28개 AI 에이전트 정의
│   ├── skills/moai-*/         # 52개 스킬 모듈
│   ├── hooks/moai/            # 자동화 훅 스크립트
│   └── rules/moai/            # 코딩 규칙 및 표준
└── .moai/
    ├── config/                # MoAI 설정 파일
    │   └── sections/
    │       └── quality.yaml   # TRUST 5 품질 설정
    ├── specs/                 # SPEC 문서 저장소
    │   └── SPEC-XXX/
    │       └── spec.md
    └── memory/                # 세션 간 컨텍스트 유지

주요 파일 설명:

다국어 지원

MoAI-ADK는 4개 언어를 지원합니다. 사용자가 한국어로 요청하면 한국어로 응답하고, 영어로 요청하면 영어로 응답합니다.

다음 단계

MoAI-ADK의 전체 그림을 이해했다면, 이제 각 핵심 개념을 자세히 알아볼 차례입니다.

• SPEC 기반 개발 — 요구사항을 어떻게 문서로 정의하는지 배웁니다
• 도메인 주도 개발 — 기존 코드를 안전하게 개선하는 방법을 배웁니다
• TRUST 5 품질 — 코드 품질을 자동으로 검증하는 방법을 배웁니다
• MoAI Memory — 세션 간 컨텍스트가 어떻게 보존되는지 배웁니다