modu-ai/moai-adk

MoAI‑ADK – AI 코드 에이전트를 위한 검증 중심 하니스

개요

• Claude Code(및 GLM, Codex와 같은 기타 LLM 백엔드)를 신뢰할 수 있는 소프트웨어 개발 에이전트로 오케스트레이션하는 오픈 소스 명령줄 도구(Go로 작성).
• 엄격한 검증 계층 추가: 에이전트가 주장하는 모든 내용(예: "테스트 통과")은 실제로 실행된 명령과 그 출력에 의해 뒷받침되어야 합니다. 검증되지 않은 주장은 시스템 수준에서 거부됩니다.

중요성

• 대규모 언어 모델 에이전트는 코드를 생성할 수 있지만, 외부 검사 없이는 결과를 신뢰할 수 없습니다. MoAI‑ADK는 SPEC 라이프사이클(계획 → 실행 → 동기화)과 각 단계에 증거를 바인딩하는 "TRUST 5" 게이트 세트를 강제합니다.
• 많은 에이전트를 병렬("레인")로 실행하면서 각 레인을 자체 Git 워크트리에 격리하여 실수로 덮어쓰는 것을 방지합니다.
• 장기 실행 세션을 위해 구축되었습니다: 진행 상황은 progress.md에 저장되며, /clear 후에도 컨텍스트를 잃지 않고 세션을 재개할 수 있습니다.

핵심 개념

용어	의미
Leader	백로그 큐를 감시하고 레인에 cards(작업 단위)를 배분하는 조정 세션. 직접 코드를 작성하지 않습니다.
Lane	전체 SPEC 파이프라인을 통해 단일 카드를 처리하는 작업자 세션 + 격리된 워크트리. 여러 레인이 나란히 실행됩니다.
Card	작업 단위(예: 버그 수정, 기능, 설계 변경). moai gtd "…"를 통해 추가됩니다.
Factory Mode	리더와 일련의 레인이 협업하는 기본 오케스트레이션 모드.
SPEC	3단계 라이프사이클: plan(사양 작성), run(TDD/DDD를 사용한 구현), sync(문서/PR 생성).

작동 방식

1. 카드 추가 – moai gtd "fix stale rename hint"로 작업을 백로그 큐에 넣습니다.
2. 팩토리 시작 – moai cc -f로 리더("팩토리")를 시작합니다.
3. 레인 생성 – 별도의 터미널에서 moai cc -l (Claude), moai glm -l (GLM), 또는 moai codex -l (Codex)을 실행합니다. 각 레인은 카드를 받고, 격리된 Git 워크트리를 생성하며, SPEC 단계를 실행합니다.
4. 검증 – 레인이 단계를 완료하면 증거(명령 출력, 테스트 결과)를 progress.md에 기록합니다. 리더는 레인의 주장만으로 카드를 진행시키지 않고, 이 증거를 읽은 후에만 진행시킵니다.
5. 완료 – 동기화 단계 후 레인은 사용자에게 /clear 실행을 요청합니다. 사용자가 입력한 명령은 작업이 실제로 완료되었음을 확인합니다.

주요 기능

• Factory Mode: 자동 레인 번호 매기기 및 자동 실행 기록 처리.
• 병렬 안전 격리: 각 레인은 자체 워크트리와 브랜치(WT‑<slug>)를 가지며, 리포지토리당 한 번에 하나의 쓰기 가능 에이전트만 실행됩니다.
• 세션 간 메시지 제어: crosssession.yaml을 통한 제어(다른 세션의 메시지 승인, 거부, 자동 수락).
• 홈 디렉토리 위생: moai clean --home으로 ~/.moai 아래의 오래된 상태를 제거; 위치는 MOAI_HOME으로 재정의 가능.
• 웹 콘솔 (moai web): 레인, SPEC 카운트, 큐 상태 시각화.
• 16개 프로그래밍 언어 지원: 마커 기반 자동 감지를 통해 모든 언어에 동일한 도구 지원 제공.
• 자기 개선 루프: 실패 패턴이 결정 메모리에 기록되며 사용자 승인 후 새로운 규칙으로 승격 가능.
• 멀티 백엔드: 레인별로 Claude, GLM, Codex 선택 가능; 리더는 저렴한 백엔드(GLM)에서 실행하고 레인은 더 비싼 모델을 사용할 수 있습니다.

빠른 시작

# 리더(팩토리) 시작
moai cc -f

# 별도의 터미널에서 레인 시작(자동으로 번호가 매겨짐)
moai cc -l      # Claude 레인
moai glm -l    # GLM 레인(선택 사항)
moai codex -l  # Codex 레인(선택 사항)

moai gtd "your task"로 작업을 추가하고 웹 UI(moai web)를 확인하거나 moai factory status와 같은 CLI 명령을 사용하여 진행 상황을 모니터링합니다.

사용 권장 대상

• LLM 기반 코드 생성을 실험하고 싶지만 강력한 안전 보장이 필요한 개발자.
• Claude Code(또는 유사 에이전트)를 대규모로 운영하며 재현 가능하고 감사 가능한 워크플로우를 원하는 팀.
• 토큰 예산을 존중하고, 폭주하는 세션을 피하며, 깨끗한 Git 기록을 유지하는 자율 코딩 루프 구축에 관심이 있는 사람.

더 알아보기

• 공식 문서: https://adk.mo.ai.kr
• 상세 "Factory Mode" 가이드(README에 링크됨).
• 커뮤니티 Discord: https://discord.gg/Z7E7Mdc5aN

---

위의 모든 정보는 리포지토리의 README에서 직접 가져온 것이며, 추가 기능은 추론되지 않았습니다.