# 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 = "moai-adk-go"
version = "0.1.0"
requires-python = ">={{PYTHON_VERSION}}"
authors = [{ name = "@user" }]

[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

```
프로젝트 초기화:
Use the InitProject tool → 코드 템플릿 선택 → 스캐폴딩 → 버전 추적

피드백 제출:
/moai:9-feedback → 자동 분류 → 템플릿 적용 → GitHub 이슈 생성

템플릿 업데이트:
버전 감지 → 백업 생성 → 스마트 머지 → 버전 기록
```

---

Version: 1.0.0
Last Updated: 2025-12-06
