소개

MoAI-ADK는 비용 (토크노믹스) · 자기 개선 (에이전틱 루프 엔지니어링) · 품질 통제 (에이전틱 하네스) 세 가지로 Claude Code를 감싸는 Agentic Development Kit입니다. 같은 품질의 코드를 더 적은 토큰으로 만듭니다. 완료 조건만 선언하면 루프가 알아서 일하고, 그 과정에서 쌓인 관찰은 하네스 학습의 원료가 됩니다. ‘끝’은 SPEC 3단계와 TRUST 5 게이트가 증거로 판정합니다. 모델 선택도, 추론 깊이도, 컨텍스트 사용량도 시스템이 관리합니다. Go로 작성된 단일 바이너리라 의존성 없이 바로 실행됩니다.

이 페이지는 MoAI-ADK 가 무엇이고, 왜 이런 모양을 하고 있는지를 한 흐름에 소개합니다. 세 가지 핵심이 각각 어떤 문제에 대답하는지, SPEC · TRUST 5 같은 용어가 이 안에서 어디에 서 있는지, 그리고 처음 시작할 때 어디로 가면 되는지까지를 다룹니다. 설치 절차와 첫 프로젝트 실행은 설치 와 빠른 시작 페이지에 맡기고, 여기서는 “왜” 에 집중합니다.

이 문서에서 코드 블록의 접두사는 실행 환경을 나타냅니다:

• Claude Code 대화창에서 입력하는 명령어

  bash 복사

  > /moai plan "기능 설명"

• 터미널 (Terminal)에서 입력하는 명령어

  bash 복사

  $ moai init my-project

MoAI-ADK는 Claude Code를 세 축으로 감싸는 Agentic Development Kit입니다 — 비용 · 자기 개선 · 품질 통제. 한 축만 밀면 나머지가 무너집니다. 비용만 줄이면 품질이 삭막해지고, 품질 게이트만 세우면 같은 실수가 매 세션 반복되며, 자율 루프만 돌리면 한 번의 과금이 한도를 태웁니다. 세 축이 서로를 지탱합니다.

같은 품질을 더 적은 토큰으로. 비용은 단가가 아니라 모델 선택이 정합니다 — DeepSWE 벤치마크에서 Opus 최저 추론이 Sonnet 최고 추론보다 점수가 높으면서 16분의 1 비용이었습니다. 세션 모델 정책 · 프롬프트 캐싱 · Token Circuit Breaker가 예산을 시스템이 관리합니다.

하네스가 돌수록 더 똑똑해집니다. 완료 조건을 선언하면 루프가 알아서 일하고(/moai goal · /moai loop), 관찰이 규칙으로 쌓여 다음 세션이 같은 실수를 반복하지 않습니다.

‘끝’을 증거로 판정합니다. SPEC 3단계 라이프사이클 + TRUST 5 게이트 + worktree 격리로 재작업(가장 큰 토큰 낭비)을 막고, 만든 사람이 검사하지 않게 계획과 감사를 분리합니다.

각 핵심의 자세한 내용은 핵심 개념 섹션에서 다룹니다.

• /moai goal — 완료 조건 선언 한 줄로 세션이 자율 진행합니다.
• 팩토리 모드 — 여러 세션을 동시에 실행합니다.
• BAS Navigator — 3단계 코드맵을 자동 동기화합니다.
• manager-lead — SPEC 안의 Tier L 마일스톤 팬아웃은 물론, 팩토리 리더 세션 디스패치까지 아우르는 조율 에이전트입니다.
• multi-model audit — 다중 모델 교차 검증으로 편향을 잡습니다.
• autonomy tier — 자율성 단계를 조절해 안전하게 돌립니다.
• 세션 모델 정책 — 한 번의 선택으로 세션 기본 추론 강도를 정합니다. 서브에이전트는 세션의 모델과 추론 깊이를 그대로 따릅니다.

MoAI-ADK는 SPEC 기반 TDD/DDD 방법론을 따르며, TRUST 5 품질 프레임워크로 코드 품질을 보장합니다.

SPEC (Specification)은 “AI와 나눈 대화를 문서로 남기는 것"입니다.

바이브코딩 (Vibe Coding)의 가장 큰 문제는 맥락 유실입니다:

• AI와 1시간 동안 논의한 내용이 세션이 끊기면 사라집니다
• 다음 날 이어서 작업하려면 처음부터 다시 설명해야 합니다
• 복잡한 기능일수록 의도와 다른 결과가 나옵니다

SPEC이 이 문제를 해결합니다:

• 요구사항을 파일로 저장하여 영구 보존
• 세션이 끊겨도 SPEC만 읽으면 이어서 작업 가능
• EARS 형식으로 모호함 없이 명확하게 정의
• 같은 설명을 반복하지 않으니 토큰도 절약됩니다

정보

한 줄 요약: 어제 AI와 논의한 “JWT 인증 + 1시간 만료 + 리프레시 토큰"을 오늘 다시 설명할 필요 없이, /moai run SPEC-AUTH-001 한 줄로 바로 구현을 시작합니다!

구현 방식은 프로젝트 상태에 따라 둘 중 하나가 자동으로 배정되고, 결과물은 공통된 품질 기준으로 검증됩니다.

정보

MoAI-ADK v2.5.0+는 TDD와 DDD 중 하나만 고릅니다. 명확성과 일관성을 위해 hybrid 모드는 없앴습니다. 방법론은 moai init 시 자동으로 정해지며, .moai/config/sections/quality.yaml의 development_mode에서 변경할 수 있습니다.

MoAI-ADK는 Python Edition을 Go로 완전히 재작성하여 성능과 효율성을 극대화했습니다.

• 13개 에이전트 카탈로그 (12 MoAI 커스텀 + 1 Anthropic 빌트인 Explore)
• 31개 스킬 (template-managed)
• 36개 터미널 CLI 명령 · 16종 /moai 슬래시 서브커맨드
• 16개 프로그래밍 언어 지원
• 543개 SPEC 문서 기반으로 개발된 코드베이스

필수 조건:

• Git이 모든 플랫폼에 설치되어 있어야 합니다
• Windows 사용자: 가장 매끄럽게 쓰려면 WSL (Windows Subsystem for Linux) 을 권장합니다

MoAI 오케스트레이터는 직접 구현하지 않고 13개의 전문 에이전트에게 작업을 위임합니다. 계획과 감사는 분리되어 있습니다. 만든 사람이 검사하지 않습니다.

목표는 요금제의 사용량 한도 안에서 품질을 최대한 끌어올리는 것입니다. 오래 이어지는 에이전틱 작업에서는 약한 모델이 스텝을 더 많이 소모해 작업당 비용이 오히려 올라가기 때문에, 모델 클래스를 바꾸는 대신 같은 모델 안에서 추론 깊이만 조절합니다. v3.2부터 이 조절은 세션 단위입니다. 서브에이전트는 메인 세션의 모델과 추론 깊이를 그대로 따르고, 에이전트 정의는 어느 쪽도 선언하지 않으며, 프로필의 세션 모델 정책 (moai profile setup)이 추론 강도를 따로 고르지 않았을 때의 기본값을 정합니다.

정보

사라진 --model-policy / --profile 플래그는 지원 종료 스텁입니다. moai profile setup을 안내하는 경고를 낼 뿐 아무 효과가 없습니다. 세션의 effort는 /effort나 ultrathink로, 모델은 /model로 그때그때 바꿀 수 있습니다. 자세한 내용은 모델 정책 페이지를 참조하세요.

자연어 요청은 Analyze-First 라우팅을 거칩니다. 어떤 언어로 요청하든 의도를 먼저 분석해 알맞은 워크플로우로 연결합니다. 오케스트레이터는 작업 복잡도에 따라 순차 서브에이전트 (기본), 병렬 서브에이전트 팬아웃, 동적 워크플로우 중 하나를 선택합니다.

/moai run SPEC-AUTH-001           # 복잡도 기반 자동 선택
/moai run SPEC-AUTH-001 --solo    # 순차 서브에이전트 강제

정보

v3.0 변경: 과거의 Agent Teams 정적 오케스트레이션 계층은 폐지되었습니다. --team을 강제해도 서브에이전트 모드로 폴백합니다. CG는 폐기되었습니다. moai migrate cg로 이전 선택지를 먼저 확인하세요.

MoAI-ADK는 3단계 개발 워크플로우를 따릅니다. Run 단계의 방법론은 프로젝트 상태에 따라 자동 선택됩니다:

flowchart TD
    A["Phase 1: SPEC
/moai plan"] -->|"EARS 형식으로 요구사항 정의"| B{"방법론 선택"}
    B -->|"신규 프로젝트 (TDD)"| C["Phase 2: TDD
/moai run"]
    B -->|"기존 프로젝트 (DDD)"| D["Phase 2: DDD
/moai run"]
    C -->|"RED → GREEN → REFACTOR"| E["Phase 3: Docs
/moai sync"]
    D -->|"ANALYZE → PRESERVE → IMPROVE"| E
    E -->|"문서화 및 배포"| F["완료"]

    style C fill:#4CAF50,color:#fff
    style D fill:#2196F3,color:#fff

완료 조건을 선언하면 루프가 스스로 일합니다:

/moai goal "모든 테스트가 통과하고 lint가 깨끗할 때까지"   # 조건 선언형 루프
/moai loop                                              # 진단 기반 반복 수정 (loop_prevention 기본 100회)
/moai fix                                               # 단일 패스 자동 수정

/moai loop는 goal 엔진 위의 프리셋입니다. 진단 도구가 찾은 이슈 큐를 다 비울 때까지 반복 수정합니다.

반복 한도는 서로 다른 층위를 맡는 두 설정이 각각 정합니다. workflow.loop_prevention.max_iterations (기본값 100) 는 개별 작업의 진단 수정 루프 한도이고, workflow.agentic_loop.max_iterations (기본값 10) 는 파이프라인 전체의 완료 루프 상한입니다. 둘은 별개의 설정이므로 값이 서로 달라도 정상입니다.

신규 기능 개발:

/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 codemaps

문서 업데이트:

/moai codemaps → /moai sync

MoAI-ADK는 다음 4가지 언어를 지원합니다:

• 한국어 (Korean)
• 영어 (English)
• 일본어 (Japanese)
• 중국어 (Chinese)

설치 마법사에서 선호하는 언어를 선택하거나, 설정 파일에서 직접 변경할 수 있습니다.

LSP (Language Server Protocol)는 코드 편집기와 언어 도구 사이의 표준 통신 프로토콜입니다. 코드 오류, 타입 오류, 린트 결과를 실시간으로 감지해 곧바로 알려 줍니다.

Ralph-Loop Style은 LSP 진단 결과를 피드백 루프로 활용하는 자율 워크플로우입니다. 품질 문제가 감지되면 수정 에이전트를 자동 호출하고, 품질 기준을 달성할 때까지 반복합니다.

MoAI-ADK의 Ralph-Loop Style LSP 통합은 다음과 같이 동작합니다:

• LSP 기반 완료 자동 감지: 코드 품질 상태를 실시간으로 모니터링
• 실시간 회귀 탐지: 변경 사항이 기존 기능에 미치는 영향을 즉시 감지
• 자동 완료 조건: 0 에러, 0 타입 에러, 85% 커버리지 달성 시 자동으로 완료 처리

정보

Ralph-Loop Style LSP 통합은 개발 워크플로우의 품질 게이트를 자동화해, 사람이 일일이 손대지 않아도 코드 품질을 높게 유지해 줍니다.

Claude나 GLM을 실행하지 않고 설정 이전 안내와 함께 종료합니다. moai cc의 별칭이 아닙니다. llm.team_mode: cg가 남은 프로젝트는 세션을 실행하기 전에 이전할 구성을 명시적으로 선택해야 합니다. CG 폐기와 설정 이전 CG는 폐기되었습니다. moai migrate cg로 이전 선택지를 먼저 확인하세요.

llm.team_mode: claude, llm.gateway.teammate_mode: in-process, llm.gateway.teammate_provider: inherit을 저장합니다. 기존 혼합 역할 배정을 없애는 변경이며, Claude 리더와 GLM 팀원 창의 분업을 보존하는 이전이 아닙니다.

claude-glm 대상은 Claude 리더와 tmux의 GLM 팀원 구성을 뜻합니다. 현재 TEAMMATE 통합 검증을 통과하지 않아 적용과 실행은 사용할 수 없으며 미리보기만 가능합니다. tmux를 설치하거나 verified: true를 적어도 이 제한은 해제되지 않습니다.

정보

자기 개선 (에이전틱 루프 엔지니어링) 의 실전 도구: 완료 조건을 선언하면 조건이 충족될 때까지 세션이 스스로 일합니다. /moai goal "<조건>"은 조건 선언형 자율 루프, /moai loop는 LSP 진단·AST-grep·린터가 찾은 이슈 큐를 다 비울 때까지 반복 수정 (파이프라인 완료 루프 기본 10회 — agentic_loop.max_iterations), /moai fix는 단일 패스 자동 수정입니다. 루프가 남긴 관찰 (사용자 교정, 실패 패턴, 라우팅 결정) 은 4단계 학습 사다리 (관찰 → 휴리스틱 → 규칙 → 자동 업데이트, 사용자 승인 게이트 아래) 를 거쳐 하네스 지침으로 쌓입니다. 그래서 다음 세션은 이전 세션의 실수를 되풀이하지 않습니다.

MoAI-ADK를 시작하려면 다음 순서로 진행하세요:

1. 설치 - 시스템에 MoAI-ADK 설치
2. 초기 설정 - 인터랙티브 설정 마법사 실행
3. 빠른 시작 - 첫 프로젝트 생성
4. 핵심 개념 - MoAI-ADK 심화 이해

• GitHub 저장소
• 문서 사이트
• GitHub Issues

설치 가이드에서 MoAI-ADK 설치 방법을 알아보세요.