muno-claude-plugin 1.0.0

package/templates/skills/hld-generator/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: hld-generator
+description: |
+  PRD를 기반으로 HLD(High-Level Design)를 생성합니다.
+  HLD는 구현 전에 시스템의 큰 그림을 설계하는 문서로, 방향 정렬, 리스크 조기 발견,
+  의사결정 기록, 시니어/아키텍트의 조기 피드백을 위해 작성합니다.
+  "HLD 작성해줘", "상위 설계 문서 만들어줘", "시스템 설계", "아키텍처 설계" 등의 요청에 사용합니다.
+allowed-tools: Read, Glob, Grep, Write, Edit, WebSearch, WebFetch
+---
+
+# HLD Generator
+
+## 페르소나
+
+@.claude/personas/principal-engineer.md
+
+---
+
+## HLD란?
+
+**High-Level Design (HLD)**는 구현 전에 전체 시스템의 큰 그림을 설계하는 문서입니다.
+
+### 언제 작성하는가
+
+```
+요구사항 분석(PRD) → HLD → LLD(Low-Level Design) → 구현
+```
+
+- 요구사항이 어느 정도 정리된 후
+- 실제 코딩을 시작하기 전
+- 새로운 기능, 시스템, 또는 큰 변경이 있을 때
+
+### 목적
+
+| 목적 | 설명 |
+|------|------|
+| **방향 정렬** | 이해관계자(PM, 개발자, 아키텍트)가 "우리가 뭘 만들 건지" 합의 |
+| **리스크 조기 발견** | 구현 전 기술적 리스크, 병목, 의존성 파악 → 뒤엎는 비용 감소 |
+| **의사결정 기록** | 왜 이 구조를 선택했는지 (trade-off) 기록 |
+| **조기 피드백** | 코드 전 설계 단계에서 시니어/아키텍트 개입 가능 |
+
+### HLD vs LLD
+
+| 구분 | HLD | LLD |
+|------|-----|-----|
+| 범위 | 전체 구조, 큰 그림 | 세부 구현, 클래스/함수 레벨 |
+| 질문 | "어떤 컴포넌트가 있고 어떻게 연결되는가" | "컴포넌트 내부는 어떻게 동작하는가" |
+| 대상 | 비개발자도 이해 가능 | 개발자용 |
+
+### HLD에 포함되는 것
+
+- 시스템 아키텍처 다이어그램
+- 주요 컴포넌트와 역할
+- 데이터 흐름
+- API 인터페이스 (대략적)
+- 기술 스택 선택과 이유
+- 고려한 대안과 왜 선택/기각했는지
+
+---
+
+## 워크플로우
+
+```mermaid
+flowchart TD
+    A[사용자 요청] --> B{PRD 존재?}
+    B -->|No| C[PRD 작성 권유]
+    B -->|Yes| D[Step 1: PRD 분석]
+    D --> E{정보 충분?}
+    E -->|No| F[보충 질문 2-3개]
+    F --> G[사용자 응답]
+    G --> E
+    E -->|Yes| H[Step 2: 아키텍처 방향 파악]
+    H --> I{정보 충분?}
+    I -->|No| J[보충 질문 2-3개]
+    J --> K[사용자 응답]
+    K --> I
+    I -->|Yes| L[Step 3: 기술적 제약/리스크 파악]
+    L --> M{정보 충분?}
+    M -->|No| N[보충 질문 2-3개]
+    N --> O[사용자 응답]
+    O --> M
+    M -->|Yes| P[Step 4: HLD 작성]
+    P --> Q[사용자 검토 요청]
+    Q -->|수정| P
+    Q -->|승인| R[저장]
+```
+
+---
+
+## Step 0: PRD 확인
+
+HLD 작성 전 반드시 PRD 존재 여부를 확인합니다.
+
+### PRD가 없는 경우
+```
+HLD 작성을 위해 PRD(제품 요구사항 정의서)가 필요합니다.
+PRD가 준비되어 있으신가요? 없다면 먼저 PRD를 작성해주세요.
+```
+
+### PRD가 있는 경우
+PRD를 읽고 다음 정보를 추출합니다:
+- 문제 정의 (Problem Statement)
+- 핵심 요구사항 (Must-have)
+- 성공 지표
+- 범위 (In-Scope / Out-of-Scope)
+
+---
+
+## Step 1: PRD 분석 & 용어 파악
+
+### 수집해야 할 정보
+- PRD에 나온 도메인 용어 중 명확한 정의가 필요한 것
+- 기존 시스템과 신규 시스템의 용어 차이
+- 비즈니스 요구사항의 기술적 해석
+
+### 질문 예시 (한 번에 2-3개)
+```
+PRD를 확인했습니다. 몇 가지 확인이 필요합니다.
+
+1. "[용어]"가 정확히 어떤 의미인가요?
+2. 기존 시스템에서 유사한 개념이 있나요?
+3. [요구사항]의 우선순위는 어떻게 되나요?
+```
+
+---
+
+## Step 2: 아키텍처 방향 파악
+
+### 수집해야 할 정보
+- 현재 시스템 아키텍처 (모놀리식, MSA, 레이어드 등)
+- 선호하는 기술 스택 또는 제약사항
+- 확장성 요구사항
+- 기존 시스템과의 통합 방식
+
+### 질문 예시 (한 번에 2-3개)
+```
+아키텍처 설계 방향을 정하고 싶습니다.
+
+1. 현재 시스템은 어떤 아키텍처인가요?
+2. 기술 스택에 제약이 있나요?
+3. 연동해야 할 외부 시스템이 있나요?
+```
+
+---
+
+## Step 3: 기술적 제약 & 리스크 파악
+
+### 수집해야 할 정보
+- 성능 요구사항 (응답시간, TPS)
+- 기술적 제약 (레거시 호환성)
+- 알려진 기술적 리스크
+- 장애 허용 수준
+
+### 질문 예시 (한 번에 2-3개)
+```
+제약조건과 리스크를 파악하고 싶습니다.
+
+1. 예상 트래픽 규모는 어느 정도인가요?
+2. 반드시 호환해야 하는 레거시 시스템이 있나요?
+3. 가장 우려되는 기술적 리스크는 무엇인가요?
+```
+
+---
+
+## Step 4: HLD 작성
+
+모든 정보가 수집되면 아래 구조로 HLD를 작성합니다.
+
+### HLD 문서 구조
+
+```markdown
+# [기능명] - High-Level Design
+
+## 문서 정보
+
+| 항목 | 내용 |
+|------|------|
+| 작성자 | @작성자 |
+| 작성일 | YYYY-MM-DD |
+| PRD | [PRD 링크] |
+| 상태 | Draft / Review / Approved |
+
+---
+
+## 1. 개요 (Overview)
+
+### 1.1 목적
+[이 설계의 목적과 해결하려는 문제]
+
+### 1.2 범위
+| 포함 | 미포함 |
+|------|--------|
+| [범위1] | [미포함1 - 이유] |
+
+### 1.3 용어 정의
+| 용어 | 정의 |
+|------|------|
+| [Term] | [Definition] |
+
+---
+
+## 2. 시스템 아키텍처 (Architecture)
+
+### 2.1 아키텍처 다이어그램
+
+```mermaid
+graph TB
+    subgraph Client
+        Web[Web App]
+    end
+    subgraph Backend
+        API[API Server]
+        DB[(Database)]
+    end
+    Web --> API --> DB
+```
+
+### 2.2 주요 컴포넌트
+
+| 컴포넌트 | 역할 | 기술 |
+|----------|------|------|
+| [컴포넌트1] | [역할] | [기술스택] |
+
+---
+
+## 3. 데이터 흐름 (Data Flow)
+
+### 3.1 주요 흐름
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant API
+    participant DB
+    User->>API: Request
+    API->>DB: Query
+    DB-->>API: Result
+    API-->>User: Response
+```
+
+### 3.2 데이터 모델 (개략)
+
+```mermaid
+erDiagram
+    Entity1 ||--o{ Entity2 : has
+```
+
+---
+
+## 4. 핵심 설계 결정 (Key Design Decisions)
+
+### 4.1 [결정 사항]
+
+- **결정**: [무엇을 결정했는가]
+- **배경**: [왜 이 결정이 필요했는가]
+- **대안 검토**:
+  | 대안 | 장점 | 단점 |
+  |------|------|------|
+  | [대안1] | [장점] | [단점] |
+  | [대안2] | [장점] | [단점] |
+- **선택 이유**: [왜 이 대안을 선택했는가]
+
+---
+
+## 5. 기술 스택 (Tech Stack)
+
+| 레이어 | 기술 | 선택 이유 |
+|--------|------|-----------|
+| Backend | [기술] | [이유] |
+| Database | [기술] | [이유] |
+| Infra | [기술] | [이유] |
+
+---
+
+## 6. 리스크 및 대응 (Risks & Mitigations)
+
+| 리스크 | 영향도 | 발생 가능성 | 대응 방안 |
+|--------|--------|-------------|-----------|
+| [리스크1] | High/Medium/Low | High/Medium/Low | [대응] |
+
+---
+
+## 7. 미결정 사항 (Open Questions)
+
+- [ ] [아직 결정되지 않은 사항1]
+- [ ] [아직 결정되지 않은 사항2]
+
+---
+
+## 다음 단계
+
+- [ ] HLD 리뷰 완료
+- [ ] LLD 작성
+- [ ] 구현 시작
+```
+
+---
+
+## 작성 원칙
+
+### 포함해야 하는 것
+- 시스템 아키텍처 다이어그램
+- 주요 컴포넌트와 역할
+- 데이터 흐름
+- 기술 스택 선택과 이유
+- 고려한 대안과 선택/기각 이유
+- 리스크와 대응 방안
+
+### 포함하지 않는 것
+- 상세 구현 코드
+- API 스펙 (상세)
+- DB 스키마 (상세)
+- 일정/마일스톤 (프로젝트 관리 영역)
+
+### 작성 규칙
+1. **비개발자도 이해 가능하게**: 큰 그림을 전달
+2. **Why를 기록**: 왜 이 결정을 했는지 근거 명시
+3. **다이어그램 활용**: Mermaid로 구조 시각화
+4. **대안 검토 기록**: 검토한 대안과 기각 이유
+
+---
+
+## 금지 사항
+
+### 절대 하지 말 것
+
+1. **PRD 없이 작성 금지**
+   ```
+   ❌ PRD 없이 HLD 작성 시작
+   ✅ "PRD를 먼저 준비해주세요" 안내
+   ```
+
+2. **정보 없이 추측하여 작성 금지**
+   ```
+   ❌ 사용자가 "HLD 써줘"라고 하면 바로 작성
+   ✅ 필요한 정보 질문 → 수집 → 작성
+   ```
+
+3. **모호한 표현 금지**
+   ```
+   ❌ "빠르게 처리", "적절한 캐싱"
+   ✅ "P99 < 200ms", "Redis 캐시 TTL 5분"
+   ```
+
+4. **대안 없이 결정만 기록 금지**
+   ```
+   ❌ "MySQL을 사용한다"
+   ✅ "PostgreSQL vs MySQL 검토 후, [이유]로 MySQL 선택"
+   ```
+
+---
+
+## 산출물
+
+**저장 위치**: `documents/tasks/{task명}/{task명}-hld.md`
+
+**사용자 검토**: HLD 작성 후 반드시 사용자에게 검토 요청
+```
+HLD 초안을 작성했습니다. 검토 후 수정이 필요하면 말씀해주세요.
+특히 다음 부분을 확인해주세요:
+- 아키텍처가 현재 시스템 구조와 맞는지
+- 기술 스택 선택이 적절한지
+- 누락된 리스크가 있는지
+
+승인되면 저장하고 LLD 작성으로 넘어갑니다.
+```
+
+---
+
+## 리뷰 체크리스트
+
+Staff Engineer 관점에서 HLD 리뷰:
+
+### 아키텍처
+- [ ] 기존 시스템과의 일관성
+- [ ] 확장성/유지보수성 고려
+- [ ] 적절한 추상화 수준
+
+### 설계 결정
+- [ ] 대안 검토가 충분한가
+- [ ] 선택 이유가 명확한가
+- [ ] 트레이드오프가 기록되어 있는가
+
+### 리스크
+- [ ] 주요 리스크가 식별되었는가
+- [ ] 대응 방안이 현실적인가
+- [ ] 누락된 리스크가 없는가
+
+### 완성도
+- [ ] 다이어그램이 구조를 명확히 표현하는가
+- [ ] 비개발자도 큰 그림을 이해할 수 있는가
+- [ ] 미결정 사항이 명시되어 있는가
+
+---
+
+## 관련 스킬
+
+- `/skill:prd-generator`: PRD 생성 (HLD 작성 전 필수)
+- `/skill:lld-generator`: HLD 기반 Low Level Design 생성
+- `/skill:task-generator`: LLD 기반 Task 생성

package/templates/skills/hld-generator/reference/hld-examples.md

@@ -0,0 +1,305 @@
+# HLD 예시
+
+## Good Practice vs Bad Practice
+
+### 1. 목적 (Purpose)
+
+**Good Practice**:
+```markdown
+## 1.1 목적
+
+현재 사용자 인증 시스템은 세션 기반으로 구현되어 있어 다음과 같은 문제가 있습니다:
+- 수평 확장 시 세션 동기화 비용 발생
+- 모바일 앱에서 세션 관리의 어려움
+- 외부 서비스 연동 시 토큰 기반 인증 필요
+
+이 설계는 JWT 기반 인증 시스템으로 전환하여 위 문제를 해결하고,
+마이크로서비스 아키텍처로의 전환을 준비합니다.
+```
+
+**Bad Practice**:
+```markdown
+## 목적
+인증 시스템을 개선합니다.
+```
+→ 왜 개선이 필요한지, 어떤 문제를 해결하는지 명확하지 않음
+
+---
+
+### 2. 범위 (Scope)
+
+**Good Practice**:
+```markdown
+## 1.2 범위
+
+| 포함 (In-Scope) | 미포함 (Out-of-Scope) |
+|-----------------|----------------------|
+| JWT 토큰 발급/검증 | 소셜 로그인 연동 - Phase 2에서 진행 |
+| Refresh Token 관리 | 2FA 인증 - 별도 설계 필요 |
+| 기존 세션 마이그레이션 | 권한 관리(RBAC) - 기존 시스템 유지 |
+```
+
+**Bad Practice**:
+```markdown
+## 범위
+인증 관련 기능을 개발합니다.
+```
+→ 포함/미포함 구분 없음, 범위가 모호함
+
+---
+
+### 3. 용어 정의 (Terminology)
+
+**Good Practice**:
+```markdown
+## 1.3 용어 정의
+
+| 용어 | 정의 |
+|------|------|
+| Access Token | 인증된 사용자임을 증명하는 단기 토큰 (유효기간: 15분) |
+| Refresh Token | Access Token 재발급을 위한 장기 토큰 (유효기간: 7일) |
+| Token Rotation | Refresh Token 사용 시 새 Refresh Token 발급하는 보안 기법 |
+| Blacklist | 무효화된 토큰 목록. Redis에 저장하여 검증 |
+```
+
+**Bad Practice**:
+```markdown
+## 용어
+토큰, 인증 등의 용어를 사용합니다.
+```
+→ 구체적인 정의 없이 일반적인 용어만 나열
+
+---
+
+### 4. 아키텍처 다이어그램
+
+**Good Practice**:
+```markdown
+## 2.1 아키텍처 다이어그램
+
+```mermaid
+graph TB
+    subgraph Client
+        Web[Web App]
+        Mobile[Mobile App]
+    end
+
+    subgraph Gateway
+        APIGW[API Gateway]
+    end
+
+    subgraph Auth
+        AuthSvc[Auth Service]
+        Redis[(Token Blacklist)]
+    end
+
+    subgraph Services
+        UserSvc[User Service]
+        OrderSvc[Order Service]
+    end
+
+    subgraph Data
+        AuthDB[(Auth DB)]
+        UserDB[(User DB)]
+    end
+
+    Web --> APIGW
+    Mobile --> APIGW
+    APIGW -->|Token 검증| AuthSvc
+    APIGW --> UserSvc
+    APIGW --> OrderSvc
+    AuthSvc --> Redis
+    AuthSvc --> AuthDB
+    UserSvc --> UserDB
+```
+
+### 2.2 주요 컴포넌트
+
+| 컴포넌트 | 역할 | 기술 |
+|----------|------|------|
+| API Gateway | 모든 요청의 진입점, 토큰 검증 | Kong |
+| Auth Service | 토큰 발급/갱신/무효화 | Spring Boot |
+| Token Blacklist | 무효화된 토큰 저장 | Redis |
+| Auth DB | 사용자 인증 정보, Refresh Token 저장 | PostgreSQL |
+```
+
+**Bad Practice**:
+```markdown
+## 아키텍처
+서버와 DB로 구성됩니다.
+```
+→ 다이어그램 없음, 컴포넌트 역할 설명 없음
+
+---
+
+### 5. 핵심 설계 결정 (Key Design Decisions)
+
+**Good Practice**:
+```markdown
+## 4.1 토큰 저장소 선택
+
+- **결정**: Access Token은 메모리, Refresh Token은 DB에 저장
+- **배경**: 토큰 무효화 기능이 필요하며, 확장성을 고려해야 함
+- **대안 검토**:
+
+  | 대안 | 장점 | 단점 |
+  |------|------|------|
+  | 모든 토큰 DB 저장 | 완전한 제어 | 매 요청마다 DB 조회 필요, 성능 저하 |
+  | 모든 토큰 Stateless | 빠른 검증 | 토큰 무효화 불가 |
+  | Access Token Stateless + Blacklist ✓ | 빠른 검증 + 무효화 가능 | Redis 의존성 추가 |
+
+- **선택 이유**: 대부분의 요청은 빠르게 처리하면서, 필요시 토큰 무효화 가능
+- **영향**: Redis 클러스터 운영 필요, Blacklist TTL 관리 정책 수립 필요
+```
+
+**Bad Practice**:
+```markdown
+## 설계 결정
+Redis를 사용합니다.
+```
+→ 왜 Redis를 선택했는지, 어떤 대안을 검토했는지 없음
+
+---
+
+### 6. 기술 스택
+
+**Good Practice**:
+```markdown
+## 5. 기술 스택
+
+| 레이어 | 기술 | 버전 | 선택 이유 |
+|--------|------|------|-----------|
+| Language | Kotlin | 1.9 | 기존 프로젝트와 일관성, Null Safety |
+| Framework | Spring Boot | 3.2 | 팀 익숙도, Spring Security 통합 |
+| Token | JWT (jjwt) | 0.12 | 업계 표준, 라이브러리 성숙도 |
+| Cache | Redis | 7.2 | 빠른 Blacklist 조회, 기존 인프라 활용 |
+| Database | PostgreSQL | 15 | 기존 User DB와 통합 |
+```
+
+**Bad Practice**:
+```markdown
+## 기술
+Spring Boot, Redis를 사용합니다.
+```
+→ 선택 이유 없음, 버전 정보 없음
+
+---
+
+### 7. 리스크 및 대응
+
+**Good Practice**:
+```markdown
+## 6. 리스크 및 대응
+
+| 리스크 | 영향도 | 발생 가능성 | 대응 방안 |
+|--------|--------|-------------|-----------|
+| Redis 장애로 Blacklist 조회 불가 | High | Low | Redis Sentinel 구성, 장애 시 DB fallback |
+| 토큰 탈취 | High | Medium | Access Token 유효기간 15분으로 제한, HTTPS 강제 |
+| Refresh Token 동시 사용 공격 | Medium | Low | Token Rotation 적용, 기존 토큰 즉시 무효화 |
+| 마이그레이션 중 인증 실패 | High | Medium | 병렬 운영 기간 설정, 점진적 전환 |
+```
+
+**Bad Practice**:
+```markdown
+## 리스크
+보안 문제가 발생할 수 있습니다.
+```
+→ 구체적인 리스크 식별 없음, 대응 방안 없음
+
+---
+
+### 8. 미결정 사항
+
+**Good Practice**:
+```markdown
+## 7. 미결정 사항
+
+- [ ] Access Token 유효기간 (현재 15분 제안) - @security-team 12/20
+- [ ] Refresh Token 최대 발급 개수 제한 - @backend-lead 12/18
+- [ ] 기존 세션 마이그레이션 방식 (점진적 vs 일괄) - @devops 12/22
+```
+
+**Bad Practice**:
+```markdown
+## 미결정
+나중에 정합니다.
+```
+→ 무엇을 언제까지 누가 결정할지 없음
+
+---
+
+## 완성된 HLD 예시 (요약)
+
+```markdown
+# JWT 인증 시스템 - High-Level Design
+
+## 문서 정보
+| 항목 | 내용 |
+|------|------|
+| 작성자 | @backend-lead |
+| 작성일 | 2024-12-15 |
+| PRD | docs/prd/auth-improvement.md |
+| 상태 | Review |
+
+## 1. 개요
+### 1.1 목적
+세션 기반 인증을 JWT 기반으로 전환하여 수평 확장성 확보 및 MSA 전환 준비
+
+### 1.2 범위
+| 포함 | 미포함 |
+|------|--------|
+| JWT 토큰 발급/검증 | 소셜 로그인 - Phase 2 |
+| Refresh Token 관리 | 2FA - 별도 설계 |
+
+### 1.3 용어 정의
+| 용어 | 정의 |
+|------|------|
+| Access Token | 인증 증명용 단기 토큰 (15분) |
+| Refresh Token | Access Token 재발급용 장기 토큰 (7일) |
+
+## 2. 시스템 아키텍처
+[다이어그램 + 컴포넌트 테이블]
+
+## 3. 데이터 흐름
+[시퀀스 다이어그램 + ER 다이어그램]
+
+## 4. 핵심 설계 결정
+### 4.1 토큰 저장 방식
+- 결정: Access Token Stateless + Blacklist
+- 대안 검토: [테이블]
+- 선택 이유: 성능과 무효화 기능 균형
+
+## 5. 기술 스택
+[기술 + 버전 + 선택 이유 테이블]
+
+## 6. 리스크 및 대응
+[리스크 + 영향도 + 대응 테이블]
+
+## 7. 미결정 사항
+- [ ] Access Token 유효기간 최종 확정
+
+## 다음 단계
+- [ ] HLD 리뷰 완료
+- [ ] LLD 작성
+```
+
+---
+
+## 체크리스트
+
+HLD 작성 시 자가 점검:
+
+### 구조 체크
+- [ ] 목적이 "왜 이 설계가 필요한가"에 답하는가?
+- [ ] 범위가 포함/미포함으로 명확히 구분되어 있는가?
+- [ ] 용어 정의가 비전문가도 이해할 수 있는가?
+
+### 설계 체크
+- [ ] 아키텍처 다이어그램이 컴포넌트 관계를 보여주는가?
+- [ ] 데이터 흐름이 시퀀스 다이어그램으로 표현되어 있는가?
+- [ ] 핵심 결정에 대안 검토와 선택 이유가 있는가?
+
+### 리스크 체크
+- [ ] 주요 리스크가 식별되었는가?
+- [ ] 각 리스크에 대응 방안이 있는가?
+- [ ] 미결정 사항이 담당자/일정과 함께 기록되어 있는가?