moai-adk 0.3.3__py3-none-any.whl → 0.3.6__py3-none-any.whl

{moai_adk-0.3.3.dist-info → moai_adk-0.3.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.3.3
+Version: 0.3.6
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk
@@ -21,6 +21,7 @@ Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.13
 Requires-Dist: click>=8.1.0
 Requires-Dist: gitpython>=3.1.45
+Requires-Dist: packaging>=21.0
 Requires-Dist: pyfiglet>=1.0.2
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: rich>=13.0.0
@@ -56,236 +57,308 @@ Description-Content-Type: text/markdown
 
 ## 목차
 
-- [v0.3.x 주요 개선사항](#-v03x-주요-개선사항)
-- [Meet Alfred](#-meet-alfred---10개-ai-에이전트-팀)
-- [AI 모델 선택 가이드](#-ai-모델-선택-가이드)
+- [이런 문제 겪고 계신가요?](#-이런-문제-겪고-계신가요)
+- [Meet Alfred](#-meet-alfred---12개-ai-에이전트-팀)
+- [5분 만에 이해하는 핵심 개념](#-5분-만에-이해하는-핵심-개념)
 - [Quick Start](#-quick-start-3분-실전)
+- [첫 번째 프로젝트: Todo API](#-첫-번째-프로젝트-todo-api-만들기)
 - [3단계 워크플로우](#-3단계-워크플로우)
+- [실전 시나리오](#-실전-시나리오)
+- [AI 모델 선택 가이드](#-ai-모델-선택-가이드)
 - [CLI Reference](#-cli-reference)
 - [출력 스타일](#-alfreds-output-styles)
 - [언어 지원](#-universal-language-support)
 - [TRUST 5원칙](#-trust-5원칙)
+- [코드 품질 가이드](#-코드-품질-가이드)
 - [FAQ](#-faq)
 - [문제 해결](#-문제-해결)
 
 ---
 
-## 🆕 v0.3.x 주요 개선사항
-
-### 🚀 핵심 기능 강화
-
-#### 1. Template Processor 개선 - 안전한 업데이트 시스템
-- **Alfred 폴더 자동 백업**: 업데이트 전 `.moai-backups/alfred-{timestamp}/` 폴더에 자동 백업
-- **선택적 복사 전략**: Alfred 시스템 폴더만 덮어쓰고, 사용자 커스터마이징 파일 보존
-- **지능형 병합**: `product/structure/tech.md` 등 프로젝트 문서를 BackupMerger가 자동으로 병합
-- **롤백 지원**: 문제 발생 시 백업에서 복구 가능
-
-#### 2. Event-Driven Checkpoint 시스템
-- **자동 백업**: 위험한 작업(`rm -rf`, 병합, 스크립트 실행) 전 자동 checkpoint 생성
-- **Hooks 통합**: `SessionStart`, `PreToolUse`, `PostToolUse` 훅이 실시간 감지
-- **최대 10개 유지**: FIFO + 7일 보존 정책으로 디스크 효율 관리
-- **투명한 동작**: 백그라운드 자동 생성, 사용자에게 알림
-
-#### 3. Hooks vs Agents vs Commands 역할 분리
-- **Hooks** (가드레일): 위험 차단, 자동 백업, JIT Context (<100ms)
-- **Agents** (분석): SPEC 검증, TRUST 원칙 확인, TAG 관리 (수 초)
-- **Commands** (워크플로우): 여러 단계 오케스트레이션 (수 분)
-
-#### 4. Context Engineering 전략 완성
-- **JIT Retrieval**: 필요한 순간에만 문서 로드 (초기 컨텍스트 최소화)
-- **Compaction**: 토큰 사용량 >70% 시 요약 후 새 세션 시작 권장
-- **Explore 에이전트**: 대규모 코드베이스 효율적 탐색 가이드 추가
-
-#### 5. AI 모델 최적화 - Haiku/Sonnet 전략적 배치
-- **Haiku 에이전트 적용** (5개): doc-syncer, tag-agent, git-manager, trust-checker, Explore
-  - 빠른 응답 속도 (2~5배 향상)
-  - 비용 67% 절감
-  - 반복 작업 및 패턴 매칭에 최적화
-- **Sonnet 에이전트 유지** (5개): spec-builder, code-builder, debug-helper, cc-manager, project-manager
-  - 복잡한 판단 및 설계에 집중
-  - 높은 품질 보장
-- **/model 명령어 지원**:
-  - `/model haiku` → **패스트 모드** (빠른 응답, 반복 작업)
-  - `/model sonnet` → **스마트 모드** (복잡한 판단, 설계)
-
-### 🛠️ 도구 & 명령어 개선
-
-#### CLI 명령어 표준화
-```bash
-# 새 프로젝트 생성
-moai-adk init project-name
-
-# 기존 프로젝트에 설치
-moai-adk init .
-
-# 상태 확인
-moai-adk status
-
-# 업데이트
-moai-adk update
-```
-
-#### Alfred 커맨드 단계별 커밋 지침 추가
-- **0-project**: 문서 생성 완료 시 커밋
-- **1-spec**: SPEC 작성 + Git 브랜치/PR 생성 시 커밋
-- **2-build**: TDD 전체 사이클(RED→GREEN→REFACTOR) 완료 시 1회 커밋
-- **3-sync**: 문서 동기화 완료 시 커밋
+## 🚨 이런 문제 겪고 계신가요?
 
-#### PyPI 배포 자동화
-- GitHub Actions 워크플로우 추가 (`.github/workflows/publish-pypi.yml`)
-- 템플릿 프로젝트에도 배포 워크플로우 제공
-- 버전 관리 및 자동 배포 지원
+### AI 코딩의 현실
 
-### 📚 문서 강화
+- 💥 **"AI가 만든 코드, 나중에 유지보수 불가능..."**
+  - 같은 기능을 매번 다르게 구현
+  - 코드 스타일이 파일마다 제각각
+  - 테스트 코드는 없고 버그는 많음
 
-#### SPEC 메타데이터 표준 (SSOT)
-- **필수 필드 7개**: id, version, status, created, updated, author, priority
-- **선택 필드 9개**: category, labels, depends_on, blocks, related_specs, related_issue, scope
-- **HISTORY 섹션**: 모든 버전 변경 이력 기록 (필수)
-- `.moai/memory/spec-metadata.md`에 전체 가이드 문서화
+- 🔄 **"같은 질문 반복해도 매번 다른 답변..."**
+  - 이전 대화 내용을 기억하지 못함
+  - 일관된 아키텍처를 유지하기 어려움
+  - 프로젝트 전체 맥락을 놓침
 
-#### Explore 에이전트 활용 가이드
-- 코드 분석 권장 상황 명확화
-- thoroughness 레벨별 사용법 (quick/medium/very thorough)
-- JIT Retrieval 최적화 전략
+- 📚 **"코드는 많은데 문서는 없고, 추적 불가능..."**
+  - 왜 이렇게 만들었는지 알 수 없음
+  - 코드 변경 이력 추적 불가
+  - 요구사항과 코드가 따로 놈
 
-### 🔒 보안 & 안정성
+- 🤯 **"프롬프트 엔지니어링에만 하루가 다 갔어요..."**
+  - 완벽한 프롬프트를 찾기 위해 수십 번 시도
+  - AI에게 매번 같은 제약사항을 반복 설명
+  - 코드 품질을 수동으로 검증
 
-#### 크로스 플랫폼 지원 강화
-- Windows/macOS/Linux 동일 동작 보장
-- 플랫폼별 에러 메시지 제공
-- PowerShell + Python 보안 스캔 스크립트
+### MoAI-ADK는 이렇게 해결합니다
 
-#### .gitignore 및 프로젝트 정리
-- 로컬 설정 파일 자동 제외 (`.claude/settings.local.json`)
-- 임시 테스트 파일 제외 (`*-test-report.md`)
-- 불필요한 파일 자동 정리
+```mermaid
+flowchart TD
+    Problem["😫 문제: 플랑켄슈타인 코드"] --> Solution["✨ MoAI-ADK"]
+    Solution --> SPEC["📋 SPEC 우선<br/>명세 없으면 코드 없다"]
+    Solution --> TDD["🔴🟢♻️ TDD 강제<br/>테스트 없으면 구현 없다"]
+    Solution --> TAG["🏷️ @TAG 추적<br/>모든 코드가 SPEC과 연결"]
 
-### 🎨 출력 스타일 개선
+    SPEC --> Result["🎉 결과"]
+    TDD --> Result
+    TAG --> Result
 
-#### 3가지 표준 스타일
-- **MoAI Beginner Learning**: 개발 입문자를 위한 친절한 가이드
-- **MoAI Professional**: 전문 개발자를 위한 효율적인 출력
-- **MoAI Alfred (기본)**: 균형잡힌 AI 협업 스타일
+    Result --> Quality["✅ 높은 품질<br/>TRUST 5원칙 자동 검증"]
+    Result --> Track["📊 완벽한 추적성<br/>SPEC→TEST→CODE→DOC"]
+    Result --> Maintain["🔧 쉬운 유지보수<br/>코드 변경 이력 완전 기록"]
+```
 
 ---
 
-## 🎩 Meet Alfred - 10개 AI 에이전트 팀
+## 🎩 Meet Alfred - 12개 AI 에이전트 팀
 
 안녕하세요, 모두의AI SuperAgent **🎩 Alfred**입니다!
 
 ![Alfred Logo](https://github.com/modu-ai/moai-adk/raw/main/docs/public/alfred_logo.png)
 
-저는 MoAI-ADK의 SuperAgent이자 중앙 오케스트레이터 AI입니다. **10개의 AI 에이전트 팀**(Alfred + 9개 전문 에이전트)을 조율하여 Claude Code 환경에서 완벽한 개발 지원을 제공합니다.
+저는 MoAI-ADK의 SuperAgent이자 중앙 오케스트레이터 AI입니다. **12개의 AI 에이전트 팀**(Alfred + 11개 전문 에이전트)을 조율하여 Claude Code 환경에서 완벽한 개발 지원을 제공합니다.
 
 ### 🌟 흥미로운 사실: AI가 만든 AI 개발 도구
 
 이 프로젝트의 모든 코드는 **100% AI에 의해 작성**되었습니다.
 
 - **AI 협업 설계**: GPT-5 Pro와 Claude 4.1 Opus가 함께 아키텍처를 설계
-- **Agentic Coding 적용**: 10개 AI 에이전트 팀이 자율적으로 SPEC 작성, TDD 구현, 문서 동기화 수행
+- **Agentic Coding 적용**: 12개 AI 에이전트 팀(Alfred + 11개 전문 에이전트)이 자율적으로 SPEC 작성, TDD 구현, 문서 동기화 수행
 - **투명성**: 완벽하지 않은 부분을 숨기지 않고, 커뮤니티와 함께 개선해나가는 오픈소스
 
-### 🎩 Alfred가 제공하는 4가지 핵심 가치
+### Alfred가 제공하는 4가지 핵심 가치
+
+```mermaid
+mindmap
+  root((Alfred))
+    일관성
+      SPEC-First
+      TDD 강제
+      플랑켄슈타인 코드 방지
+    품질
+      TRUST 5원칙
+      자동 검증
+      85%+ 커버리지
+    추적성
+      @TAG 시스템
+      SPEC→TEST→CODE→DOC
+      완벽한 연결
+    범용성
+      17개 언어 지원
+      Python TypeScript Java Go
+      모바일 Flutter Swift
+```
 
 #### 1️⃣ 일관성 (Consistency)
+
 **SPEC → TDD → Sync** 3단계 파이프라인으로 플랑켄슈타인 코드 방지
 
 #### 2️⃣ 품질 (Quality)
+
 **TRUST 5원칙** 자동 적용 및 검증 (Test First, Readable, Unified, Secured, Trackable)
 
 #### 3️⃣ 추적성 (Traceability)
+
 **@TAG 시스템**으로 `@SPEC → @TEST → @CODE → @DOC` 완벽 연결
 
 #### 4️⃣ 범용성 (Universality)
+
 **모든 주요 언어 지원** (Python, TypeScript, Java, Go, Rust, Dart, Swift, Kotlin 등)
 
 ---
 
-## 🧠 AI 모델 선택 가이드
+## 📚 5분 만에 이해하는 핵심 개념
 
-MoAI-ADK는 **Haiku 4.5**와 **Sonnet 4.5** 두 가지 AI 모델을 전략적으로 활용하여 **최적의 성능과 비용 효율**을 제공합니다.
+### 1️⃣ SPEC-First: 설계도 먼저 그리기
 
-### 패스트 모드 vs 스마트 모드
+**비유**: 집을 짓기 전에 설계도를 그리듯이, 코드를 쓰기 전에 SPEC을 작성합니다.
 
-Claude Code에서 `/model` 명령어로 전체 세션의 기본 모델을 변경할 수 있습니다:
+```mermaid
+graph LR
+    A["🏗️ SPEC 작성<br/>(설계도)"] --> B["🔴 RED<br/>(실패하는 테스트)"]
+    B --> C["🟢 GREEN<br/>(최소 구현)"]
+    C --> D["♻️ REFACTOR<br/>(품질 개선)"]
+    D --> E["📖 SYNC<br/>(문서화)"]
+```
 
-```text
-# 패스트 모드 (빠른 응답, 반복 작업)
-/model haiku
+#### EARS 구문으로 명세 작성 (실제 예시)
 
-# 스마트 모드 (복잡한 판단, 설계)
-/model sonnet
+**EARS (Easy Approach to Requirements Syntax)**: 체계적인 요구사항 작성 방법론
+
+```markdown
+# @SPEC:AUTH-001: JWT 인증 시스템
+
+## Ubiquitous (기본 기능)
+- 시스템은 사용자 인증 기능을 제공해야 한다
+
+## Event-driven (이벤트 기반)
+- WHEN 사용자가 유효한 자격증명으로 로그인하면,
+  시스템은 JWT 토큰을 발급해야 한다
+- WHEN 토큰이 만료되면,
+  시스템은 401 에러를 반환해야 한다
+
+## State-driven (상태 기반)
+- WHILE 사용자가 인증된 상태일 때,
+  시스템은 보호된 리소스 접근을 허용해야 한다
+
+## Optional (선택적 기능)
+- WHERE 리프레시 토큰이 제공되면,
+  시스템은 새로운 액세스 토큰을 발급할 수 있다
+
+## Constraints (제약사항)
+- IF 잘못된 토큰이 제공되면,
+  시스템은 접근을 거부해야 한다
+- 액세스 토큰 만료시간은 15분을 초과하지 않아야 한다
 ```
 
-### 10개 에이전트의 모델 배치 전략
+**실습**: Claude Code에서 직접 해보기
 
-Alfred는 **작업 특성**에 따라 각 에이전트에 최적 모델을 할당합니다:
+```bash
+/alfred:1-spec "JWT 기반 사용자 로그인 API"
+# Alfred가 위 형식으로 SPEC을 자동 생성합니다
+```
 
-#### 🚀 Haiku 에이전트 (5개) - 패스트 모드
+---
 
-**빠른 응답이 필요한 반복 작업 및 패턴 매칭**
+### 2️⃣ @TAG 추적: 코드와 문서를 실로 엮기
 
-| 에이전트            | 역할            | 왜 Haiku?                                    |
-| ------------------- | --------------- | -------------------------------------------- |
-| **doc-syncer** 📖    | 문서 동기화     | 패턴화된 문서 업데이트, Living Document 생성 |
-| **tag-agent** 🏷️     | TAG 시스템 관리 | 반복적 패턴 매칭, TAG 체인 검증              |
-| **git-manager** 🚀   | Git 워크플로우  | 정형화된 Git 명령어 실행, 브랜치/PR 생성     |
-| **trust-checker** ✅ | TRUST 원칙 검증 | 규칙 기반 체크리스트 확인                    |
-| **Explore** 🔍       | 코드베이스 탐색 | 대량 파일 스캔, 키워드 검색                  |
+**비유**: 책의 색인처럼, 모든 코드를 SPEC과 연결합니다.
 
-**장점**:
-- ⚡ **속도 2~5배 향상**: 실시간 응답 (수 초 → 1초 이내)
-- 💰 **비용 67% 절감**: 반복 작업이 많은 프로젝트에 효과적
-- 🎯 **높은 정확도**: 패턴화된 작업에서 Sonnet과 동등한 품질
+```mermaid
+graph TD
+    SPEC["📋 @SPEC:AUTH-001<br/>.moai/specs/SPEC-AUTH-001/spec.md"] --> TEST["🔴 @TEST:AUTH-001<br/>tests/test_auth_login.py"]
+    TEST --> CODE["🟢 @CODE:AUTH-001<br/>src/auth/service.py"]
+    CODE --> DOC["📖 @DOC:AUTH-001<br/>docs/api/auth.md"]
+```
 
-#### 🧠 Sonnet 에이전트 (5개) - 스마트 모드
+#### 실제 코드 예시
 
-**복잡한 판단과 창의적 설계가 필요한 작업**
+```python
+# tests/test_auth_login.py
+# @TEST:AUTH-001 | SPEC: SPEC-AUTH-001.md
 
-| 에이전트              | 역할             | 왜 Sonnet?                           |
-| --------------------- | ---------------- | ------------------------------------ |
-| **spec-builder** 🏗️    | SPEC 작성        | EARS 구조 설계, 복잡한 요구사항 분석 |
-| **code-builder** 💎    | TDD 구현         | 아키텍처 설계, 복잡한 리팩토링       |
-| **debug-helper** 🔬    | 디버깅           | 오류 원인 분석, 해결 방법 도출       |
-| **cc-manager** 🛠️      | Claude Code 설정 | 워크플로우 최적화, 복잡한 설정       |
-| **project-manager** 📋 | 프로젝트 초기화  | 전략 수립, 복잡한 의사결정           |
+def test_login_success():
+    """사용자가 유효한 자격증명으로 로그인하면 JWT 토큰을 발급해야 한다"""
+    response = login(username="user@example.com", password="valid_pass")
+    assert response.status_code == 200
+    assert "access_token" in response.json()
+```
 
-**장점**:
-- 🎯 **높은 품질**: 복잡한 코드 품질 보장
-- 🧠 **깊은 이해**: 맥락 파악 및 창의적 해결책 제시
-- 🏆 **정확한 판단**: 아키텍처 결정, 설계 선택
+```python
+# src/auth/service.py
+# @CODE:AUTH-001 | SPEC: SPEC-AUTH-001.md | TEST: tests/test_auth_login.py
 
-### 사용 시나리오별 권장 모델
+def login(username: str, password: str) -> TokenResponse:
+    """JWT 토큰 발급 로직"""
+    if not validate_credentials(username, password):
+        raise UnauthorizedError()
 
-| 시나리오               | 권장 모델 | 이유                          |
-| ---------------------- | --------- | ----------------------------- |
-| 🆕 **새 프로젝트 시작** | Sonnet    | SPEC 설계, 아키텍처 결정 필요 |
-| 🔄 **반복 개발**        | Haiku     | 이미 정해진 패턴 반복 구현    |
-| 🐛 **버그 수정**        | Sonnet    | 원인 분석 및 해결 방법 도출   |
-| 📝 **문서 작성**        | Haiku     | Living Document 동기화        |
-| 🔍 **코드 탐색**        | Haiku     | 파일 검색, TAG 조회           |
-| ♻️ **리팩토링**         | Sonnet    | 구조 개선, 복잡한 변경        |
+    token = generate_jwt_token(username)
+    return TokenResponse(access_token=token)
+```
 
-### 모델 전환 팁
+#### TAG 검증 실습 (실제로 해볼 수 있는 명령어)
 
-```text
-# 새 기능 설계 시작
-/model sonnet
-/alfred:1-spec "사용자 인증 시스템"
+```bash
+# 1. 모든 TAG 스캔
+rg '@(SPEC|TEST|CODE|DOC):' -n .moai/specs/ tests/ src/ docs/
 
-# SPEC 승인 후 TDD 구현
-/alfred:2-build AUTH-001
+# 2. 특정 도메인 TAG 확인
+rg '@SPEC:AUTH' -n .moai/specs/
 
-# 구현 완료 후 문서 동기화 (자동으로 Haiku 사용)
-/alfred:3-sync
+# 3. 고아 TAG 탐지 (CODE는 있는데 SPEC이 없는 경우)
+rg '@CODE:AUTH-001' -n src/          # CODE 있음
+rg '@SPEC:AUTH-001' -n .moai/specs/  # SPEC 있는지 확인
+```
 
-# 다음 기능 설계
-/model sonnet
-/alfred:1-spec "결제 시스템"
+---
+
+### 3️⃣ TRUST 품질: 5가지 원칙으로 코드 품질 보장
+
+**비유**: 자동차 안전검사처럼, 코드도 5가지 기준으로 검사합니다.
+
+```mermaid
+mindmap
+  root((TRUST 5원칙))
+    Test First
+      테스트 커버리지 ≥85%
+      pytest Vitest JUnit
+      SPEC 기반 테스트 케이스
+    Readable
+      파일 ≤300 LOC
+      함수 ≤50 LOC
+      매개변수 ≤5개
+      복잡도 ≤10
+    Unified
+      타입 안전성
+      아키텍처 일관성
+      코딩 스타일 통일
+    Secured
+      입력 검증
+      로깅 감사
+      비밀 관리
+      정적 분석
+    Trackable
+      @TAG 체계
+      CODE-FIRST 스캔
+      HISTORY 기록
 ```
 
-**Pro Tip**: Alfred는 각 에이전트를 호출할 때 자동으로 최적 모델을 사용하므로, **세션 전체 모델 변경은 선택사항**입니다. 기본 설정(Sonnet)으로도 충분히 효율적입니다.
+#### 코드 제약 구체적 예시
+
+```python
+# ✅ 좋은 예: 함수 ≤50 LOC, 매개변수 ≤5개
+def create_user(
+    username: str,
+    email: str,
+    password: str,
+    role: str = "user",
+    is_active: bool = True
+) -> User:
+    """사용자 생성 (40 LOC)"""
+    # 입력 검증
+    if not username or len(username) < 3:
+        raise ValueError("Username must be at least 3 characters")
+
+    if not email or "@" not in email:
+        raise ValueError("Invalid email address")
+
+    # 비밀번호 해싱
+    hashed_password = hash_password(password)
+
+    # 사용자 생성
+    user = User(
+        username=username,
+        email=email,
+        password=hashed_password,
+        role=role,
+        is_active=is_active
+    )
+
+    # DB 저장
+    db.session.add(user)
+    db.session.commit()
+
+    return user
+
+
+# ❌ 나쁜 예: 함수 > 50 LOC, 매개변수 > 5개
+def create_user_with_profile_and_settings_and_notifications(
+    username, email, password, role, is_active, profile_data,
+    settings_data, notification_preferences, theme, language
+):
+    """100 LOC 넘는 거대 함수..."""
+    # ... 너무 많은 책임 ...
+```
 
 ---
 
@@ -327,6 +400,7 @@ moai-adk --version
 #### 3️⃣ 프로젝트 시작 (1분)
 
 **새 프로젝트:**
+
 ```bash
 moai-adk init my-project
 cd my-project
@@ -334,6 +408,7 @@ claude
 ```
 
 **기존 프로젝트:**
+
 ```bash
 cd existing-project
 moai-adk init .
@@ -341,11 +416,13 @@ claude
 ```
 
 **Claude Code에서 초기화:**
+
 ```text
 /alfred:0-project
 ```
 
 **첫 기능 개발:**
+
 ```text
 /alfred:1-spec "사용자 인증 기능"
 /alfred:2-build AUTH-001
@@ -355,6 +432,7 @@ claude
 ### 🎉 완료!
 
 **생성된 것들:**
+
 - ✅ `.moai/specs/SPEC-AUTH-001/spec.md` (명세)
 - ✅ `tests/test_auth_login.py` (테스트)
 - ✅ `src/auth/service.py` (구현)
@@ -363,50 +441,188 @@ claude
 
 ---
 
-## ⬆️ 업그레이드 가이드 (v0.3.0 → v0.3.x)
+## 🎓 첫 번째 프로젝트: Todo API 만들기
 
-### 1단계: 패키지 업데이트
+### Step 1: SPEC 작성 (5분)
+
+**Alfred에게 요청**:
 
 ```bash
-uv pip install --upgrade moai-adk
+/alfred:1-spec "할 일 추가, 조회, 수정, 삭제 API"
 ```
 
-### 2단계: 프로젝트 업데이트
+**Alfred가 생성하는 것**:
+
+- `.moai/specs/SPEC-TODO-001/spec.md` (EARS 구문)
+- `.moai/specs/SPEC-TODO-001/plan.md` (구현 계획)
+- `feature/SPEC-TODO-001` 브랜치 (Team 모드)
+- Draft PR (Team 모드)
+
+**생성된 SPEC 예시**:
+
+```yaml
+---
+id: TODO-001
+version: 0.0.1
+status: draft
+created: 2025-10-17
+updated: 2025-10-17
+author: @Goos
+priority: high
+---
+
+# @SPEC:TODO-001: Todo API
+
+## Ubiquitous
+- 시스템은 할 일 CRUD 기능을 제공해야 한다
+
+## Event-driven
+- WHEN 사용자가 새 할 일을 생성하면, 시스템은 고유 ID를 부여해야 한다
+- WHEN 사용자가 할 일을 완료 처리하면, 시스템은 completed_at 타임스탬프를 기록해야 한다
+
+## Constraints
+- 할 일 제목은 1-200자여야 한다
+- 할 일은 작성자만 수정/삭제할 수 있어야 한다
+```
+
+---
+
+### Step 2: TDD 구현 (10분)
+
+**Alfred에게 요청**:
 
 ```bash
-cd your-project
-moai-adk update
+/alfred:2-build TODO-001
 ```
 
-**자동 백업**: 업데이트 전 `.moai-backups/{timestamp}/`에 자동 백업 생성
+**Alfred의 3단계 TDD 프로세스**:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Phase1: SPEC 분석
+    Phase1 --> Phase2: 계획 수립
+
+    Phase2 --> RED: TDD 시작
+    RED --> GREEN: 테스트 통과
+    GREEN --> REFACTOR: 품질 개선
+
+    REFACTOR --> Phase3: 품질 검증
+    Phase3 --> [*]: 완료
+
+    note right of RED
+        🔴 RED
+        - 실패하는 테스트 작성
+        - @TEST:TODO-001 TAG 추가
+    end note
+
+    note right of GREEN
+        🟢 GREEN
+        - 최소 구현으로 테스트 통과
+        - @CODE:TODO-001 TAG 추가
+    end note
+
+    note right of REFACTOR
+        ♻️ REFACTOR
+        - 코드 품질 개선
+        - 중복 제거, 가독성 향상
+    end note
+
+    note right of Phase3
+        ✅ 품질 게이트
+        - TRUST 5원칙 검증
+        - 테스트 커버리지 확인
+    end note
+```
 
-### 3단계: Claude Code 최적화
+**생성된 파일들**:
 
 ```text
-claude
-/alfred:0-project
+tests/test_todo_api.py          # @TEST:TODO-001
+src/todo/service.py             # @CODE:TODO-001:DOMAIN
+src/todo/models.py              # @CODE:TODO-001:DATA
+src/todo/routes.py              # @CODE:TODO-001:API
 ```
 
-병합 프롬프트에서 **Merge** 선택 → 기존 문서 유지 + 새 템플릿 추가
+---
 
-### 검증 체크리스트
+### Step 3: 문서 동기화 (2분)
+
+**Alfred에게 요청**:
 
 ```bash
-# 상태 확인
-moai-adk status
+/alfred:3-sync
+```
+
+**Alfred가 자동 수행**:
+
+1. **품질 검증** (Haiku 에이전트)
+   - TRUST 5원칙 준수 확인
+   - TAG 체인 무결성 검증
+
+2. **문서 동기화** (Haiku 에이전트)
+   - API 문서 자동 생성 (`docs/api/todo.md`)
+   - @DOC:TODO-001 TAG 추가
+
+3. **PR 준비** (Team 모드)
+   - Draft → Ready 전환
+   - CI/CD 확인
+   - (선택) `--auto-merge`로 자동 병합
+
+**생성된 문서**:
+
+```markdown
+# @DOC:TODO-001: Todo API
+
+## API Endpoints
+
+### POST /api/todos
 
-# 확인 항목
-# ✅ .moai/config.json → moai.version: "0.3.x"
-# ✅ .moai/config.json → project.moai_adk_version: "0.3.x"
-# ✅ 모든 커맨드 정상 작동
-# ✅ 템플릿 파일 병합 완료
+할 일 생성
 
-### v0.3.x 시리즈 주요 개선사항
+**Request**:
 
-- **Event-Driven Checkpoint**: 위험한 작업 전 자동 백업
-- **BackupMerger**: 스마트 백업 병합 (사용자 파일 보존)
-- **버전 추적**: 자동 버전 감지 및 최적화 안내
-- **Claude Code Hooks 통합**: SessionStart, PreToolUse, PostToolUse 훅
+```json
+{
+  "title": "장보기",
+  "description": "우유, 빵"
+}
+```
+
+**Response**:
+
+```json
+{
+  "id": "uuid-123",
+  "title": "장보기",
+  "completed": false,
+  "created_at": "2025-10-17T10:00:00Z"
+}
+```
+```
+
+---
+
+### 🎉 완료! 15분 만에 Todo API 완성
+
+**생성된 것들**:
+
+- ✅ `.moai/specs/SPEC-TODO-001/` (명세, 계획, 수락 기준)
+- ✅ `tests/test_todo_api.py` (테스트 - 커버리지 87%)
+- ✅ `src/todo/` (구현 - 3개 파일, 총 180 LOC)
+- ✅ `docs/api/todo.md` (API 문서)
+- ✅ `@SPEC → @TEST → @CODE → @DOC` TAG 체인
+
+**검증 명령어**:
+
+```bash
+# TAG 체인 확인
+rg '@(SPEC|TEST|CODE|DOC):TODO-001' -n
+
+# 테스트 실행
+pytest tests/test_todo_api.py -v
+
+# API 문서 확인
+cat docs/api/todo.md
 ```
 
 ---
@@ -415,11 +631,21 @@ moai-adk status
 
 Alfred의 핵심은 **체계적인 3단계 워크플로우**입니다.
 
+```mermaid
+graph TD
+    Start([사용자 요청]) --> Spec[1️⃣ SPEC 작성<br/>/alfred:1-spec]
+    Spec --> Build[2️⃣ TDD 구현<br/>/alfred:2-build]
+    Build --> Sync[3️⃣ 문서 동기화<br/>/alfred:3-sync]
+    Sync --> End([완료])
+    Sync -.-> Spec
+```
+
 ### 1️⃣ SPEC - 명세 작성
 
 **명령어**: `/alfred:1-spec "JWT 기반 사용자 로그인 API"`
 
 **Alfred가 자동 수행:**
+
 - EARS 형식 명세 자동 생성
 - `@SPEC:ID` TAG 부여
 - Git 브랜치 자동 생성 (Team 모드)
@@ -427,6 +653,7 @@ Alfred의 핵심은 **체계적인 3단계 워크플로우**입니다.
 - HISTORY 섹션 자동 추가
 
 **산출물:**
+
 - `.moai/specs/SPEC-AUTH-001/spec.md`
 - `.moai/specs/SPEC-AUTH-001/plan.md`
 - `.moai/specs/SPEC-AUTH-001/acceptance.md`
@@ -435,36 +662,217 @@ Alfred의 핵심은 **체계적인 3단계 워크플로우**입니다.
 
 **명령어**: `/alfred:2-build AUTH-001`
 
-**Alfred가 자동 수행:**
-- **RED**: 실패하는 테스트 작성
-- **GREEN**: 최소 구현으로 테스트 통과
-- **REFACTOR**: 코드 품질 개선
-- TRUST 5원칙 자동 검증
-- 단계별 Git 커밋 (TDD 완료 시 1회)
+**Alfred가 자동 수행 (3개 에이전트 협업):**
+
+- **Phase 1 (implementation-planner)**: SPEC 분석, 라이브러리 선정, TAG 체인 설계
+- **Phase 2 (tdd-implementer)**: RED → GREEN → REFACTOR TDD 사이클
+  - **RED**: 실패하는 테스트 작성 (@TEST:ID)
+  - **GREEN**: 최소 구현으로 테스트 통과 (@CODE:ID)
+  - **REFACTOR**: 코드 품질 개선
+- **Phase 3 (quality-gate)**: TRUST 5원칙 자동 검증 (Pass/Warning/Critical)
+- **Phase 4 (git-manager)**: 단계별 Git 커밋 (TDD 완료 시 1회)
 
 **산출물:**
+
 - `tests/test_auth_login.py` (테스트 코드)
 - `src/auth/service.py` (구현 코드)
 - `@TEST:AUTH-001` → `@CODE:AUTH-001` TAG 체인
+- 품질 검증 리포트
 
 ### 3️⃣ SYNC - 문서 동기화
 
 **명령어**: `/alfred:3-sync`
 
 **Alfred가 자동 수행:**
-- Living Document 업데이트
-- TAG 시스템 무결성 검증
-- sync-report.md 생성
-- PR Ready 전환 (Team 모드)
-- 선택적 자동 머지 (`--auto-merge`)
+
+- **Phase 1 (quality-gate)**: 동기화 전 빠른 품질 검증 (조건부, 변경 라인 >50줄)
+- **Phase 2 (doc-syncer)**: Living Document 업데이트
+- **Phase 3 (tag-agent)**: TAG 시스템 무결성 검증
+- **Phase 4 (git-manager)**: sync-report.md 생성, PR Ready 전환 (Team 모드)
+- **선택적 자동 머지** (`--auto-merge`): CI/CD 확인 후 자동 병합
 
 **산출물:**
+
 - `docs/api/auth.md` (API 문서)
 - `.moai/reports/sync-report.md`
 - `@DOC:AUTH-001` TAG 추가
 
 ---
 
+## 🔥 실전 시나리오
+
+### 시나리오 1: 긴급 버그 수정 (Hotfix)
+
+**상황**: 프로덕션에서 로그인 에러 발생!
+
+```bash
+# 옵션 1: 표준 방식 (권장)
+git checkout develop
+git checkout -b hotfix/auth-error
+# ... 수정 ...
+git push origin hotfix/auth-error
+# PR 생성: hotfix -> develop -> main
+
+# 옵션 2: 직접 main 수정 (허용, 하지만 권장 안 함)
+git checkout main
+# ... 수정 ...
+git commit -m "Fix critical auth bug"
+git push origin main  # ⚠️ Advisory 경고 표시되지만 진행됨
+```
+
+**Alfred의 Advisory 경고**:
+
+```text
+⚠️  ADVISORY: Non-standard GitFlow detected
+
+Current branch: hotfix/auth-error
+Target branch: main
+
+Recommended GitFlow workflow:
+  1. Push to hotfix and create PR to develop
+  2. Merge into develop after code review
+  3. When develop is stable, create PR from develop to main
+  4. Release manager merges develop -> main with tag
+
+✓ Push will proceed (flexibility mode enabled)
+```
+
+---
+
+### 시나리오 2: 새 기능 개발 (Feature)
+
+```bash
+# 1. develop에서 최신 코드 받기
+git checkout develop
+git pull origin develop
+
+# 2. Claude Code에서 SPEC 작성
+/alfred:1-spec "사용자 프로필 이미지 업로드"
+# → feature/SPEC-PROFILE-001 브랜치 자동 생성
+# → Draft PR 자동 생성 (feature → develop)
+
+# 3. TDD 구현
+/alfred:2-build PROFILE-001
+
+# 4. 문서 동기화 + 자동 머지
+/alfred:3-sync --auto-merge
+# → 문서 동기화
+# → PR Ready 전환
+# → CI/CD 확인
+# → PR 자동 머지 (squash)
+# → develop 체크아웃
+# → 다음 작업 준비 완료 ✅
+```
+
+---
+
+### 시나리오 3: Release 준비
+
+```bash
+# 표준 방식 (권장):
+git checkout develop
+gh pr create --base main --head develop --title "Release v1.0.0"
+
+# 직접 push 방식 (허용):
+git checkout develop
+git push origin main  # ⚠️ Advisory 경고 표시되지만 진행됨
+git tag -a v1.0.0 -m "Release v1.0.0"
+git push origin v1.0.0
+```
+
+---
+
+## 🧠 AI 모델 선택 가이드
+
+MoAI-ADK는 **Haiku 4.5**와 **Sonnet 4.5** 두 가지 AI 모델을 전략적으로 활용하여 **최적의 성능과 비용 효율**을 제공합니다.
+
+### 패스트 모드 vs 스마트 모드
+
+Claude Code에서 `/model` 명령어로 전체 세션의 기본 모델을 변경할 수 있습니다:
+
+```text
+# 패스트 모드 (빠른 응답, 반복 작업)
+/model haiku
+
+# 스마트 모드 (복잡한 판단, 설계)
+/model sonnet
+```
+
+### 12개 에이전트의 모델 배치 전략
+
+Alfred는 **작업 특성**에 따라 각 에이전트에 최적 모델을 할당합니다:
+
+#### 🚀 Haiku 에이전트 (6개) - 패스트 모드
+
+**빠른 응답이 필요한 반복 작업 및 패턴 매칭**
+
+| 에이전트            | 역할            | 왜 Haiku?                                    |
+| ------------------- | --------------- | -------------------------------------------- |
+| **doc-syncer** 📖    | 문서 동기화     | 패턴화된 문서 업데이트, Living Document 생성 |
+| **tag-agent** 🏷️     | TAG 시스템 관리 | 반복적 패턴 매칭, TAG 체인 검증              |
+| **git-manager** 🚀   | Git 워크플로우  | 정형화된 Git 명령어 실행, 브랜치/PR 생성     |
+| **trust-checker** ✅ | TRUST 원칙 검증 | 규칙 기반 체크리스트 확인                    |
+| **quality-gate** 🛡️  | 품질 검증       | TRUST 원칙 자동 검증, 빠른 품질 게이트       |
+| **Explore** 🔍       | 코드베이스 탐색 | 대량 파일 스캔, 키워드 검색                  |
+
+**장점**:
+
+- ⚡ **속도 2~5배 향상**: 실시간 응답 (수 초 → 1초 이내)
+- 💰 **비용 67% 절감**: 반복 작업이 많은 프로젝트에 효과적
+- 🎯 **높은 정확도**: 패턴화된 작업에서 Sonnet과 동등한 품질
+
+#### 🧠 Sonnet 에이전트 (6개) - 스마트 모드
+
+**복잡한 판단과 창의적 설계가 필요한 작업**
+
+| 에이전트                     | 역할             | 왜 Sonnet?                           |
+| ---------------------------- | ---------------- | ------------------------------------ |
+| **spec-builder** 🏗️           | SPEC 작성        | EARS 구조 설계, 복잡한 요구사항 분석 |
+| **implementation-planner** 📋 | 구현 전략 수립   | 아키텍처 설계, 라이브러리 선정       |
+| **tdd-implementer** 🔬        | TDD 구현         | RED-GREEN-REFACTOR, 복잡한 리팩토링  |
+| **debug-helper** 🔍           | 디버깅           | 런타임 오류 분석, 해결 방법 도출     |
+| **cc-manager** 🛠️             | Claude Code 설정 | 워크플로우 최적화, 복잡한 설정       |
+| **project-manager** 📂        | 프로젝트 초기화  | 전략 수립, 복잡한 의사결정           |
+
+**장점**:
+
+- 🎯 **높은 품질**: 복잡한 코드 품질 보장
+- 🧠 **깊은 이해**: 맥락 파악 및 창의적 해결책 제시
+- 🏆 **정확한 판단**: 아키텍처 결정, 설계 선택
+
+### 사용 시나리오별 권장 모델
+
+| 시나리오               | 권장 모델 | 이유                          |
+| ---------------------- | --------- | ----------------------------- |
+| 🆕 **새 프로젝트 시작** | Sonnet    | SPEC 설계, 아키텍처 결정 필요 |
+| 🔄 **반복 개발**        | Haiku     | 이미 정해진 패턴 반복 구현    |
+| 🐛 **버그 수정**        | Sonnet    | 원인 분석 및 해결 방법 도출   |
+| 📝 **문서 작성**        | Haiku     | Living Document 동기화        |
+| 🔍 **코드 탐색**        | Haiku     | 파일 검색, TAG 조회           |
+| ♻️ **리팩토링**         | Sonnet    | 구조 개선, 복잡한 변경        |
+
+### 모델 전환 팁
+
+```text
+# 새 기능 설계 시작
+/model sonnet
+/alfred:1-spec "사용자 인증 시스템"
+
+# SPEC 승인 후 TDD 구현
+/alfred:2-build AUTH-001
+
+# 구현 완료 후 문서 동기화 (자동으로 Haiku 사용)
+/alfred:3-sync
+
+# 다음 기능 설계
+/model sonnet
+/alfred:1-spec "결제 시스템"
+```
+
+**Pro Tip**: Alfred는 각 에이전트를 호출할 때 자동으로 최적 모델을 사용하므로, **세션 전체 모델 변경은 선택사항**입니다. 기본 설정(Sonnet)으로도 충분히 효율적입니다.
+
+---
+
 ## 🛠️ CLI Reference
 
 ### 프로젝트 관리
@@ -518,12 +926,12 @@ moai-adk --help
 
 각 Alfred 커맨드는 적절한 에이전트를 호출하며, **자동으로 최적 모델**을 사용합니다:
 
-| 커맨드              | 에이전트          | 모델           | 작업 특성                           | 예상 시간 |
-| ------------------- | ----------------- | -------------- | ----------------------------------- | --------- |
-| `/alfred:0-project` | project-manager 📋 | 세션 기본 모델 | 프로젝트 전략 수립, 복잡한 의사결정 | 1~2분     |
-| `/alfred:1-spec`    | spec-builder 🏗️    | 세션 기본 모델 | EARS 명세 설계, 요구사항 분석       | 2~3분     |
-| `/alfred:2-build`   | code-builder 💎    | 세션 기본 모델 | TDD 구현, 아키텍처 설계             | 3~5분     |
-| `/alfred:3-sync`    | doc-syncer 📖      | **Haiku 지정** | Living Document 동기화, 패턴 기반   | 30초~1분  |
+| 커맨드              | 에이전트 (Phase)                                              | 모델                       | 작업 특성                                | 예상 시간 |
+| ------------------- | ------------------------------------------------------------- | -------------------------- | ---------------------------------------- | --------- |
+| `/alfred:0-project` | project-manager 📂                                             | 세션 기본 모델             | 프로젝트 전략 수립, 복잡한 의사결정      | 1~2분     |
+| `/alfred:1-spec`    | spec-builder 🏗️                                                | 세션 기본 모델             | EARS 명세 설계, 요구사항 분석            | 2~3분     |
+| `/alfred:2-build`   | implementation-planner 📋 → tdd-implementer 🔬 → quality-gate 🛡️ | 세션 기본 모델 + **Haiku** | SPEC 분석 → TDD 구현 → 품질 검증 (3단계) | 3~5분     |
+| `/alfred:3-sync`    | quality-gate 🛡️ → doc-syncer 📖 → tag-agent 🏷️                   | **Haiku 지정**             | 사전 검증 → 문서 동기화 → TAG 검증       | 30초~1분  |
 
 #### 온디맨드 에이전트 호출
 
@@ -534,14 +942,15 @@ moai-adk --help
 @agent-tag-agent "AUTH 도메인 TAG 목록 조회"
 @agent-git-manager "브랜치 생성 및 PR 생성"
 @agent-trust-checker "TRUST 원칙 준수 여부 확인"
+@agent-quality-gate "코드 품질 검증 실행"
+@agent-Explore "JWT 인증 관련 코드 위치 탐색"
 
 # Sonnet 에이전트 (복잡한 작업)
-@agent-debug-helper "TypeError 오류 원인 분석"
 @agent-spec-builder "SPEC-AUTH-001 메타데이터 검증"
+@agent-implementation-planner "AUTH-001 구현 계획 수립"
+@agent-tdd-implementer "AUTH-001 TDD 구현 실행"
+@agent-debug-helper "TypeError 런타임 오류 원인 분석"
 @agent-cc-manager "Claude Code 설정 최적화"
-
-# Explore 에이전트 (Haiku, 코드 탐색)
-@agent-Explore "JWT 인증 관련 코드 위치 탐색"
 ```
 
 #### 모델별 성능 비교
@@ -556,6 +965,7 @@ moai-adk --help
 | **디버깅**      | 1분            | 2~3분           | 세션 기본 모델 사용        |
 
 **핵심 설계**:
+
 - `/alfred:0-project`, `/alfred:1-spec`, `/alfred:2-build`: **사용자가 선택한 세션 기본 모델** 사용
   - `/model sonnet` (기본값): 높은 품질, 복잡한 판단
   - `/model haiku`: 빠른 속도, 반복 작업
@@ -575,9 +985,10 @@ Alfred는 작업 특성과 사용자 경험 수준에 따라 **3가지 출력
 
 **대상**: 실무 개발자, 팀 리더, 아키텍트
 
-Alfred SuperAgent가 9개 전문 에이전트를 조율하여 빠른 개발과 협업을 자동으로 전환하는 통합 코딩 모드입니다.
+Alfred SuperAgent가 11개 전문 에이전트를 조율하여 빠른 개발과 협업을 자동으로 전환하는 통합 코딩 모드입니다.
 
 **두 가지 작업 방식**:
+
 - **⚡ Fast Mode (기본)**: 빠른 개발, 구현 위주 작업
   - SPEC → TDD → SYNC 자동화
   - 간결한 기술 커뮤니케이션
@@ -590,12 +1001,14 @@ Alfred SuperAgent가 9개 전문 에이전트를 조율하여 빠른 개발과
   - 실시간 코드 리뷰
 
 **핵심 원칙**:
+
 - SPEC 우선: 모든 작업은 @SPEC:ID부터 시작
 - TAG 무결성: `rg` 스캔 기반 실시간 검증
 - TRUST 준수: 5원칙 자동 검증 및 품질 게이트
 - 다중 언어: 17개 언어 지원 (Python, TypeScript, JavaScript, Java, Go, Rust, Dart, Swift, Kotlin, PHP, Ruby, C++, C, C#, Haskell, Shell, Lua)
 
 **사용**:
+
 ```text
 /output-style agentic-coding
 ```
@@ -611,6 +1024,7 @@ MoAI-ADK의 핵심 개념과 3단계 워크플로우를 친절하게 설명하
 **핵심 철학**: "명세 없으면 코드 없다, 테스트 없으면 구현 없다"
 
 **3가지 핵심 개념**:
+
 1. **SPEC-First**: 코드 작성 전 명세를 먼저 작성
    - EARS 구문 (5가지 패턴)으로 요구사항 작성
    - Ubiquitous, Event-driven, State-driven, Optional, Constraints
@@ -621,12 +1035,14 @@ MoAI-ADK의 핵심 개념과 3단계 워크플로우를 친절하게 설명하
    - Test First, Readable, Unified, Secured, Trackable
 
 **학습 내용**:
+
 - 각 개념을 실생활 비유로 쉽게 설명
 - 3단계 워크플로우 단계별 학습
 - 실제 예시로 SPEC 작성 연습
 - FAQ로 자주 묻는 질문 해결
 
 **사용**:
+
 ```text
 /output-style moai-adk-learning
 ```
@@ -662,12 +1078,14 @@ Alfred가 함께 배우는 친구처럼 새로운 기술을 쉽게 설명하고,
    - 완성된 코드 품질 검증
 
 **특징**:
+
 - 복잡한 개념을 쉽게 풀어서 설명
 - 실생활 비유로 이해도 향상
 - 단계별로 함께 실습
 - 자주 묻는 질문에 답변
 
 **사용**:
+
 ```text
 /output-style study-with-alfred
 ```
@@ -687,6 +1105,7 @@ Alfred가 함께 배우는 친구처럼 새로운 기술을 쉽게 설명하고,
 | 🤝 **팀 협업**       | Agentic Coding (Collab) | 트레이드오프 분석, 브레인스토밍  |
 
 **스타일 전환 예시**:
+
 ```text
 # MoAI-ADK 처음 시작 시
 /output-style moai-adk-learning
@@ -789,6 +1208,7 @@ Alfred는 프로젝트 루트의 설정 파일을 자동으로 감지하여 언
 | **T**rackable  | @TAG         | @TAG         | @TAG               |
 
 **공통 원칙**:
+
 - 모든 언어는 `@TAG 시스템`으로 SPEC→TEST→CODE→DOC 추적성 보장
 - 언어별 표준 도구 체인을 자동 감지 및 적용
 - TRUST 5원칙은 모든 프로젝트에 일관되게 적용
@@ -819,28 +1239,33 @@ Alfred는 각 디렉토리의 언어를 자동 감지하고 적절한 도구 체
 Alfred가 모든 코드에 자동으로 적용하는 품질 기준입니다.
 
 ### T - Test First (테스트 우선)
+
 - SPEC 기반 테스트 케이스 작성
 - TDD RED → GREEN → REFACTOR 사이클
 - 테스트 커버리지 ≥ 85%
 
 ### R - Readable (가독성)
+
 - 파일 ≤ 300 LOC
 - 함수 ≤ 50 LOC
 - 매개변수 ≤ 5개
 - 복잡도 ≤ 10
 
 ### U - Unified (통일성)
+
 - 타입 안전성 또는 런타임 검증
 - 아키텍처 일관성
 - 코딩 스타일 통일
 
 ### S - Secured (보안)
+
 - 입력 검증
 - 로깅 및 감사
 - 비밀 관리
 - 정적 분석
 
 ### T - Trackable (추적성)
+
 - `@SPEC → @TEST → @CODE → @DOC` TAG 체인
 - CODE-FIRST 원칙 (코드 직접 스캔)
 - HISTORY 섹션 기록
@@ -862,11 +1287,146 @@ Alfred가 모든 코드에 자동으로 적용하는 품질 기준입니다.
 
 ---
 
+## 📐 코드 품질 가이드
+
+### 리팩토링 규칙: 3회 반복 규칙
+
+**원칙**: 동일한 패턴이 3번째 반복될 때 리팩토링을 고려합니다.
+
+```python
+# ❌ 반복 1회: 복사-붙여넣기 OK
+def process_user_data(user):
+    if not user.is_active:
+        return None
+    return user.data
+
+# ❌ 반복 2회: 복사-붙여넣기 OK (하지만 주의)
+def process_admin_data(admin):
+    if not admin.is_active:
+        return None
+    return admin.data
+
+# ✅ 반복 3회: 리팩토링 필수!
+def process_data(entity):
+    """공통 로직 추출"""
+    if not entity.is_active:
+        return None
+    return entity.data
+```
+
+### 변수 역할 참고 (11가지 패턴)
+
+**변수 명명에 도움이 되는 역할 분류**:
+
+| 역할               | 설명                    | 예시                                  |
+| ------------------ | ----------------------- | ------------------------------------- |
+| Fixed Value        | 초기화 후 불변          | `const MAX_SIZE = 100`                |
+| Stepper            | 순차적으로 변화         | `for (let i = 0; i < n; i++)`         |
+| Flag               | 불린 상태 표시          | `let isValid = true`                  |
+| Walker             | 자료구조 순회           | `while (node) { node = node.next; }`  |
+| Most Recent Holder | 가장 최근 값 보관       | `let lastError`                       |
+| Most Wanted Holder | 최적/최대값 보관        | `let bestScore = -Infinity`           |
+| Gatherer           | 누적기                  | `sum += value`                        |
+| Container          | 여러 값 저장            | `const list = []`                     |
+| Follower           | 다른 변수의 이전 값     | `prev = curr; curr = next;`           |
+| Organizer          | 데이터 재구성           | `const sorted = array.sort()`         |
+| Temporary          | 임시 저장               | `const temp = a; a = b; b = temp;`    |
+
+**실제 적용 예시**:
+
+```python
+# ✅ 좋은 예: 역할이 명확한 변수명
+def find_max_score(scores: List[int]) -> int:
+    """최고 점수 찾기"""
+    best_score = -float('inf')  # Most Wanted Holder
+
+    for score in scores:  # Stepper (implicit)
+        if score > best_score:
+            best_score = score
+
+    return best_score
+
+
+# ❌ 나쁜 예: 역할이 불명확한 변수명
+def find_max(data):
+    x = -999999
+    for d in data:
+        if d > x:
+            x = d
+    return x
+```
+
+---
+
+## ⬆️ 업그레이드 가이드
+
+### 1단계: 패키지 업데이트
+
+```bash
+moai-adk update
+
+# 또는
+uv pip install --upgrade moai-adk
+```
+
+### 2단계: 프로젝트 업데이트
+
+```bash
+cd your-project
+moai-adk init .
+```
+
+**자동 백업**: 업데이트 전 `.moai-backups/{timestamp}/`에 자동 백업 생성
+
+### 3단계: Claude Code 최적화
+
+```text
+$ claude
+> /alfred:0-project
+```
+
+병합 프롬프트에서 **Merge** 선택 → 기존 문서 유지 + 새 템플릿 추가
+
+### 검증 체크리스트
+
+```bash
+# 상태 확인
+moai-adk status
+
+## 출력 예시:
+╭────── Project Status ──────╮
+│   Mode          team       │
+│   Locale        ko         │
+│   SPECs         23         │
+│   Branch        develop    │
+│   Git Status    Clean      │
+╰────────────────────────────╯
+```
+
+```bash
+# 시스템 진단
+moai-adk doctor
+
+## 출력 예시:
+Running system diagnostics...
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
+┃ Check                                    ┃ Status ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
+│ Python >= 3.13                           │   ✓    │
+│ Git installed                            │   ✓    │
+│ Project structure (.moai/)               │   ✓    │
+│ Config file (.moai/config.json)          │   ✓    │
+└──────────────────────────────────────────┴────────┘
+```
+
+---
+
 ## ❓ FAQ
 
 ### Q1: MoAI-ADK는 어떤 프로젝트에 적합한가요?
 
 **A**: 다음과 같은 프로젝트에 적합합니다:
+
 - ✅ 새로운 프로젝트 (그린필드)
 - ✅ 기존 프로젝트 (레거시 도입)
 - ✅ 개인 프로젝트 (Personal 모드)
@@ -884,12 +1444,14 @@ Alfred가 모든 코드에 자동으로 적용하는 품질 기준입니다.
 ### Q4: Personal 모드와 Team 모드의 차이는?
 
 **A**:
+
 - **Personal 모드**: 로컬 작업 중심, 체크포인트만 생성
 - **Team 모드**: GitFlow 지원, Draft PR 자동 생성, develop 브랜치 기반
 
 ### Q5: SPEC 메타데이터는 어떻게 관리하나요?
 
 **A**: `.moai/memory/spec-metadata.md`에 전체 가이드가 있습니다.
+
 - **필수 7개**: id, version, status, created, updated, author, priority
 - **선택 9개**: category, labels, depends_on, blocks, related_specs, related_issue, scope
 - **HISTORY 섹션**: 모든 변경 이력 기록 (필수)
@@ -901,13 +1463,14 @@ Alfred가 모든 코드에 자동으로 적용하는 품질 기준입니다.
 ### Q7: Context Engineering이란?
 
 **A**:
+
 - **JIT Retrieval**: 필요한 순간에만 문서 로드 (초기 컨텍스트 최소화)
-- **Compaction**: 토큰 사용량 >70% 시 요약 후 새 세션 권장
 - **Explore 에이전트**: 대규모 코드베이스 효율적 탐색
 
 ### Q8: 자동 백업은 어떻게 작동하나요?
 
 **A**:
+
 - **Template Processor**: 업데이트 전 `.moai-backups/alfred-{timestamp}/` 자동 백업
 - **Event-Driven Checkpoint**: 위험한 작업 전 자동 checkpoint 생성
 - **보존 정책**: 최대 10개 유지, 7일 후 자동 정리
@@ -915,6 +1478,7 @@ Alfred가 모든 코드에 자동으로 적용하는 품질 기준입니다.
 ### Q9: /model 명령어를 사용해야 하나요?
 
 **A**: **선택사항**입니다. Alfred는 이미 각 에이전트에 최적 모델을 할당했으므로:
+
 - ✅ **기본 설정 유지** (권장): Alfred가 자동으로 작업별 최적 모델 사용
 - ⚡ **패스트 모드**: `/model haiku` - 반복 작업 시 전체 세션을 Haiku로
 - 🧠 **스마트 모드**: `/model sonnet` - 복잡한 판단이 계속 필요할 때
@@ -924,11 +1488,13 @@ Alfred가 모든 코드에 자동으로 적용하는 품질 기준입니다.
 ### Q10: Haiku와 Sonnet의 비용 차이는?
 
 **A**:
+
 - **Haiku**: $1 / 1M 입력 토큰, $5 / 1M 출력 토큰
 - **Sonnet**: $3 / 1M 입력 토큰, $15 / 1M 출력 토큰
 - **절감 효과**: Haiku 에이전트 사용 시 **비용 67% 절감**
 
 **예시 (100만 토큰 기준)**:
+
 - 100% Sonnet: $18 (입력 + 출력)
 - MoAI-ADK (혼합): $6~$9 (작업 특성에 따라)
 - **절감액**: $9~$12 (50~67%)
@@ -962,11 +1528,42 @@ uv pip install moai-adk --force-reinstall
 ```bash
 # 프로젝트 상태 확인
 moai-adk status
+```
+
+**출력 예시**:
+
+```text
+╭────── Project Status ──────╮
+│   Mode          team       │
+│   Locale        ko         │
+│   SPECs         23         │
+│   Branch        develop    │
+│   Git Status    Clean      │
+╰────────────────────────────╯
+```
 
+```bash
 # 시스템 진단
 moai-adk doctor
+```
+
+**출력 예시**:
+
+```text
+Running system diagnostics...
+
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
+┃ Check                                    ┃ Status ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
+│ Python >= 3.13                           │   ✓    │
+│ Git installed                            │   ✓    │
+│ Project structure (.moai/)               │   ✓    │
+│ Config file (.moai/config.json)          │   ✓    │
+└──────────────────────────────────────────┴────────┘
+```
 
-# 강제 재초기화
+```bash
+# 강제 재초기화 (문제가 있을 경우)
 moai-adk init . --force
 ```
 
@@ -986,6 +1583,7 @@ ls -la .claude/commands/alfred/
 ### 일반적인 에러
 
 #### 에러: "moai-adk: command not found"
+
 ```bash
 # PATH 확인 및 전체 경로 사용
 ~/.local/bin/moai-adk --version
@@ -995,6 +1593,7 @@ pip install --force-reinstall moai-adk
 ```
 
 #### 에러: ".moai/ 디렉토리를 찾을 수 없습니다"
+
 ```bash
 # 초기화 실행
 moai-adk init .
@@ -1004,6 +1603,7 @@ moai-adk init .
 ```
 
 #### 에러: "SPEC ID 중복"
+
 ```bash
 # 기존 SPEC 확인
 rg "@SPEC:" -n .moai/specs/
@@ -1017,15 +1617,16 @@ rg "@SPEC:" -n .moai/specs/
 ## 📚 문서 및 지원
 
 ### 공식 문서
+
 - **GitHub Repository**: https://github.com/modu-ai/moai-adk
 - **PyPI Package**: https://pypi.org/project/moai-adk/
 - **Issue Tracker**: https://github.com/modu-ai/moai-adk/issues
 - **Discussions**: https://github.com/modu-ai/moai-adk/discussions
 
 ### 커뮤니티
+
 - **GitHub Discussions**: 질문, 아이디어, 피드백 공유
 - **Issue Tracker**: 버그 리포트, 기능 요청
-- **Email**: email@mo.ai.kr
 
 ### 기여하기
 
@@ -1047,9 +1648,6 @@ MIT License - 자유롭게 사용하실 수 있습니다.
 
 MoAI-ADK는 다음 프로젝트와 커뮤니티의 도움으로 만들어졌습니다:
 
-- **Anthropic Claude Code**: AI 에이전트 시스템의 기반
-- **OpenAI GPT Models**: 초기 설계 협업
-- **Python & TypeScript Communities**: 언어 지원 및 도구 체인
 - **모두의AI Community**: 지속적인 피드백과 개선 아이디어
 
 ---