modu-ai/moai-adk

modu-ai/moai-adk has 1,255 GitHub stars and 223 forks. GitHot measured 0 stars in 24 hours, +3 in 7 days, and +9 in 15 days. Last checked 2026-11-12 09:43 UTC. Last push 2026-11-01.

이 수치를 측정하는 방법

Agentic development harness for Claude Code — SPEC-driven plan/run/sync, TRUST 5 quality gates, model+effort routing, and Claude×GLM multi-LLM cost control. Single Go binary, 16 languages, zero deps.

1,255 스타 223 forks

측정된 스타 증가

in 24h: 0
in 7 days: +3
in 15 days: +9
in 1 month: 업데이트 지연

서로 겹치는 기간의 순증가량이며 일별 합계가 아닙니다. 측정값이 없으면 비워 둡니다. 스타는 관심도를 나타내며 품질을 보장하지 않습니다.

README.ko.md

Original

MoAI-ADK

검증-구동 에이전트 오케스트레이션 하네스 — Claude Code가 쓴 코드를 믿을 수 있게 만드는 구조

English · 한국어 · 日本語 · 中文

공식 문서 · 도서: 클로드 코드로 시작하는 실전 에이전틱 코딩 · Discord

"모델은 토큰 단위로 나아가는 확률적 작업자다. 이번 턴에 무엇을 얼마나 썼는지, 결과가 좋은지, 지난 세션에서 어디까지 했는지를 턴마다 기억하지 못한다. 하네스는 이 세 가지를 바깥에서 강제한다."

v3.2 새 기능 — 팩토리 모드

세션 하나는 컨텍스트 창 하나를 쓴다. 긴 SPEC은 그 창을 채우고, 뒤에 오는 작업은 앞의 것을 전부 지고 간다. 계획은 이미 끝났는데도 리뷰하는 내내 창에 남아 있고, 그 리뷰는 문서를 쓰는 내내 또 남아 있다. 흔한 탈출구인 /clear는 짐과 함께 맥락까지 버린다.

팩토리 모드는 일을 리더 세션 하나와 번호가 붙은 레인 세션 여럿으로 나눈다. 리더는 큐를 지키며 카드를 빈 레인에 나른다. 카드는 단계마다 세션을 갈아타지 않고 통째로 레인 하나에 들어가며, 그 레인이 세션 안에서 plan → run → sync를 순서대로 끝까지 맡는다. 각 단계는 Agent() 서브에이전트로 띄우고, 레인 자신은 오케스트레이션만 한다. 무제한이 되는 것이 아니다 — 세션마다 한도는 그대로 있다. 달라지는 것은 카드 한 장의 이력이 그 카드를 맡은 레인에만 쌓인다는 점이다. 그래서 같은 예산이 훨씬 멀리 가고, 레인은 카드 하나가 끝날 때마다 맥락을 비운 채 다음 카드를 받는다.

시작하기

moai cc -f                    # 리더 — 팩토리를 연다
moai cc -l                    # 레인, 각자 별도 터미널에서 — 다음 빈 번호로 합류
moai cc -l                    # lane-1, lane-2 … 순으로 붙는다
moai glm -l                   # GLM 백엔드로 띄운 레인
moai codex -l                 # Codex 레인

-f(긴 형태 --factory)가 리더를 열고, -l(긴 형태 --lane)이 실행 중인 팩토리에 레인으로 합류한다. 둘 다 인자를 받지 않는다. 레인 번호는 운영자가 고르지 않고 자동으로 배정된다. 레인은 터미널을 하나씩 새로 열어 직접 띄운다. 세션은 다른 세션을 대신 띄우지 못한다. moai codex에는 리더 진입이 없어 레인으로만 합류할 수 있다.

한 번의 실행에는 진입 토큰이 하나뿐이라 -f와 -l을 함께 쓰면 에러다. 값이 붙은 형태(moai cc -f <값>, moai cc -l lane-2)도 한 줄 에러로 거부되고, 에러 문구가 올바른 형태를 알려 준다. 예전 다중 세션 보드 모드의 -k는 제거되었다. GPT 모델은 moai codex로 돌린다.

어느 백엔드로 돌릴까

백엔드는 레인마다 따로 고른다. moai cc -l은 Claude, moai glm -l은 GLM, moai codex -l은 Codex 레인이다. 리더는 판정을 내리는 자리가 아니라 큐를 지키며 카드를 나르는 자리라, 상시 대기 비용이 크지 않은 GLM(moai glm -f)이 어울린다. 한 계정이 429로 막히기 시작하면 레인을 계정에 분산해 배치하는 운영이 통한다. 이 조합은 어디까지나 한 예일 뿐 — 전 세션을 한 백엔드로 통일해도 무방하다.

레인 N개에 카드를 한꺼번에

레인은 -l을 한 번 더 쳐서 하나씩 늘린다. 번호는 자동 배정이라 --name/-n을 함께 주면 에러다. 번호는 살아 있는 세션이 쥔 것만 건너뛴다 — 죽은 레인의 claim은 더 이상 그 번호를 막지 않지만, 자동 배정은 항상 살아 있는 최고 번호+1만 받으므로 중간 빈 번호를 채우지는 않는다. 레인 소유권은 ~/.moai/db/<project-key>/factory/factory.db에 기록한다. 기점 디렉터리가 임시 디렉터리면(절대 MOAI_HOME 오버라이드 없음) 프로젝트 로컬 <base>/.moai/db/<project-key>/factory/ 아래에 기록한다 — 백로그 큐와 같은 예외다. 기존 .moai/state/factory/workers.json은 한 번만 가져오고 롤백 증거로만 남긴다.

데이터베이스 경로는 추측하지 말고 moai paths로 확인합니다. ~/.moai/db/todo.db처럼 추측한 경로를 sqlite3로 열면 빈 파일이 만들어지므로 열지 않습니다. 직접 읽어야 하면 .db, .db-wal, .db-shm을 함께 복사한 스냅샷에서만 읽고, 평소에는 moai todo list --json, moai factory status 같은 CLI를 우선 씁니다.

레인 하나가 동시에 돌리는 Agent() 서브에이전트는 최대 10개이고, 쓰기를 맡는 스폰은 각자의 워크트리로 격리한다. 레인을 한꺼번에 켜지 말고 첫 레인을 먼저 올려 실제로 출력이 나오는 것을 확인한 뒤 나머지를 띄운다. 카드는 레인에 쪼개어 넣지 않는다.

팩토리 런은 자기를 소유한 세션의 프로세스 신원을 기록한다. 리더가 죽은 런은 다음 레인이 합류하는 시점에 자동으로 회수되므로 합류가 AMBIGUOUS_FACTORY에서 막히지 않는다. 그 반대도 막혀 있다: 레인이 합류할 때 실행 기록이 없거나 은퇴했는데 살아 있는 리더 세션이 있으면, 합류는 그 리더를 검증하고(pid + 프로세스 시작 지문, 대상은 긴 형태 --leader <이름>으로 지정, 기본값 leader) 그 런 기록을 복원한 뒤 그대로 합류한다 — 검증된 리더가 둘 이상이면 후보를 모두 이름 대고 실패로 닫는다. --leader는 -l/--lane과만 함께 쓰는 선택자이고 진입 토큰의 짧은 형태가 아니다. moai factory runs는 모든 런을 소유자 생존 여부와 함께 보여주고, moai factory runs --retire <run-id>는 지목한 런 하나를 손으로 회수한다. 소유자가 실제로 죽지 않았으면 거절하고, 완료·실패·종료 상태가 아닌 카드가 남아 있는 런도 거절하면서 그 카드 목록과 대신 쓸 방법(moai cc -l --factory-run <run-id>로 합류, moai cc -f --factory-run <run-id>로 이어받기, 카드별 moai factory decide <카드> --choice abandon --run <run-id>)을 보여준다. 합류와 이어받기는 런이 활성인 동안만 통하고, 카드 종료는 되돌릴 수 없다. 강제로 회수하는 플래그는 없다. 이미 회수된 런을 다시 지목하면 쓰기 없이 결과를 알리고 남은 카드를 나열한다. 이런 카드가 남은 활성 런은 moai factory relaunch --from-run도 활성 상태로 두고 left active (N in-progress cards)로 알리며, 이미 회수된 런은 건드리지 않는다(not active (retired), left untouched).

런이 죽거나 바뀐 뒤에도 레인 세션은 환경에 박힌 옛 런을 계속 가리키는데, 이 레인은 moai factory relaunch로 살아 있는 런에 다시 붙인다. 이 명령은 공급자의 레인 합류 줄(moai cc -l, moai glm -l, Codex는 moai codex -l)을 그대로 다시 실행하고, 옵션은 --provider·--lane·--run·--from-run <run-id>·--dry-run이다. -l은 인자를 받지 않으므로 --lane을 줘도 합류 줄에는 실리지 않는다. 명령이 stderr로 그렇게 알리고, 레인은 다음 빈 번호로 합류한다. --from-run은 그 런이 활성이면서 소유자가 죽은 경우에만 먼저 회수하고, --dry-run은 실행 줄만 찍고 아무것도 바꾸지 않는다. 한 런 안에서 카드를 돌며 도는 --clear-policy relaunch 루프와는 별개의 일회성 명령이다. stale-run 안내문도 산문 대신 이 명령을 채워 넣은 줄로 보여 준다.

자세히: 팩토리 모드

카드는 큐에서 출발한다. backlog에는 주인 세션이 일부러 없다. 그래서 일감은 사람이 넣을 때만 큐에 들어온다.

/moai gtd "rename 힌트가 낡았다"   # 카드 추가
/moai gtd                          # 큐 확인

/moai gtd가 정식 작업 관리 표면입니다. /moai todo는 같은 SQLite 대기열, 카드 ID, 순서, 보관·복원 동작을 쓰는 호환 이름으로 남습니다. moai gtd capture|clarify|organize|reflect|engage는 승인된 일이 기존 backlog → plan → run → sync → done 개발 흐름에 들어가기 전에 Capture → Clarify → Organize → Reflect → Engage를 실제 SQLite 상태로 이어 갑니다. 작업 receipt와 실제 상태 재확인이 중간 종료 뒤 발행·선택·배차의 중복을 막습니다.

팩토리를 정직하게 유지하는 규칙이 둘 있다. 리더는 카드의 progress.md에서 직접 읽은 증거로만 카드를 넘긴다 — 레인의 답장으로는 넘기지 않는다. 답장은 관측이 아니라 주장이고, 세션 간 전달은 보장되지도 않기 때문이다. 그리고 카드가 끝나면 레인이 /clear를 요청한다. /clear는 사람이 직접 치는 명령이라 지시로 보낼 수 없다(--clear-policy로 바꿀 수 있다).

팩토리가 쓰는 말

팩토리 문서에 되풀이되는 낱말을 한 장에 모으면 이렇다. 리더 (leader) 는 큐를 지키며 카드를 나르는 세션이고, 레인 (lane) 은 카드 한 장을 끝까지 나르는 세션과 워크트리의 짝이다.

낱말	한 줄 정의
카드 (card)	작업 단위 하나. `/moai gtd`로 들어오고 짧은 아이디로 불린다
백로그 (backlog)	입구 대기열. 주인 세션이 없어 사람만 넣을 수 있다
리더 (leader)	조율하는 세션. 읽은 증거로만 카드를 넘기고, 코드는 직접 쓰지 않는다
레인 (lane)	카드 한 장을 끝까지 나르는 세션+워크트리의 짝. 병렬 작업 흐름 하나이고 `lane-1`, `lane-2` … 번호가 자동으로 붙는다
런 아이디 (run-id)	팩토리 실행 하나를 가리키는 짧은 식별자. 실행이 여럿 살아 있으면 `--factory-run <run-id>`로 합류할 실행을 고른다
워크트리 (worktree)	카드 전용 격리 체크아웃. 디렉터리는 카드 아이디, 브랜치는 한 일을 담은 `WT-<슬러그>`
배차 (dispatch)	리더가 레인에 보내는 지시 — 일의 포인터이지 복사물이 아니다

카드도 모양에 따라 레인이 거치는 단계가 갈린다. 리더는 카드가 큐를 떠날 때 세 클래스로 분류해 배차문에 이름 붙인다.

클래스	모양	지름길
A — 바로 닫기	파일 하나·한 줄, 설계 판단 없음, 회귀는 CI가 잡음	레인 하나가 PR까지 통째로 (`plan` 건너뜀)
B — 원인 미확인 결함	잘못된 건 분명한데 원인이 아직 안 서 있음	`run → sync` (`plan` 없이, SPEC 없음)
C — 설계 변경	결정이 들어 있거나 하위 시스템에 걸침	세 단계 모두

클래스 A는 주장이 아니라 확인된 증거로만 인정한다 — 파일 하나로 측정된 diff와 머지될 HEAD의 초록 CI를 인용하지 못하면 클래스 A가 아니다. 클래스 B는 plan만 건너뛰고 sync 게이트의 리뷰는 그대로 돌아가며, 원인 확립 증거(재현 명령과 출력)를 카드의 진행 기록에 남긴다.

팩토리를 눈으로 보기

moai web은 로컬 콘솔을 띄운다. Factory 화면에서 팩토리 레인과 SPEC 파이프라인을 함께 보고, Overview·Specs·Monitor·Settings·Todo 화면이 함께 붙는다.

moai web 콘솔 Overview 화면 — SPEC 집계, 진행 중 SPEC 목록, 세션 레지스트리

자세한 안내: 팩토리 모드 · manager-lead 리더 코디네이터 · /moai todo

v3.1.1에서 더해진 것

앞서 v3.1.1에 들어온 것들이다. 각각은 뒤의 해당 절에서 자세히 다룬다.

홈 디렉터리 정리. 오래 쓸수록 ~/.moai에는 지난 실행 산출물이 쌓인다. moai clean --home이 허용목록 범위 안에서만 그것을 치운다 — 기본은 dry-run이라 무엇이 지워질지 먼저 보여주고, 실제 삭제는 --force를 줘야 한다. 며칠 지난 것부터 치울지는 state.home_retention_days(기본 30일, 0이면 끔)로 정한다. 지금 얼마나 불었는지는 moai doctor의 Home Disk Usage 항목이 알려준다. 홈 경로 자체는 MOAI_HOME 환경변수로 옮길 수 있다 — 절대 경로만 받는다. 다만 이 변수를 읽는 건 Go 프로세스뿐이라, 경로를 옮겨도 statusline과 셸 훅은 여전히 $HOME/.moai를 본다. .env.glm 같은 셸 쪽 자격증명과 statusline 데이터만 옛 자리에 남아, 상태가 조용히 두 곳으로 갈린다.

~/.moai 홈 정리 — MOAI_HOME으로 경로를 한 곳에 모으고, moai doctor로 사용량을 보고, moai clean --home으로 허용목록 안에서만 지운다

세션 간 메시지 설정. 다른 Claude Code 세션이 보내는 메시지를 바로 받을지, 승인을 받고 받을지, 아예 막을지를 crosssession.yaml에서 정한다. 이 머신 밖으로 나가는 메시지에 승인을 요구하는 스위치도 여기 있다.

세션 간 메시징 — inbound·isolate_machines·dialog_expiry 세 설정으로 받는 쪽을 통제한다. 메시지는 사실만 나르고 승인은 사용자 몫이다

스테이터스라인 GitLab 지원. statusline.forge로 열린 작업을 GitHub과 GitLab 중 어느 쪽에서 셀지 고른다. 비워 두면 origin 리모트 호스트를 보고 판단한다.

맨 /loop가 팩토리 포어맨이 된다. 인자 없이 /loop만 치면 백로그 큐를 지켜보다 운영자가 이미 picked로 골라둔 다음 카드를 격리된 워커에 배차하고, 완료는 주장이 아니라 읽은 증거로 확인한 뒤 보고하는 사이클이 돈다. 사람이 지켜보지 않는 자리라 카드를 큐에 넣는 것도 고르는 것도 운영자 몫이고, 포먼은 고르지 않고 나르기만 한다.

왜 moai-adk인가요?

에이전트가 코드를 쓰는 시대가 왔지만, 에이전트가 내놓은 결과를 그대로 믿을 수는 없다. "테스트가 통과했습니다"라는 말이 진짜 테스트를 돌린 결과인지, 그냥 에이전트의 추측인지를 구분하는 것이 처음부터 가장 큰 문제다. moai-adk는 바로 그 지점에서 출발한다 — 검증하지 않은 완료 선언을 시스템 차원에서 금지하고, 모든 완료 주장에 실제로 돌린 명령과 그 출력을 증거로 묶는다.

moai-adk는 Claude Code를 바깥에서 감싸는 하네스다. Claude Code를 대체하지 않고, 사용자가 직접 챙겨야 했던 부분 — 어느 모델을 쓸지, 얼마나 깊이 추론할지, 결과를 어떻게 검증할지, 세션이 끊겼을 때 어떻게 이을지, 병렬로 돌릴 때 서로 밟지 않게 어떻게 갈라놓을지 — 을 구조로 떠맡는다. 검증 무결성, SPEC 라이프사이클, 진짜 경계가 있는 자율 실행, 살아 있는 코드베이스 내비게이터, 자가 개선 루프, 병렬 안전 구조. 이 여섯 가지가 moai-adk의 정체성을 이룬다.

Claude Code를 감싸는 에이전트 개발 하네스

이 정체성은 세 가지 핵심 (three axes) 으로 정리된다 — 같은 품질을 더 적은 토큰으로 얻는 비용 (토크노믹스), 관측을 규칙으로 바꿔 달라질수록 잘되는 자가 개선 (에이전틱 루프 엔지니어링), 그리고 재작업을 구조적으로 막는 품질 관리 (SPEC 라이프사이클·TRUST 5 게이트·격리). 어느 하나만으로는 부족하다 — 아래에서 각각이 왜 서로를 필요로 하는지 본다.

여덟 가지 차별점

차별점	설명
거짓 검증 없음	"테스트가 통과했다"는 주장은 반드시 실제로 돌린 명령과 그 출력에 귀속된다. 돌리지 않은 검증을 성공으로 말하는 것을 시스템이 금지한다 — 검증 주장 무결성(verification-claim integrity)이 모든 에이전트와 오케스트레이터 표면에 묶여 있다.
자율 + 진짜 경계	`/moai goal`이 완료 조건을 선언하면 세션이 조건을 채울 때까지 알아서 일한다. 다만 턴 한도(기본 30), 정체 가드, 벽시계 예산, 사전 승인 게이트라는 네 개의 하드 경계가 묶여 있어 무한 루프에 빠지지 않는다.
병렬 안전	SPEC마다 독립된 작업 트리를 주고, 브랜치 상태 가드가 주 체크아웃에서 실수로 브랜치를 바꾸는 것을 막으며, 쓰기 에이전트를 띄우기 전에 원격과의 간격을 검사한다. 두 개의 쓰기 에이전트가 동시에 돌지 않는다.
장기 지속	`/clear`를 넘어도 작업이 이어진다. 진행 상태는 `progress.md`에, 핸드오프 메시지는 메모리에, 라우팅 결정은 결정 메모리에 남는다. 다음 세션은 맨땅이 아니라 지난 세션이 배운 지점에서 시작한다.
비용 효율	세션의 모델과 추론 강도를 한 번 고르면 모든 에이전트가 그것을 그대로 상속한다. 프롬프트 캐시를 재사용하고 긴 출력은 디스크로 흘려보내 컨텍스트를 가볍게 유지한다.
16가지 프로그래밍 언어 동등 지원	Go, Python, TypeScript, JavaScript, Rust, Java, Kotlin, C#, Ruby, PHP, Elixir, C++, Scala, R, Flutter, Swift — 16가지 프로그래밍 언어를 한 집단으로 묶어 마커 기반 자동 감지로 처리한다. 어느 하나가 우대를 받지 않는다.
자가 개선	되풀이되는 실패 패턴을 관측하면 규칙 변경 제안으로 올린다. 몰래 적용하지 않고 승인을 받아 반영한다. 라우팅 결정과 게이트 증거가 결정 메모리에 쌓여 다음 실행의 재료가 된다.
모국어 친화	한국어·일본어·중국어·영어 네 로케일을 같은 PR에서 다루고, 번역투를 금지하며 모국어 글말을 따로 둔다. 모국어를 쓰는 사용자에게 영어를 강제하지 않는다.

무엇이 다른가

	Claude Code 단독	일반 하네스	moai-adk
완료 주장의 증거 귀속	사용자가 직접 확인	보통 없음	시스템이 강제 (5-섹션 증거 보고 형식)
SPEC 라이프사이클	없음	제한적	plan→run→sync 3-페이즈 + Tier S/M/L
자율 루프의 하드 경계	해당 없음	대개 turn cap만	턴 한도 + 정체 가드 + 벽시계 + 승인 게이트
병렬 작업 격리	수동	제한적	worktree + 브랜치 가드 + 사전 동기화 검사
세션 연속성	`/clear` 후 끊김	제한적	핸드오프 + 메모리 + 진행 파일
16가지 프로그래밍 언어 동등 처리	해당 없음	해당 없음	마커 자동 감지 + 언어별 툴체인
자가 개선 루프	없음	제한적	실패 관측 → 규칙 승격 (승인제)

flowchart TD
    User["사용자 요청"] --> Analyze["의도 분석<br/>Analyze-First 라우팅"]
    Analyze --> Plan["plan — SPEC 작성"]
    Plan --> Audit["독립 감사<br/>plan-auditor"]
    Audit --> Run["run — TDD/DDD 구현"]
    Run --> Verify["trust-but-verify<br/>검증 일괄 실행"]
    Verify --> Sync["sync — 문서 + PR"]
    Sync --> Learn["결정 메모리 + 교훈"]
    Learn -.다음 세션.-> Analyze

세 핵심이 서로를 지탱한다

비용만 밀면 품질이 조용히 무너진다 — 재작업과 디버그 루프가 뒤따르고, 재작업은 모든 토큰 지출 중 가장 비싸다. 품질 게이트만 있고 학습 루프가 없으면 같은 실수가 매 세션 반복된다. 비용 상한 없는 자율 루프는 과제 하나가 할당량 전체를 태울 수 있다. 세 핵심은 서로를 지탱한다 — 품질이 재작업을 막아 비용이 경제적으로 유지되고, 루프가 잘 통했던 것을 포착해 품질이 강제 가능해지며, 비용 게이트가 초과 전에 멈춰 루프가 감당 가능한 범위에 머문다.

모든 설계 결정은 이 세 핵심 중 하나에 속한다. 어느 모델을 쓸지, 얼마나 깊이 추론할지, 컨텍스트를 어떻게 쓸지 — 어느 것도 턴마다 그때그때 정해지지 않는다. 시스템이 정하고, 그 결정을 기록해 다음 실행이 더 똑똑해진다.

moai-adk의 세 가지 핵심 — 토크노믹스 · 에이전틱 루프 · 에이전틱 하네스

비용은 단가가 아니라 배정이 결정한다

토큰 가격은 3년간 98% 떨어졌지만 (Linux Foundation), 같은 기간 기업의 AI 지출은 320% 올랐다. 가격 하락을 사용량 증가가 덮어쓴 것이다. 에이전트는 과제 하나를 풀기 위해 수십에서 수백 스텝을 돌고, 토큰을 그에 비례해 태운다. 사용량 과금에서는 이것이 그대로 청구서가 되고, 구독제에서는 모든 모델이 공유하는 주간 할당량을 잡아먹는다.

Uber는 Claude Code를 엔지니어 5,000명에게 배포했다가 4개월에 1년치 코딩 예산을 태웠고, 월별 토큰 한도를 도입했다. Meta·Amazon·Microsoft도 각자 무제한 AI 정책을 철회했다. 과제에 맞는 모델을 배정해 토큰 효율을 높이는 토크노믹스 는 기술 업계의 새 기준선이 됐다.

전통적 비용 통제는 단가 상승에 맞춰 지어졌으므로, 단가는 떨어지는데 총지출은 오르는 이 역설 앞에서 무력하다. 병목은 단가가 아니라 사용량, 정확히는 에이전트가 과제를 끝내기 전까지 도는 스텝 수다.

DeepSWE 리더보드 (과제 113개, 노력도별 보기)가 이를 보여준다. 같은 Claude 계열 안에서 과제당 비용은 모델이 토큰을 얼마에 파는지가 아니라 얼마나 효율적으로 끝내는지를 따라간다.

모델 [effort]	점수	과제당 비용	비고
opus-5 [low]	58%±2	$1.66
opus-5 [medium]	69%±1	$3.29	가성비 무릎
opus-5 [high]	73%±2	$6.08	점수 +4, 비용 1.8배
opus-5 [xhigh]	73%±3	$9.07	순손실 — high와 동점, 비용만 +49%
opus-5 [max]	74%±4	$11.84
glm-5.2 [max]	44%±2	$3.92	API 과금에서 불리 · z.ai 정액제에서는 유용
sonnet-5 [max] (Sonnet 5)	54%±4	$26.40	opus-5 [low]에 지배된다

Opus 5를 가장 낮은 노력으로 돌린 쪽이 Sonnet 5를 가장 높은 노력으로 돌린 쪽보다 점수가 높고 (58% vs 54%), 과제당 비용은 16분의 1이다 ($1.66 vs $26.40) — Sonnet의 토큰 단가가 더 싸다는 점은 이길 수 없다. 원인은 268 스텝 대 36 스텝이다. 청구서를 쓰는 것은 토큰 요율이 아니라 재시도 루프다. 비용은 과제마다 알맞은 모델과 추론 깊이를 배정하는 것으로 결정된다.

위 표는 Opus 5에서 측정한 값이다. MoAI의 opus 별칭은 이제 Opus 5.5를 가리키며 (Claude Code v2.1.280 이상 필요, 기본 effort medium), sonnet 별칭은 이제 Sonnet 5.5를 가리킨다(공식 문서 기준 1M 컨텍스트). 둘 다 아직 재측정하지 않았다.

토크노믹스의 역설 — 가격은 98% 하락, 지출은 320% 상승. 해법은 측정→배정→다이어트→중단의 4단계

DeepSWE 벤치마크 — 모델×노력도별 점수와 과제당 비용

출처: DeepSWE v1.1 리더보드 (datacurve.ai, 과제 113개, 2026-07-25)

빠르게 시작

설치

macOS / Linux / WSL

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

Windows (PowerShell 7.x+)

irm https://adk.mo.ai.kr/install.ps1 | iex

소스에서 빌드 (Go 1.26+)

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

이미 설치했다면 moai update로 최신 버전으로 올린다. v3.2.0부터 moai update는 기존 프로젝트를 보존 기반으로 갱신한다 — 템플릿 관리 디렉터리를 통째로 지우고 다시 깔지 않는다. 직접 넣어 둔 파일은 그 자리에 살아남고, 템플릿 파일을 편집했다면 3-way 병합한다(충돌이면 편집본을 그대로 두고 새 버전을 <경로>.moai-new.N 사이드카로 옆에 둔다). 템플릿이 더 이상 운반하지 않는 파일은 삭제 전에 .moai/archive/files/로 옮겨 둔다 — 요약이 갱신·병합·충돌·보존·아카이브를 경로별로 모두 보고한다.

💡 비용을 줄이려면 — z.ai GLM 추천: 이 링크로 z.ai에 가입하면 일정 토큰을 보너스로 받는다. 이 링크는 moai-adk 오픈소스 개발을 후원하는 경로이기도 하다. 무료 모델(GLM-4.7-Flash, GLM-4.5-Flash)도 있으니 z.ai 요금제를 참고한다.

프로젝트 초기화

moai init my-project
cd my-project

대화형 마법사가 언어·프레임워크·방법론을 자동으로 감지하고 Claude Code 통합 파일까지 만든다.

에이전트 하니스 고르기

마법사가 프로젝트에 배포하고 연결할 에이전트 하니스를 묻는다. --llm 플래그로 비대화형으로 같은 선택을 할 수 있다:

선택	프로젝트 루트에 생기는 것
`claude` (기본값)	`.claude/` 표면 전체와 `AGENTS.md` — 지금까지의 기본 동작
`gpt`	Codex 단독 배포: `AGENTS.md`와 Codex 표면(`.codex/`, `.agents/skills/`, `.moai/`)만 설치. `.claude/` 디렉터리, `CLAUDE.md`, `.mcp.json`은 생기지 않는다. Claude 전용 런타임 기능(AskUserQuestion, 서브에이전트 소환, output style, 슬래시 명령, Workflow 스크립트)은 사용할 수 없다
`both`	`claude` 배포에 `.codex/` 연결을 더한다. `.mcp.json` 프로비저닝은 강제로 켜진다

공용 에셋은 사용자 폴더에

공용 스킬과 에이전트는 더 이상 프로젝트 파일이 아니다. 어떤 하니스를 고르든 moai init은 핵심 스킬 세트와 에이전트를 사용자 폴더 — ~/.claude/, ~/.agents/, ~/.codex/ — 에 설치하고, 놓은 파일 하나하나를 ~/.moai/user-assets.json에 기록한다(파일별 해시, 소속 번들, 설치한 moai 버전). --bundles <이름> 플래그로 첫 init에서 추가 번들을 함께 설치할 수 있다. 프로젝트 트리에는 프로젝트 고유 내용만 남는다: 설정, 룰, 훅, AGENTS.md/CLAUDE.md, 템플릿 잠금 파일, .mcp.json. 예전의 moai 플러그인 운반체는 은퇴했다 — 플러그인과 마켓플레이스 매니페스트는 더 이상 배포되지 않으며, .moai/config/sections/llm.yaml의 deployment_mode는 기록으로만 남는다.

moai update는 이 매니페스트를 기준으로 사용자 설치를 갱신한다: 배포본이 바뀐 추적 파일은 제자리에서 다시 쓰고, 직접 편집한 파일은 보존하며 ~/.moai/ 아래에 백업하고, 선택을 해제한 번들의 파일은 걷어내고, 기존 프로젝트의 템플릿 관리 스킬·에이전트는 첫 update에서 사용자 폴더로 이전한다. moai bundle add|remove <이름>으로 설치 번들 선택을 조정하고, moai doctor가 User Install과 Project Lock 어긋남을 보고한다. 선언된 v1 한계 하나: MoAI 프로필 루트(~/.moai/claude-profiles/<이름>)로 실행한 세션은 공유 사용자 에셋을 보지 못한다.

GPT 게이트웨이 철회(2026-09-16). 내장 번역 게이트웨이로 GPT 모델을 Claude Code에 얹던 옛 런처는 제거되었습니다. GPT 모델은 이제 원래 하네스인 moai codex(Codex CLI)로 사용합니다. 위의 --llm gpt init 값은 영향을 받지 않습니다 — 철회된 런처가 아니라 Codex 단독 배포를 선택하는 값입니다.

moai init my-project --llm gpt   # Codex 단독 프로젝트

이 선택이 생기기 전에 초기화한 프로젝트에는 llm.harness 키가 없어 update에서도 claude 동작을 유지한다 — 마이그레이션할 것이 없다.

첫 워크플로우

claude        # 또는 moai cc — 프로젝트 안에서 Claude Code 실행

/moai plan "JWT 로그인 추가"      # SPEC 작성
/moai run SPEC-AUTH-001           # TDD/DDD 구현
/moai sync SPEC-AUTH-001          # 문서 동기화 + PR 생성

자연어로 던져도 된다. /moai "로그인 버그 잡아줘"처럼 쓰면 의도 분석(Analyze-First 라우팅)이 요청을 읽고 알맞은 워크플로우로 넘긴다.

요구사항

플랫폼	지원 환경	비고
macOS	Terminal, iTerm2	완전 지원
Linux	Bash, Zsh	완전 지원
Windows	WSL 권장, PowerShell 7.x+	네이티브 cmd.exe 미지원

Git — 모든 플랫폼에서 필수
Claude Code — moai-adk는 Claude Code를 위한 하네스다
권장: gh CLI(PR 자동화), tmux(작업트리 창), 사용 언어의 린트/테스트 툴체인(예: golangci-lint)

핵심 기능

단일 진입점 `/moai`

자연어와 16개 서브커맨드가 같은 파이프라인으로 들어간다. /moai plan, /moai run, /moai sync가 SPEC 파이프라인의 주축이고, goal, loop, fix, review, gate, clean, codemaps, e2e, mx, feedback, project, harness, todo가 주변을 채운다.

은퇴한 서브커맨드 4개 — design · brain · coverage · security. security가 하던 일은 moai-ref-owasp-checklist + moai-ref-llm-security 스킬이 대신한다.

MCP 서버

moai init은 기본으로 정확히 하나의 활성 MCP 엔트리를 깐다 — 자체 moai mcp-server(로컬 stdio 서버)다. 이 서버가 MoAI 도구들을 Claude Code에 노출한다. 아래 표는 주요 그룹만 싣는다 — 전체 목록은 MCP 서버 가이드에 있고, 도구 수와 목록의 기준은 설치된 바이너리가 tools/list로 돌려주는 목록이다. 문서에 기록되었지만 비활성인 네 엔트리(context7, chrome-devtools, playwright, ast-grep)는 moai mcp add <이름>으로 켠다. moai mcp add|remove|list CLI가 atomic-RWM seam으로 엔트리를 관리하므로, 사용자가 .mcp.json을 직접 손편집할 일은 없다.

그룹	도구	목적
SPEC 라이프사이클	`spec_progress`, `spec_audit`, `spec_drift`	시대 분류 + 드리프트 감지
검증	`verify_snapshot`, `verify_trend`	키별 증거 스냅샷
골 + 세션	`goal_arm`, `goal_status`, `session_list`	자율 루프 + 다중 세션 조율
교차 모델 감사	`audit_multi`, `claude_audit`, `codex_audit`, `glm_audit`, `audit_cache`	다중 감사자 수렴
codex 위임	`codex_task`, `codex_setup`, `codex_job_*`	백그라운드 교차 모델 작업
GLM 위임	`glm_task`, `glm_job_status`, `glm_job_result`, `glm_job_cancel`	GLM(z.ai) 백그라운드 작업 위임

모든 백엔드는 fail-open이다 — GLM(~/.moai/.env.glm)과 codex(~/.codex/auth.json)는 선택적이며, 사용 불가 백엔드는 inconclusive를 반환할 뿐 hard error가 아니다.

Codex가 활성화된 하네스(moai init --llm gpt|both)에서 Codex의 상태 표시줄은 기본 식별자 배열(tui.status_line)만 지원하므로, goal·todo·SPEC 상태 같은 MoAI 전용 항목은 표시할 수 없다 — 명령 기반 상태 표시줄을 지원하는 openai/codex#17827이 해소되기 전까지의 한계다.

자세히: MCP 서버 가이드 · Claude Code MCP

goal 엔진 — 진짜 경계가 있는 자율 루프

완료 조건을 선언하면 세션이 조건을 채울 때까지 알아서 일한다. 턴 한도, 정체 가드, 벽시계 예산, 사전 승인 게이트가 묶여 있어 무한 루프에 빠지지 않는다. 기계적 조건(명령 종료 코드)과 모델 조건(대화 기록의 주장)을 같이 쓴다. --max-turns 0으로 auto-compact 기반 무한 골을 무장할 수도 있다 — 이때는 --max-duration과 정체 가드가 경계를 만든다.

moai goal --auto "<임무>"는 별도의 mission_mode=auto 초안을 만들고, approve가 범위·행위·근거·한도를 한 번 봉인한다. 이후 run, status, revoke, 정책으로 제한된 resume가 그 저장 계약을 사용한다. super-advisor는 비구속 조언자이고 manager-todo의 읽기 전용 판정 하위 역할이 구조화된 결정을 내며, 결정적 owner adapter가 receipt 기반 대기열·배차, 명시 경로 커밋, lease가 있는 local develop --no-ff 병합을 수행한다. 지속 실행 능력이 실제 공급자에서 입증되지 않으면 active-session-only로 낮아지고, 원격 push·PR·병합 완료는 아직 입증되지 않았다. GTD와 auto 임무 안내

최종 실행 경계는 더 엄격하다. run --supervise는 publish→pick→lease 기반 디스크 배차→commit→local develop --no-ff 계획을 제한 반복한다. 감독 Git 효과에는 분리된 --card-worktree와 --develop-worktree 경로가 필요하며, 기존 --repo만 쓰면 효과는 0건이다. 완료에는 참으로 판정된 typed evidence와 병합 ancestry를 봉인한 0600 --completion-receipt가 추가로 필요하므로, 행동 목록 소진만으로 완료되지 않는다. 완료 상태 재실행도 효과 0건이다. --recommend는 권한이 아니며 각 효과에는 저장소 안의 0600 governor receipt와 독립 감사 PASS receipt가 모두 필요하다. 미구성 원격·release provider는 성공을 흉내 내지 않고 provider_unsupported를 반환한다.

병렬 worktree

SPEC마다 독립된 작업 트리를 준다. moai cc -w <이름>으로 진입하고, --spawn을 붙이면 현재 세션을 유지한 채 새 창에서 연다. 브랜치 상태 가드가 주 체크아웃에서 실수로 브랜치를 바꾸는 것을 막는다.

팩토리 모드

-f(--factory)가 팩토리 리더를, -l(--lane)이 레인을 연다. 둘 다 인자를 받지 않는다. 리더 하나가 큐의 카드를 번호가 붙은 레인에 나르고, 레인은 카드 한 장을 plan → run → sync로 끝까지 맡는다. 실행 순서는 위 "v3.2 새 기능 — 팩토리 모드" 절에 있다.

세션의 계보는 Origin-Trail Chain이 따로 맡는다 — 팩토리 모드와 독립이라 리더도 레인도 필요 없고, moai cc -w <이름>처럼 worktree를 지정해 띄운 모든 세션이 체인에 오른다. append-only JSONL 계보 트리로 worktree 조상을 추적하고, 깊이 망각(/clear 뒤 루트-리프 체인 복구)을 해결하며, 하트비트가 끊긴 세션을 stale로 가려낸다.

개념	하는 일
Origin-Trail Chain	`.moai/state/chain/events.jsonl`의 append-only JSONL 이벤트 스트림
WorktreeNode (13 필드)	세션별 상태: ID, 부모, 깊이, origin 체인, 마일스톤, 재개 목표
CWD 충돌 해결	`(worktree_path, session_id)` 쌍으로 재사용 경로를 구분
깊이 상한	중첩 복잡도를 제한

지금 쓸 수 있다: moai chain <status|lineage|back|list|prune>으로 계보를 읽고, moai todo(인자 없이 대기열 보기, add·list·next·done·unpick·drop·undrop·edit·move·analyze, 두 단어 이상은 그대로 카드 추가)로 backlog 큐를 운영한다.

자세히: 팩토리 모드 · 세션 계보 체인

CG 폐기와 설정 이전

CG 런처는 폐기되었습니다. 이전 절차와 안내는 CG 폐기와 설정 이전 문서를 참고하세요.

moai migrate cg
moai migrate cg --target claude-only --apply --accept-role-change

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를 적어도 이 제한은 해제되지 않습니다.

16가지 프로그래밍 언어 동등 지원

Go, Python, TypeScript, JavaScript, Rust, Java, Kotlin, C#, Ruby, PHP, Elixir, C++, Scala, R, Flutter, Swift. 마커 기반 자동 감지로 각 언어의 표준 린트/포맷/테스트 툴체인을 돌린다.

자동 품질 게이트

TRUST 5(Tested · Readable · Unified · Secured · Trackable)가 모든 변경에 적용된다. /moai gate가 린트 + 포맷 + 타입 + 테스트를 한 번에 돌리고, sync-auditor가 기능·보안·제작·일관성 4차원으로 점수를 매긴다.

@MX 태그

AI 에이전트끼리 컨텍스트·불변 계약·위험 구역을 주고받는 인라인 코드 어노테이션이다. 팬인이 높거나 복잡하거나 위험한 코드만 골라 표시한다.

Navigator — 살아 있는 코드베이스 지도

@NAV:DEC, @NAV:SYM, @MX:SPEC 세 토큰 계열을 하나의 주소 가능 그래프(nav-graph.json)로 묶는다. 설계 결정·SPEC·코드 심볼이 양방향으로 이어져, 코드를 고칠 때 그 결정의 맥락이 따라온다.

세션 핸드오프

/clear를 넘어도 작업이 이어진다. 6-블록 paste-ready resume 메시지가 진행 상태를 다음 세션으로 가져가고, 자동 주입 모드에서는 메시지 한 줄로 세션을 재개한다.

loop / fix — 에러 주도 개발

/moai loop가 LSP 진단·AST-grep·린터를 병렬로 훑어 잡힌 문제를 레벨로 묶고 큐가 빌 때까지 돈다. /moai fix는 한 패스로 끝내는 단발 수리다.

review --deep

/moai review --deep이 다중 에이전트 적대적 취약점 스캔을 돌린다. OWASP · LLM 보안 · 공급망 · DevSecOps 레퍼런스 스킬이 뒤에 붙는다.

4-로케일 문서

한국어·일본어·중국어·영어 문서를 같은 PR에서 다룬다. 번역투를 금지하고 모국어 글말을 따로 두며, 4-로케일 패리티 검사가 빌드 게이트에 묶여 있다.

moai web 콘솔

moai web 콘솔 설정 화면 — 프로파일 바와 설정 탭

moai web이 로컬호스트에만 열리는 콘솔을 띄운다. 화면은 Overview·Factory·Specs·Monitor·Settings·Todo 여섯 개이고, 설정 화면은 Identity·Language·Claude settings·GLM Settings·Codex settings·Workflow·Git & Worktree·Audit·Report·MCP·Cross-Session·Feedback·Quality Gate 탭으로 나뉜다. Codex 설정 탭은 흩어져 있는 codex 설정을 한 화면에 모아 보여주는 읽기 전용 화면이라, 값은 원래 자기 탭에서 고친다. 프로파일 생성·이름 변경·삭제도 같은 화면에서 한다.

ref / domain 스킬

ref 스킬 11개(moai-ref-api-patterns, moai-ref-owasp-checklist, moai-ref-llm-security, moai-ref-react-patterns, moai-ref-testing-pyramid, moai-ref-ui-polish, moai-ref-secops, moai-ref-supply-chain, moai-ref-seo, moai-ref-git-workflow, moai-ref-cross-model-audit)와 domain 스킬 7개(moai-domain-backend, moai-domain-frontend, moai-domain-database, moai-domain-design-dna, moai-domain-html-report, moai-domain-humanize, moai-domain-svg-infographic)가 에이전트에 현장 지식을 주입한다.

SVG 기술 인포그래픽

moai-domain-svg-infographic 스킬이 편집 가능한 SVG 기술 인포그래픽을 만든다. 마크업을 쓰기 전에 좌표를 수치로 계산하고, 완성된 파일은 소스 린트와 2배 해상도 PNG 렌더 검증을 거친다. 승인 게이트 흐름, 전후 비교, KPI 카드 그리드, 의사결정 매트릭스, 레이어 스택, 중첩 스코프, 프로세스 흐름, 로드맵 타임라인, 토폴로지 구조 아홉 가지 형태를 외부 카탈로그 벤치마크로 실측해 모두 재현 가능함을 확인했다(형태별 산출물과 판정: .moai/reports/t272/verdict.md).

크로스 플랫폼

별도 의존성 없이 macOS·Linux·Windows에서 도는 Go 단일 바이너리다. 훅 시스템이 게이트를 기계적으로 강제하고, 스테이터스라인이 비용과 컨텍스트를 실시간으로 보여준다.

어떻게 돌아가나요?

SPEC 3-페이즈 라이프사이클

모든 작업은 plan → run → sync 세 페이즈로 흐른다. Tier S/M/L 크기 분류가 검증 깊이와 PR 라우팅을 정한다. GEARS 형식 요구사항과 인수 기준이 완료를 증거로 판정한다.

flowchart TD
    P["plan — SPEC 작성<br/>GEARS 요구사항 + 인수 기준"] --> PA["plan-auditor<br/>독립 감사 (편향 방지)"]
    PA -->|PASS| R["run — TDD / DDD 구현<br/>cycle_type 자동 선택"]
    PA -->|DEBT| P
    R --> SA["sync-auditor<br/>4-차원 품질 채점"]
    SA -->|PASS| S["sync — 문서 동기화 + PR"]
    SA -->|DEBT| R
    S --> MX["@MX 태그 + Navigator 갱신"]

SPEC 3-페이즈 워크플로우 — plan → run → sync

방법론(TDD/DDD)은 프로젝트 상태가 고른다. moai init이 커버리지를 보고 자동 선택한다.

flowchart TD
    A["프로젝트 분석"] --> B{"신규 프로젝트이거나<br/>커버리지 10% 이상?"}
    B -->|"예"| C["TDD (기본)"]
    B -->|"아니오"| D["DDD"]
    C --> F["RED → GREEN → REFACTOR"]
    D --> G["ANALYZE → PRESERVE → IMPROVE"]

방법론	주기	대상
TDD (기본)	RED → GREEN → REFACTOR	신규 프로젝트·기능 작업
DDD	ANALYZE → PRESERVE → IMPROVE	커버리지 10% 미만의 기존 코드

13-에이전트 카탈로그

분류	에이전트	역할
매니저	manager-spec	plan 단계 SPEC 작성
	manager-develop	run 단계 TDD/DDD/autofix 구현
	manager-docs	sync 단계 문서화
	manager-git	PR 생성·라우팅
	manager-design	디자인 단계 협업 (Claude Design)
	manager-lead	계층 팀 Tier L 조율 + 팩토리 리더 세션 배차 (유일한 Agent 보유, 깊이 2 봉인)
평가자	plan-auditor	독립 plan 감사 (편향 방지)
	sync-auditor	4차원 품질 채점 (기능성 40 · 보안 25 · 제작 20 · 일관성 15)
빌더	builder-harness	프로젝트 전용 에이전트·스킬·커맨드·훅 스캐폴딩
자문	super-advisor	고추론 자문 (E1-E4 에스컬레이션)
스페셜리스트	e2e-tester	웹/모바일/데스크톱 E2E 테스트 실행 (CLI 우선)
	manager-todo	투두 큐 관리(큐 수명 주기, `/moai:todo --auto` 직렬 사이클, 배차 안내) — 봉인 스냅숏에 대한 읽기 전용 판정 하위 역할은 판정 하나만 돌려주고 직접 적용하지 않는다 (GTD 워크플로가 부르므로 선택 결정 트리에 행이 없다)
내장	Explore	읽기 전용 코드베이스 탐색

모든 에이전트는 세션의 모델과 추론 강도를 그대로 상속한다 — 세션을 어떤 모델·effort로 띄웠는지가 곧 전체 에이전트의 배정이다. 작성과 감사를 처음부터 나눠 맡기니 자기 일을 자기가 채점하는 일이 없다.

열세 개 가운데 열두 개가 moai-adk가 만든 에이전트이고, Explore는 Claude Code에 이미 있는 내장 에이전트다.

trust-but-verify — 완료 주장에 증거를 묶기

에이전트가 "테스트가 통과했다"고 보고할 때, 오케스트레이터는 그 주장을 그대로 믿지 않고 직접 검증 일괄을 돌린다. 7개 읽기 전용 검증(테스트·커버리지·서브에이전트 경계·센티널 스캔·CLI 스모크·벤치마크·린트)을 한 턴에 병렬로 돌려 각각의 exit code와 출력을 증거로 남긴다.

검증 주장 무결성(verification-claim integrity) 규칙이 이 흐름을 뒤에서 받친다 — 돌리지 않은 검증을 성공으로 말하면 안 되고, 이전에 잰 값을 새 측정인 척 가져오면 안 되고, 관측하지 못한 것을 빈칸으로 넘기면 안 된다. 5-섹션 보고 형식(주장 · 증거 · baseline 귀속 · 미검증 · 잔여 위험)이 에이전트와 오케스트레이터의 모든 완료 보고에 묶여 있다.

검증 비용을 줄이고, 예산 초과 전에 멈춘다

검증은 필요하지만 검증 출력까지 컨텍스트에 앉을 필요는 없다. 장황한 검증 출력은 디스크 파일로 흘려보내고, 컨텍스트에는 exit code와 잘린 꼬리(최대 50줄)만 남긴다. 프롬프트 캐시를 재사용해 (캐시 읽기는 0.1배 비용) 창을 가볍게 유지하고, 컨텍스트 다이어트 /clear 전략이 임계(1M 50% / 200K 90%)에서 권고를 낸다.

예산 쪽은 토큰 회로 차단기가 지킨다 — 하드 한도(기본 90%)에서 실행을 중단하고, 진행 상태를 progress.md에 저장하며, 붙여넣기만 하면 이어지는 resume 메시지를 낸다. 스테이터스라인이 컨텍스트 사용량·캐시 적중률·레이트리밋 소진을 항상 보여주므로, 초과는 눈에 띈 채로 지나가지 않는다.

스테이터스라인 읽기

🤖 Opus | 🧠 xhigh·t | ♻️ 87% | 🔅 v2.1.212 | 🗿 v3.1.3 | ⏳ 2h 34m | 💬 MoAI
🪫 CW: ████████░░ 88% (⚠️/clear) | 🔋 5H: ████░░░░░░ 45% (4h 30m) | 🪫 7D: ████████░░ 82% (Jan 21)
📁 moai-adk-go | 📡 modu-ai/moai-adk, 7/3 | 🅱️ [WT] release/v3.1.3 +3 | 💾 +1 M2 ?0 | 📋 [run SPEC-AUTH-001-run] | 💌 PR #1042 (⌥approved)
🏷️ run | 👤 manager-develop | 🔄 TODO: 1/3

요소	의미
🤖 모델	현재 활성 모델
🧠 effort	추론 강도 — 확장 추론이 켜져 있으면 `·t` 접미
♻️ 캐시 적중률	프롬프트 캐시 적중률
CW: 컨텍스트	컨텍스트 창 사용률 + 2단계 `/clear` 마커 (⚠️ 소프트, 🛑 하드)
5H / 7D	요금제 사용률 + 초기화 시각
📁 디렉터리	프로젝트 디렉터리 이름
📡 리포	GitHub 리포 `owner/name` + 열린 이슈/PR 쌍 (`, 7/3`, 못 읽으면 `, -/-`)
🅱️ 브랜치	현재 브랜치 — 워크트리면 `[WT]` 표시, `+`는 변경 수(수정+스테이지+추적 안 됨)
💾 git 상태	스테이지 `+` · 수정 `M` · 추적 안 됨 `?` 개수 — 아이콘은 상태와 무관하게 💾 하나
📋 작업	활성 SPEC 워크플로우 `[커맨드 SPEC-ID-페이즈]`
💌 PR	활성 GitHub PR 번호 + 리뷰 상태 (`⌥상태`)
🏷️ 세션 라인	마지막 줄에 조건부 — 세션 이름 · 👤 에이전트 · 🔄 `TODO: 진행 중/대기` 백로그

자세히: 스테이터스라인 가이드

워크플로우 예시

새 기능 만들기 (TDD)

/moai plan "사용자 프로필 이미지 업로드 추가"
/moai run SPEC-PROFILE-001
/moai sync SPEC-PROFILE-001

신규 코드나 커버리지가 충분한 코드에는 TDD(RED → GREEN → REFACTOR)가 붙는다. moai init이 프로젝트 상태를 감지해 TDD와 DDD 중 하나를 고른다.

장시간 돌리기 (goal)

/moai plan "결제 모듈 리팩터링"
/moai run SPEC-PAY-001
/moai goal "go test ./... exits 0 && lint clean, or stop after 20 turns"

완료 조건을 선언하면 세션이 조건을 채울 때까지 알아서 일한다. 턴 한도가 기본 30이고 정체 가드가 묶여 있다. 컨텍스트가 임계(1M 50% / 200K 90%)에 닿으면 /clear를 권고하고 진행 상태를 progress.md에 저장한다.

병렬로 돌리기 (worktree)

moai cc -w feature-auth        # auth 작업 트리 열기
moai cc -w feature-billing --spawn   # billing은 새 창에서, 현재 세션 유지

# auth 트리 안에서
/moai run SPEC-AUTH-001

# billing 트리 안에서
/moai run SPEC-BILL-001

SPEC마다 독립된 작업 트리를 주어 두 에이전트가 서로 밟지 않게 한다. 브랜치 상태 가드가 주 체크아웃에서 실수로 브랜치를 바꾸는 것을 막는다.

CG 폐기와 설정 이전

CG 런처는 폐기되었습니다. 이전 절차와 안내는 CG 폐기와 설정 이전 문서를 참고하세요.

moai migrate cg
moai migrate cg --target claude-only --apply --accept-role-change

버그 자동으로 잡기 (loop)

/moai loop

LSP 진단·AST-grep·린터를 병렬로 훑어 잡힌 문제를 레벨로 묶고 큐가 빌 때까지 돈다. 단발 문제는 /moai fix로 한 패스에 끝낸다.

설정과 프로파일

`.moai/config/sections/`

프로젝트 설정은 YAML 단면 파일로 나뉜다. moai init이 깔아 주는 단면 파일은 모두 30개이고, 그 가운데 자주 손대는 것은 아래 여섯 개다.

단면	역할
`language.yaml`	사용자 이름 · 대화 언어 · 코드 주석 언어 · 커밋 메시지 언어
`quality.yaml`	품질 게이트 · 개발 모드(TDD/DDD) · 커버리지
`harness.yaml`	하네스 깊이(minimal · standard · thorough) · 자동 감지
`workflow.yaml`	워크플로우 동작
`lsp.yaml`	LSP 게이트 임계값 (SSOT)
`user.yaml`	사용자 정보

v3.1.1에서 손댈 만한 단면이 넷 늘었다.

단면	역할
`crosssession.yaml`	세션 간 메시지 취급. `inbound`(빈 값·`accept`·`hold`·`refuse`), `isolate_machines`(이 머신 밖으로 나가는 메시지에 승인을 요구할지), `dialog_expiry`(보류된 메시지의 승인 대화 기한)
`cache.yaml`	프롬프트 캐시 설정 파일. `session_ttl`(`1h`·`5m`·`off`)과 `spec_ttl`, 캐시할 최소 조각 크기를 담고 `moai web` 설정 편집기를 그대로 오간다. 다만 지금은 이 값을 읽는 코드가 없어, 고쳐도 동작은 달라지지 않는다
`state.yaml`	`home_retention_days` — `moai clean --home`이 며칠 지난 것부터 치울지. HOME 티어(`~/.moai/config/sections/state.yaml`)에서만 읽고, 기본은 30일, `0`을 주면 홈 정리를 끈다
`statusline.yaml`	기존 테마·세그먼트 토글에 `forge` 키가 붙었다. `github`·`gitlab`·`none` 중 하나로, 스테이터스라인이 열린 작업을 어느 호스팅에서 셀지 정한다. 비워 두면 origin 리모트 호스트로 판단하므로, 자체 호스팅 인스턴스에서는 직접 적어 준다

gate.yaml의 ast_grep_gate.rules_dir은 새 키가 아니라 기본값이 바뀐 키다. 빈 문자열이던 기본값이 .moai/config/astgrep-rules가 됐고, moai init/moai update가 그 자리에 번들 룰셋을 깐다. 코드 쪽 폴백 경로는 사라졌으니 이제 이 키가 룰셋 위치의 유일한 출처다 — 룰을 다른 곳으로 옮겼다면 이 값도 함께 고쳐야 게이트가 룰을 찾는다.

환경변수가 파일 값을 덮어쓴다. 자세한 우선순위와 전체 단면 목록은 CLI 레퍼런스를 본다.

settings.json / settings.local.json 분리

파일	역할	템플릿
`.claude/settings.json`	템플릿에서 렌더 — 프로젝트 공유 설정	포함
`.claude/settings.local.json`	런타임 관리 — 머신별 값(tmux pane ID · API 토큰 · 절대 경로)	절대 포함 않음

settings.local.json은 moai glm, moai cc가 런타임에 고치고 SessionStart 훅이 환경을 채운다. 실수로 커밋했으면 git rm --cached .claude/settings.local.json으로 뺀다.

어디서나 쓸 수 있어요

16가지 프로그래밍 언어 동등 지원


Go	Python	TypeScript	JavaScript
Rust	Java	Kotlin	C#
Ruby	PHP	Elixir	C++
Scala	R	Flutter	Swift

각 언어를 프로젝트 마커로 자동 감지해서 그 언어의 표준 린트/포맷/테스트 툴체인을 돌린다. 설치되지 않은 도구는 조용히 건너뛴다. Dart/Flutter의 정식 이름은 "flutter"다. 어느 하나가 우대를 받지 않는다.

4-로케일 문서

로케일	사이트
한국어	adk.mo.ai.kr/ko
English	adk.mo.ai.kr/en
日本語	adk.mo.ai.kr/ja
中文	adk.mo.ai.kr/zh

네 로케일을 같은 PR에서 다루고 4-로케일 패리티 검사가 빌드 게이트에 묶여 있다. 번역투를 금지하고 모국어 글말을 따로 둔다.

운영체제

플랫폼	상태
macOS	완전 지원 (Terminal, iTerm2)
Linux	완전 지원 (Bash, Zsh)
Windows	WSL 권장, PowerShell 7.x+ 지원, 네이티브 cmd.exe 미지원

Claude + GLM

z.ai GLM을 Claude Code의 대체 백엔드로 쓴다. 환경변수만 바꾸면 코드는 그대로다.

커맨드	리더	워커	tmux	비용 절감
`moai cc`	Claude	Claude	필요 없음	—
`moai glm`	GLM	GLM	권장	약 70%

GLM Coding Plan은 월 $10부터다. glm-5.3-flash(기본값), glm-5.3, glm-4.7, glm-4.5-air와 무료 모델(GLM-4.7-Flash, GLM-4.5-Flash)을 쓸 수 있다.

Claude의 각 티어는 ANTHROPIC_DEFAULT_*_MODEL 환경변수를 통해 GLM 모델로 매핑된다:

Claude 티어	GLM 모델	컨텍스트
Opus	glm-5.3-flash	1M
Sonnet	glm-5.3-flash	1M
Haiku	glm-5.3-flash	1M
Fable	glm-5.3-flash	1M

glm-5.3은 여전히 어느 티어 슬롯에서든 선택할 수 있다(llm.yaml의 llm.glm.models.*). 슬롯을 되돌리는 것도 한 줄 설정 변경이다.

자세히: Multi-LLM 가이드 · z.ai 요금제

문서와 학습

공식 문서 — adk.mo.ai.kr

adk.mo.ai.kr 온라인 문서는 12개 섹션으로 나뉜다.

섹션	설명
시작하기	소개 · 설치 · Windows 가이드 · init 마법사 · 퀵스타트 · CLI 개요 · FAQ
핵심 개념	정체성 · 컨스티튜션 · 하네스 엔지니어링 · SPEC 기반 개발 · DDD · TRUST 5
워크플로우 커맨드	`plan` · `run` · `sync` — SPEC 파이프라인 주축
유틸리티 커맨드	`fix` · `loop` · `gate` · `review` · `clean` · `codemaps` · `e2e` · `feedback` · `goal` · `gtd` (`todo` 호환)
CLI 레퍼런스	터미널 `moai` 바이너리의 모든 커맨드 (전체 49개)
Claude Code 가이드	Claude Code 통합 — 기초 · 컨텍스트/메모리 · 에이전틱 · 확장성
Multi-LLM	CG 설정 이전과 모델 정책
비용 최적화	프롬프트 캐싱 전략과 토큰 비용 절감
가이드	CI 자율화 · multi-LLM CI 등 실전 운영 레시피
Git Worktree	병렬 SPEC 개발을 위한 worktree 가이드
Advanced	토크노믹스 · 토큰 예산 · 스테이터스라인 · settings.json · 훅 · @MX 태그 · 스킬 · Harness v4 Builder · 자가 진화 · 결정 메모리
기여하기	오픈소스 기여 가이드

도서

클로드 코드로 시작하는 실전 에이전틱 코딩 — moai-adk 저자가 쓴 실전 하네스 엔지니어링 가이드. book.mo.ai.kr

CLI 명령표 (자주 쓰는 17개)

커맨드	설명
`moai init`	대화형 프로젝트 설정 (언어/프레임워크/방법론 자동 감지)
`moai doctor`	시스템 상태 진단과 환경 검증 — Home Disk Usage 항목이 `~/.moai`가 얼마나 불었는지 권고로 알려준다
`moai status`	프로젝트 상태 요약 (Git 브랜치, 품질 지표)
`moai update`	최신 버전으로 업데이트 (로컬 파일 보존 · 3-way 병합과 충돌 사이드카 · 삭제 전 아카이브)
`moai graph <build\|query>`	코드베이스 그래프(edges.jsonl) 생성·조회 — 호출자 찾기, 폭발 반경, 마일스톤 교차검사
`moai cc` / `moai glm`	Claude 전용 / GLM 전용 세션
`moai codex [cli\|status\|app]`	Codex 런처 — 인자 없이 부르면 Codex CLI를 기동한다. `status`는 준비 상태만 보여주고 아무것도 띄우지 않는다
`moai worktree <sync\|done\|sweep\|hoist\|remove\|clean\|recover\|snapshot\|verify\|restore>`	Git worktree 유지 관리 (워크트리 진입은 런처의 몫)
`moai session <list\|register\|current>`	멀티 세션 조율
`moai spec <audit\|archive\|lint\|list\|new>`	SPEC 라이프사이클 도구
`moai goal <arm\|status\|clear>`	Goal 엔진 CLI
`moai harness <status\|apply\|rollback\|disable>`	하네스 학습 라이프사이클
`moai handoff <save\|show\|clear>`	세션 핸드오프 기록
`moai preference <list\|decay-scan\|toggle>`	결정 메모리 관리
`moai memory <doctor\|archive>`	에이전트 메모리 점검과 오래된 항목 보관
`moai tokens record`	풀별 토큰 사용 원장 기록
`moai clean [--home] [--codex-skills] [--reports-archive]`	오래된 실행 산출물 정리. `--home`을 붙이면 `~/.moai`를 허용목록 범위 안에서 치우고, `--codex-skills`를 붙이면 `~/.codex/config.toml`에서 선언된 경로가 부재로 증명된 `[[skills.config]]` 등록을 지운다. `--reports-archive`를 붙이면 `.moai/reports/`의 오래된 증거 디렉터리를 `archive/<YYYY-MM>/`로 옮긴다 — 삭제는 없고 이동만 한다(기본 보존 90일, `--reports-archive-days`). 스코프는 한 번에 하나만 고른다. 기본은 dry-run이고 `--force`를 줘야 실제로 지운다
`moai web`	웹 콘솔 — 6개 화면(Overview · Factory · Specs · Monitor · Settings · Todo), 설정 탭

전체 49개 커맨드: CLI 레퍼런스

ref / domain 스킬

ref (현장 지식) 11개: moai-ref-api-patterns, moai-ref-owasp-checklist, moai-ref-llm-security, moai-ref-react-patterns, moai-ref-testing-pyramid, moai-ref-ui-polish, moai-ref-secops, moai-ref-supply-chain, moai-ref-seo, moai-ref-git-workflow, moai-ref-cross-model-audit

domain (전문 영역) 7개: moai-domain-backend, moai-domain-frontend, moai-domain-database, moai-domain-design-dna, moai-domain-html-report, moai-domain-humanize, moai-domain-svg-infographic

moai-domain-design-dna는 v3.1.1에 새로 들어왔다. 스크린샷이든 이미지 묶음이든 살아 있는 URL이든 참고할 디자인 하나를 받아 색·간격·모서리·타이포 같은 잴 수 있는 값과 그 디자인의 결, 특수 렌더링 효과까지 Design DNA JSON 한 벌로 역추출한다. 그 JSON을 다시 넣으면 같은 결을 지닌 새 산출물을 만든다 — "이 화면처럼 만들어 줘"를 말로 옮기지 않고 값으로 옮기는 경로다. 다이어그램 프로파일도 지원한다: 활성 프로파일 표식이 프로젝트 루트의 .design-dna/ 아래 저장되어 moai update를 넘겨 살아남고, 옵트인 mermaid·drawio 임포터는 소스를 신뢰하지 않는 입력으로 다뤄 좌표·색·글꼴·레이아웃은 넘어오지 않는다.

CHANGELOG

최근 변경은 CHANGELOG.md를 본다.

코드 품질 요구사항

모든 기여는 TRUST 5 게이트를 지난다 — 85% 이상 커버리지 · 린트 오류 0 · 타입 오류 0 · Conventional commits. 기존 코드는 특성화 테스트로 동작을 고정한 뒤 점진 개선(DDD), 신규 코드는 RED → GREEN → REFACTOR(TDD).

자주 묻는 질문

모든 함수에 @MX 태그가 없는 이유는?

정상이다. 태그는 팬인이 높거나, 복잡하거나, 위험한 코드에만 붙는다. 어느 프로젝트든 대부분의 코드는 태그 임계에 닿지 않으며, 태그 없는 파일은 결함이 아니다.

스테이터스라인의 버전 표시는 무슨 뜻인가?

🗿 v3.1.2 -> 🗿 v3.1.3

앞의 값이 현재 설치된 moai-adk 버전이고, 화살표는 올릴 수 있는 업데이트가 있다는 뜻이다. moai update를 실행하면 사라진다.

GLM 없이 Claude만 쓸 수 있나?

됩니다. moai cc로 GLM 없이 Claude 세션을 실행할 수 있습니다. 기존 CG 설정이 남은 프로젝트만 먼저 설정을 이전해야 합니다.

기존 프로젝트에서도 쓸 수 있나?

된다. moai init이 프로젝트 상태를 감지해 방법론을 고른다 — 커버리지 10% 미만의 기존 코드에는 DDD(특성화 테스트로 동작을 고정한 뒤 점진 개선), 신규·잘 테스트된 코드에는 TDD.

함께 만들어요

기여하기

기여는 언제든 환영한다. 자세한 절차는 CONTRIBUTING.md에 정리해 두었다.

리포지토리 포크
기능 브랜치 생성: git checkout -b feature/my-feature
테스트 작성 — 신규 코드는 TDD, 기존 코드는 특성화 테스트
테스트 · 린트 · 포맷 통과 확인: make test · make lint · make fmt
Conventional commit 메시지로 커밋하고 풀 리퀘스트 열기

코드 품질 요구사항: 85% 이상 커버리지 · 린트 오류 0 · 타입 오류 0 · Conventional commits

피드백

Claude Code 안에서는 /moai feedback으로 버그 리포트와 기능 요청을 GitHub 이슈로 바로 올린다. 터미널에서는 GitHub Issues를 쓴다.

커뮤니티

Discord — 실시간 토론과 팁
GitHub Issues — 버그 리포트 · 기능 요청

라이선스

Apache License 2.0 — 자세한 내용은 LICENSE 파일을 본다.

스타 히스토리

_{MoAI-ADK 팀이 만들었습니다 · adk.mo.ai.kr}

측정된 스타 증가

README.ko.md

MoAI-ADK

v3.2 새 기능 — 팩토리 모드

시작하기

어느 백엔드로 돌릴까

레인 N개에 카드를 한꺼번에

팩토리가 쓰는 말

팩토리를 눈으로 보기

v3.1.1에서 더해진 것

왜 moai-adk인가요?

여덟 가지 차별점

무엇이 다른가

세 핵심이 서로를 지탱한다

비용은 단가가 아니라 배정이 결정한다

빠르게 시작

설치

macOS / Linux / WSL

Windows (PowerShell 7.x+)

소스에서 빌드 (Go 1.26+)

프로젝트 초기화

에이전트 하니스 고르기

공용 에셋은 사용자 폴더에

첫 워크플로우

요구사항

핵심 기능

단일 진입점 /moai

MCP 서버

goal 엔진 — 진짜 경계가 있는 자율 루프

병렬 worktree

팩토리 모드

CG 폐기와 설정 이전

16가지 프로그래밍 언어 동등 지원

자동 품질 게이트

@MX 태그

Navigator — 살아 있는 코드베이스 지도

세션 핸드오프

loop / fix — 에러 주도 개발

review --deep

4-로케일 문서

moai web 콘솔

ref / domain 스킬

SVG 기술 인포그래픽

크로스 플랫폼

어떻게 돌아가나요?

SPEC 3-페이즈 라이프사이클

13-에이전트 카탈로그

trust-but-verify — 완료 주장에 증거를 묶기

검증 비용을 줄이고, 예산 초과 전에 멈춘다

스테이터스라인 읽기

워크플로우 예시

새 기능 만들기 (TDD)

장시간 돌리기 (goal)

병렬로 돌리기 (worktree)

CG 폐기와 설정 이전

버그 자동으로 잡기 (loop)

설정과 프로파일

.moai/config/sections/

settings.json / settings.local.json 분리

어디서나 쓸 수 있어요

16가지 프로그래밍 언어 동등 지원

4-로케일 문서

운영체제

Claude + GLM

문서와 학습

공식 문서 — adk.mo.ai.kr

도서

CLI 명령표 (자주 쓰는 17개)

ref / domain 스킬

CHANGELOG

코드 품질 요구사항

자주 묻는 질문

모든 함수에 @MX 태그가 없는 이유는?

스테이터스라인의 버전 표시는 무슨 뜻인가?

GLM 없이 Claude만 쓸 수 있나?

기존 프로젝트에서도 쓸 수 있나?

함께 만들어요

기여하기

피드백

커뮤니티

단일 진입점 `/moai`

`.moai/config/sections/`