MoAI-ADK: 검증 중심 하네스로 Claude Code를 통제하고, Factory Mode로 리더와 레인에 컨텍스트를 나눈다

개요

MoAI-ADK는 modu-ai 팀이 공개한 오픈소스 에이전트 오케스트레이션 하네스입니다. Go로 작성되었고 Go 1.26 이상이 필요하며 라이선스는 Apache-2.0입니다. 저장소의 릴리스 배지는 v3.1.3을 보여 주고, What's New 절에서는 v3.2의 Factory Mode를 예고합니다. 더 나은 코딩 모델을 새로 훈련하는 프로젝트가 아니라, Claude Code 같은 기존 코딩 에이전트에 외부 구조를 입혀 결과 코드를 믿을 수 있게 만드는 것이 목표입니다. 영어, 한국어, 일본어, 중국어 문서와 『Practical Agentic Coding with Claude Code』라는 동반 도서, 디스코드 커뮤니티도 제공하며 CI, CodeQL, Codecov 배지도 달려 있습니다.

핵심 주장: 세 가지 책임을 모델 밖으로

README는 설계 철학을 한 문장으로 요약하며 시작합니다. 모델은 토큰 하나씩 나아가는 확률적 작업자여서, 턴과 턴 사이에 무엇을 얼마나 썼는지 기억하지 못하고, 결과가 좋은지 판단하지 못하며, 지난 세션이 어디까지 진행됐는지도 모릅니다. 이 세 가지를 하네스가 바깥에서 강제한다는 것입니다. 공학적으로는 예산, 품질, 진행 상황입니다. MoAI-ADK는 이를 모델의 책임이 아니라 결정적 코드의 책임으로 둡니다. 프롬프트를 끝없이 길게 쓰는 방식과 달리, 모델에게 부탁하지 않고 모델을 제한하고 검사합니다.

Factory Mode의 구조

Factory Mode가 겨냥하는 것은 컨텍스트 윈도우 문제입니다. 세션 하나는 윈도우 하나를 씁니다. 긴 SPEC이 윈도우를 채우면 이후의 모든 작업이 앞선 내용을 모두 짊어지게 됩니다. 계획은 오래전에 끝났는데도 리뷰 내내 남아 있고, 리뷰는 정리 글을 쓰는 내내 남습니다. 흔한 해법인 /clear는 짐과 함께 유용한 맥락까지 버립니다.

Factory Mode는 작업을 리더 세션 하나와 번호가 붙은 여러 레인 세션으로 나눕니다. 리더는 큐를 지켜보다가 빈 레인에 카드를 넘깁니다. 카드는 단계마다 세션을 옮기지 않고 한 레인에 통째로 들어가, 그 레인이 자기 세션 안에서 plan, run, sync를 차례로 처리합니다. 각 단계는 Agent() 서브에이전트로 띄우고 레인 자신은 조율만 합니다. 한도가 사라지는 것은 아니며 세션별 제한은 그대로입니다. 달라지는 것은 기록이 쌓이는 위치입니다. 카드 하나의 이력은 그 카드를 가진 레인에만 쌓이므로 같은 예산으로 더 멀리 가고, 레인은 카드를 하나 끝낼 때마다 컨텍스트를 비운 뒤 다음 카드를 받습니다.

동작 방식

진입은 두 개의 토큰뿐입니다. moai cc -f(긴 형식 --factory)는 리더를 열고, moai cc -l(긴 형식 --lane)은 실행 중인 공장에 레인으로 합류합니다. 둘 다 값을 받지 않으며 레인 번호는 자동으로 배정됩니다. -f와 -l을 함께 쓰면 오류입니다. moai cc -l lane-2처럼 값을 붙이면 올바른 형식을 알려 주는 한 줄 오류와 함께 거부됩니다. 예전 다중 세션 보드 모드의 -k 진입은 제거되었고, moai cg는 이전 안내를 출력하고 종료합니다(moai migrate cg로 미리 볼 수 있습니다). moai gpt 명령은 없으며 GPT 모델은 moai codex로 실행합니다. moai codex에는 리더 진입이 없고 레인으로만 합류할 수 있습니다. 백엔드는 레인마다 고릅니다. moai cc -l은 Claude 레인, moai glm -l은 GLM 레인, moai codex -l은 Codex 레인입니다. 문서는 리더 자리가 판정을 내리는 곳이 아니라 큐를 보고 카드를 나르는 곳이므로 기다려도 비용이 적은 GLM(moai glm -f)이 어울린다고 설명합니다. 한 계정에서 429가 나기 시작하면 레인을 여러 계정에 나누면 됩니다. 이 조합은 하나의 예일 뿐이고 모든 세션을 단일 백엔드로 돌려도 괜찮다고 밝힙니다. 여러 카드를 동시에 처리하려면 -l을 한 번 더 실행합니다. 번호는 살아 있는 세션이 점유하는 동안에만 건너뜁니다. 죽은 레인의 점유는 더 이상 번호를 막지 않지만, 자동 배정은 항상 살아 있는 최고 번호에 1을 더한 값을 택하므로 중간의 빈자리를 채우지 않습니다. 레인 소유 정보는 ~/.moai/db/<project-key>/factory/factory.db에 기록됩니다. 기본 디렉터리가 임시 디렉터리이고 절대 경로의 MOAI_HOME 재정의가 없으면 프로젝트 안의 <base>/.moai/db/<project-key>/factory/ 아래에 기록되며, 백로그 큐도 같은 예외를 씁니다. 예전의 .moai/state/factory/workers.json은 한 번만 가져오고 롤백 증거로만 남깁니다.

레인 하나는 Agent() 서브에이전트를 최대 10개까지 동시에 돌리고, 쓰기 권한이 있는 실행은 각자의 worktree에 격리됩니다. 첫 레인을 띄워 실제로 출력이 나오는지 확인한 뒤 나머지를 시작하라는 것이 권고입니다. 카드는 여러 레인으로 쪼개지지 않습니다. 공장 실행은 그것을 소유한 세션의 프로세스 신원도 기록합니다. 리더가 죽은 실행은 다음 레인이 합류할 때 자동으로 퇴역하므로 합류가 AMBIGUOUS_FACTORY에서 멈추지 않습니다. 반대 경우도 다룹니다. 레인이 합류할 때 실행 기록이 없거나 퇴역 상태인데 살아 있는 리더 세션이 있으면, pid와 프로세스 시작 지문으로 그 리더를 검증합니다.

성능과 비용: 근거는 어디에 있나

제공된 README 발췌에는 벤치마크 수치가 없습니다. 처리량도, 토큰 비용 비교도, 결함률의 전후 비교도 없습니다. 제시된 것은 구조적 논거로, 카드의 이력이 담당 레인 안에만 쌓이므로 같은 예산으로 더 멀리 간다는 주장입니다. 합리적인 원리이지만 측정값이 공개되기 전까지는 검증된 이득이 아니라 가설로 읽어야 합니다. 평가하려면 카드당 평균 컨텍스트 사용량, 레인이 비워진 뒤의 윈도우 재사용 효율, 429 발생률, 리더와 레인 사이의 조율 비용 같은 측정 가능한 지표를 추적하면 됩니다.

개발자와 팀에 미치는 영향

개인 개발자에게 Factory Mode는 별도 스케줄러 없이 병렬화하는 방법입니다. 터미널을 여러 개 열어 각각 moai cc -l을 실행하면 됩니다. 팀에게는 상태가 프로젝트 키 아래의 SQLite 파일에 있어 감사와 복구가 쉽습니다. 다중 백엔드 지원으로 한 공급자에 기대지 않고 비용과 한도에 맞춰 조합할 수 있습니다. 더 넓게 보면 경쟁의 축이 모델 자체에서 모델을 감싸는 프로세스와 검증 계층으로 옮겨 가고 있음을 보여 줍니다.

한계와 전망

첫째, 한 세션이 다른 세션을 띄울 수 없으므로 레인은 터미널마다 손으로 하나씩 시작해야 합니다. 완전 자동화에 한계가 있습니다. 둘째, 공개 자료에 정량 벤치마크가 없습니다. 셋째, 프로세스 신원 검증과 예전 상태의 일회성 가져오기는 장애 복구가 이미 상당한 복잡도를 안고 있음을 보여 주며, 사용자는 이런 경계 사례를 이해해야 합니다. 넷째, 카드를 쪼개지 않는 원칙 때문에 매우 큰 단일 작업은 여전히 레인 하나의 윈도우를 가득 채울 수 있습니다. 측정 보고서 공개, 백엔드 확대, 더 세밀한 카드 분할 정책이 기대되는 방향입니다. 요컨대 MoAI-ADK는 눈여겨볼 만하지만, 실제 운영 흐름에 넣기 전에 작은 규모의 실제 작업으로 직접 측정해 보시기 바랍니다.