@su-record/vibe 0.1.4 → 0.2.0

package/.claude/commands/vibe.analyze.md

@@ -0,0 +1,123 @@
+---
+description: Analyze project (code quality, architecture, dependencies)
+argument-hint: --code or --deps or --arch (optional)
+---
+
+# /vibe.analyze
+
+프로젝트를 분석합니다 (코드 품질, 아키텍처, 의존성).
+
+## Usage
+
+```
+/vibe.analyze
+/vibe.analyze --code
+/vibe.analyze --deps
+/vibe.analyze --arch
+```
+
+## Process
+
+### 1. 분석 범위 확인
+
+사용자가 지정한 옵션에 따라 분석 범위를 결정합니다:
+
+- **기본** (`/vibe.analyze`): 전체 분석 (코드 + 의존성 + 아키텍처)
+- **--code**: 코드 품질 분석만
+- **--deps**: 의존성 분석만
+- **--arch**: 아키텍처 분석만
+
+### 2. MCP 도구 사용
+
+다음 MCP 도구를 사용합니다 (`@su-record/hi-ai` 기반):
+
+#### 코드 품질 분석 (--code)
+- `mcp__su-record-hi-ai__analyze_complexity`: 복잡도 분석
+- `mcp__su-record-hi-ai__validate_code_quality`: 코드 품질 검증
+- `mcp__su-record-hi-ai__check_coupling_cohesion`: 결합도/응집도 체크
+
+#### 의존성 분석 (--deps)
+- `package.json` / `pyproject.toml` / `pubspec.yaml` 읽기
+- 버전 충돌, 보안 취약점, 업데이트 필요 패키지 분석
+
+#### 아키텍처 분석 (--arch)
+- `mcp__su-record-hi-ai__find_symbol`: 핵심 모듈 찾기
+- `mcp__su-record-hi-ai__find_references`: 모듈 간 의존성 파악
+- 순환 의존성, 레이어 위반 검출
+
+### 3. 분석 리포트 생성
+
+`.vibe/reports/analysis-{date}.md` 파일에 분석 결과 저장:
+
+```markdown
+# 프로젝트 분석 리포트
+
+## 개요
+- 분석 일시: 2025-11-17 15:30
+- 분석 범위: 전체 (코드 + 의존성 + 아키텍처)
+
+## 코드 품질 (85/100)
+- 평균 복잡도: 8.2 (양호)
+- 높은 복잡도 파일: 3개
+  - src/service.py (CC: 15)
+  - src/utils.py (CC: 12)
+
+## 의존성 (92/100)
+- 총 패키지: 42개
+- 업데이트 필요: 3개
+  - express: 4.17.1 → 4.18.2
+  - lodash: 4.17.20 → 4.17.21 (보안)
+
+## 아키텍처 (78/100)
+- 순환 의존성: 2개 발견
+  - A → B → C → A
+- 레이어 위반: 1개
+  - Controller가 직접 DB 접근
+
+## 개선 제안
+1. service.py 리팩토링 (복잡도 15 → 10 이하)
+2. lodash 보안 패치 적용
+3. 순환 의존성 제거
+```
+
+### 4. 개선 제안
+
+분석 결과를 바탕으로 구체적인 개선 방안 제시:
+- 리팩토링이 필요한 파일 목록
+- 의존성 업데이트 명령어
+- 아키텍처 개선 방향
+
+## Example
+
+```
+User: /vibe.analyze --code
+
+Claude: 코드 품질 분석을 시작합니다...
+
+[MCP 도구 사용]
+- analyze_complexity 실행 중...
+- validate_code_quality 실행 중...
+- check_coupling_cohesion 실행 중...
+
+✅ 분석 완료!
+
+📊 코드 품질 점수: 85/100 (B+)
+
+**주요 발견사항:**
+- 높은 복잡도: src/service.py (CC: 15)
+- 낮은 응집도: src/utils.py (응집도: 0.3)
+- 강한 결합: Controller ↔ Service (결합도: 0.8)
+
+**개선 제안:**
+1. src/service.py를 3개 모듈로 분리
+2. src/utils.py의 관련 없는 함수 분리
+3. Dependency Injection 패턴 도입
+
+상세 리포트: .vibe/reports/analysis-2025-11-17.md
+```
+
+## Notes
+
+- MCP 서버(`@su-record/hi-ai`)가 설치되어 있어야 합니다
+- 대규모 프로젝트는 분석에 시간이 걸릴 수 있습니다 (1-5분)
+- 분석 결과는 `.vibe/reports/` 폴더에 저장됩니다

package/.claude/commands/vibe.diagram.md

@@ -0,0 +1,174 @@
+---
+description: Generate diagrams (architecture, ERD, flowchart)
+argument-hint: --er or --flow (optional)
+---
+
+# /vibe.diagram
+
+다이어그램을 생성합니다 (아키텍처, ERD, 플로우차트).
+
+## Usage
+
+```
+/vibe.diagram
+/vibe.diagram --er
+/vibe.diagram --flow
+```
+
+## Process
+
+### 1. 다이어그램 타입 결정
+
+- **기본** (`/vibe.diagram`): 아키텍처 다이어그램
+- **--er**: ERD (Entity-Relationship Diagram)
+- **--flow**: 플로우차트 (주요 프로세스)
+
+### 2. 프로젝트 분석
+
+#### 아키텍처 다이어그램
+- 프로젝트 구조 파악 (폴더 구조)
+- 주요 모듈 및 레이어 식별
+- 의존성 관계 분석
+
+#### ERD
+- 데이터베이스 스키마 파일 찾기
+  - `backend/models/`
+  - `migrations/`
+  - `schema.sql`
+- 테이블 간 관계 파악
+
+#### 플로우차트
+- 주요 비즈니스 로직 흐름
+- 사용자 액션 → 시스템 응답
+
+### 3. Mermaid 코드 생성
+
+ASCII 아트 또는 Mermaid 코드로 다이어그램 생성:
+
+#### 아키텍처 다이어그램 (Mermaid)
+
+```mermaid
+graph TB
+    Client[React Frontend]
+    API[FastAPI Backend]
+    DB[(PostgreSQL)]
+    Cache[(Redis)]
+
+    Client -->|HTTP| API
+    API -->|Query| DB
+    API -->|Cache| Cache
+```
+
+#### ERD (Mermaid)
+
+```mermaid
+erDiagram
+    USER ||--o{ FEED : creates
+    USER ||--o{ FOLLOW : follows
+    FEED }o--|| RESTAURANT : references
+
+    USER {
+        uuid id PK
+        string email
+        int tier
+    }
+    FEED {
+        uuid id PK
+        uuid user_id FK
+        uuid restaurant_id FK
+        text content
+    }
+```
+
+#### 플로우차트 (Mermaid)
+
+```mermaid
+flowchart TD
+    Start([사용자가 피드 작성])
+    GPS{GPS 인증}
+    Vision{Vision API 검증}
+    OCR{OCR 인증}
+    Save[피드 저장]
+
+    Start --> GPS
+    GPS -->|50m 이내| Vision
+    GPS -->|범위 밖| Fail
+    Vision -->|음식 감지| OCR
+    Vision -->|실패| Fail
+    OCR -->|선택| Save
+    Save --> End([완료])
+```
+
+### 4. 렌더링 안내
+
+생성된 Mermaid 코드를 렌더링하는 방법 안내:
+
+- **GitHub**: `.md` 파일에 붙여넣기 (자동 렌더링)
+- **VSCode**: Mermaid 확장 프로그램 설치
+- **온라인**: https://mermaid.live/
+
+## Example
+
+```
+User: /vibe.diagram --er
+
+Claude: ERD를 생성합니다...
+
+프로젝트 분석 중...
+- 데이터베이스 스키마 발견: backend/models/
+- 테이블 수: 15개
+- 주요 관계: USER, FEED, RESTAURANT
+
+✅ ERD 생성 완료!
+
+```mermaid
+erDiagram
+    USER ||--o{ FEED : creates
+    USER ||--o{ FOLLOW : "follows/followed_by"
+    USER ||--o{ BOOKMARK : bookmarks
+    FEED }o--|| RESTAURANT : references
+    FEED ||--o{ COMMENT : has
+    FEED ||--o{ LIKE : has
+
+    USER {
+        uuid id PK
+        string email UK
+        string username UK
+        int tier
+        int points
+        timestamp created_at
+    }
+
+    FEED {
+        uuid id PK
+        uuid user_id FK
+        uuid restaurant_id FK
+        text content
+        geography location
+        boolean ocr_verified
+        timestamp created_at
+    }
+
+    RESTAURANT {
+        uuid id PK
+        string name
+        geography location
+        string category
+        timestamp created_at
+    }
+```
+
+**다이어그램 저장 위치:**
+  .vibe/diagrams/erd-2025-11-17.md
+
+**렌더링 방법:**
+  1. GitHub에 푸시 (자동 렌더링)
+  2. VSCode에서 Mermaid 확장 프로그램 사용
+  3. https://mermaid.live/ 에서 확인
+```
+
+## Notes
+
+- Mermaid는 GitHub, GitLab, VSCode 등에서 지원됩니다
+- 복잡한 다이어그램은 수동 조정이 필요할 수 있습니다
+- 생성된 다이어그램은 `.vibe/diagrams/` 폴더에 저장됩니다

package/.claude/commands/vibe.plan.md

@@ -0,0 +1,81 @@
+---
+description: Create PLAN document with Planning Agent
+argument-hint: "feature name"
+---
+
+# /vibe.plan
+
+PLAN 문서를 작성합니다 (Planning Agent).
+
+## Usage
+
+```
+/vibe.plan "기능명"
+```
+
+## Description
+
+SPEC 문서를 분석하여 기술 구현 계획(PLAN)을 작성합니다.
+
+## Process
+
+1. **SPEC 문서 읽기**: `.vibe/specs/{기능명}.md` 분석
+2. **Feature 파일 읽기**: `.vibe/features/{기능명}.feature` 확인 (BDD)
+3. **프로젝트 컨텍스트 파악**:
+   - `CLAUDE.md` 읽기 (기술 스택 확인)
+   - `package.json` / `pyproject.toml` / `pubspec.yaml` 확인
+4. **PLAN 문서 작성**: 15개 섹션 포함
+   - 기술 스택 선정 (기존 스택 재사용 우선)
+   - 아키텍처 설계
+   - API 설계
+   - DB 스키마
+   - 외부 서비스 통합
+   - 보안 설계
+   - 성능 최적화
+   - 에러 처리
+   - 모니터링 및 로깅
+   - **테스트 전략 (BDD/Contract Testing 포함)**
+     - BDD 도구 선정 (pytest-bdd, behave, cucumber 등)
+     - Contract Testing 도구 (Pact, Spring Cloud Contract 등)
+     - Feature 파일과 SPEC 매핑
+     - API Contract 스키마 정의
+   - 배포 전략
+   - 비용 예측
+   - 마일스톤 (Phase별)
+   - 리스크 및 완화 방안
+   - 다음 단계
+5. **품질 검증**: 기술 선택 근거, 비용, 일정 현실성, BDD 테스트 전략 타당성
+
+## Agent
+
+`~/.vibe/agents/planning-agent.md`
+
+## Input
+
+- `.vibe/specs/{기능명}.md` (SPEC 문서)
+- `.vibe/features/{기능명}.feature` (BDD Feature 파일)
+- `CLAUDE.md` (프로젝트 기술 스택)
+
+## Output
+
+- `.vibe/plans/{기능명}.md` - PLAN 문서
+- 예상 공수 (시간/일)
+- 예상 비용 ($)
+- Phase별 마일스톤
+
+## Example
+
+```
+/vibe.plan "푸시 알림 설정 기능"
+```
+
+**결과:**
+- 3 Phases (Backend → Frontend → FCM)
+- 24시간 (3일)
+- $0.50/월 추가 비용
+
+## Next Step
+
+```
+/vibe.tasks "푸시 알림 설정 기능"
+```

package/.claude/commands/vibe.run.md

@@ -0,0 +1,158 @@
+---
+description: Execute task with Implementation Agent
+argument-hint: "Task 1-1" or --phase N or --all
+---
+
+# /vibe.run
+
+Task를 구현합니다 (Implementation Agent).
+
+## Usage
+
+```
+/vibe.run "Task 1-1"           # 특정 Task 실행
+/vibe.run --phase 1            # Phase 1 전체 실행
+/vibe.run --all                # 모든 Task 실행
+```
+
+## Description
+
+TASKS 문서의 특정 Task를 읽고 구현 가이드를 생성한 후, 실제 코드를 작성합니다.
+
+## Process
+
+### 1️⃣ Task 정보 읽기
+- `.vibe/tasks/{기능명}.md`에서 Task 찾기
+- Task 메타데이터 확인:
+  - 담당 Agent (Backend Python Expert / Frontend Flutter Expert)
+  - 예상 시간
+  - 우선순위
+  - 의존성 (선행 Task 완료 여부 확인)
+  - Acceptance Criteria
+
+### 2️⃣ 구현 가이드 생성
+- `.vibe/guides/task-{N}-{M}.md` 생성
+- 포함 내용:
+  - 목표 (Goal)
+  - 파일 경로 (Files to Create/Modify)
+  - 코드 템플릿 (Code Template)
+  - 구현 순서 (Implementation Steps)
+  - 검증 방법 (Verification)
+  - 다음 Task
+
+### 3️⃣ 코드 구현
+- 구현 가이드에 따라 실제 파일 생성/수정
+- 담당 Agent의 스킬 적용:
+  - Backend Python Expert: `~/.vibe/agents/backend-python-expert.md`
+  - Frontend Flutter Expert: `~/.vibe/agents/frontend-flutter-expert.md`
+- TRUST 5 원칙 준수:
+  - **Test-first (BDD/Contract Testing 우선)**
+    - Contract 파일 먼저 작성 (Provider/Consumer)
+    - BDD Step Definitions 작성
+    - Unit Tests 작성
+  - Readable (명확한 코드)
+  - Unified (일관된 스타일)
+  - Secured (보안 고려)
+  - Trackable (로깅, 모니터링)
+
+### 4️⃣ Acceptance Criteria 검증
+- TASKS 문서의 체크리스트 확인
+- 검증 명령어 실행 (pytest, flutter test 등)
+- 모든 기준 통과 확인
+
+### 5️⃣ Task 상태 업데이트
+- TASKS 문서에서 Task 상태를 ✅ 완료로 변경
+- 완료 일시 기록
+- 진행률 업데이트
+
+## Agent Selection
+
+| Task | Agent |
+|------|-------|
+| Task 1-1 ~ 1-9 (Backend + Contract Provider) | Backend Python Expert |
+| Task 2-1 ~ 2-9 (Frontend + Contract Consumer) | Frontend Flutter Expert |
+| Task 3-1 ~ 3-2 (FCM Backend) | Backend Python Expert |
+| Task 3-3 (BDD Step Definitions) | QA / Backend/Frontend Expert |
+| Task 3-4 (Contract Verification) | QA |
+| Task 3-5 (E2E Test) | QA / Frontend Flutter Expert |
+
+## Input
+
+- `.vibe/tasks/{기능명}.md` (TASKS 문서)
+- `.vibe/plans/{기능명}.md` (PLAN 참고)
+- `.vibe/specs/{기능명}.md` (SPEC 참고)
+- `.vibe/features/{기능명}.feature` (BDD Feature 파일 - Contract Test 매핑용)
+
+## Output
+
+- `.vibe/guides/task-{N}-{M}.md` - 구현 가이드
+- 실제 코드 파일 (생성/수정)
+- TASKS 문서 업데이트 (상태: ✅ 완료)
+
+## Example
+
+### 개별 Task 실행
+
+```
+/vibe.run "Task 1-1"
+```
+
+**동작:**
+1. TASKS 문서 읽기
+2. Task 1-1 정보 파싱:
+   - 담당: Backend Python Expert
+   - 내용: DB 마이그레이션 파일 작성
+   - 예상 시간: 30분
+3. 구현 가이드 생성: `.vibe/guides/task-1-1.md`
+4. 코드 작성: `backend/alembic/versions/xxxx_add_notification_settings.py`
+5. 검증: `alembic upgrade head` 실행
+6. Task 상태 업데이트: ⬜ → ✅
+
+### Phase 실행
+
+```
+/vibe.run --phase 1
+```
+
+**동작:**
+- Phase 1의 9개 Task 순차 실행
+- Task 1-1 → 1-2 → ... → 1-9 (Contract Provider 포함)
+- 각 Task마다 의존성 확인 후 실행
+
+### 전체 실행
+
+```
+/vibe.run --all
+```
+
+**동작:**
+- 의존성 그래프에 따라 23개 Task 순차 실행
+- Phase 1 (9개) → Phase 2 (9개) → Phase 3 (5개)
+- BDD/Contract Testing 포함
+- 예상 시간: 28시간
+
+## Verification
+
+각 Task 완료 후:
+- [ ] Acceptance Criteria 모두 통과
+- [ ] 검증 명령어 실행 성공
+- [ ] 코드 품질 기준 충족 (TRUST 5)
+- [ ] TASKS 문서 상태 업데이트
+
+## Error Handling
+
+Task 실행 실패 시:
+1. 에러 메시지 확인
+2. 구현 가이드 재검토
+3. 코드 수정 후 재시도
+4. 여전히 실패 시 사용자에게 보고
+
+## Next Step
+
+Task 완료 후:
+- 의존성 그래프 확인
+- 다음 Task 실행 또는 Phase 완료 확인
+- 모든 Task 완료 시:
+  ```
+  /vibe.verify "푸시 알림 설정 기능"
+  ```