moai-adk 0.32.8__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-workflow-templates/examples.md

@@ -0,0 +1,552 @@
+# Enterprise Template Management Examples
+
+실용적인 예시를 통해 코드 템플릿, 피드백 템플릿, 템플릿 최적화 패턴을 학습합니다.
+
+---
+
+## Example 1: FastAPI 프로젝트 스캐폴딩
+
+**Scenario**: FastAPI 백엔드 프로젝트를 인증, 데이터베이스, Celery 기능과 함께 생성
+
+**Input**:
+```python
+from moai_workflow_templates import load_template
+
+# 템플릿 로드
+template = load_template("backend/fastapi")
+
+# 프로젝트 스캐폴딩
+project = template.scaffold(
+    name="my-api",
+    features=["auth", "database", "celery"],
+    customizations={
+        "db": "postgresql",
+        "auth_type": "jwt",
+        "python_version": "3.13"
+    }
+)
+```
+
+**Output**:
+```
+my-api/
+├── src/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── config.py
+│   ├── database.py
+│   ├── auth/
+│   │   ├── __init__.py
+│   │   ├── router.py
+│   │   ├── schemas.py
+│   │   ├── models.py
+│   │   └── jwt.py
+│   ├── models/
+│   │   ├── __init__.py
+│   │   └── user.py
+│   └── tasks/
+│       ├── __init__.py
+│       └── celery_app.py
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py
+│   ├── test_auth.py
+│   └── test_main.py
+├── alembic/
+│   ├── versions/
+│   └── env.py
+├── docker/
+│   ├── Dockerfile
+│   └── docker-compose.yml
+├── .github/
+│   └── workflows/
+│       └── ci.yml
+├── pyproject.toml
+├── .env.example
+└── README.md
+```
+
+```python
+# 생성된 src/main.py
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from src.auth.router import router as auth_router
+from src.config import settings
+
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(auth_router, prefix="/api/auth", tags=["auth"])
+
+@app.get("/health")
+async def health_check():
+    return {"status": "healthy"}
+```
+
+**Explanation**: FastAPI 템플릿은 프로젝트 구조, 인증 모듈, 데이터베이스 설정, Celery 작업, Docker 구성, CI/CD 파이프라인을 한 번에 생성합니다. features 옵션으로 필요한 기능만 선택할 수 있습니다.
+
+---
+
+## Example 2: GitHub 피드백 템플릿 활용
+
+**Scenario**: /moai:9-feedback 명령으로 버그 리포트 이슈 생성
+
+**Input**:
+```bash
+# 피드백 명령 실행
+/moai:9-feedback "로그인 시 JWT 토큰이 만료되어도 갱신되지 않음"
+```
+
+**Output**:
+```markdown
+## Bug Report Template (자동 선택됨)
+
+### Issue Title
+[Bug] JWT 토큰 자동 갱신 실패
+
+### Environment
+- **OS**: macOS 15.1
+- **Python**: 3.13.0
+- **FastAPI**: 0.109.0
+- **Project Version**: 1.2.3
+
+### Description
+로그인 시 JWT 토큰이 만료되어도 갱신되지 않음
+
+### Steps to Reproduce
+1. 사용자 로그인
+2. access_token 만료 대기 (기본 15분)
+3. 보호된 엔드포인트 요청
+4. 401 Unauthorized 응답 수신
+
+### Expected Behavior
+access_token 만료 시 refresh_token을 사용하여 자동 갱신
+
+### Actual Behavior
+토큰 갱신 없이 401 에러 반환
+
+### Possible Solution
+- AuthMiddleware에서 토큰 만료 검사 추가
+- 자동 갱신 로직 구현
+
+### Additional Context
+- 관련 코드: `src/auth/middleware.py`
+- 영향 범위: 모든 인증된 API 엔드포인트
+
+### Labels
+`bug`, `auth`, `high-priority`
+
+---
+Generated by: MoAI-ADK Feedback System
+SPEC Reference: SPEC-001 (User Authentication)
+```
+
+**Explanation**: 피드백 템플릿은 6가지 유형(Bug, Feature, Improvement, Refactor, Docs, Question) 중 적절한 것을 자동 선택합니다. 환경 정보, 재현 단계, 예상/실제 동작을 구조화하여 완전한 이슈를 생성합니다.
+
+---
+
+## Example 3: 스마트 템플릿 머지 (업데이트)
+
+**Scenario**: MoAI-ADK 업데이트 후 사용자 커스터마이징을 보존하며 템플릿 병합
+
+**Input**:
+```python
+from moai_workflow_templates import TemplateOptimizer
+
+optimizer = TemplateOptimizer()
+
+# 백업에서 사용자 커스터마이징 추출
+backup_id = "backup-2025-10-15-v0.27.0"
+user_customizations = optimizer.extract_customizations(backup_id)
+
+# 최신 템플릿과 스마트 머지
+merge_result = optimizer.smart_merge(
+    backup=backup_id,
+    template="v0.28.2",  # 최신 버전
+    preserve_customizations=True
+)
+```
+
+**Output**:
+```json
+{
+  "merge_status": "success",
+  "backup_version": "0.27.0",
+  "template_version": "0.28.2",
+  "user_customizations_preserved": [
+    {
+      "file": ".moai/config/config.yaml",
+      "preserved_fields": [
+        "user.name",
+        "language.conversation_language",
+        "team_settings.custom_agents"
+      ]
+    },
+    {
+      "file": ".claude/settings.json",
+      "preserved_fields": [
+        "permissions.allow",
+        "permissions.deny"
+      ]
+    }
+  ],
+  "template_updates_applied": [
+    {
+      "file": ".moai/config/config.yaml",
+      "updates": [
+        "Added: system.new_feature_flag",
+        "Updated: version to 0.28.2"
+      ]
+    },
+    {
+      "file": ".claude/agents/",
+      "updates": [
+        "Added: 3 new agent definitions",
+        "Updated: 5 existing agents"
+      ]
+    }
+  ],
+  "conflicts_resolved": [
+    {
+      "file": ".moai/config/sections/quality.yaml",
+      "resolution": "Merged both changes",
+      "details": "User's custom thresholds + new quality metrics"
+    }
+  ],
+  "manual_review_required": [],
+  "restoration_point": ".moai/backups/pre-merge-2025-12-06/"
+}
+```
+
+**Explanation**: 스마트 머지는 3-way 머지 알고리즘을 사용합니다. 사용자 커스터마이징(설정, 권한)을 보존하면서 최신 템플릿 기능(새 에이전트, 기능 플래그)을 적용합니다. 충돌은 자동 해결되며, 롤백용 복원 지점이 생성됩니다.
+
+---
+
+## Common Patterns
+
+### Pattern 1: 템플릿 변수 시스템
+
+템플릿에서 동적 값을 대체하는 패턴입니다.
+
+```json
+// templates/fastapi-backend/template.json
+{
+  "name": "fastapi-backend",
+  "version": "1.0.0",
+  "variables": {
+    "PROJECT_NAME": {
+      "type": "string",
+      "required": true,
+      "description": "Project name (kebab-case)"
+    },
+    "AUTHOR": {
+      "type": "string",
+      "default": "MoAI Team"
+    },
+    "PYTHON_VERSION": {
+      "type": "string",
+      "default": "3.13",
+      "enum": ["3.11", "3.12", "3.13"]
+    },
+    "DATABASE": {
+      "type": "string",
+      "default": "postgresql",
+      "enum": ["postgresql", "mysql", "sqlite"]
+    }
+  },
+  "files": {
+    "pyproject.toml": "substitute",
+    "README.md": "substitute",
+    "src/**/*.py": "copy",
+    ".env.example": "substitute"
+  },
+  "post_hooks": [
+    "uv sync",
+    "git init"
+  ]
+}
+```
+
+```toml
+# templates/fastapi-backend/pyproject.toml.template
+[project]
+name = "{{PROJECT_NAME}}"
+version = "0.1.0"
+requires-python = ">={{PYTHON_VERSION}}"
+authors = [{ name = "{{AUTHOR}}" }]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23"
+]
+```
+
+### Pattern 2: 피드백 유형 자동 분류
+
+사용자 입력에서 피드백 유형을 자동으로 분류합니다.
+
+```python
+def classify_feedback(user_input: str) -> str:
+    """피드백 유형 자동 분류"""
+
+    # 키워드 기반 분류
+    classifiers = {
+        "bug": ["error", "bug", "broken", "not working", "crash", "fail"],
+        "feature": ["add", "new feature", "implement", "create", "support"],
+        "improvement": ["improve", "enhance", "better", "optimize", "upgrade"],
+        "refactor": ["refactor", "restructure", "reorganize", "clean up"],
+        "docs": ["document", "docs", "readme", "guide", "tutorial"],
+        "question": ["how to", "what is", "why", "question", "help"]
+    }
+
+    user_lower = user_input.lower()
+
+    for feedback_type, keywords in classifiers.items():
+        for keyword in keywords:
+            if keyword in user_lower:
+                return feedback_type
+
+    return "improvement"  # 기본값
+
+# 사용 예시
+feedback_type = classify_feedback("JWT 토큰이 갱신되지 않는 버그")
+# → "bug"
+
+feedback_type = classify_feedback("다크 모드 지원 추가해주세요")
+# → "feature"
+```
+
+### Pattern 3: 버전 추적 시스템
+
+템플릿 버전과 커스터마이징 이력을 추적합니다.
+
+```json
+// .moai/config/template-history.json
+{
+  "template_optimization": {
+    "last_optimized": "2025-12-06T12:00:00Z",
+    "backup_version": "backup-2025-10-15-v0.27.0",
+    "template_version": "0.28.2",
+    "customizations_preserved": [
+      "language",
+      "team_settings",
+      "domains",
+      "custom_agents"
+    ]
+  },
+  "version_history": [
+    {
+      "version": "0.28.2",
+      "date": "2025-12-06",
+      "changes": ["Added new agents", "Updated quality thresholds"]
+    },
+    {
+      "version": "0.27.0",
+      "date": "2025-10-15",
+      "changes": ["Initial template setup"]
+    }
+  ],
+  "migration_log": [
+    {
+      "from": "0.27.0",
+      "to": "0.28.2",
+      "date": "2025-12-06",
+      "status": "success",
+      "conflicts_resolved": 1
+    }
+  ]
+}
+```
+
+---
+
+## Anti-Patterns (피해야 할 패턴)
+
+### Anti-Pattern 1: 템플릿 직접 수정
+
+**Problem**: 공유 템플릿을 직접 수정하여 팀 충돌 발생
+
+```bash
+# 잘못된 예시 - 템플릿 직접 수정
+vim .claude/skills/moai-workflow-templates/modules/code-templates.md
+# → MoAI-ADK 업데이트 시 충돌
+# → 팀원 간 불일치
+```
+
+**Solution**: 커스터마이징 레이어 사용
+
+```python
+# 올바른 예시 - 커스터마이징 분리
+# 1. 프로젝트별 오버라이드 생성
+custom_templates = {
+    "backend/fastapi": {
+        "overrides": {
+            "PYTHON_VERSION": "3.12",  # 팀 표준
+            "DATABASE": "mysql"
+        }
+    }
+}
+
+# 2. 커스터마이징 저장
+save_project_customizations(custom_templates)
+# → .moai/config/template-overrides.json에 저장
+# → 템플릿 업데이트와 독립적
+```
+
+### Anti-Pattern 2: 백업 없는 머지
+
+**Problem**: 복원 지점 없이 템플릿 머지 수행
+
+```python
+# 잘못된 예시 - 백업 없음
+optimizer.smart_merge(
+    backup=None,  # 위험!
+    template="v0.28.2"
+)
+# → 머지 실패 시 복구 불가
+# → 사용자 설정 손실 위험
+```
+
+**Solution**: 항상 백업 생성 후 머지
+
+```python
+# 올바른 예시 - 백업 우선
+# 1. 백업 생성
+backup_id = optimizer.create_backup("pre-merge")
+
+# 2. 머지 수행
+try:
+    result = optimizer.smart_merge(
+        backup=backup_id,
+        template="v0.28.2"
+    )
+except MergeError as e:
+    # 3. 실패 시 복원
+    optimizer.restore_from_backup(backup_id)
+    raise
+```
+
+### Anti-Pattern 3: 불완전한 피드백 템플릿
+
+**Problem**: 필수 정보 없이 피드백 제출
+
+```markdown
+# 잘못된 예시 - 정보 부족
+## Bug Report
+로그인이 안 됩니다.
+<!-- 환경, 재현 단계, 예상 동작 없음 -->
+```
+
+**Solution**: 템플릿의 모든 섹션 작성
+
+```markdown
+# 올바른 예시 - 완전한 정보
+## Bug Report
+
+### Environment
+- OS: macOS 15.1
+- Browser: Chrome 120
+- Version: 1.2.3
+
+### Steps to Reproduce
+1. Navigate to /login
+2. Enter valid credentials
+3. Click "Login" button
+
+### Expected Behavior
+Redirect to dashboard with valid session
+
+### Actual Behavior
+Stays on login page, no error message
+
+### Logs
+```
+Error: Session token validation failed
+```
+```
+
+### Anti-Pattern 4: 템플릿 버전 무시
+
+**Problem**: 템플릿 버전을 확인하지 않고 사용
+
+```python
+# 잘못된 예시 - 버전 무시
+template = load_template("backend/fastapi")
+# 어떤 버전인지 모름
+project = template.scaffold(name="my-api")
+# → 오래된 패턴 사용 가능
+# → 보안 취약점 포함 가능
+```
+
+**Solution**: 버전 확인 후 사용
+
+```python
+# 올바른 예시 - 버전 확인
+template = load_template("backend/fastapi")
+
+# 버전 확인
+if template.version < "1.2.0":
+    print(f"Warning: Template version {template.version} is outdated")
+    template = update_template("backend/fastapi")
+
+# 최신 버전으로 스캐폴딩
+project = template.scaffold(name="my-api")
+```
+
+---
+
+## Template Types Reference
+
+### 코드 템플릿
+
+| 템플릿 | 용도 | 포함 기능 |
+|--------|------|----------|
+| backend/fastapi | FastAPI REST API | Auth, DB, Celery, Docker |
+| backend/django | Django 웹 앱 | ORM, Admin, REST framework |
+| frontend/react | React SPA | Vite, Router, Zustand |
+| frontend/nextjs | Next.js 풀스택 | App Router, API Routes |
+| fullstack/t3 | T3 Stack | Next.js, tRPC, Prisma |
+
+### 피드백 템플릿
+
+| 유형 | 트리거 키워드 | 필수 섹션 |
+|------|--------------|----------|
+| Bug | error, bug, broken | Environment, Steps, Expected/Actual |
+| Feature | add, new, implement | Description, Use Case, Acceptance |
+| Improvement | improve, enhance | Current, Proposed, Benefits |
+| Refactor | refactor, restructure | Scope, Rationale, Impact |
+| Docs | document, guide | Section, Changes, Examples |
+| Question | how to, what is | Context, Question, Attempts |
+
+---
+
+## Workflow Integration
+
+```
+프로젝트 초기화:
+/moai:0-project → 코드 템플릿 선택 → 스캐폴딩 → 버전 추적
+
+피드백 제출:
+/moai:9-feedback → 자동 분류 → 템플릿 적용 → GitHub 이슈 생성
+
+템플릿 업데이트:
+버전 감지 → 백업 생성 → 스마트 머지 → 버전 기록
+```
+
+---
+
+Version: 1.0.0
+Last Updated: 2025-12-06