# MoAI-ADK 도입 계획서

작성일: 2026-03-31
작성자: 므네모시네 (마케팅 전략가)
상태: 초안 확정 — 실행 준비 중

---

## 1. Executive Summary

### 목표

MoAI 멀티에이전트 시스템에 Google ADK(Agent Development Kit)를 점진적으로 도입하여 토큰 효율, QC 신뢰도, 워크플로우 격리 품질을 정량적으로 개선한다.

### 범위

10개 도입 항목을 P1–P4 우선순위로 분류하고, 8주(+장기 P4) 타임라인으로 순차·병렬 실행한다. 모든 항목은 feature_flags.json 기반 킬스위치로 안전하게 배포한다.

### 기간

- 기준선 측정: 2026-04-01 ~ 04-06 (CODE FREEZE 포함)
- 실행 본체: 2026-04-07 ~ 05-29 (Week 1–8)
- 장기(P4): Week 9 이후, 별도 재논의

### 핵심 성과 지표 (KPI)

| 지표 | 기준선 (측정 후 확정) | 목표 |
|---|---|---|
| 프롬프트 평균 토큰 | .metrics/ JSON 기록 | summary ≤600, standard ≤1800 |
| FNR (QC 오탐률) | 기준선 측정 | <15% |
| TRUST 태그 매핑 불일치율 | — | <3% |
| haiku 전환율 (A/B) | — | Fisher's exact p<0.05, n>150 |
| hooks 위반 자동 차단 | 0% | circuit breaker 적용 |

---

## 2. 도입 항목 로드맵

### 2.1 P1 — 즉시 적용 (Week 1–3)

#### 항목 1: Progressive Disclosure

**목표**: 프롬프트 컨텍스트를 3단계로 단계적 공개하여 불필요한 토큰 소비를 줄인다.

**수정 파일**: `build_prompt.py`

**구현 방법**:
- `disclosure_phase` 파라미터 3단계 신설: `summary` / `standard` / `full`
- CRITICAL 섹션(~80 토큰) 하드코딩 — 모든 phase에서 항상 포함
- 비율 검증 조건: summary 15–25% / standard 40–60% / full 100%
- feature flag: `progressive_disclosure_enabled`

**테스트**: 각 phase별 토큰 카운트 단위 테스트, CRITICAL 섹션 누락 여부 assertion

**DoD (완료 기준)**:
- 3단계 분기 로직 구현 완료
- CRITICAL 하드코딩 검증 테스트 통과
- 비율 범위 벗어나면 경고 로그 출력

**DRI**: 헤르메스
**데드라인**: Week 2 (4/17 버퍼 데이 전)

---

#### 항목 2: 읽기/쓰기 격리

**목표**: 에이전트 타입을 명시 선언하여 write 에이전트의 불필요한 읽기 전용 작업 혼용을 방지한다.

**수정 파일**: `dispatch.py`, `worktree_manager.py`

**구현 방법**:
- `dispatch.py` — `--agent-type` 플래그 추가: `read` / `write` (기본값: `"write"`)
- `worktree_manager.py` — `--read-only` 옵션 추가, read 타입이면 자동 전달
- WORKFLOW 섹션 5 추가: read/write 선택 기준 명시
- feature flag: `rw_isolation_enabled`

**테스트**: read 에이전트가 write 작업 시도 시 차단 여부, 기본값 "write" 동작 확인

**DoD**:
- `--agent-type read` 시 worktree read-only 마운트 확인
- 기존 호출부 호환성 유지 (기본값 유지)

**DRI**: 헤르메스
**데드라인**: Week 2

---

#### 항목 7: Hooks 자동 강제

**목표**: 코드 품질 위반을 자동으로 감지·차단하여 사람의 리뷰 부담을 줄인다.

**수정 파일**: `hooks/settings.json`, PostToolUse 훅 구현체

**구현 방법**:
- PostToolUse 이벤트에 `pyright` + `ruff` 자동 실행
- 심각도 2단계: WARNING(로그만) / ERROR(차단)
- circuit breaker: (tool, error_code, file_path) 3-튜플 키
  - 동일 3-튜플 15회 → 30초 cooling
  - 30초 내 재발 → 동일 횟수 연장
- feature flag: `hooks_enforcement_enabled`

**테스트**: 의도적 pyright 오류 파일로 차단 동작 검증, circuit breaker 임계치 단위 테스트

**DoD**:
- pyright + ruff 훅 연동 완료
- circuit breaker 로직 구현 및 테스트 통과
- 심각도별 처리 분기 확인

**DRI**: 헤르메스
**데드라인**: Week 3

---

### 2.2 P2 — 2주 내 (Week 3–8)

#### 항목 4: TRUST 5 태그

**목표**: 기존 9종 verifier 결과를 TRUST 5차원으로 표준화하여 QC 결과 일관성을 높인다.

**수정 파일**: `qc_verify.py`, `QC-RULES.md`

**구현 방법**:
- `qc_verify.py` — `trust_summary` JSON 출력 추가
- verifier 9종 → TRUST 5차원 매핑 테이블 정의 (QC-RULES.md 반영)
- 매핑 불일치율 모니터링: <3% 유지 조건
- feature flag: `trust5_tags_enabled`

**TRUST 5차원**: (구체 차원명은 QC-RULES.md에서 확정)

**테스트**: 매핑 커버리지 100% 단위 테스트, 불일치 케이스 시나리오 테스트

**DoD**:
- 9종 verifier 전부 TRUST 차원에 매핑
- `trust_summary` JSON 스키마 검증 통과
- 매핑 불일치율 <3% 모니터링 로직 추가

**DRI**: 마아트
**데드라인**: Week 3

---

#### 항목 3: Haiku 전용화 (A/B 실험)

**목표**: 특정 작업군에서 claude-haiku 전환 시 품질 저하 없이 비용을 절감할 수 있는지 통계적으로 검증한다.

**수정 파일**: `qc_verify.py`, A/B 실험 설정 파일

**구현 방법**:
- Fisher's exact test 기반 A/B 실험
- 유의 수준: α=0.05, 최소 샘플: n>150
- FNR <15% 유지 조건
- 실험 기간: 4주 + 필요 시 1주 연장
- 주 1회 sonnet으로 재검증(샘플 20%)
- feature flag: `haiku_specialization_enabled`

**테스트**: A/B 할당 로직 단위 테스트, Fisher's exact 계산 검증

**DoD**:
- A/B 실험 설계 문서 `/memory/specs/adk-impl-spec-3.md` 완성
- n>150 달성 후 통계 판정 실행
- FNR <15% 조건 미충족 시 자동 롤백 트리거

**DRI**: 마아트
**데드라인**: Week 4 시작, Week 8 최종 판정

---

#### 항목 5: 모델 매핑 테이블

**목표**: 에이전트-모델 매핑을 코드 내 상수로 명시하여 임의 변경을 방지하고 staleness를 감지한다.

**수정 파일**: `team_prompts.py`

**구현 방법**:
- `MODEL_MAP` 상수 정의 (에이전트명 → 모델명)
- 마지막 수정일 기준 7일 초과 시 경고 로그 출력
- feature flag: `model_map_enabled`

**테스트**: staleness 경고 발생 조건 단위 테스트, 미정의 에이전트 접근 시 오류 확인

**DoD**:
- `MODEL_MAP` 상수 선언 완료
- 7일 staleness 경고 동작 검증
- 스펙 문서: `/memory/specs/adk-impl-spec-5.md`

**DRI**: 헤르메스
**데드라인**: Week 4

---

### 2.3 P3 — 1개월 내 (Week 5–8, 설계)

#### 항목 10: Task 파일 구조 표준화

**목표**: 태스크 파일의 디렉토리 구조와 네이밍 규칙을 표준화하여 에이전트 간 파일 탐색 오버헤드를 줄인다.

**수정 파일**: `DIRECT-WORKFLOW.md`, 관련 태스크 템플릿

**구현 방법**:
- Week 5–8: 표준 구조 설계 및 문서화
- 자동 생성 도구는 P4로 이관 (Week 9+)
- 표준 스펙: `/memory/specs/adk-impl-spec-10.md`

**DoD (P3 설계 단계)**:
- 표준 디렉토리 트리 정의 완료
- DIRECT-WORKFLOW.md 업데이트
- 기존 파일 마이그레이션 가이드 작성

**DRI**: 오딘
**데드라인**: Week 8 (설계 완료)

---

### 2.4 P4 — 장기 (Week 9+)

P1/P2 효과 검증 완료 후 재논의. 하기 항목은 외부 의존성 또는 추가 데이터 필요.

#### 항목 6: @MX 태그

- **현황**: P1/P2 효과 검증 전 구현 보류
- **재논의 트리거**: Week 8 전체 평가 결과에서 태그 체계 개선 필요성이 확인될 때
- **DRI**: 미정

#### 항목 8: Context Search

- **현황**: ADK 네이티브 기능 출시 대기
- **재논의 트리거**: Google ADK Context Search API 공개 발표
- **DRI**: 미정

#### 항목 9: Agent Teams API

- **현황**: Google ADK 로드맵 의존 — 공개 ETA 미정
- **재논의 트리거**: Google ADK Agent Teams API 베타 진입
- **DRI**: 미정

---

## 3. 파일 변경 매트릭스

| 파일 | 항목 1 | 항목 2 | 항목 3 | 항목 4 | 항목 5 | 항목 7 | 항목 10 |
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| `build_prompt.py` | ✓ | | | | | | |
| `dispatch.py` | | ✓ | | | | | |
| `worktree_manager.py` | | ✓ | | | | | |
| `team_prompts.py` | | | | | ✓ | | |
| `qc_verify.py` | | | ✓ | ✓ | | | |
| `QC-RULES.md` | | | | ✓ | | | |
| `hooks/settings.json` | | | | | | ✓ | |
| `DIRECT-WORKFLOW.md` | | ✓ | | | | | ✓ |
| `feature_flags.json` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
| `.metrics/*.json` | ✓ | | ✓ | ✓ | | | |

---

## 4. 실행 타임라인

### Phase 0a: 기준선 측정 (4/1–4/3, CODE FREEZE)

- `.metrics/` 디렉토리 초기화
- 현재 평균 토큰, FNR, 에러율 JSON 기록
- 측정 항목: 프롬프트 토큰 분포, QC 결과 분포, hooks 위반 빈도
- **CODE FREEZE**: 기간 중 코드 변경 금지

### Phase 0b: 사전 준비 (4/4–4/6)

- `feature_flags.json` 초기 생성 (6플래그, 전체 기본값 `false`)
- 스펙 문서 템플릿 생성: `/memory/specs/adk-impl-spec-{#}.md`
- 팀별 작업 브랜치 및 워크트리 설정

### Week 1–2: 그룹 A — P1 핵심 (4/7–4/17)

| 날짜 | 작업 | DRI |
|---|---|---|
| 4/7–4/10 | 항목 1 build_prompt.py disclosure_phase 구현 | 헤르메스 |
| 4/7–4/10 | 항목 2 dispatch.py --agent-type 구현 | 헤르메스 |
| 4/11–4/14 | 항목 1 테스트 + 항목 2 worktree_manager.py 연동 | 헤르메스 |
| 4/15–4/16 | 통합 테스트 + feature flag 검증 | 헤르메스 |
| **4/17** | **버퍼 데이 (예비일)** | |

### Week 3: 그룹 C — Hooks + TRUST 태그 (4/18–4/24)

| 날짜 | 작업 | DRI |
|---|---|---|
| 4/18–4/21 | 항목 7 hooks PostToolUse + circuit breaker 구현 | 헤르메스 |
| 4/18–4/21 | 항목 4 TRUST 5 매핑 테이블 + qc_verify.py 수정 | 마아트 |
| 4/22–4/24 | 항목 7 + 항목 4 통합 검증 | 헤르메스, 마아트 |

### Week 4: P2 완성 + A/B 시작 (4/25–5/1)

| 날짜 | 작업 | DRI |
|---|---|---|
| 4/25–4/28 | 항목 5 MODEL_MAP 상수 + staleness 경고 구현 | 헤르메스 |
| 4/25–4/28 | 항목 3 A/B 실험 설계 문서 완성 | 마아트 |
| 4/29–5/1 | 전체 P1+P2 통합 테스트 + A/B 실험 시작 | 전체 |

### Week 5–7: A/B 진행 + P3 설계 (5/2–5/22)

| 주차 | 작업 | DRI |
|---|---|---|
| Week 5 | A/B 중간 점검 (n 달성 현황) + 항목 10 설계 착수 | 마아트, 오딘 |
| Week 6 | 주 1회 sonnet 재검증 20% 실행 + 항목 10 표준 스펙 초안 | 마아트, 오딘 |
| Week 7 | A/B 데이터 누적 + 항목 10 DIRECT-WORKFLOW.md 업데이트 | 마아트, 오딘 |

### Week 8: 최종 판정 (5/23–5/29)

- 항목 3 A/B 최종 판정 (Fisher's exact, n>150 확인)
- 전체 KPI 대비 실적 평가
- P4 항목 재논의 여부 결정
- 회고 및 다음 단계 계획

---

## 5. 팀 배정 및 DRI

### 헤르메스

**책임 파일**: `dispatch.py`, `team_prompts.py`, `feature_flags.json`
**담당 항목**: 1 (Progressive Disclosure), 2 (읽기/쓰기 격리), 5 (MODEL_MAP), 7 (Hooks 자동 강제)

| 항목 | 산출물 | 스펙 문서 |
|---|---|---|
| 1 | `build_prompt.py` disclosure_phase 3단계 | `/memory/specs/adk-impl-spec-1.md` |
| 2 | `dispatch.py` --agent-type + `worktree_manager.py` --read-only | `/memory/specs/adk-impl-spec-2.md` |
| 5 | `team_prompts.py` MODEL_MAP 상수 | `/memory/specs/adk-impl-spec-5.md` |
| 7 | PostToolUse hooks + circuit breaker | `/memory/specs/adk-impl-spec-7.md` |

---

### 오딘

**책임 파일**: `DIRECT-WORKFLOW.md`, `hooks/settings.json`
**담당 항목**: 10 (Task 파일 구조 표준화, P3 설계)

| 항목 | 산출물 | 스펙 문서 |
|---|---|---|
| 10 | 표준 디렉토리 트리 + DIRECT-WORKFLOW.md 업데이트 | `/memory/specs/adk-impl-spec-10.md` |

---

### 마아트

**책임 파일**: `QC-RULES.md`, `qc_verify.py`
**담당 항목**: 3 (haiku A/B), 4 (TRUST 5 태그)

| 항목 | 산출물 | 스펙 문서 |
|---|---|---|
| 3 | A/B 실험 설계 + 최종 판정 보고서 | `/memory/specs/adk-impl-spec-3.md` |
| 4 | verifier 9종 → TRUST 5 매핑 + trust_summary JSON | `/memory/specs/adk-impl-spec-4.md` |

---

## 6. 인프라 요구사항

### 6.1 feature_flags.json

```json
{
  "progressive_disclosure_enabled": false,
  "rw_isolation_enabled": false,
  "haiku_specialization_enabled": false,
  "trust5_tags_enabled": false,
  "model_map_enabled": false,
  "hooks_enforcement_enabled": false
}
```

- **캐시**: mtime 기반 — 파일 변경 시에만 재로드
- **쓰기**: atomic write (임시 파일 → rename)
- **기본값**: 전체 `false` (안전 우선)
- **위치**: 프로젝트 루트 또는 `/memory/config/`

### 6.2 .metrics/ 기준선 JSON

```
.metrics/
  baseline_tokens.json     # 프롬프트 토큰 분포
  baseline_qc.json         # QC 결과 분포, FNR
  baseline_hooks.json      # hooks 위반 빈도
  baseline_ab.json         # A/B 실험 누적 데이터
```

- Phase 0a에서 생성, 이후 weekly 업데이트
- 모든 파일 JSON Lines 또는 단일 JSON 객체

### 6.3 Circuit Breaker

- 키: `(tool, error_code, file_path)` 3-튜플
- 임계치 1: 동일 3-튜플 15회 → 30초 cooling
- 임계치 2: 30초 내 재발 → 동일 횟수(15회) 기준 연장
- 상태 저장: 인메모리 (프로세스 재시작 시 리셋)

### 6.4 A/B 실험 인프라

- 통계 방법: Fisher's exact test (one-sided)
- 유의 수준: α=0.05
- 최소 샘플: n>150 (제어군 + 실험군 각각)
- 중간 점검: 매주 1회
- 재검증: 주 1회 sonnet으로 haiku 결과 20% 샘플 재평가

### 6.5 스펙 문서 위치

```
/memory/specs/
  adk-impl-spec-1.md   # Progressive Disclosure
  adk-impl-spec-2.md   # 읽기/쓰기 격리
  adk-impl-spec-3.md   # haiku A/B
  adk-impl-spec-4.md   # TRUST 5 태그
  adk-impl-spec-5.md   # MODEL_MAP
  adk-impl-spec-7.md   # hooks 강제
  adk-impl-spec-10.md  # Task 파일 구조
```

---

## 7. 위험 관리

### 7.1 롤백 전략 — 3-Layer

| 레이어 | 방법 | 소요 시간 |
|---|---|---|
| L1 — Flag | `feature_flags.json`에서 해당 플래그 `false`로 변경 | 즉시 (초 단위) |
| L2 — 설정 | 설정 파일 이전 버전으로 교체 | 수 분 |
| L3 — Git | `git revert` 해당 커밋 | 수 분~수십 분 |

**원칙**: L1 먼저, 실패 시 L2, 최후 수단 L3.

### 7.2 항목별 위험 및 대응

| 항목 | 주요 위험 | 대응 |
|---|---|---|
| 1 (Progressive Disclosure) | CRITICAL 섹션 누락 | 하드코딩 + assertion 테스트 |
| 2 (읽기/쓰기 격리) | 기존 호출부 호환성 깨짐 | 기본값 "write" 유지, 회귀 테스트 |
| 3 (haiku A/B) | FNR>15% 조기 초과 | 자동 롤백 트리거 + 즉시 중단 |
| 4 (TRUST 5) | 매핑 불일치율>3% | 매핑 테이블 리뷰 게이트 추가 |
| 5 (MODEL_MAP) | 모델명 오타/누락 | staleness 경고 + 코드리뷰 |
| 7 (Hooks) | circuit breaker 오발동 | 3-튜플 키 세분화, 임계치 조정 |
| 10 (파일 구조) | 기존 파일 마이그레이션 충돌 | 설계 단계에서 마이그레이션 가이드 선행 |

### 7.3 CODE FREEZE 규칙

- Phase 0a (4/1–4/3) 중 코드 변경 금지
- 위반 시 기준선 데이터 무효화 → 측정 재시작

### 7.4 Contingency

- A/B 4주 후 n>150 미달 시: 1주 연장 (최대 1회)
- P4 항목 외부 의존성 해소 안 될 시: Week 8 평가에서 명시적 보류 결정

---

## 8. 성공 기준

### 8.1 P1 DoD (Week 3 완료 시점)

- [ ] `disclosure_phase` 3단계 분기 동작, CRITICAL 섹션 항상 포함
- [ ] `--agent-type read` 시 write 작업 차단 확인
- [ ] pyright + ruff PostToolUse 훅 동작, circuit breaker 임계치 테스트 통과
- [ ] 모든 P1 항목 feature flag로 독립 켜기/끄기 가능

### 8.2 P2 DoD (Week 8 완료 시점)

- [ ] TRUST 5 매핑 커버리지 100%, 불일치율 <3%
- [ ] MODEL_MAP 상수 선언, staleness 경고 동작
- [ ] haiku A/B n>150 달성, Fisher's exact 판정 완료, FNR <15%

### 8.3 P3 DoD (Week 8, 설계 완료)

- [ ] Task 파일 표준 디렉토리 트리 문서화
- [ ] DIRECT-WORKFLOW.md 업데이트
- [ ] 자동 생성 도구 요구사항 정의 (P4 인계)

### 8.4 전체 프로젝트 성공 기준 (Week 8 평가)

| KPI | 목표 | 판정 방법 |
|---|---|---|
| 프롬프트 토큰 감소 | summary ≤600 / standard ≤1800 | .metrics/ 대비 비교 |
| QC FNR | <15% | A/B 판정 보고서 |
| TRUST 매핑 불일치율 | <3% | qc_verify.py 모니터링 |
| hooks 위반 자동 차단 | circuit breaker 정상 동작 | 로그 검증 |
| 전체 기능 flag 제어 | 6플래그 전부 독립 동작 | 통합 테스트 |

---

*이 계획서는 Week 4 및 Week 8 평가 시점에 갱신한다.*
*P4 항목 재논의는 Week 8 전체 평가 결과를 기반으로 별도 회의에서 결정한다.*