muno-claude-plugin 1.0.0

package/README.md

@@ -0,0 +1,834 @@
+# Muno Claude Plugin
+
+> Claude Code를 제대로 활용하기 위한 통합 개발 워크플로우 플러그인
+
+AI 기반 소프트웨어 개발의 전체 라이프사이클을 지원합니다. 요구사항 정의부터 테스트까지, 체계적인 워크플로우와 전문가 페르소나를 통해 Claude Code의 잠재력을 극대화합니다.
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+- [Skills Reference](#skills-reference)
+- [Personas Reference](#personas-reference)
+- [Subagents Reference](#subagents-reference)
+- [Workflow Guide](#workflow-guide)
+- [Usage Examples](#usage-examples)
+- [Customization](#customization)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick Start
+
+```bash
+# 설치 (Project Level)
+npx muno-claude-plugin install
+
+# Claude Code에서 사용
+/prd-generator        # PRD 문서 생성
+/dev                  # Developer 페르소나 활성화
+```
+
+30초 만에 시작하세요. 설치 후 Claude Code에서 바로 사용 가능합니다.
+
+---
+
+## Features
+
+### 1. Development Workflow Skills
+PRD → Epic/Story → HLD → LLD → Task → TC 전체 개발 라이프사이클 자동화
+
+### 2. Expert Personas
+역할별 전문가 페르소나로 상황에 맞는 최적의 답변 제공
+
+### 3. TDD-based Subagents
+테스트 먼저(Test-First) 방식의 자동 서브에이전트 체계
+
+### 4. Status Tracking
+Epic/Story/Task 상태 자동 추적 및 관리
+
+---
+
+## Installation
+
+### Project Level (권장)
+
+팀원들과 Git으로 공유할 수 있습니다.
+
+```bash
+npx muno-claude-plugin install
+```
+
+설치 위치: `<project>/.claude/`
+
+### User Level
+
+모든 프로젝트에서 자동 적용됩니다.
+
+```bash
+npx muno-claude-plugin install-user
+```
+
+설치 위치: `~/.claude/`
+
+### Commands
+
+| 명령어 | 설명 |
+|--------|------|
+| `npx muno-claude-plugin install` | Project 레벨 설치 |
+| `npx muno-claude-plugin install-user` | User 레벨 설치 |
+| `npx muno-claude-plugin install --force` | 기존 파일 덮어쓰기 |
+| `npx muno-claude-plugin status` | 설치 상태 확인 |
+| `npx muno-claude-plugin uninstall` | 제거 |
+| `npx muno-claude-plugin help` | 도움말 |
+
+### 설치 후 디렉토리 구조
+
+```
+.claude/
+├── agents/              # Subagent 정의 (자동 호출)
+│   ├── tc-reviewer.md
+│   ├── acceptance-test-generator.md
+│   ├── unit-test-generator.md
+│   ├── task-tracker.md
+│   └── ...
+├── skills/              # 워크플로우 스킬 (/command로 호출)
+│   ├── prd-generator/
+│   ├── epic-story-generator/
+│   ├── hld-generator/
+│   ├── lld-generator/
+│   ├── task-generator/
+│   └── tc-generator/
+├── commands/            # Slash 명령어 정의
+├── personas/            # 페르소나 상세 정의
+├── references/          # 참조 문서
+└── WORKFLOW.md          # 워크플로우 가이드
+```
+
+---
+
+## Core Concepts
+
+### Skills vs Personas vs Subagents
+
+| 구분 | 호출 방식 | 용도 | 예시 |
+|------|----------|------|------|
+| **Skill** | `/skill-name` (명시적) | 특정 산출물 생성 | `/prd-generator` |
+| **Persona** | `/persona-name` (명시적) | 역할 기반 대화 | `/dev`, `/qa` |
+| **Subagent** | 자동 호출 | 품질 검증, 테스트 생성 | tc-reviewer |
+
+### TDD Workflow (2-Level)
+
+```
+Story Level (인수 테스트)
+├── tc-generator → TC 명세 생성
+├── tc-reviewer → TC 품질 리뷰 (자동)
+└── acceptance-test-generator → 인수 테스트 생성 (Red)
+
+Task Level (단위 테스트)
+├── unit-test-generator → Unit Test 생성 (Red)
+├── 구현 → 테스트 통과 (Green)
+└── 리팩토링 (Refactor)
+```
+
+---
+
+## Skills Reference
+
+### /prd-generator
+
+**Product Requirements Document 생성**
+
+입력: 요구사항 (자연어)
+출력: `documents/prd/<feature>-prd.md`
+
+```
+/prd-generator
+
+사용자가 상품을 장바구니에 담고 주문할 수 있는 기능이 필요합니다.
+- 장바구니 담기/빼기
+- 수량 변경
+- 주문서 작성
+- 결제 연동
+```
+
+**생성되는 PRD 구조:**
+- 문제 정의 (Problem Statement)
+- 목표 및 성공 지표 (Goals & Metrics)
+- 사용자 스토리 (User Stories)
+- 기능 요구사항 (Functional Requirements)
+- 비기능 요구사항 (Non-Functional Requirements)
+- 제약사항 및 가정 (Constraints & Assumptions)
+- 용어 정의 (Glossary)
+
+---
+
+### /epic-story-generator
+
+**Epic & User Story 생성**
+
+입력: PRD 문서
+출력: `backlogs/<feature>/` 디렉토리
+
+```
+/epic-story-generator
+
+@documents/prd/cart-prd.md 를 기반으로 Epic과 Story를 생성해주세요.
+```
+
+**생성 구조:**
+```
+backlogs/cart-feature/
+├── index.md              # 전체 백로그 개요
+├── EPIC-001-cart.md      # Epic 정의
+├── STORY-001-add-item.md # User Story (AC 포함)
+├── STORY-002-remove-item.md
+└── ...
+```
+
+**User Story 포함 내용:**
+- 스토리 설명 (As a... I want... So that...)
+- Acceptance Criteria (Given-When-Then)
+- 기술적 고려사항
+- 의존성
+
+---
+
+### /hld-generator
+
+**High-Level Design 생성**
+
+입력: Story 또는 PRD
+출력: `documents/hld/<feature>-hld.md`
+
+```
+/hld-generator
+
+@backlogs/cart-feature/STORY-001-add-item.md 에 대한 HLD를 작성해주세요.
+```
+
+**HLD 포함 내용:**
+- 시스템 컨텍스트 다이어그램
+- 컴포넌트 아키텍처
+- 데이터 흐름
+- 기술 스택 선정 근거
+- 통합 포인트
+- 보안 고려사항
+
+---
+
+### /lld-generator
+
+**Low-Level Design 생성**
+
+입력: Story + HLD
+출력: `documents/lld/<feature>-lld.md`
+
+```
+/lld-generator
+
+@backlogs/cart-feature/STORY-001-add-item.md
+@documents/hld/cart-hld.md
+
+위 문서를 기반으로 LLD를 작성해주세요.
+```
+
+**LLD 포함 내용:**
+- ERD (Entity Relationship Diagram)
+- 클래스/모듈 설계
+- API 명세 (OpenAPI 형식)
+- 시퀀스 다이어그램
+- 에러 처리 전략
+- 데이터 검증 규칙
+
+---
+
+### /task-generator
+
+**Implementation Task 생성**
+
+입력: Story + LLD
+출력: `.tasks/<story-id>/` 디렉토리
+
+```
+/task-generator
+
+@backlogs/cart-feature/STORY-001-add-item.md
+@documents/lld/cart-lld.md
+
+구현 태스크를 생성해주세요.
+```
+
+**생성 구조:**
+```
+.tasks/STORY-001/
+├── index.md              # 태스크 목록 및 의존성
+├── TASK-001-entity.md    # 엔티티 구현
+├── TASK-002-repository.md
+├── TASK-003-service.md
+├── TASK-004-controller.md
+└── ...
+```
+
+**Task 포함 내용:**
+- 구현 목표
+- 완료 조건 (Definition of Done)
+- 기술적 상세
+- 의존 태스크
+- 예상 복잡도
+
+---
+
+### /tc-generator
+
+**Test Case 생성**
+
+입력: Story (Acceptance Criteria)
+출력: `test-cases/<story-id>/` 디렉토리
+
+```
+/tc-generator
+
+@backlogs/cart-feature/STORY-001-add-item.md
+
+AC 기반 테스트 케이스를 생성해주세요.
+```
+
+**생성 구조:**
+```
+test-cases/STORY-001/
+├── index.md                    # TC 목록
+├── TC-001-01-happy-path.md     # 정상 시나리오
+├── TC-001-02-empty-cart.md     # 빈 장바구니
+├── TC-001-03-max-quantity.md   # 최대 수량 초과
+└── ...
+```
+
+**자동 호출되는 Subagent:**
+1. `tc-reviewer` - TC 품질 리뷰 및 보완
+2. `acceptance-test-generator` - 실제 테스트 코드 생성
+
+---
+
+## Personas Reference
+
+### /dev - Developer
+
+**전문 분야:** 소프트웨어 설계 및 구현
+
+```
+/dev
+
+이 서비스 클래스의 트랜잭션 처리가 적절한지 검토해주세요.
+```
+
+**역량:**
+- 클린 코드 & SOLID 원칙
+- 디자인 패턴 적용
+- TDD/BDD 실천
+- 성능 최적화
+- 코드 리뷰
+
+**활용 시점:**
+- 코드 구현 중 설계 질문
+- 리팩토링 조언
+- 버그 분석 및 해결
+- 코드 리뷰 요청
+
+---
+
+### /qa - QA Engineer
+
+**전문 분야:** 테스트 설계 및 품질 보증
+
+```
+/qa
+
+이 기능에 대한 테스트 전략을 수립해주세요.
+엣지 케이스와 경계값 테스트도 포함해주세요.
+```
+
+**역량:**
+- 테스트 전략 수립
+- TC 설계 (경계값, 동등 분할)
+- 자동화 테스트 설계
+- 탐색적 테스트
+- 성능/보안 테스트
+
+**활용 시점:**
+- TC 작성 전 전략 수립
+- 테스트 커버리지 검토
+- 버그 재현 시나리오 설계
+- 테스트 자동화 설계
+
+---
+
+### /po - Product Owner
+
+**전문 분야:** 제품 기획 및 요구사항 관리
+
+```
+/po
+
+이 기능의 우선순위를 어떻게 정해야 할까요?
+MVP 범위를 정의해주세요.
+```
+
+**역량:**
+- 요구사항 정의 및 우선순위화
+- 사용자 스토리 작성
+- 백로그 관리
+- 이해관계자 커뮤니케이션
+- 비즈니스 가치 분석
+
+**활용 시점:**
+- PRD 작성 및 검토
+- 스코프 조정
+- MVP 정의
+- 기능 우선순위 결정
+
+---
+
+### /sm - Scrum Master
+
+**전문 분야:** 애자일 프로세스 및 팀 퍼실리테이션
+
+```
+/sm
+
+스프린트 플래닝에서 이 Epic을 어떻게 분해해야 할까요?
+```
+
+**역량:**
+- 스프린트 계획 및 실행
+- 장애물 제거
+- 프로세스 개선
+- 팀 협업 촉진
+- 메트릭스 관리
+
+**활용 시점:**
+- 스프린트 계획
+- 회고 진행
+- 팀 이슈 해결
+- 프로세스 개선
+
+---
+
+### /principal-engineer
+
+**전문 분야:** 시스템 아키텍처 및 기술 전략
+
+```
+/principal-engineer
+
+MSA로 전환할 때 서비스 경계를 어떻게 나눠야 할까요?
+```
+
+**역량:**
+- 시스템 아키텍처 설계
+- 기술 의사결정
+- 성능/확장성 설계
+- 기술 부채 관리
+- 멘토링
+
+**활용 시점:**
+- 아키텍처 의사결정
+- 기술 스택 선정
+- 시스템 설계 검토
+- 복잡한 기술 문제 해결
+
+---
+
+### /staff-engineer
+
+**전문 분야:** 기술 리더십 및 조직 영향력
+
+```
+/staff-engineer
+
+이 프로젝트의 기술적 리스크를 평가해주세요.
+```
+
+**역량:**
+- 기술 로드맵 수립
+- 크로스팀 기술 조율
+- 기술 표준화
+- 시니어 멘토링
+- 기술 전략
+
+**활용 시점:**
+- 기술 전략 수립
+- 팀 간 기술 조율
+- 기술 표준 정의
+- 복잡한 의사결정
+
+---
+
+### /claude-code-expert
+
+**전문 분야:** Claude Code 및 AI 도구 활용
+
+```
+/claude-code-expert
+
+MCP 서버를 설정하는 방법을 알려주세요.
+커스텀 스킬을 만들고 싶어요.
+```
+
+**역량:**
+- Claude Code 기능 활용
+- MCP 서버 설정
+- 커스텀 스킬/에이전트 개발
+- AI 페어 프로그래밍
+- 프롬프트 엔지니어링
+
+**활용 시점:**
+- Claude Code 기능 질문
+- 커스터마이징
+- AI 활용 최적화
+- 워크플로우 개선
+
+---
+
+## Subagents Reference
+
+Subagent는 특정 시점에 **자동으로 호출**됩니다.
+
+### tc-reviewer
+
+**호출 시점:** TC 생성 직후
+**역할:** TC 품질 리뷰 및 보완
+
+검토 기준:
+- AC 커버리지 100% 확인
+- 경계값/엣지케이스 포함 여부
+- 테스트 독립성
+- 명확한 기대 결과
+
+---
+
+### acceptance-test-generator
+
+**호출 시점:** TC 리뷰 완료 후
+**역할:** TC 기반 인수 테스트 코드 생성
+
+생성 위치: `src/test/`
+
+---
+
+### unit-test-generator
+
+**호출 시점:** Task 구현 시작 전
+**역할:** TDD 기반 Unit Test 생성 (Red 단계)
+
+Task의 완료 조건(DoD)을 테스트로 변환합니다.
+
+---
+
+### task-tracker
+
+**호출 시점:** Task 완료, TC 통과, 리뷰 승인 시
+**역할:** Epic/Story/Task 상태 자동 추적
+
+상태 흐름: `todo → inprogress → resolve → review → close`
+
+---
+
+### prd-reviewer / epic-story-reviewer / hld-reviewer / lld-reviewer
+
+**호출 시점:** 각 산출물 생성 후
+**역할:** 품질 검토 및 피드백 제공
+
+---
+
+## Workflow Guide
+
+### 복잡도별 워크플로우 선택
+
+#### L1~L2: 단순 작업 (버그 수정, 작은 기능)
+```
+요구사항 → 바로 구현
+```
+
+#### L3: 중간 복잡도 (일반적인 기능)
+```
+요구사항 → Story → Task + LLD → 구현 → TC → 테스트
+```
+
+#### L4~L5: 높은 복잡도 (대규모 기능, 신규 시스템)
+```
+요구사항 → PRD → Epic/Story → HLD → LLD → Task → 구현 → TC → 테스트
+```
+
+### 전체 워크플로우 다이어그램
+
+```
+[기획]
+    요구사항
+        │
+        ▼
+    /prd-generator ──────────────────────► PRD 문서
+        │                                     │
+        │                          ┌──────────┘
+        │                          ▼
+[백로그]│                   /epic-story-generator
+        │                          │
+        │           ┌──────────────┴──────────────┐
+        │           ▼                             ▼
+        │         Epic                          Story
+        │                                         │
+        │                          ┌──────────────┼──────────────┐
+        │                          ▼              │              │
+[테스트 설계]               /tc-generator         │              │
+        │                          │              │              │
+        │                          ▼              │              │
+        │                      TC 문서            │              │
+        │                          │              │              │
+        │                          ▼              │              │
+        │               tc-reviewer (auto)        │              │
+        │                          │              │              │
+        │                          ▼              │              │
+        │         acceptance-test-generator       │              │
+        │                    (auto)               │              │
+        │                          │              │              │
+        │                          ▼              │              │
+        │              인수 테스트 생성 (Red)      │              │
+        │                                         │              │
+        │                                         ▼              ▼
+[설계]  │                                  /hld-generator  /lld-generator
+        │                                         │              │
+        │                                         ▼              ▼
+        │                                     HLD 문서       LLD 문서
+        │                                                        │
+        │                                                        ▼
+[구현]  │                                                 /task-generator
+        │                                                        │
+        │                                                        ▼
+        │                                              Implementation Tasks
+        │                                                        │
+        │                                    ┌───────────────────┤
+        │                                    ▼                   │
+[TDD]   │                       unit-test-generator (auto)       │
+        │                                    │                   │
+        │                                    ▼                   │
+        │                          Unit Test 생성 (Red)          │
+        │                                    │                   │
+        │                                    ▼                   ▼
+        │                              구현 (Green) ◄───── Task 기반 구현
+        │                                    │
+        │                                    ▼
+        │                              리팩토링 (Refactor)
+        │                                    │
+[검증]  │                                    ▼
+        └────────────────────────►  인수 테스트 실행 (Green)
+                                             │
+                                             ▼
+                                    task-tracker (auto)
+                                             │
+                                             ▼
+                                      상태 자동 업데이트
+```
+
+### 문서 저장 위치
+
+| 산출물 | 위치 |
+|--------|------|
+| PRD | `documents/prd/<feature>-prd.md` |
+| HLD | `documents/hld/<feature>-hld.md` |
+| LLD | `documents/lld/<feature>-lld.md` |
+| Epic/Story | `backlogs/<feature>/` |
+| Task | `.tasks/<story-id>/` |
+| TC | `test-cases/<story-id>/` |
+
+---
+
+## Usage Examples
+
+### Example 1: 새 기능 개발 (Full Workflow)
+
+```bash
+# 1. PRD 생성
+/prd-generator
+"""
+사용자 인증 기능이 필요합니다.
+- 이메일/비밀번호 로그인
+- 소셜 로그인 (Google, Apple)
+- 비밀번호 재설정
+- 세션 관리
+"""
+
+# 2. Epic/Story 생성
+/epic-story-generator
+@documents/prd/auth-prd.md 기반으로 생성해주세요.
+
+# 3. TC 생성 (자동으로 tc-reviewer, acceptance-test-generator 호출됨)
+/tc-generator
+@backlogs/auth/STORY-001-email-login.md
+
+# 4. HLD 생성
+/hld-generator
+@backlogs/auth/STORY-001-email-login.md
+
+# 5. LLD 생성
+/lld-generator
+@backlogs/auth/STORY-001-email-login.md
+@documents/hld/auth-hld.md
+
+# 6. Task 생성 (자동으로 unit-test-generator가 테스트 먼저 생성)
+/task-generator
+@backlogs/auth/STORY-001-email-login.md
+@documents/lld/auth-lld.md
+
+# 7. 구현 시작 (Developer 페르소나 활용)
+/dev
+TASK-001 구현을 시작하겠습니다. 테스트가 통과하도록 구현해주세요.
+```
+
+### Example 2: 버그 수정 (간단한 워크플로우)
+
+```bash
+/dev
+로그인 시 세션이 제대로 생성되지 않는 버그가 있습니다.
+SessionService.createSession() 메서드를 확인해주세요.
+```
+
+### Example 3: 코드 리뷰 요청
+
+```bash
+/dev
+이 PR의 코드를 리뷰해주세요.
+특히 트랜잭션 처리와 예외 처리가 적절한지 확인해주세요.
+```
+
+### Example 4: 테스트 전략 수립
+
+```bash
+/qa
+이 결제 기능에 대한 테스트 전략을 수립해주세요.
+- 어떤 종류의 테스트가 필요한가요?
+- 엣지 케이스는 무엇인가요?
+- 성능 테스트도 필요한가요?
+```
+
+### Example 5: 아키텍처 상담
+
+```bash
+/principal-engineer
+현재 모놀리식 아키텍처에서 MSA로 전환을 고려하고 있습니다.
+- 서비스 경계는 어떻게 나눠야 할까요?
+- 데이터 분리 전략은?
+- 전환 시 주의할 점은?
+```
+
+---
+
+## Customization
+
+### 페르소나 커스터마이징
+
+`.claude/personas/<name>.md` 파일을 수정하여 팀에 맞게 조정:
+
+```markdown
+# Persona: Developer (Dev)
+
+## Identity
+[팀의 기술 스택과 문화에 맞게 수정]
+
+## Expertise
+[팀에서 중요하게 생각하는 역량 추가]
+
+## Mindset
+[팀의 개발 철학 반영]
+```
+
+### 스킬 템플릿 커스터마이징
+
+`.claude/skills/<skill>/reference/` 디렉토리의 템플릿 수정:
+
+```
+.claude/skills/prd-generator/reference/
+├── prd-template.md      # PRD 템플릿 수정
+└── prd-examples.md      # 예시 추가
+```
+
+### 새 페르소나 추가
+
+```bash
+# 1. 페르소나 정의
+touch .claude/personas/devops.md
+
+# 2. 명령어 정의
+touch .claude/commands/devops.md
+```
+
+---
+
+## Troubleshooting
+
+### Q: 설치 후 스킬이 인식되지 않아요
+
+```bash
+# Claude Code 재시작
+# 또는 설치 상태 확인
+npx muno-claude-plugin status
+```
+
+### Q: 기존 .claude 폴더가 있어서 설치가 안 돼요
+
+```bash
+npx muno-claude-plugin install --force
+```
+
+### Q: User Level과 Project Level 중 어떤 걸 선택해야 하나요?
+
+| 상황 | 추천 |
+|------|------|
+| 팀 프로젝트 | Project Level (Git 공유) |
+| 개인 프로젝트 | User Level (전역 적용) |
+| 팀마다 다른 설정 | Project Level |
+
+### Q: 특정 스킬만 설치하고 싶어요
+
+현재는 전체 설치만 지원됩니다. 설치 후 불필요한 파일 삭제 가능:
+
+```bash
+rm -rf .claude/skills/prd-generator  # 특정 스킬 제거
+```
+
+### Q: Subagent가 자동으로 호출되지 않아요
+
+Subagent는 Claude Code가 해당 시점을 인식할 때 자동 호출됩니다.
+명시적으로 호출하려면:
+
+```
+TC 생성이 완료되었습니다. tc-reviewer로 검토해주세요.
+```
+
+---
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Claude Code CLI
+
+---
+
+## License
+
+MIT
+
+---
+
+## Contributing
+
+이슈 및 PR 환영합니다.
+
+1. Fork the repository
+2. Create your feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request