moai-adk 0.3.13__py3-none-any.whl → 0.4.0__py3-none-any.whl

moai_adk/templates/.claude/agents/alfred/cc-manager.md

@@ -222,6 +222,258 @@ Brief description of agent's expertise and purpose.
 - `!command`: Bash 명령어 실행
 - `@file.txt`: 파일 내용 참조
 
+## 🎓 Skills 시스템 (재사용 가능한 기능 블록)
+
+**Skills**는 특정 작업에 대한 재사용 가능한 지식과 실행 패턴을 캡슐화한 기능 블록입니다.
+
+### Skills vs Agents vs Commands 비교
+
+| 항목 | Skills | Agents | Commands |
+|------|--------|--------|----------|
+| **목적** | 재사용 가능한 작업 패턴 | 독립 컨텍스트 전문가 | 워크플로우 오케스트레이션 |
+| **실행 방식** | 메인 세션 내 통합 | 별도 서브에이전트 세션 | 슬래시 커맨드 |
+| **컨텍스트** | 메인 세션 공유 | 독립 컨텍스트 | 메인 세션 공유 |
+| **사용 예** | SQL 쿼리, API 호출 패턴 | 복잡한 분석, 검증 | 다단계 파이프라인 |
+
+### Skills 파일 표준 구조
+
+**파일 위치**: `.claude/skills/`
+
+```markdown
+---
+name: skill-name
+description: Clear description of what this skill provides
+model: haiku
+---
+
+# Skill Name
+
+Detailed explanation of the skill's purpose and capabilities.
+
+## Usage Pattern
+
+- When to use this skill
+- Prerequisites
+- Expected inputs
+
+## Examples
+
+```language
+# Example usage
+code example here
+```
+
+## Best Practices
+
+- Dos and don'ts
+- Common pitfalls
+- Optimization tips
+```
+
+**필수 YAML 필드**:
+
+- `name`: 스킬 이름 (kebab-case)
+- `description`: 명확한 한 줄 설명
+- `model`: AI 모델 지정 (haiku/sonnet/opus)
+
+### Skills 활용 가이드
+
+**언제 Skills를 사용하는가?**
+
+- ✅ 반복적인 작업 패턴 (SQL 쿼리 작성, API 호출 템플릿)
+- ✅ 도메인 지식 공유 (프로젝트별 코딩 컨벤션, 특정 프레임워크 사용법)
+- ✅ 메인 세션과 컨텍스트 공유가 필요할 때
+- ❌ 복잡한 다단계 워크플로우 (→ Commands 사용)
+- ❌ 독립적인 분석/검증 (→ Agents 사용)
+
+**MoAI-ADK와의 통합 예시**:
+
+```markdown
+# .claude/skills/ears-pattern.md
+---
+name: ears-pattern
+description: EARS 방식 요구사항 작성 패턴 가이드
+model: haiku
+---
+
+# EARS Requirements Pattern
+
+MoAI-ADK의 SPEC 작성 시 사용하는 EARS 패턴 적용 가이드.
+
+## 5가지 EARS 구문
+
+1. **Ubiquitous**: 시스템은 [기능]을 제공해야 한다
+2. **Event-driven**: WHEN [조건]이면, 시스템은 [동작]해야 한다
+3. **State-driven**: WHILE [상태]일 때, 시스템은 [동작]해야 한다
+4. **Optional**: WHERE [조건]이면, 시스템은 [동작]할 수 있다
+5. **Constraints**: IF [조건]이면, 시스템은 [제약]해야 한다
+
+## Usage
+
+SPEC 작성 시 이 패턴을 참조하여 요구사항을 구조화합니다.
+```
+
+### Skills 우선순위 규칙
+
+1. **Project-level**: `.claude/skills/` (프로젝트별 특화)
+2. **User-level**: `~/.claude/skills/` (개인 전역 설정)
+3. **Marketplace**: 공개 마켓플레이스 스킬
+
+프로젝트 레벨이 사용자 레벨보다 우선순위가 높습니다.
+
+## 🔌 Plugins 시스템 (외부 도구 통합)
+
+**Plugins**는 Claude Code를 외부 서비스, API, 도구와 통합하는 확장 메커니즘입니다.
+
+### Plugins 핵심 개념
+
+**Plugin의 역할**:
+
+- **외부 API 통합**: GitHub, Linear, Jira, Slack 등 외부 서비스 연동
+- **도구 확장**: MCP (Model Context Protocol) 서버를 통한 도구 추가
+- **워크플로우 자동화**: 외부 시스템과의 데이터 교환 자동화
+
+**MCP (Model Context Protocol)**:
+
+- Claude Code가 외부 도구와 통신하는 표준 프로토콜
+- JSON-RPC 기반 통신
+- Resources, Prompts, Tools 제공
+
+### Plugin 설치 및 사용
+
+**설치 위치**:
+
+```bash
+# 프로젝트 레벨 (권장)
+.claude/plugins/
+
+# 사용자 레벨
+~/.claude/plugins/
+```
+
+**설정 파일** (`.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
+    }
+  }
+}
+```
+
+### MoAI-ADK와 Plugins 통합
+
+**권장 Plugin 구성**:
+
+| Plugin | 용도 | MoAI-ADK 연동 |
+|--------|------|--------------|
+| **GitHub MCP** | PR/Issue 관리 | `/alfred:3-sync`에서 PR 자동 생성 |
+| **Filesystem MCP** | 파일 시스템 접근 | `.moai/` 디렉토리 안전한 접근 |
+| **Brave Search MCP** | 웹 검색 | 기술 문서 참조 시 자동 검색 |
+
+**MoAI-ADK 최적화 설정 예시**:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    },
+    "moai-filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "${CLAUDE_PROJECT_DIR}/.moai",
+        "${CLAUDE_PROJECT_DIR}/src",
+        "${CLAUDE_PROJECT_DIR}/tests"
+      ]
+    }
+  }
+}
+```
+
+### Plugin 보안 원칙
+
+- **환경변수 사용**: API 토큰은 절대 하드코딩하지 않고 환경변수로 관리
+- **경로 제한**: Filesystem MCP는 허용된 디렉토리만 명시
+- **최소 권한**: 필요한 Plugin만 활성화
+- **민감 정보 차단**: `.env`, `secrets/` 등 접근 금지
+
+## 🏪 Plugin Marketplaces
+
+**공식 Plugin 저장소**:
+
+1. **Anthropic MCP Servers**: https://github.com/modelcontextprotocol/servers
+2. **Community Plugins**: https://glama.ai/mcp/servers
+
+### 추천 Plugin 목록 (MoAI-ADK 관점)
+
+| Plugin | 설명 | MoAI-ADK 활용 |
+|--------|------|--------------|
+| **@modelcontextprotocol/server-github** | GitHub API 통합 | PR/Issue 자동 생성, 코드 리뷰 |
+| **@modelcontextprotocol/server-filesystem** | 안전한 파일 시스템 접근 | `.moai/` 구조화된 읽기/쓰기 |
+| **@modelcontextprotocol/server-brave-search** | 웹 검색 | 기술 문서 참조 검색 |
+| **@modelcontextprotocol/server-sqlite** | SQLite DB 접근 | 프로젝트 메타데이터 저장 |
+
+### Plugin 설치 가이드
+
+**1. npm을 통한 설치**:
+
+```bash
+# GitHub Plugin 설치 예시
+npx @modelcontextprotocol/server-github
+```
+
+**2. settings.json에 등록**:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+**3. 환경변수 설정**:
+
+```bash
+# .bashrc 또는 .zshrc
+export GITHUB_TOKEN="your_github_token_here"
+```
+
+**4. Claude Code 재시작**:
+
+Plugin이 활성화되려면 Claude Code를 재시작해야 합니다.
+
+### Plugin 검증 체크리스트
+
+- [ ] Plugin 출처 신뢰성 확인 (공식 또는 검증된 커뮤니티)
+- [ ] 필요한 환경변수 설정 완료
+- [ ] settings.json 구문 오류 없음
+- [ ] 파일 시스템 접근 경로 제한 확인
+- [ ] API 토큰 보안 관리 (환경변수 사용)
+
 ## ⚙️ Claude Code 권한 설정 최적화
 
 ### 권장 권한 구성 (.claude/settings.json)
@@ -345,12 +597,30 @@ Brief description of agent's expertise and purpose.
 - [ ] 도구 권한 최소화 원칙 적용
 - [ ] 에이전트명 kebab-case 준수
 
+### Skills 파일 검증
+
+- [ ] YAML frontmatter 존재 및 유효성
+- [ ] `name`, `description`, `model` 필드 완전성
+- [ ] 스킬명 kebab-case 준수
+- [ ] Usage Pattern 섹션 포함
+- [ ] Examples 섹션에 구체적 예시 포함
+- [ ] Best Practices 섹션 포함
+
+### Plugins 설정 검증
+
+- [ ] settings.json의 mcpServers 섹션 구문 오류 없음
+- [ ] 각 Plugin의 command, args 필드 완전성
+- [ ] 환경변수 사용 (API 토큰 하드코딩 금지)
+- [ ] Filesystem MCP 경로 제한 확인
+- [ ] Plugin 출처 신뢰성 확인 (공식/검증된 커뮤니티)
+
 ### 설정 파일 검증
 
 - [ ] settings.json 구문 오류 없음
 - [ ] 필수 권한 설정 완전성
 - [ ] 보안 정책 준수 (민감 파일 차단)
 - [ ] 훅 설정 유효성
+- [ ] mcpServers 설정 유효성 (Plugins 사용 시)
 
 ## 🛠️ 파일 생성/수정 가이드라인
 
@@ -371,6 +641,51 @@ Brief description of agent's expertise and purpose.
 5. 다른 에이전트와의 협업 규칙 설정
 6. 표준 검증 통과 확인
 
+### 새 Skill 생성 절차
+
+1. **재사용 가능성 확인**: 반복적 패턴인지 확인
+2. **표준 템플릿 적용**: `.claude/skills/` 위치에 생성
+3. **필수 섹션 포함**:
+   - Usage Pattern (사용 시점 명시)
+   - Examples (구체적 코드 예시)
+   - Best Practices (권장사항/주의사항)
+4. **모델 선택**: haiku (일반), sonnet (복잡한 판단)
+5. **검증**: YAML frontmatter 완전성 확인
+
+**Skill 생성 예시**:
+
+```bash
+@agent-cc-manager "EARS 패턴 작성 가이드를 Skill로 생성해주세요"
+```
+
+### 새 Plugin 설정 절차
+
+1. **Plugin 출처 확인**: 공식 또는 검증된 커뮤니티인지 확인
+2. **필요성 검증**: 외부 시스템 통합이 실제로 필요한지 확인
+3. **settings.json 업데이트**:
+   ```json
+   {
+     "mcpServers": {
+       "plugin-name": {
+         "command": "npx",
+         "args": ["-y", "@modelcontextprotocol/server-name"],
+         "env": {
+           "API_TOKEN": "${API_TOKEN}"
+         }
+       }
+     }
+   }
+   ```
+4. **환경변수 설정**: API 토큰 등 환경변수로 관리
+5. **경로 제한 확인**: Filesystem MCP 사용 시 허용 경로 명시
+6. **테스트**: Claude Code 재시작 후 동작 확인
+
+**Plugin 설정 예시**:
+
+```bash
+@agent-cc-manager "GitHub MCP Plugin 설정을 추가해주세요"
+```
+
 ### 기존 파일 수정 절차
 
 1. 현재 표준 준수도 확인
@@ -404,6 +719,82 @@ Brief description of agent's expertise and purpose.
 2. 필수 필드 누락 확인
 3. 파일 경로 및 이름 확인
 
+### Skill 인식 실패
+
+**증상**: Skill이 로드되지 않거나 사용할 수 없음
+**해결**:
+
+1. `.claude/skills/` 디렉토리 경로 확인
+2. YAML frontmatter 구문 오류 확인 (name, description, model)
+3. 파일명이 kebab-case인지 확인
+4. Claude Code 재시작
+
+**검증 명령어**:
+
+```bash
+# Skills 디렉토리 확인
+ls -la .claude/skills/
+
+# YAML frontmatter 검증
+head -10 .claude/skills/your-skill.md
+```
+
+### Plugin 연결 실패
+
+**증상**: MCP Plugin이 작동하지 않음
+**해결**:
+
+1. **settings.json 구문 확인**:
+   ```bash
+   # JSON 유효성 검증
+   cat .claude/settings.json | jq .
+   ```
+
+2. **환경변수 확인**:
+   ```bash
+   # API 토큰 설정 여부 확인
+   echo $GITHUB_TOKEN
+   echo $ANTHROPIC_API_KEY
+   ```
+
+3. **Plugin 설치 확인**:
+   ```bash
+   # MCP Server 설치 테스트
+   npx @modelcontextprotocol/server-github --version
+   ```
+
+4. **Claude Code 로그 확인**:
+   - 메뉴 → View → Toggle Developer Tools
+   - Console 탭에서 MCP 관련 오류 확인
+
+5. **Claude Code 재시작**: Plugin 변경 후 반드시 재시작
+
+### Filesystem MCP 권한 오류
+
+**증상**: Filesystem MCP가 특정 디렉토리에 접근할 수 없음
+**해결**:
+
+1. **허용 경로 확인**:
+   ```json
+   {
+     "mcpServers": {
+       "moai-fs": {
+         "args": [
+           "-y",
+           "@modelcontextprotocol/server-filesystem",
+           "${CLAUDE_PROJECT_DIR}/.moai",  // ✅ 허용
+           "${CLAUDE_PROJECT_DIR}/src",     // ✅ 허용
+           "/unauthorized/path"              // ❌ 차단됨
+         ]
+       }
+     }
+   }
+   ```
+
+2. **환경변수 확장 확인**: `${CLAUDE_PROJECT_DIR}` 제대로 확장되는지 확인
+
+3. **절대 경로 사용**: 상대 경로 대신 절대 경로 권장
+
 ### 성능 저하
 
 **증상**: Claude Code 응답이 느림
@@ -412,6 +803,8 @@ Brief description of agent's expertise and purpose.
 1. 불필요한 도구 권한 제거
 2. 복잡한 훅 로직 최적화
 3. 메모리 파일 크기 확인
+4. **과도한 Plugin 사용 확인**: 필요한 Plugin만 활성화
+5. **Skill 파일 크기 확인**: Skills는 간결하게 유지 (≤200 LOC)
 
 ## 📋 MoAI-ADK 특화 워크플로우
 
@@ -429,6 +822,97 @@ Brief description of agent's expertise and purpose.
 - **독립 실행**: 에이전트 간 직접 호출 금지
 - **명확한 핸드오프**: 작업 완료 시 다음 단계 안내
 
+### Skills & Plugins 활용 전략
+
+**MoAI-ADK 권장 구성**:
+
+#### 1. Skills (도메인 지식 공유)
+
+| Skill | 목적 | 사용 시점 |
+|-------|------|----------|
+| **ears-pattern** | EARS 요구사항 작성 패턴 | `/alfred:1-spec` 실행 시 |
+| **tag-syntax** | @TAG 작성 규칙 | 코드 작성 시 |
+| **trust-checklist** | TRUST 5원칙 검증 | `/alfred:2-build` 완료 전 |
+| **git-convention** | Git 커밋 메시지 표준 | Git 작업 시 |
+
+**Skills 생성 예시**:
+
+```bash
+# .claude/skills/tag-syntax.md 생성
+@agent-cc-manager "TAG 작성 규칙을 Skill로 생성해주세요"
+```
+
+#### 2. Plugins (외부 도구 통합)
+
+| Plugin | 목적 | MoAI-ADK 워크플로우 연동 |
+|--------|------|------------------------|
+| **GitHub MCP** | PR/Issue 자동화 | `/alfred:3-sync`에서 PR 생성 |
+| **Filesystem MCP** | 구조화된 파일 접근 | `.moai/` 안전한 읽기/쓰기 |
+| **SQLite MCP** | 메타데이터 저장 | SPEC 진행 상태 추적 |
+
+**Plugin 설정 예시** (`.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    },
+    "moai-fs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "${CLAUDE_PROJECT_DIR}/.moai",
+        "${CLAUDE_PROJECT_DIR}/src",
+        "${CLAUDE_PROJECT_DIR}/tests",
+        "${CLAUDE_PROJECT_DIR}/docs"
+      ]
+    }
+  }
+}
+```
+
+#### 3. Skills vs Agents vs Commands vs Plugins 통합 결정 트리
+
+```
+작업 분류
+    ↓
+┌───────────────────────────────────────┐
+│ 외부 시스템 통합이 필요한가?          │
+│ (GitHub API, 파일 시스템 등)          │
+└───────────────────────────────────────┘
+    ↓ YES                          ↓ NO
+┌──────────┐               ┌────────────────────┐
+│ Plugins  │               │ 재사용 가능한 지식인가? │
+└──────────┘               │ (패턴, 컨벤션)      │
+                           └────────────────────┘
+                               ↓ YES          ↓ NO
+                           ┌─────────┐   ┌───────────────┐
+                           │ Skills  │   │ 독립 컨텍스트가 │
+                           └─────────┘   │ 필요한가?      │
+                                         └───────────────┘
+                                             ↓ YES      ↓ NO
+                                         ┌─────────┐ ┌──────────┐
+                                         │ Agents  │ │ Commands │
+                                         └─────────┘ └──────────┘
+```
+
+**실무 예시**:
+
+- **Q**: "EARS 패턴을 어디에 저장?"
+  - **A**: Skills (`.claude/skills/ears-pattern.md`)
+- **Q**: "GitHub PR 생성을 어디에 구현?"
+  - **A**: Plugins (GitHub MCP) + Commands (`/alfred:3-sync`)
+- **Q**: "SPEC 메타데이터 검증을 어디에?"
+  - **A**: Agents (`@agent-spec-builder`)
+- **Q**: "TDD 워크플로우를 어디에?"
+  - **A**: Commands (`/alfred:2-build`)
+
 ### TRUST 원칙 통합
 
 @.moai/memory/development-guide.md 기준 적용
@@ -459,16 +943,87 @@ Brief description of agent's expertise and purpose.
 
 ### cc-manager 직접 호출
 
-```
+**기본 사용**:
+
+```bash
+# 에이전트 생성
 @agent-cc-manager "새 에이전트 생성: data-processor"
+
+# 커맨드 생성
+@agent-cc-manager "새 커맨드 생성: /alfred:4-deploy"
+
+# Skill 생성
+@agent-cc-manager "EARS 패턴 작성 가이드를 Skill로 생성해주세요"
+
+# Plugin 설정
+@agent-cc-manager "GitHub MCP Plugin 설정을 추가해주세요"
+
+# 표준 검증
 @agent-cc-manager "커맨드 파일 표준화 검증"
 @agent-cc-manager "설정 최적화"
 ```
 
+**Skills & Plugins 관리**:
+
+```bash
+# Skill 검증
+@agent-cc-manager ".claude/skills/ 디렉토리의 모든 Skill 검증해주세요"
+
+# Plugin 설정 검증
+@agent-cc-manager "settings.json의 mcpServers 설정 검증해주세요"
+
+# MoAI-ADK 최적 설정 제안
+@agent-cc-manager "MoAI-ADK에 최적화된 Skills와 Plugins 구성을 제안해주세요"
+```
+
+**통합 워크플로우**:
+
+```bash
+# 1. 프로젝트 초기 설정
+@agent-cc-manager "MoAI-ADK 프로젝트 초기 설정 (Skills + Plugins)"
+
+# 2. Skills 생성 (반복 패턴)
+@agent-cc-manager "다음 패턴을 Skill로 생성:
+- EARS 요구사항 작성
+- TAG 작성 규칙
+- TRUST 체크리스트"
+
+# 3. Plugins 설정 (외부 통합)
+@agent-cc-manager "다음 Plugins 설정:
+- GitHub MCP (PR 자동화)
+- Filesystem MCP (.moai/ 접근)
+- Brave Search MCP (문서 검색)"
+```
+
 ### 자동 실행 조건
 
 - MoAI-ADK 프로젝트에서 세션 시작 시
-- 커맨드/에이전트 파일 관련 작업 시
+- 커맨드/에이전트/Skill 파일 관련 작업 시
+- Plugin 설정 변경 시
 - 표준 검증이 필요한 경우
 
-이 cc-manager는 Claude Code 공식 문서의 모든 핵심 내용을 통합하여 외부 참조 없이도 완전한 지침을 제공합니다. 중구난방의 지침으로 인한 오류를 방지하고 일관된 표준을 유지합니다.
+### 베스트 프랙티스
+
+**1. Skills 우선 고려**:
+
+- 반복적 패턴은 먼저 Skill로 생성
+- 예: EARS 패턴, TAG 규칙, Git 컨벤션
+
+**2. Plugins는 필요시만**:
+
+- 외부 시스템 통합이 명확할 때만 추가
+- 불필요한 Plugin은 성능 저하 원인
+
+**3. 점진적 확장**:
+
+- 커맨드 → 에이전트 → Skills → Plugins 순으로 확장
+- 각 단계의 필요성을 검증 후 진행
+
+**4. 표준 준수 검증**:
+
+- 주기적으로 `@agent-cc-manager "전체 표준 검증"` 실행
+- CI/CD에 표준 검증 통합 권장
+
+---
+
+이 cc-manager는 Claude Code 공식 문서의 모든 핵심 내용(Agents, Commands, Skills, Plugins)을 통합하여 외부 참조 없이도 완전한 지침을 제공합니다. 중구난방의 지침으로 인한 오류를 방지하고 일관된 표준을 유지합니다.