# MoAI-ADK 심층 분석 보고서

> 작성: 헤르메스 (개발1팀장) | 날짜: 2026-03-31
> 분석 대상: github.com/modu-ai/moai-adk v2.8.1 (CLAUDE.md v13.1.0)
> 분석 범위: Go 소스 434파일, 테스트 211파일, 에이전트 24개, 스킬 389개, 규칙 31개

---

## 1. 아키텍처 분석

### 1.1 전체 구조

MoAI-ADK는 Claude Code의 "전략적 오케스트레이터"로, Go 단일 바이너리에 24개 에이전트, 389개 스킬, 31개 규칙을 `go:embed`로 내장하여 배포한다.

```
moai-adk/
├── cmd/moai/main.go             # 진입점 (15줄, cli.Execute() 위임)
├── internal/                    # 23개 비공개 패키지
│   ├── cli/                     # Cobra CLI 커맨드 (30+ 파일)
│   ├── template/                # go:embed 기반 템플릿 배포/렌더링
│   │   └── templates/           # 실제 편집 위치 (에이전트/스킬/룰/훅)
│   ├── hook/                    # Claude Code 훅 이벤트 핸들러 (25개 이벤트)
│   ├── merge/                   # 3-way 머지 엔진 (6개 전략)
│   ├── manifest/                # 파일 프로비넌스 4-상태 추적
│   ├── core/project/            # 5단계 초기화 파이프라인
│   ├── resilience/              # 서킷 브레이커 패턴
│   ├── lsp/                     # LSP 기반 품질 게이트
│   ├── tmux/                    # CG 모드 (Claude+GLM 비용 최적화)
│   └── ... (git, github, config, i18n, astgrep 등)
├── pkg/                         # 공개 라이브러리 (models, version)
├── .claude/                     # 에이전트/스킬/규칙/훅 정의
├── .moai/                       # 프로젝트 설정 YAML
└── CLAUDE.md                    # 오케스트레이터 실행 지시서
```

### 1.2 24개 에이전트의 역할과 구조

MoAI-ADK의 에이전트는 4계층으로 조직된다:

**Manager 에이전트 (8개) — 워크플로우 조율:**
- `manager-spec` (opus): EARS 요구사항 명세, SPEC 문서 작성
- `manager-strategy` (opus): 아키텍처 설계, 기술 선택
- `manager-ddd` (sonnet): ANALYZE-PRESERVE-IMPROVE 사이클 (기존 코드 리팩토링)
- `manager-tdd` (sonnet): RED-GREEN-REFACTOR 사이클 (신규 개발)
- `manager-docs` (sonnet): API 문서, README, CHANGELOG, PR 생성
- `manager-project` (sonnet): 프로젝트 문서화
- `manager-quality` (haiku): TRUST 5 품질 게이트 검증 (bypassPermissions)
- `manager-git` (haiku): Git 커밋/PR 자동화

**Expert 에이전트 (8개) — 도메인 전문가:**
- `expert-backend` (sonnet): API, DB, 인증 (11개 언어 스킬 선탑재)
- `expert-frontend` (sonnet): UI/UX, 상태관리 (Pencil MCP 17개 도구)
- `expert-security` (opus): OWASP, 취약점 분석 (유일한 opus Expert)
- `expert-devops` (sonnet): CI/CD, 컨테이너
- `expert-performance`, `expert-debug`, `expert-testing`, `expert-refactoring` (sonnet)

**Builder 에이전트 (3개) — 메타 구성:**
- `builder-agent`, `builder-skill`, `builder-plugin` (sonnet, bypassPermissions, memory:user)

**Team 에이전트 (5개, 실험적) — Agent Teams 병렬 실행:**
- 쓰기: `team-coder`, `team-tester`, `team-designer` (sonnet, isolation:worktree, background:true)
- 읽기: `team-reader` (sonnet, permissionMode:plan), `team-validator` (haiku, plan)

**우리 8팀 체계와 비교:**

| 차원 | MoAI-ADK | 우리 시스템 |
|------|---------|-----------|
| 에이전트 수 | 24개 (4계층) | 8팀 (단일 계층) |
| 역할 분리 | Manager(조율) + Expert(구현) 명확 분리 | 팀 자체가 조율+구현 |
| 모델 차등 | opus(설계/보안), sonnet(구현), haiku(검증/git) | Opus(팀장) + Sonnet/Haiku(팀원) |
| 특화 영역 | 도메인별 전문가 (security, devops, performance 등) | 역할별 팀 (dev, design, marketing 등) |

### 1.3 389개 스킬의 분류와 트리거 방식

스킬은 51개 디렉토리에 389개 마크다운 파일로 구성된다:

- **foundation** (6): 핵심 원칙(TRUST 5, SPEC-First), 위임 패턴, 품질
- **language** (14): Go, Python, TypeScript, Rust, Java 등 14개 언어별 베스트 프랙티스
- **domain** (4): backend, frontend, database, uiux
- **workflow** (8): TDD, DDD, SPEC, project, testing, loop, jit-docs, worktree
- **platform** (4): auth, deployment, database-cloud, chrome-extension
- **기타**: design(2), library(3), tool(2), framework(1), docs(1) 등

**트리거 메커니즘 (4종):**
1. `keywords`: 대화/프롬프트의 키워드 매칭
2. `agents`: 특정 에이전트 실행 시 자동 로드 (frontmatter `skills:` 배열)
3. `phases`: 워크플로우 단계별 (plan/run/sync)
4. `languages`: 파일 확장자/언어 감지

**Progressive Disclosure 3-Level 시스템:**
- Level 1 (~100 토큰): YAML frontmatter만, 항상 로드
- Level 2 (~5K 토큰): 마크다운 본문, 트리거 조건 충족 시 로드
- Level 3 (가변): modules/ 하위 파일, Claude가 명시적 요청 시 on-demand

**토큰 절감 효과:**
- 전체 로드: ~90,000 토큰 (18개 활성 스킬 × ~5K)
- Level 1만: ~1,800 토큰 → **약 81% 절감**
- 트리거 3개 Level 2 + 나머지 Level 1: ~17,100 토큰

### 1.4 Sub-Agent vs Agent Teams 듀얼 모드

**Sub-Agent 모드 (기본):**
- Agent() 호출로 직렬/병렬 위임
- 각 호출은 격리된, 무상태 컨텍스트
- MoAI만 사용자와 상호작용 (AskUserQuestion)

**Agent Teams 모드 (실험적):**
- TeamCreate/SendMessage/TaskList API 기반
- 쓰기 에이전트는 `isolation: worktree`로 격리
- 읽기 에이전트는 `permissionMode: plan`으로 충분 (격리 불필요)
- 자동 선택 기준: domains >= 3 OR files >= 10 OR complexity score >= 7

**CG Mode (비용 최적화):**
- Claude(리더) + GLM(팀메이트) tmux 격리 구조
- 60-70% 비용 절감 (구현 집중 작업)
- GLM은 env var 오버라이드로 적용 (model field가 아님)

### 1.5 Go 단일 바이너리 구조의 이점

Go를 선택한 이유와 실질적 이점:

1. **go:embed 단일 바이너리**: 24개 에이전트 + 389개 스킬 + 31개 규칙을 하나의 바이너리에 내장. 외부 런타임(Python, Node.js) 불필요
2. **크로스 플랫폼**: CI에서 5개 플랫폼 크로스 컴파일 (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64)
3. **빠른 시작**: 훅 스크립트가 Go 바이너리를 호출하므로 Python startup overhead 없음
4. **강타입 시스템**: 25개 훅 이벤트, 6개 머지 전략, 4개 프로비넌스 상태를 컴파일 타임에 검증
5. **동시성**: errgroup 기반 병렬 처리, `-race` 플래그로 경쟁 조건 탐지

**의존성**: charmbracelet TUI 생태계(bubbletea, lipgloss, huh, glamour), cobra CLI, yaml.v3

---

## 2. 방법론 분석

### 2.1 Harness Engineering 패러다임

MoAI-ADK가 정의하는 Harness Engineering:
> "코드를 직접 작성하는 대신 AI 에이전트를 위한 환경을 설계한다."

개발자의 역할: 코드 작성자 → 환경 설계자

**7대 구성 요소:**
1. 자가 검증 루프 (TDD/DDD 사이클)
2. 컨텍스트 맵 (@MX 태그 기반 AI 컨텍스트 전달)
3. 세션 지속성 (이전 세션 컨텍스트 검색/재사용)
4. 실패 체크리스트 (TRUST 5 품질 게이트)
5. 언어 중립 (17개 프로그래밍 언어 지원)
6. 가비지 컬렉션 (/moai clean 데드코드 자동 제거)
7. 스캐폴딩 우선 (SPEC 문서 기반 구조 우선 설계)

**우리의 "아누 가이드"와의 차이:**

| 차원 | MoAI Harness Engineering | 아누 가이드 |
|------|-------------------------|-----------|
| 구현 방식 | Go 바이너리 + CLAUDE.md 실행 지시서 | Python dispatch.py + 프롬프트 |
| 규칙 적용 | Claude Code hooks로 자동 강제 | 프롬프트 지시로 가이드 |
| 스킬 시스템 | 389개 스킬, Progressive Disclosure | 프롬프트 내 인라인 지시 |
| 방법론 | DDD+TDD 자동 전환 (quality.yaml) | 워크플로우 MD 파일 참조 |
| 품질 게이트 | LSP 통합 + TRUST 5 자동 검증 | qc_verify.py 스크립트 |

### 2.2 SPEC 기반 워크플로우

3단계 파이프라인: Plan → Run → Sync

**Plan (30K 토큰):** `/moai plan "기능 설명"` → manager-spec → EARS 포맷 SPEC 문서 생성
- 3파일 구조: spec.md + plan.md + acceptance.md
- 컨텍스트: product.md, structure.md, tech.md, 기존 SPEC 중복 방지

**Run (180K 토큰):** `/moai run SPEC-XXX` → manager-ddd 또는 manager-tdd
- development_mode 설정에 따라 자동 선택
- UltraThink 자동 활성화: 2+ 도메인, 8+ 파일, 아키텍처 패턴
- 체크포인트/재개 지원: `.moai/state/checkpoints/`

**Sync (40K 토큰):** `/moai sync SPEC-XXX` → manager-docs → 문서화 + PR 생성
- Deep Code Review, 커버리지 분석, SPEC 다이버전스 분석

**6단계 Agent Chain:**
spec(opus) → strategy(opus) → backend(sonnet) → frontend(sonnet) → quality(haiku) → docs(sonnet)

### 2.3 DDD + TDD 하이브리드 방법론

**TDD (신규 개발, 기본값):** RED-GREEN-REFACTOR
- RED: 실패하는 명세 테스트 작성
- GREEN: 최소 구현 (단계별 LSP 검증)
- REFACTOR: 코드 품질 개선 → simplify 스킬 자동 실행

**DDD (기존 코드 리팩토링):** ANALYZE-PRESERVE-IMPROVE
- ANALYZE: 기존 동작/코드 구조 파악
- PRESERVE: 특성화 테스트(Characterization Tests) 작성
- IMPROVE: 증분 변경 (변환별 LSP 검증)

**자동 선택 기준:**
- 신규/테스트 >=10%: TDD
- 브라운필드 테스트 <10%: DDD
- quality.yaml의 `development_mode` 설정으로 재정의 가능

**하이브리드 설계 근거:** 두 에이전트 모두 TDD+DDD 스킬을 동시 로드. DDD의 IMPROVE에서 TDD 패턴 적용, TDD의 Pre-RED에서 브라운필드 컨텍스트 이해.

### 2.4 @MX 태그 시스템

AI 에이전트 간 코드 수준 컨텍스트 전달 메커니즘:

| 태그 | 우선순위 | 조건 | 한도 |
|------|---------|------|------|
| `@MX:ANCHOR` | P1 | fan_in >= 3 함수 | 파일당 3개 |
| `@MX:WARN` | P2 | goroutine, complexity >= 15 | 파일당 5개 |
| `@MX:NOTE` | P3 | 컨텍스트 전달 목적 | 제한 없음 |
| `@MX:TODO` | P4 | 테스트 없는 공개 함수 | GREEN에서 제거 |

에이전트 생성 태그에는 `[AUTO]` 접두사 필수. `@MX:WARN`과 `@MX:ANCHOR`에는 `@MX:REASON` 서브라인 필수.

3-Pass 스캔: 구조 분석(fan_in) → 우선순위 큐 → 태그 삽입

---

## 3. 코드 구조 분석

### 3.1 핵심 패키지별 역할

**template 패키지 (핵심):**
- `embed.go`: `//go:embed all:templates` — 바이너리에 임베드
- `deployer.go`: 4-Provenance 상태머신 (TemplateManaged → UserModified → UserCreated → Deprecated)
- `renderer.go`: `missingkey=error` + passthrough 토큰 화이트리스트 ($CLAUDE_PROJECT_DIR, $HOME)
- `model_policy.go`: 24개 에이전트별 [high, medium, low] 3-tier 모델 매핑

**hook 패키지:**
- 25개 이벤트 타입 (SessionStart, PreToolUse, PostToolUse, TeammateIdle, TaskCompleted 등)
- registry.go: 순차 실행 + block 단락(short-circuit) 디스패치
- protocol.go: Claude Code stdin JSON 수신 → stdout JSON 응답

**merge 패키지 — 6개 전략:**
- LineMerge (기본), YAMLDeep, JSONMerge, SectionMerge(CLAUDE.md), EntryMerge(.gitignore), Overwrite(바이너리)

**manifest 패키지 — Triple Hash 설계:**
- TemplateHash (임베드 원본), DeployedHash (배포 당시), CurrentHash (현재 디스크)
- `DeployedHash != CurrentHash` → UserModified 승격 → 3-way 머지 필요

### 3.2 에이전트 정의 방식

`.claude/agents/moai/*.md` — YAML frontmatter + 마크다운 지시문:
- `tools`: CSV 문자열 (배열 금지)
- `skills`: YAML 배열 (tools와 다름)
- `model`: inherit/opus/sonnet/haiku
- `permissionMode`: default/acceptEdits/delegate/dontAsk/bypassPermissions/plan
- `hooks`: 에이전트별 인라인 훅 (PreToolUse, PostToolUse, Stop, SubagentStop)

### 3.3 설정 파일 구조

- `.moai/config/sections/quality.yaml`: development_mode, LSP 게이트, 커버리지 타겟
- `.moai/config/sections/workflow.yaml`: team 설정, 토큰 예산, auto_selection 기준
- `.claude/settings.json`: 15개 훅 핸들러, 권한, env, StatusLine
- `.claude/rules/moai/`: paths frontmatter 기반 조건부 로딩 (Go 파일 편집 시만 Go 규칙 로드)

---

## 4. 품질 관리

### 4.1 테스트 구조

- 총 211개 테스트 파일, 88,304 라인
- 1,118개 `t.Parallel()` 병렬 실행
- 656개 서브테스트 (`t.Run()`)
- 커버리지 목표: 패키지 85%, 핵심 패키지 90%+

**특이한 접근:**
- `coverage_improvement_test.go` (7,305라인): 미커버 브랜치 전담 타겟팅
- 요구사항 추적: 테스트명에 `REQ-HOOK-181`, `SPEC-HOOK-003` 직접 참조
- 인메모리 파일시스템: `fstest.MapFS`로 디스크 I/O 없는 배포 테스트

### 4.2 CI/CD 파이프라인

- **test**: 3 OS 매트릭스 (ubuntu/macos/windows), `-race`, `-covermode=atomic`
- **lint**: golangci-lint v2.1.6 (5분 타임아웃)
- **build**: 5 플랫폼 크로스 컴파일 (CGO_ENABLED=0)
- **AI 리뷰**: Claude Code Action (opus, high effort) + CodeRabbit (assertive)
- **보안**: CodeQL 주간 스캔

### 4.3 TRUST 5 프레임워크

| 차원 | 의미 | 검증 방법 |
|------|------|----------|
| Tested | 테스트 완비 | 85%+ 커버리지, LSP 타입 에러 0 |
| Readable | 가독성 | lint 0, 명확한 네이밍 |
| Unified | 일관성 | gofumpt 포맷팅 |
| Secured | 보안 | OWASP, CodeQL, SECURITY.md SLA |
| Trackable | 추적성 | Conventional Commits, 이슈 참조 |

**LSP 품질 게이트:**
- Plan: baseline 캡처
- Run: errors=0, type_errors=0, lint_errors=0
- Sync: errors=0, warnings <= 10

### 4.4 에러 핸들링과 복구

- `fmt.Errorf("%w")` 598회 — 컨텍스트 포함 에러 래핑
- 서킷 브레이커 패턴: Closed → Open → Half-Open 3상태 머신
- 에이전트 레벨: 3회 시도 후 팀 리드에게 보고, 한 태스크 실패 시 나머지 계속

---

## 5. 우리 시스템과의 비교 분석

### 5.1 공통점

1. **멀티 에이전트 오케스트레이션**: 둘 다 중앙 디스패처가 전문화된 에이전트에 작업 위임
2. **스킬 시스템**: 재사용 가능한 지식/패턴을 스킬로 패키지화
3. **품질 검증**: 자동화된 QC 파이프라인 (우리: qc_verify.py, MoAI: TRUST 5)
4. **Worktree 격리**: 병렬 작업 시 git worktree 기반 충돌 방지
5. **보고서 기반 워크플로우**: 에이전트가 작업 결과를 구조화된 보고서로 제출
6. **모델 차등화**: 작업 복잡도에 따라 Opus/Sonnet/Haiku 차등 배치

### 5.2 차이점

| 차원 | MoAI-ADK | 우리 시스템 (아누 + 8팀) |
|------|---------|----------------------|
| 언어 | Go 단일 바이너리 | Python 스크립트 |
| 에이전트 수 | 24개 (4계층) | 8팀 + 횡단조직 4명 |
| 계층화 | Manager/Expert/Builder/Team | 팀장(Opus) + 팀원(Sonnet/Haiku) |
| 스킬 수 | 389개 (Progressive Disclosure) | 80+ 스킬 (인라인 로딩) |
| 방법론 | DDD+TDD 자동 전환 | DIRECT-WORKFLOW.md 참조 |
| 규칙 적용 | Claude Code hooks 자동 강제 | 프롬프트 지시 기반 |
| 토큰 관리 | Progressive Disclosure (81% 절감) | 수동 컨텍스트 관리 |
| 세션 연속성 | Context Search Protocol (자동) | 체인 매니저 + task 파일 |
| 코드 주석 | @MX 태그 (fan_in 기반 자동) | 없음 |
| 비용 최적화 | CG Mode (GLM 60-70% 절감) | Sonnet/Haiku 팀원 위임 |

### 5.3 우리가 배울 점

1. **Progressive Disclosure**: 스킬 콘텐츠를 3단계로 분리하여 81% 토큰 절감. 우리 80+ 스킬도 Level 1 메타데이터만 항상 로드하고, 필요 시 본문 로드하는 방식 도입 가능
2. **역할별 모델 차등화의 정교함**: 24개 에이전트별 [high/medium/low] 3-tier 매핑. 우리도 검증/git 작업은 haiku, 설계/보안은 opus로 세분화 가능
3. **읽기/쓰기 에이전트 격리 최적화**: 읽기 전용은 worktree 불필요 (permissionMode:plan). 우리 worktree_manager.py에도 적용 가능
4. **TRUST 5 프레임워크**: 5가지 품질 차원을 명시적으로 정의하고 자동 검증. 우리 QC-RULES.md를 TRUST 5 수준으로 체계화 가능
5. **@MX 태그 시스템**: 코드 수준 AI 컨텍스트 전달. 에이전트가 코드를 수정할 때 의도를 명시적으로 전달하는 메커니즘
6. **hooks 기반 자동 강제**: PreToolUse/PostToolUse 훅으로 코드 품질 규칙을 자동 강제. 프롬프트 지시보다 확실한 방법

### 5.4 우리가 더 나은 점

1. **실전 운영 경험**: 8팀 체계로 실제 프로젝트(InsuWiki, InsuRo) 운영 중. MoAI-ADK는 오픈소스 프레임워크로 실전 운영 사례가 제한적
2. **도메인 특화 팀**: marketing, design, research 등 비개발 도메인 팀 보유. MoAI-ADK는 순수 개발 도메인에 집중
3. **체인 시스템**: chain_manager.py로 멀티 Phase 작업을 자동 연결. MoAI-ADK의 SPEC 파이프라인보다 유연한 체이닝
4. **Telegram 통합**: 스케줄링, 알림, 파일 전송이 Telegram으로 통합. MoAI-ADK는 터미널 중심
5. **QC 게이트 자동화**: qc_verify.py --gate가 .done 파일 생성을 제어. MoAI-ADK는 커버리지 임계값이 문서/리뷰에 의존
6. **횡단조직**: 보안(로키), 디자인(비너스), 품질(마아트), 기획(야누스)이 팀을 횡단하며 전문 리뷰 제공

---

## 6. 도입 가능한 아이디어

### 6.1 즉시 적용 가능

1. **Progressive Disclosure 패턴 도입**
   - 현재: 모든 스킬이 프롬프트에 인라인 로드
   - 개선: 스킬 메타데이터(이름, 트리거 조건) ~100토큰만 항상 로드, 본문은 필요 시 로드
   - 효과: Opus 컨텍스트 창 절약, 더 많은 스킬 등록 가능

2. **읽기/쓰기 에이전트 격리 분리**
   - 현재: 모든 서브에이전트에 worktree 격리 적용 가능
   - 개선: 리서치/분석 에이전트는 worktree 없이 메인 레포에서 직접 읽기
   - 효과: worktree 생성/정리 오버헤드 제거

3. **검증 작업 haiku 전용화**
   - 현재: QC 검증도 sonnet 사용
   - 개선: qc_verify.py 실행, lint 체크 등 기계적 검증을 haiku 팀원에게 위임
   - 효과: 토큰 비용 절감 (haiku는 sonnet의 1/4 비용)

### 6.2 중기적으로 검토할 것

4. **@MX 태그 시스템 도입**
   - 코드에 `@MX:ANCHOR`, `@MX:WARN` 등 AI 컨텍스트 주석 추가
   - 에이전트가 코드 수정 시 의도를 명시적으로 전달
   - fan_in 기반 자동 태깅은 IDE/LSP 연동 필요

5. **TRUST 5 프레임워크 채택**
   - QC-RULES.md를 5차원(Tested/Readable/Unified/Secured/Trackable)으로 구조화
   - 각 차원별 자동 검증 스크립트 구현
   - 보고서에 TRUST 5 점수 포함

6. **hooks 기반 자동 강제**
   - Claude Code hooks 시스템 활용하여 코드 품질 규칙 자동 강제
   - PreToolUse에서 Write/Edit 전 lint 체크
   - PostToolUse에서 테스트 통과 확인

### 6.3 참고만 할 것

7. **Go 단일 바이너리 구조**: 우리 시스템은 Python 기반으로 충분히 작동. Go 전환은 ROI 낮음
8. **CG Mode (GLM 통합)**: 현재 Claude 전용으로 충분. GLM 모델 품질 검증 후 검토
9. **Agent Teams API**: Claude Code 실험적 기능. 안정화 후 팀 모드 전환 검토
10. **SPEC 문서 시스템**: 우리는 task 파일 기반으로 충분. EARS 포맷은 대규모 프로젝트에서 유용

---

## 부록: 핵심 파일 참조 목록

| 파일 | 역할 |
|-----|------|
| `CLAUDE.md` | MoAI 실행 지시서 v13.1.0 (17개 섹션) |
| `.claude/agents/moai/` | 24개 에이전트 정의 (14,133줄) |
| `.claude/skills/moai/` | 389개 스킬 정의 (51개 디렉토리) |
| `.claude/rules/moai/` | 31개 규칙 (paths 기반 조건부 로딩) |
| `.moai/config/sections/quality.yaml` | 품질 설정 (DDD/TDD, LSP 게이트) |
| `.moai/config/sections/workflow.yaml` | 워크플로우 설정 (팀, 토큰 예산) |
| `internal/template/embed.go` | go:embed 템플릿 임베딩 |
| `internal/hook/registry.go` | 훅 이벤트 중앙 디스패치 |
| `internal/merge/strategies.go` | 6개 머지 전략 |
| `internal/template/model_policy.go` | 24개 에이전트 모델 매핑 |