# MoAI-ADK → 우리 시스템 적용 제안서

> 작성: 헤르메스 (개발1팀장) | 날짜: 2026-03-31
> 기반 분석: moai-adk-analysis.md
> 적용 대상: 아누 시스템 (dispatch.py + 8팀 + 횡단조직)

---

## 1. 적용 우선순위 매트릭스

| 우선순위 | 아이디어 | 난이도 | 효과 | 적용 시기 |
|---------|---------|-------|------|---------|
| P1 | Progressive Disclosure 스킬 로딩 | 중 | 높음 | 즉시 |
| P1 | 읽기/쓰기 에이전트 격리 분리 | 낮음 | 중 | 즉시 |
| P1 | 검증 작업 haiku 전용화 | 낮음 | 중 | 즉시 |
| P2 | TRUST 5 기반 QC-RULES.md 구조화 | 중 | 높음 | 2주 내 |
| P2 | 에이전트별 모델 매핑 테이블 | 중 | 높음 | 2주 내 |
| P3 | @MX 태그 시스템 파일럿 | 높음 | 중 | 1개월 내 |
| P3 | Claude Code hooks 자동 강제 | 높음 | 높음 | 1개월 내 |
| P4 | Context Search Protocol | 높음 | 중 | 장기 검토 |
| P4 | Agent Teams API 전환 | 높음 | 높음 | Claude Code 안정화 후 |

---

## 2. P1 — 즉시 적용 가능

### 2.1 Progressive Disclosure 스킬 로딩

**현재 문제:**
- 80+ 스킬이 시스템 프롬프트에 전부 나열됨
- 각 스킬의 `description`과 `Use when` 조건이 프롬프트 토큰을 대량 소비
- Opus 컨텍스트 창에서 스킬 목록만으로 상당한 토큰 점유

**MoAI-ADK 패턴:**
```
Level 1 (~100 토큰): name + 1줄 description + 트리거 키워드
Level 2 (~5K 토큰): 전체 스킬 내용 (매칭 시만 로드)
Level 3 (가변): 참조 모듈 (on-demand)
```

**적용 방안:**
1. 각 스킬의 system-reminder를 Level 1 (이름 + 1줄 설명 + 트리거 키워드)로 축약
2. 스킬이 트리거되면 Skill tool 호출 시 전체 내용 로드
3. 기대 효과: 스킬 목록 토큰 50-70% 절감

**구현 난이도:** 중 (스킬 등록 방식 변경 필요, Claude Code 설정 수정)

### 2.2 읽기/쓰기 에이전트 격리 분리

**현재 문제:**
- 모든 서브에이전트에 worktree isolation 적용 가능
- 리서치/분석 목적의 에이전트도 worktree를 생성하면 오버헤드 발생

**MoAI-ADK 패턴:**
```
쓰기 에이전트 → isolation: worktree (파일 충돌 방지)
읽기 에이전트 → permissionMode: plan (worktree 불필요)
```

**적용 방안:**
1. DIRECT-WORKFLOW.md에 규칙 추가:
   - "리서치/분석 태스크의 서브에이전트는 worktree 격리 불필요"
   - "코딩 태스크의 서브에이전트만 worktree 생성"
2. worktree_manager.py에 `--read-only` 플래그 추가 (worktree 스킵)

**구현 난이도:** 낮음 (워크플로우 문서 수정 + 옵션 플래그)

### 2.3 검증 작업 haiku 전용화

**현재 문제:**
- QC 검증, lint 체크 등 기계적 작업도 sonnet 팀원이 수행
- sonnet 토큰 비용이 haiku의 4배

**MoAI-ADK 패턴:**
```
manager-quality: haiku (품질 검증은 기계적 작업)
manager-git: haiku (git 커밋/PR도 기계적 작업)
team-validator: haiku (팀 품질 검증)
```

**적용 방안:**
1. DIRECT-WORKFLOW.md의 Step 6(QC) 실행 시 `model="haiku"` 지정
2. 보고서 작성 등 기계적 포맷팅 작업도 haiku 위임
3. git 관련 작업 (커밋 메시지 생성, diff 분석)은 haiku로 충분

**구현 난이도:** 낮음 (Agent tool 호출 시 model 파라미터 변경)

---

## 3. P2 — 2주 내 검토

### 3.1 TRUST 5 기반 QC-RULES.md 구조화

**현재 문제:**
- QC-RULES.md가 체크리스트 형태로 나열
- 품질 차원이 명확히 구분되지 않음
- 검증 항목 간 우선순위 불명확

**MoAI-ADK TRUST 5:**
- **T**ested: 테스트 커버리지, 타입 에러
- **R**eadable: 네이밍, 주석, lint
- **U**nified: 포맷팅 일관성, 코드 스타일
- **S**ecured: OWASP, 입력 검증, 시크릿 관리
- **T**rackable: 커밋 메시지 규칙, 이슈 참조

**적용 방안:**
1. QC-RULES.md를 5차원으로 재구조화
2. 각 차원별 자동 검증 항목과 수동 검증 항목 구분
3. qc_verify.py에 `--dimension` 옵션으로 특정 차원만 검증 가능
4. 보고서에 TRUST 5 점수(각 차원 Pass/Fail) 포함

**구현 스케치:**
```python
# qc_verify.py 확장
class TrustValidator:
    def validate_tested(self):  # pytest 결과, 커버리지
    def validate_readable(self):  # pyright, ruff
    def validate_unified(self):  # 포맷 일관성
    def validate_secured(self):  # 시크릿 스캔, 입력 검증
    def validate_trackable(self):  # 커밋 메시지, 브랜치명
```

### 3.2 에이전트별 모델 매핑 테이블

**현재 문제:**
- "단순 코딩 → haiku, 일반 코딩 → sonnet" 정도의 가이드라인만 존재
- 작업 유형별 최적 모델 선택이 팀장 재량

**MoAI-ADK 패턴:**
```python
# 24개 에이전트별 [high, medium, low] 3-tier 매핑
agentModelMap = {
    "manager-spec":     ["opus", "opus", "sonnet"],    # 항상 opus
    "manager-quality":  ["haiku", "haiku", "haiku"],   # 항상 haiku
    "expert-security":  ["opus", "opus", "sonnet"],    # 보안은 opus
    "expert-backend":   ["opus", "sonnet", "sonnet"],  # 예산에 따라
}
```

**적용 방안:**

1. 팀원 역할별 기본 모델 매핑 테이블 작성:

```
불칸(백엔드): sonnet (일반), opus (아키텍처 설계)
이리스(프론트): sonnet (일반)
아테나(UX/UI): sonnet (디자인 리뷰), haiku (에셋 생성)
아르고스(테스터): haiku (테스트 실행/검증), sonnet (테스트 설계)
```

2. 작업 유형별 모델 오버라이드 규칙:
```
리서치/분석: sonnet
코딩 구현: sonnet
단순 테스트: haiku
QC 검증: haiku
보안 리뷰: opus (로키 소환)
설계 문서: sonnet
```

3. DIRECT-WORKFLOW.md에 "모델 선택 가이드" 섹션 확장

---

## 4. P3 — 1개월 내 파일럿

### 4.1 @MX 태그 시스템 파일럿

**목적:** 에이전트가 코드를 수정할 때 의도를 코드에 남겨, 다음 에이전트가 컨텍스트를 빠르게 파악

**MoAI-ADK 방식:**
```python
# @MX:ANCHOR: [AUTO] fan_in=3, 모든 디스패치 경로의 진입점
# @MX:REASON: dispatch.py, chain_manager.py, cron_runner.py에서 호출
def assign_task(task_id, team_id):
    ...
```

**적용 방안 (파일럿 범위 제한):**
1. 대상: `/home/jay/workspace/` 핵심 스크립트 (dispatch.py, chain_manager.py, task-timer.py)
2. 태그 종류: `@MX:ANCHOR` (핵심 함수)와 `@MX:WARN` (위험 코드)만 시작
3. 규칙: fan_in >= 3 함수에 `@MX:ANCHOR` 추가, 에이전트 자동 태깅 시 `[AUTO]` 접두사
4. 검증: 1주 후 태그가 에이전트 작업 속도에 미치는 영향 측정

**주의사항:** 전체 코드베이스에 일괄 적용하지 않고, 핵심 파일 5-10개로 파일럿 후 확장 판단

### 4.2 Claude Code hooks 자동 강제

**목적:** 프롬프트 지시 대신 Claude Code hooks로 코드 품질 규칙 자동 강제

**MoAI-ADK 방식:**
```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "command": "validation_script.sh",
      "timeout": 5
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "command": "verification_script.sh",
      "timeout": 60
    }]
  }
}
```

**적용 방안:**
1. `UserPromptSubmit` 훅: 현재 이미 작업 규칙 주입에 사용 중
2. `PostToolUse` 훅 추가: Write/Edit 후 자동으로:
   - pyright 에러 체크
   - ruff 포맷 체크
   - 테스트 파일 변경 시 pytest 실행
3. `Stop` 훅 추가: 작업 완료 시 자동으로:
   - 보고서 존재 여부 확인
   - .done 파일 검증

**주의사항:** 훅 timeout 설정 주의. pytest가 오래 걸리면 PostToolUse가 블로킹될 수 있음.

---

## 5. P4 — 장기 검토

### 5.1 Context Search Protocol

MoAI-ADK의 이전 세션 검색 기능. 우리 시스템에서는 task 파일과 보고서가 이 역할을 대체하고 있으나, 다음과 같은 개선이 가능:

- 작업 시작 시 관련 이전 보고서 자동 검색/주입
- 토큰 예산 관리: 150K 토큰 초과 시 검색 비활성화
- 주입당 최대 5K 토큰 제한

### 5.2 Agent Teams API 전환

Claude Code의 Agent Teams (TeamCreate/SendMessage/TaskList)가 안정화되면:
- 현재의 dispatch.py + Task tool 방식에서 공식 API로 전환
- 팀원 간 SendMessage로 직접 통신 (현재는 팀장을 경유)
- TaskList로 자기 조정형 작업 분배

---

## 6. 비용 영향 분석

### 현재 추정 비용 구조 (작업당)

```
팀장(Opus): ~50% 토큰 (설계/검토/통합)
팀원(Sonnet): ~40% 토큰 (구현)
팀원(Haiku): ~10% 토큰 (단순 작업)
```

### 최적화 후 예상 구조

```
팀장(Opus): ~30% 토큰 (Progressive Disclosure로 스킬 토큰 절감)
팀원(Sonnet): ~35% 토큰 (구현 집중)
팀원(Haiku): ~35% 토큰 (검증/QC/git을 haiku로 이관)
→ 예상 비용 절감: 20-30% (haiku의 1/4 비용 효과)
```

---

## 7. 실행 로드맵

### Week 1 (즉시)
- [ ] P1.2: DIRECT-WORKFLOW.md에 읽기/쓰기 격리 규칙 추가
- [ ] P1.3: QC 검증/보고서 포맷팅을 haiku 전용화

### Week 2-3
- [ ] P1.1: 스킬 메타데이터 축약 실험 (5개 스킬 파일럿)
- [ ] P2.2: 에이전트별 모델 매핑 테이블 작성 및 WORKFLOW-RULES.md 반영

### Week 3-4
- [ ] P2.1: QC-RULES.md를 TRUST 5 구조로 재편
- [ ] P2.1: qc_verify.py에 5차원 검증 추가

### Month 2
- [ ] P3.1: @MX 태그 파일럿 (핵심 스크립트 5-10개)
- [ ] P3.2: PostToolUse 훅 파일럿

---

## 8. 결론

MoAI-ADK에서 배울 핵심 교훈 3가지:

1. **토큰은 비용이다**: Progressive Disclosure, 모델 차등화, 읽기/쓰기 격리 분리 모두 토큰 비용 최적화가 핵심 동기. 우리도 "모든 것을 Opus로" 대신 "적재적소에 적정 모델을" 원칙 적용 필요.

2. **프롬프트 지시 < 자동 강제**: MoAI-ADK는 Claude Code hooks로 품질 규칙을 자동 강제한다. "해주세요"가 아니라 "하지 않으면 블록됩니다" 방식이 더 확실하다.

3. **에이전트도 사용자다**: @MX 태그, Progressive Disclosure, Context Search Protocol 모두 "AI 에이전트를 위한 UX" 설계다. 우리 시스템의 프롬프트, 보고서, task 파일도 "에이전트가 쉽게 이해할 수 있는 형태"로 최적화하면 작업 품질이 향상된다.