# MoAI-ADK Phase 3 코드화 지시서

작성일: 2026-03-31
작성자: 에이레네 (SEO & 리서치 전략가)
상태: 실행 대기 — Phase 2 완료 후 착수

---

## 개요

MoAI-ADK 도입 Phase 3는 P1/P2가 안정화된 시점(Week 5)부터 Week 8까지 실행하는
**설계 및 표준화 단계**다. 코드 변경은 없으며, 문서·규칙·파일럿 적용만 산출한다.
Phase 3 완료 후 Week 8 전체 평가에서 P4 재논의 트리거를 점검하고 프로젝트를 마무리한다.

**본 지시서의 범위**:
1. P3-10 Task 파일 구조 표준화 (Week 5–8, DRI: 오딘)
2. P4 모니터링 계획 수립
3. Week 8 전체 프로젝트 평가 준비

---

## 선행 조건

Phase 3에 착수하기 전 반드시 아래 조건을 확인한다.

- [ ] Phase 2 A/B 테스트(P2-3 haiku) 진행 중 또는 완료 (Week 4 이후)
- [ ] P1 전 항목 feature_flag ON: `progressive_disclosure_enabled`, `rw_isolation_enabled`, `hooks_enforcement_enabled`
- [ ] P2 전 항목 feature_flag ON: `trust5_tagging_enabled`, `model_map_enabled`
- [ ] 기준선 측정값 확인: `.metrics/baseline/` JSON 존재
- [ ] 계획서 확인: `/home/jay/workspace/memory/plans/moai-adoption/plan.md`
- [ ] 체크리스트 확인: `/home/jay/workspace/memory/plans/moai-adoption/checklist.md`

**선행 조건 미충족 시**: Phase 3 착수 중단 후 미충족 항목 보고.

---

## Task 1: P3-10 Task 파일 구조 표준화

**DRI**: 오딘
**기간**: Week 5–8 (2026-05-02 ~ 05-29)
**산출물 위치**: `/home/jay/workspace/memory/specs/adk-impl-spec-10.md`

### 1.1 현황 분석

현재 `/home/jay/workspace/memory/tasks/` 디렉토리의 파일 패턴을 분석한다.

**분석 명령어:**
```bash
# 파일 총 수
ls /home/jay/workspace/memory/tasks/ | wc -l

# 패턴별 분류
ls /home/jay/workspace/memory/tasks/ | grep "^task-[0-9]" | wc -l      # 번호형 task
ls /home/jay/workspace/memory/tasks/ | grep "^dispatch-" | wc -l       # dispatch형
ls /home/jay/workspace/memory/tasks/ | grep -v "^task-" | grep -v "^dispatch-" | wc -l  # 비표준

# 체인번호 패턴 확인
ls /home/jay/workspace/memory/tasks/ | grep "^task-[0-9]*\.[0-9]" | head -20

# YAML frontmatter 유무 샘플링
head -5 /home/jay/workspace/memory/tasks/task-1285.1.md
head -5 /home/jay/workspace/memory/tasks/dispatch-moai-adk-research.md
```

**분석 결과를 스펙 문서에 기록할 항목**:
- 현재 파일 총 수 (2026-03-31 기준: 약 2,183개)
- 패턴별 분포: `task-{번호}.{체인}.md` / `dispatch-{이름}.md` / 기타
- YAML frontmatter 보유 비율 (샘플 20개 기준)
- 가장 긴 파일명, 가장 짧은 파일명
- 공백/특수문자 포함 파일명 존재 여부 (`테스트 작업.md` 등)

### 1.2 YAML frontmatter 스키마 설계

모든 task 파일에 적용할 표준 YAML frontmatter 스키마를 정의한다.

**표준 스키마 (필수 필드):**
```yaml
---
task_id: "1285.1"          # task 고유 ID. 형식: {번호}.{체인번호}
team: "1팀"                 # 담당 팀. 값: 1팀/2팀/3팀/4팀/QC/전략/DA/오케스트레이터
level: 4                    # 위임 레벨. 정수 1-4
priority: "P1"              # 우선순위. 값: P1/P2/P3/P4
depends_on: []              # 선행 task_id 목록. 없으면 빈 배열
created_at: "2026-03-31"   # 생성일. ISO 8601 날짜
deadline: "2026-04-14"     # 데드라인. ISO 8601 날짜. 없으면 null
---
```

**선택 필드 (있으면 포함):**
```yaml
---
# ... 필수 필드 ...
status: "in_progress"       # 상태. 값: pending/in_progress/done/blocked
dri: "헤르메스"              # 단독 책임자
tags: ["hooks", "P1"]       # 자유 태그 목록
spec_doc: "/memory/specs/adk-impl-spec-7.md"  # 연관 스펙 문서 경로
---
```

**스키마 결정 근거 (context.md §6.4 참조)**:
- `task_id`: 기존 `task-{번호}.{체인번호}.md` 파일명에서 추출 가능 → 파일 탐색 O(1)
- `team`: 오케스트레이터가 라우팅 시 파일 내부를 파싱하지 않아도 됨
- `level`: 위임 레벨별 모델 선택 자동화 근거 (plan.md §2.4 참조)
- `depends_on`: 병렬 실행 시 의존성 체크 자동화 가능
- `created_at` / `deadline`: 타임라인 추적 + staleness 감지

**스키마 제약 조건**:
- YAML 블록은 파일 최상단 첫 줄에서 시작 (앞 공백 없음)
- `task_id` 값은 파일명과 일치해야 함 (`task-1285.1.md` → `"1285.1"`)
- `depends_on`이 없는 경우 `[]` (null 금지)
- `deadline`이 없는 경우 `null` (빈 문자열 금지)

### 1.3 네이밍 규칙 문서화

네이밍 규칙을 스펙 문서에 공식 기록한다.

**네이밍 규칙 (표준)**:

| 파일 유형 | 형식 | 예시 |
|---|---|---|
| 번호형 task | `task-{번호}.{체인번호}.md` | `task-1285.1.md` |
| dispatch 지시서 | `dispatch-{식별자}.md` | `dispatch-moai-phase3.md` |
| handoff 파일 | `task-{번호}.{체인번호}-handoff-{n}.md` | `task-1285.1-handoff-1.md` |
| phase 계획 | `task-{번호}.{체인번호}-phase-plan.md` | `task-1285.1-phase-plan.md` |

**금지 규칙**:
- 공백 포함 파일명 금지 (`테스트 작업.md` → `task-test-work.md`)
- 한글 파일명 금지 (탐색 시 인코딩 오류 위험)
- 대문자 포함 금지 (`Task-1000.md` → `task-1000.md`)
- 특수문자(`:`, `?`, `*`) 파일명 포함 금지

**규칙 문서 저장 위치**: `/home/jay/workspace/memory/specs/adk-impl-spec-10.md`

### 1.4 파일럿 적용

표준 스키마와 네이밍 규칙을 5개 task 파일에 시범 적용한다.

**파일럿 대상 선정 기준**:
1. 최근 활성 파일 (최근 4주 내 생성 또는 수정)
2. 현황이 다양한 파일: dispatch형 1개 + 번호형 4개
3. 규모 다양성: 대형(100줄+) 2개 + 소형(50줄 미만) 3개

**파일럿 대상 후보 (착수 시 확정)**:
- `task-1285.1.md` — MoAI 미팅 메인 task (번호형, 대형)
- `task-1284.1.md` — 직전 task (번호형, 중형)
- `task-1283.1.md` — 직전 task (번호형, 중형)
- `dispatch-moai-phase3.md` — 본 파일 (dispatch형, 대형)
- `dispatch-moai-adk-research.md` — 리서치 지시서 (dispatch형, 소형)

**적용 방법 (오딘 실행)**:
```
각 파일 상단에 YAML frontmatter 블록 추가.
기존 본문 내용 변경 없음.
파일명 변경은 파일럿에서 제외 (네이밍 규칙 문서화만 수행).
```

**파일럿 완료 기준 (DoD)**:
- [ ] 5개 파일 전부 YAML frontmatter 삽입 완료
- [ ] 각 파일의 `task_id` 값이 파일명과 일치
- [ ] 스펙 문서 `/memory/specs/adk-impl-spec-10.md` 작성 완료
- [ ] 파일럿 결과 검토: frontmatter 누락 필드 없음
- [ ] DIRECT-WORKFLOW.md에 네이밍 규칙 섹션 추가

**DIRECT-WORKFLOW.md 추가 섹션 위치**:
`/home/jay/workspace/prompts/DIRECT-WORKFLOW.md` 내
"TASK FILE STANDARDS" 섹션 신설 (기존 섹션 번호 유지)

---

## Task 2: P4 모니터링 계획

P4 항목들은 외부 의존성 또는 P1/P2 효과 검증이 선행되어야 논의 가능하다.
Week 5–8 기간 동안 각 항목의 재논의 트리거 조건을 모니터링한다.

**모니터링 보고 주기**: 주 1회 (매주 금요일)
**보고 파일**: `/home/jay/workspace/memory/reports/p4-monitoring-weekly.md` (Week별 추가 기록)

### 2.1 (6) @MX 태그 시스템

**현황**: P1-7 hooks 안정화 후 재논의 예정 (context.md §2 참조)

**모니터링 항목**:
- hooks 에러율 (`.metrics/hooks_log.json` 기준)
- circuit breaker 발동 빈도 (동일 3-튜플 기준)
- hooks 운영 누적 기간 (P1-7 ON 시점부터 카운트)

**트리거 조건** (이 조건 충족 시 P4 재논의 시작):
- hooks 4주 이상 운영 (P1-7 feature_flag ON 후 28일 경과)
- hooks 에러율 < 5% (4주 평균 기준)
- circuit breaker 오발동 없음 (불필요한 halt 0건)

**DRI**: 헤르메스 (P1-7 담당자)
**판정 기준일**: Week 7 말 (hooks 4주 운영 시점 기준)

### 2.2 (8) Context Search Protocol

**현황**: Google ADK 네이티브 기능 GA 릴리즈 대기 (context.md §2 참조)

**모니터링 항목**:
- Google ADK 공식 릴리즈 노트 확인
- ADK GitHub 이슈/PR 트래킹 (context search 관련 키워드)
- 커뮤니티 피드백 (Reddit r/LangChain, Hacker News, ADK Discord)

**트리거 조건** (이 조건 충족 시 P4 재논의 시작):
- ADK에 context search 기능 GA(General Availability) 릴리즈 공식 발표
- 실사용 가능 수준의 API 문서 제공 확인

**확인 방법**:
```
주 1회 아래 URL 확인:
- https://github.com/google/adk-python/releases
- https://cloud.google.com/vertex-ai/generative-ai/docs/agent-builder/what-is-agent-builder
```

**DRI**: 에이레네 (리서치 전략가 — 외부 릴리즈 모니터링 담당)

### 2.3 (9) Agent Teams API 전환

**현황**: Google ADK Agent Teams API 안정화 대기 (context.md §2 참조)

**모니터링 항목**:
- TeamCreate API 가용성
- SendMessage API 가용성
- TaskList API 가용성
- API 문서 커버리지 (공식 문서 기준 기능 수)

**트리거 조건** (이 조건 충족 시 P4 재논의 시작):
- TeamCreate / SendMessage / TaskList 3개 API 전부 공식 GA
- API 기능 커버리지 90%+ (공개 로드맵 대비)
- 베타 사용자 보고서에서 안정성 확인 (에러율 < 1%)

**DRI**: 에이레네 (ADK 릴리즈 모니터링 담당)
**모니터링 방법**: 주 1회 ADK 릴리즈 노트 + 커뮤니티 피드백 종합

### 2.4 (10-나머지) Task 파일 구조 자동 생성

**현황**: P3 네이밍 규칙 완료 후 재논의 (본 Phase 3 완료가 선행 조건)

**트리거 조건** (이 조건 충족 시 P4 재논의 시작):
- P3 파일럿 5개 task 적용 완료 (Task 1.4 DoD 달성)
- 네이밍 규칙 문서 `/memory/specs/adk-impl-spec-10.md` 확정
- DIRECT-WORKFLOW.md 업데이트 완료

**P4에서 논의할 범위** (현재 스코프 외):
- `task-gen` CLI: task 파일 자동 생성 도구
- YAML frontmatter 자동 삽입 스크립트
- 기존 파일 일괄 마이그레이션 도구

**DRI**: 오딘 (P3 DRI → P4 자동화 논의 인계)

---

## Task 3: 전체 프로젝트 평가 (Week 8)

**평가일**: 2026-05-23 (Week 8 첫째 날)
**보고서 위치**: `/home/jay/workspace/memory/reports/moai-adoption-final-report.md`
**DRI**: 마아트 (QC 기준선 측정 담당) + 프로메테우스 (전략 종합)

### 3.1 A/B 최종 판정 (haiku P2-3)

**판정 기준**:
- 수집 데이터: n > 150 (제어군/실험군 각각 75건 이상)
- 통계 검정: Fisher's exact test, 단측, α = 0.05
- 품질 기준: FNR < 15% (실험군 haiku 기준)

**판정 결과 분기**:
```
[채택] p < 0.05 AND FNR < 15%
  → haiku_specialization_enabled: true 영구 전환
  → 비용 절감 효과 정량화 (토큰/비용 단위)

[기각] p >= 0.05 OR FNR >= 15%
  → haiku_specialization_enabled: false 유지
  → 기각 근거 보고서에 기록
  → 향후 재실험 조건 제안

[연장] n < 150
  → 1주 연장 (최대 1회, 계획서 §7.4 참조)
  → Week 9 최종 판정
```

### 3.2 P1/P2 효과 보고서

기준선(`.metrics/baseline/`) 대비 Week 8 실적을 측정한다.

**KPI 측정 항목 및 목표**:

| 지표 | 측정 방법 | 목표 | 경고 임계 |
|---|---|---|---|
| 프롬프트 평균 토큰 (summary) | `.metrics/weekly/` 평균 | ≤600토큰 | 기준선 대비 개선 없음 |
| 프롬프트 평균 토큰 (standard) | `.metrics/weekly/` 평균 | ≤1,800토큰 | 기준선 대비 개선 없음 |
| QC FNR | 재검증 30건 기준 | <15% | ≥15% 시 haiku 기각 |
| TRUST 매핑 불일치율 | `qc_verify.py` 로그 분석 | <3% | ≥3% 시 매핑 재검토 |
| hooks 위반 자동 차단 건수 | circuit breaker 로그 | 측정값 기록 | 오발동 건수 분리 |
| write 에이전트 격리 위반 | worktree 로그 분석 | 0건 | 1건 이상 시 조사 |

**보고서 형식**:
```markdown
## 기준선 대비 Week 8 실적

| KPI | 기준선 | Week 8 | 변화량 | 달성 여부 |
|---|---|---|---|---|
| summary 토큰 | {baseline} | {week8} | {delta} | ✓/✗ |
...

## haiku A/B 최종 판정
...

## 항목별 DoD 달성 여부
...

## 미달성 항목 및 원인 분석
...
```

### 3.3 P3 실구현 여부 결정

Week 8 평가에서 P3 Task 파일 구조 표준화의 실구현(자동화 도구 개발) 여부를 결정한다.

**결정 기준**:
- 파일럿 5개 적용 결과: 오딘의 파일럿 보고 기반
- YAML frontmatter 유용성 평가: 오케스트레이터가 실제로 frontmatter를 활용하는가
- 자동화 ROI: 수동 적용 시간 vs 자동화 도구 개발 시간

**결정 분기**:
```
[실구현 진행] 파일럿 성공 + ROI 양호
  → P4 항목 (10-나머지) 재논의 트리거 ON
  → 오딘이 P4 자동화 스펙 초안 작성

[보류] 파일럿 부분 성공 또는 ROI 불명확
  → 3개월 후 재평가 조건 기록
  → P4 자동화 보류 지속

[폐기] 파일럿 실패 또는 ROI 음수
  → 네이밍 규칙 문서만 유지 (자동화 없음)
  → 이유 기록 후 종결
```

### 3.4 P4 재논의 트리거 점검

Week 8 시점에서 각 P4 항목의 트리거 조건 달성 여부를 점검한다.

**점검 항목**:
- (6) @MX 태그: hooks 4주 운영 + 에러율 < 5% 달성 여부
- (8) Context Search: ADK GA 릴리즈 여부
- (9) Agent Teams API: API 90%+ 커버 여부
- (10) 구조 자동 생성: P3 파일럿 완료 여부

### 3.5 프로젝트 회고 (Retrospective)

**형식**: 에이전트 미팅 (참석자: 헤르메스, 오딘, 마아트, 로키, 프로메테우스)
**기록 위치**: `/home/jay/workspace/memory/meetings/moai-adoption-retrospective.md`

**회고 항목**:
1. **잘된 것 (Keep)**: 10사이클 미팅 방식, feature_flags 킬스위치, Phase 0 CODE FREEZE
2. **개선할 것 (Problem)**: 타임라인 이탈 항목, 예상 못한 기술 부채, 모니터링 공백
3. **다음에 시도할 것 (Try)**: P4 항목 중 즉시 적용 가능한 것, 차기 MoAI-ADK 도입 사이클
4. **로키 최종 평가**: 프로젝트 전체에서 가장 큰 위험 3가지와 실제 발생 여부

---

## P4 재논의 트리거 조건표

| P4 항목 | 항목 번호 | 재논의 트리거 | 모니터링 주체 | 판정 기준일 |
|---|---|---|---|---|
| @MX 태그 시스템 | (6) | hooks 4주 운영 + 에러율 < 5% | 헤르메스 | Week 7 말 |
| Context Search Protocol | (8) | ADK context search GA 릴리즈 | 에이레네 | 릴리즈 시 즉시 |
| Agent Teams API 전환 | (9) | ADK Agent Teams API 90%+ 커버 | 에이레네 | 릴리즈 시 즉시 |
| Task 파일 구조 자동 생성 | (10-나머지) | P3 파일럿 완료 + 네이밍 규칙 확정 | 오딘 | Week 8 평가 |

**트리거 미충족 시 처리**:
- 미충족 항목은 `/home/jay/workspace/memory/plans/moai-adoption/p4-backlog.md`에 이관
- 트리거 조건 재확인 주기: 4주 후 (다음 스프린트 시작 시)
- 외부 의존성 항목(8, 9)은 ADK 릴리즈 노트 모니터링 자동화 검토

---

## 산출물 체크리스트

### P3-10 산출물
- [ ] `/home/jay/workspace/memory/specs/adk-impl-spec-10.md` — 표준 스펙 문서
- [ ] `/home/jay/workspace/prompts/DIRECT-WORKFLOW.md` — Task File Standards 섹션 추가
- [ ] 파일럿 5개 task 파일 — YAML frontmatter 삽입 완료

### P4 모니터링 산출물
- [ ] `/home/jay/workspace/memory/reports/p4-monitoring-weekly.md` — 주간 모니터링 기록

### Week 8 평가 산출물
- [ ] `/home/jay/workspace/memory/reports/moai-adoption-final-report.md` — 최종 평가 보고서
- [ ] `/home/jay/workspace/memory/meetings/moai-adoption-retrospective.md` — 회고 기록
- [ ] `/home/jay/workspace/memory/plans/moai-adoption/p4-backlog.md` — P4 미이관 항목 기록

---

## 참고 문서

| 문서 | 경로 |
|---|---|
| 계획서 | `/home/jay/workspace/memory/plans/moai-adoption/plan.md` |
| 맥락노트 | `/home/jay/workspace/memory/plans/moai-adoption/context.md` |
| 체크리스트 | `/home/jay/workspace/memory/plans/moai-adoption/checklist.md` |
| P1-2 지시서 | `/home/jay/workspace/memory/tasks/dispatch-moai-phase1.md` (Phase 1 완료 후 생성) |
| P2 지시서 | `/home/jay/workspace/memory/tasks/dispatch-moai-phase2.md` (Phase 2 완료 후 생성) |
| 스펙 문서 위치 | `/home/jay/workspace/memory/specs/adk-impl-spec-{번호}.md` |
| MoAI-ADK 분석 | `/home/jay/workspace/memory/research/moai-adk-analysis.md` |
| 현재 워크플로우 | `/home/jay/workspace/prompts/DIRECT-WORKFLOW.md` |

---

## 주의사항

1. **코드 변경 없음**: Phase 3는 문서·규칙·파일럿만 산출한다. Python 파일, settings.json 등 코드 수정은 P4 재논의 이후로 이관.
2. **파일럿 대상 변경 금지**: 파일럿 5개 파일의 본문 내용은 YAML frontmatter 추가 외 수정 금지.
3. **P4 조기 착수 금지**: 트리거 조건 미충족 상태에서 P4 항목 구현 시작 금지. 반드시 Week 8 평가 후 결정.
4. **로키 검토 필수**: 스펙 문서(`adk-impl-spec-10.md`) 초안 완성 후 로키의 비평 세션 필수 진행.
5. **DRI 단독 책임**: P3-10은 오딘이 단독 DRI. "공동 검토" 명목의 책임 분산 금지 (context.md §6.6 참조).