@kood/claude-code 0.6.7 → 0.7.1

package/templates/.claude/instructions/agent-patterns/agent-teams-usage.md

@@ -0,0 +1,376 @@
+# Agent Teams 활용 가이드
+
+> 스킬에서 Agent Teams를 효과적으로 활용하는 방법
+
+---
+
+<availability_check>
+
+## 환경 확인
+
+### 스크립트 사용
+
+```bash
+# Agent Teams 사용 가능 여부 확인
+.claude/scripts/agent-teams/check-availability.sh
+
+# tmux 환경 세팅
+.claude/scripts/agent-teams/setup-tmux.sh
+```
+
+### 프로그래매틱 확인
+
+```bash
+# 1. 환경변수 확인
+if [[ "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" == "1" ]]; then
+    AGENT_TEAMS_AVAILABLE=true
+fi
+
+# 2. settings.json 확인 (글로벌 + 프로젝트)
+for f in ~/.claude/settings.json .claude/settings.json; do
+    if grep -q '"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS".*"1"' "$f" 2>/dev/null; then
+        AGENT_TEAMS_AVAILABLE=true
+    fi
+done
+
+# 3. 에이전트 디렉토리 확인
+if [[ -d ".claude/agents" ]] && [[ $(ls .claude/agents/*.md 2>/dev/null | wc -l) -gt 0 ]]; then
+    AGENTS_AVAILABLE=true
+fi
+```
+
+</availability_check>
+
+---
+
+<subagent_vs_teams>
+
+## Subagent vs Agent Teams
+
+| 항목 | Subagents | Agent Teams |
+|------|-----------|-------------|
+| **컨텍스트** | 자체 컨텍스트, 결과만 반환 | 자체 컨텍스트, 완전 독립 |
+| **통신** | 메인 에이전트에게만 보고 | 팀원끼리 직접 메시징 |
+| **조율** | 메인 에이전트가 모든 작업 관리 | 공유 태스크 리스트로 자기조율 |
+| **토큰 비용** | 낮음 (결과 요약) | 높음 (각 팀원 별도 인스턴스) |
+| **적합** | 결과만 필요한 집중 작업 | 토론과 협업이 필요한 복잡한 작업 |
+
+### 선택 기준
+
+| 상황 | 권장 |
+|------|------|
+| 결과만 필요, 집중된 작업 | Subagent |
+| 조율/토론/독립적 결정 필요 | Agent Teams |
+| 토큰 비용 민감 | Subagent 또는 단독 세션 |
+| 병렬 연구/리뷰 | Agent Teams |
+| 단순 작업 (1-2 파일) | 직접 처리 |
+
+</subagent_vs_teams>
+
+---
+
+<decision_matrix>
+
+## 사용 결정 매트릭스
+
+| 조건 | 권장 방식 | 이유 |
+|------|----------|------|
+| Agent Teams 비활성화 | Task (subagent) | 환경 미지원 |
+| 단순 작업 (1-2 파일) | 직접 처리 | 오버헤드 불필요 |
+| 독립적 병렬 작업 | Agent Teams | 진정한 병렬 실행 |
+| 팀원 간 소통 필요 | Agent Teams | 메시지 교환 가능 |
+| 순차 의존성 있음 | blockedBy 또는 Subagent | 의존성 관리 |
+| tmux/iTerm2 환경 | split-pane 모드 | 시각적 모니터링 |
+| VS Code/일반 터미널 | in-process 모드 | 호환성 |
+
+</decision_matrix>
+
+---
+
+<teammate_modes>
+
+## teammateMode 설정
+
+### 모드별 특징
+
+| 모드 | 특징 | 권장 상황 |
+|------|------|----------|
+| **auto** | tmux 세션이면 split-pane, 아니면 in-process | 기본값 |
+| **tmux** | 각 팀원 별도 pane (tmux/iTerm2 필요) | 3명+ 팀 |
+| **in-process** | 단일 터미널, Shift+Up/Down 전환 | 2명 이하 팀, VS Code |
+
+### 설정 방법
+
+```json
+// ~/.claude/settings.json
+{
+  "teammateMode": "auto",
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+### tmux 세션 시작
+
+```bash
+# 새 tmux 세션
+tmux new -s claude
+
+# iTerm2 (macOS)
+tmux -CC
+```
+
+### 터미널 지원 현황
+
+| 터미널 | Split Panes |
+|--------|-------------|
+| tmux | ✅ |
+| iTerm2 | ✅ |
+| WezTerm | ❌ (요청 중) |
+| Zellij | ❌ (요청 중) |
+| VS Code | ❌ |
+| Windows Terminal | ❌ |
+| Ghostty | ❌ |
+
+</teammate_modes>
+
+---
+
+<usage_patterns>
+
+## 활용 패턴
+
+### 패턴 1: 환경 감지 후 분기
+
+```typescript
+if (AGENT_TEAMS_AVAILABLE && 복잡한_병렬_작업) {
+    TeamCreate({ team_name: "feature-x", description: "..." })
+    Task({ subagent_type: "...", team_name: "feature-x", name: "worker-1" })
+    Task({ subagent_type: "...", team_name: "feature-x", name: "worker-2" })
+} else {
+    // Subagent 폴백
+    Task({ subagent_type: "...", ... })
+}
+```
+
+### 패턴 2: 팀 생성 + 태스크 분배
+
+```typescript
+// 1. 팀 생성
+TeamCreate({ team_name: "review-team", description: "코드 리뷰" })
+
+// 2. 태스크 생성
+TaskCreate({ subject: "보안 검토", description: "...", activeForm: "보안 검토 중" })
+TaskCreate({ subject: "성능 검토", description: "...", activeForm: "성능 검토 중" })
+
+// 3. 팀원 스폰 (병렬)
+Task({ subagent_type: "security-reviewer", team_name: "review-team", name: "security" })
+Task({ subagent_type: "code-reviewer", team_name: "review-team", name: "performance" })
+
+// 4. 완료 대기 후 종합
+TaskList()
+```
+
+### 패턴 3: Plan-First (비용 최적화)
+
+```typescript
+// Phase 1: 계획 (저렴)
+EnterPlanMode()
+// 코드베이스 탐색 + 구현 계획 수립
+
+// Phase 2: 실행 (고비용, 고속)
+TeamCreate({ team_name: "impl-team" })
+// 승인된 계획을 팀에 전달하여 병렬 실행
+```
+
+</usage_patterns>
+
+---
+
+<send_message>
+
+## SendMessage 사용법
+
+### 메시지 타입
+
+| 타입 | 용도 |
+|------|------|
+| **message** | 특정 팀원에게 DM |
+| **broadcast** | 모든 팀원에게 전송 (비용 높음) |
+| **shutdown_request** | 팀원에게 종료 요청 |
+| **shutdown_response** | 종료 요청에 응답 |
+| **plan_approval_response** | 계획 승인/거부 |
+
+### 사용 예시
+
+```json
+// DM
+{ "type": "message", "recipient": "researcher",
+  "content": "...", "summary": "Brief status" }
+
+// 브로드캐스트 (신중히!)
+{ "type": "broadcast", "content": "...", "summary": "Critical" }
+
+// 종료 요청
+{ "type": "shutdown_request", "recipient": "researcher", "content": "완료" }
+
+// 종료 응답
+{ "type": "shutdown_response", "request_id": "abc-123", "approve": true }
+```
+
+**중요**: 텍스트 출력은 팀원에게 보이지 않음. 반드시 SendMessage 사용.
+
+</send_message>
+
+---
+
+<keyboard_shortcuts>
+
+## 키보드 단축키 (in-process)
+
+| 단축키 | 기능 |
+|--------|------|
+| `Shift+Up/Down` | 팀원 선택 |
+| `Enter` | 선택된 팀원 세션 보기 |
+| `Escape` | 현재 턴 중단 |
+| `Ctrl+T` | 태스크 목록 토글 |
+| `Shift+Tab` | Delegate mode 전환 |
+
+</keyboard_shortcuts>
+
+---
+
+<best_practices>
+
+## 베스트 프랙티스
+
+| 원칙 | 설명 |
+|------|------|
+| **환경 감지 우선** | Agent Teams 사용 전 항상 가용성 확인 |
+| **폴백 준비** | Subagent 방식으로 폴백 로직 구현 |
+| **풍부한 컨텍스트** | 팀원은 Lead 대화 기록 미상속. spawn 시 상세 프롬프트 필수 |
+| **적절한 태스크 크기** | 팀원당 5-6개 태스크 권장 |
+| **파일 충돌 방지** | 한 파일은 한 팀원만 수정 |
+| **모델 라우팅** | Lead: Opus, Teammates: Sonnet |
+| **팀 정리** | 작업 완료 후 shutdown → TeamDelete |
+| **Delegate Mode** | Lead가 직접 구현 방지, 조율에 집중 |
+| **Plan Approval** | 위험한 작업 전 계획 승인 요구 |
+
+### Context 제공 예시
+
+```
+❌ "인증 모듈 검토해"
+✅ "src/auth/ 인증 모듈을 보안 취약점 관점으로 검토해.
+   토큰 핸들링, 세션 관리, 입력 검증에 집중해.
+   JWT 토큰을 httpOnly 쿠키에 저장함."
+```
+
+</best_practices>
+
+---
+
+<common_mistakes>
+
+## 흔한 실수와 해결책
+
+| 문제 | 원인 | 해결책 |
+|------|------|--------|
+| Lead가 직접 구현 | 위임 대신 본인이 작업 | `Shift+Tab` delegate mode |
+| 팀원 안 보임 | in-process 전환 안 함 | `Shift+Down` 팀원 순환 |
+| 과도한 권한 프롬프트 | 매번 승인 요청 | permission settings 사전 승인 |
+| 팀원 에러 정지 | 예외 처리 실패 | 추가 지시 또는 대체 팀원 spawn |
+| Lead 조기 종료 | 팀원 완료 전 마무리 | "모든 팀원 완료까지 대기" 명시 |
+| 고아 tmux 세션 | 정리 안 됨 | `tmux ls` → `tmux kill-session` |
+| 4+ 팀원 동시 spawn | tmux race condition | 2-3개씩 순차 spawn |
+
+</common_mistakes>
+
+---
+
+<limitations>
+
+## 제한사항 및 주의사항
+
+### 아키텍처 제한
+
+| 제한 | 설명 |
+|------|------|
+| 세션 재개 불가 | `/resume` 시 in-process 팀원 복원 안 됨 |
+| 세션당 한 팀 | 중첩 팀 불가 |
+| 리더십 고정 | 팀 생성 세션이 전체 수명 동안 리더 |
+| 권한 상속 | 팀원별 개별 권한 설정 불가 |
+| 종료 지연 | 현재 작업 완료까지 대기 |
+| Working Dir 공유 | 팀원에 다른 repo 할당 불가 |
+
+### 알려진 버그
+
+| 버그 | 영향 | 워크어라운드 |
+|------|------|-------------|
+| 컨텍스트 압축 시 팀 손실 | Lead가 팀 인식 상실 | 200K 토큰 전 작업 완료 |
+| tmux split-pane race | `send-keys` corruption | 2-3개씩 순차 spawn |
+| PermissionRequest hook 미작동 | 서브에이전트 권한 hook 무시 | 사전 승인 또는 수동 확인 |
+| TaskUpdate 상태 비동기 | TeamDelete 후 상태 손실 | TeamDelete 후 재확인 |
+
+</limitations>
+
+---
+
+<cost_optimization>
+
+## 비용 최적화
+
+### 토큰 비용 구조
+
+- 솔로 세션: ~200k tokens
+- 3인 팀: ~800k tokens (4x)
+- 각 팀원 별도 컨텍스트 윈도우
+
+### 비용 절감 팁
+
+| 전략 | 효과 |
+|------|------|
+| 모델 혼합 (Opus Lead + Sonnet Teammates) | ~40% 절감 |
+| Plan-First 패턴 | 계획에서 실패 조기 발견 |
+| 적절한 범위 지정 | 과도한 탐색 방지 |
+| 단순 작업은 단독 세션 | 조율 오버헤드 제거 |
+
+</cost_optimization>
+
+---
+
+<ideal_use_cases>
+
+## 이상적인 사용 사례
+
+| 패턴 | 설명 |
+|------|------|
+| **경쟁 가설 디버깅** | 여러 버그 원인 병렬 검증 |
+| **다각도 코드 리뷰** | 보안/성능/테스트 동시 검토 |
+| **Cross-Layer 개발** | 프론트엔드/백엔드/테스트 분리 |
+| **연구 및 탐색** | 여러 접근법 병렬 탐색 |
+| **QA Swarm** | 다양한 품질 관점 동시 테스트 |
+
+### 부적합한 경우
+
+- 순차 작업
+- 같은 파일 편집
+- 의존성 많은 작업
+- 단순 단일 파일 수정
+
+</ideal_use_cases>
+
+---
+
+<reference>
+
+## 참조
+
+| 문서 | 경로 |
+|------|------|
+| 공식 문서 | https://code.claude.com/docs/en/agent-teams |
+| 환경 확인 스크립트 | `.claude/scripts/agent-teams/check-availability.sh` |
+| tmux 세팅 스크립트 | `.claude/scripts/agent-teams/setup-tmux.sh` |
+| agent-teams-setup 스킬 | `.claude/skills/agent-teams-setup/SKILL.md` |
+
+</reference>

package/templates/.claude/scripts/agent-teams/check-availability.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# Agent Teams 사용 가능 여부 확인
+# Usage: .claude/scripts/agent-teams/check-availability.sh
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=== Agent Teams Availability Check ===${NC}"
+echo ""
+
+PASSED=0
+FAILED=0
+WARNINGS=0
+
+# 1. 환경변수 / settings.json 확인
+echo -e "${BLUE}[1/5] Agent Teams 활성화 확인${NC}"
+
+AGENT_TEAMS_ENABLED=false
+ENABLED_SOURCE=""
+
+# 환경변수 확인
+if [[ "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" == "1" ]]; then
+    AGENT_TEAMS_ENABLED=true
+    ENABLED_SOURCE="환경변수"
+fi
+
+# 글로벌 settings.json 확인 (~/.claude/settings.json)
+GLOBAL_SETTINGS="$HOME/.claude/settings.json"
+if [[ -f "$GLOBAL_SETTINGS" ]] && grep -q '"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS".*"1"' "$GLOBAL_SETTINGS" 2>/dev/null; then
+    AGENT_TEAMS_ENABLED=true
+    if [[ -n "$ENABLED_SOURCE" ]]; then
+        ENABLED_SOURCE="$ENABLED_SOURCE + ~/.claude/settings.json"
+    else
+        ENABLED_SOURCE="~/.claude/settings.json"
+    fi
+fi
+
+# 프로젝트 settings.json 확인 (.claude/settings.json)
+PROJECT_SETTINGS=".claude/settings.json"
+if [[ -f "$PROJECT_SETTINGS" ]] && grep -q '"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS".*"1"' "$PROJECT_SETTINGS" 2>/dev/null; then
+    AGENT_TEAMS_ENABLED=true
+    if [[ -n "$ENABLED_SOURCE" ]]; then
+        ENABLED_SOURCE="$ENABLED_SOURCE + .claude/settings.json"
+    else
+        ENABLED_SOURCE=".claude/settings.json"
+    fi
+fi
+
+if [[ "$AGENT_TEAMS_ENABLED" == "true" ]]; then
+    echo -e "  ${GREEN}✓${NC} Agent Teams 활성화됨 ($ENABLED_SOURCE)"
+    ((PASSED++))
+else
+    echo -e "  ${RED}✗${NC} Agent Teams 미활성화"
+    echo -e "    설정 방법 (하나 선택):"
+    echo -e "    1. 환경변수: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1"
+    echo -e "    2. ~/.claude/settings.json:"
+    echo -e '       { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }'
+    echo -e "    3. .claude/settings.json (프로젝트):"
+    echo -e '       { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }'
+    ((FAILED++))
+fi
+
+# 2. .claude/agents/ 디렉토리 확인
+echo ""
+echo -e "${BLUE}[2/5] 에이전트 디렉토리 확인${NC}"
+AGENTS_DIR=".claude/agents"
+if [[ -d "$AGENTS_DIR" ]]; then
+    echo -e "  ${GREEN}✓${NC} $AGENTS_DIR 디렉토리 존재"
+    ((PASSED++))
+else
+    echo -e "  ${RED}✗${NC} $AGENTS_DIR 디렉토리 없음"
+    echo -e "    생성: mkdir -p $AGENTS_DIR"
+    ((FAILED++))
+fi
+
+# 3. 에이전트 파일 확인
+echo ""
+echo -e "${BLUE}[3/5] 에이전트 파일 확인${NC}"
+if [[ -d "$AGENTS_DIR" ]]; then
+    AGENT_COUNT=$(find "$AGENTS_DIR" -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
+    if [[ $AGENT_COUNT -gt 0 ]]; then
+        echo -e "  ${GREEN}✓${NC} $AGENT_COUNT개 에이전트 발견"
+
+        # 주요 에이전트 확인
+        CORE_AGENTS=("explore" "planner" "implementation-executor" "code-reviewer" "pm")
+        MISSING_CORE=()
+        for agent in "${CORE_AGENTS[@]}"; do
+            if [[ -f "$AGENTS_DIR/$agent.md" ]]; then
+                echo -e "    ${GREEN}✓${NC} $agent"
+            else
+                MISSING_CORE+=("$agent")
+            fi
+        done
+
+        if [[ ${#MISSING_CORE[@]} -gt 0 ]]; then
+            echo -e "    ${YELLOW}!${NC} 권장 에이전트 누락: ${MISSING_CORE[*]}"
+            ((WARNINGS++))
+        fi
+        ((PASSED++))
+    else
+        echo -e "  ${YELLOW}!${NC} 에이전트 파일 없음"
+        echo -e "    /agent-teams-setup 스킬로 기본 에이전트 생성 권장"
+        ((WARNINGS++))
+    fi
+else
+    echo -e "  ${YELLOW}!${NC} 디렉토리 없어 확인 불가"
+    ((WARNINGS++))
+fi
+
+# 4. Frontmatter 형식 검증
+echo ""
+echo -e "${BLUE}[4/5] Frontmatter 형식 검증${NC}"
+if [[ -d "$AGENTS_DIR" ]]; then
+    INVALID_FILES=()
+
+    for file in "$AGENTS_DIR"/*.md; do
+        [[ -f "$file" ]] || continue
+
+        # name 필드 확인
+        if ! grep -q "^name:" "$file" 2>/dev/null; then
+            INVALID_FILES+=("$(basename "$file"): name 필드 없음")
+            continue
+        fi
+
+        # description 필드 확인
+        if ! grep -q "^description:" "$file" 2>/dev/null; then
+            INVALID_FILES+=("$(basename "$file"): description 필드 없음")
+            continue
+        fi
+
+        # model 별칭 확인 (opus, sonnet, haiku만 허용)
+        if grep -q "^model:" "$file" 2>/dev/null; then
+            MODEL=$(grep "^model:" "$file" | head -1 | sed 's/model:[[:space:]]*//' | tr -d ' ')
+            if [[ ! "$MODEL" =~ ^(opus|sonnet|haiku|inherit)$ ]]; then
+                INVALID_FILES+=("$(basename "$file"): 잘못된 model ($MODEL)")
+            fi
+        fi
+    done
+
+    if [[ ${#INVALID_FILES[@]} -eq 0 ]]; then
+        echo -e "  ${GREEN}✓${NC} 모든 에이전트 frontmatter 유효"
+        ((PASSED++))
+    else
+        echo -e "  ${YELLOW}!${NC} 일부 에이전트 frontmatter 문제:"
+        for issue in "${INVALID_FILES[@]}"; do
+            echo -e "    - $issue"
+        done
+        ((WARNINGS++))
+    fi
+else
+    echo -e "  ${YELLOW}!${NC} 디렉토리 없어 검증 불가"
+    ((WARNINGS++))
+fi
+
+# 5. tmux 환경 확인 및 teammateMode 추천
+echo ""
+echo -e "${BLUE}[5/5] tmux 환경 확인${NC}"
+
+TMUX_AVAILABLE=false
+ITERM2_AVAILABLE=false
+RECOMMENDED_MODE="in-process"
+
+# tmux 설치 확인
+if command -v tmux &> /dev/null; then
+    TMUX_AVAILABLE=true
+    TMUX_VERSION=$(tmux -V 2>/dev/null | head -1)
+    echo -e "  ${GREEN}✓${NC} tmux 설치됨 ($TMUX_VERSION)"
+else
+    echo -e "  ${YELLOW}!${NC} tmux 미설치"
+    echo -e "    설치: brew install tmux (macOS) / apt install tmux (Linux)"
+fi
+
+# 현재 tmux 세션 내부인지 확인
+if [[ -n "$TMUX" ]]; then
+    echo -e "  ${GREEN}✓${NC} 현재 tmux 세션 내부"
+    RECOMMENDED_MODE="tmux"
+fi
+
+# iTerm2 확인 (macOS)
+if [[ "$TERM_PROGRAM" == "iTerm.app" ]]; then
+    ITERM2_AVAILABLE=true
+    echo -e "  ${GREEN}✓${NC} iTerm2 감지됨"
+
+    # it2 CLI 확인
+    if command -v it2 &> /dev/null; then
+        echo -e "  ${GREEN}✓${NC} it2 CLI 설치됨"
+        RECOMMENDED_MODE="tmux"
+    else
+        echo -e "  ${YELLOW}!${NC} it2 CLI 미설치"
+        echo -e "    설치: brew install mkusaka/it2/it2"
+    fi
+fi
+
+# teammateMode 설정 확인
+echo ""
+echo -e "  ${BLUE}권장 teammateMode:${NC} $RECOMMENDED_MODE"
+
+# settings.json에서 현재 teammateMode 확인
+CURRENT_MODE=""
+if [[ -f "$GLOBAL_SETTINGS" ]]; then
+    CURRENT_MODE=$(grep -o '"teammateMode"[[:space:]]*:[[:space:]]*"[^"]*"' "$GLOBAL_SETTINGS" 2>/dev/null | sed 's/.*: *"\([^"]*\)".*/\1/' || echo "")
+fi
+
+if [[ -n "$CURRENT_MODE" ]]; then
+    echo -e "  ${BLUE}현재 설정:${NC} $CURRENT_MODE"
+    if [[ "$CURRENT_MODE" == "$RECOMMENDED_MODE" ]] || [[ "$CURRENT_MODE" == "auto" ]]; then
+        echo -e "  ${GREEN}✓${NC} 적절한 설정"
+    else
+        echo -e "  ${YELLOW}!${NC} 권장 설정과 다름"
+    fi
+else
+    echo -e "  ${BLUE}현재 설정:${NC} auto (기본값)"
+fi
+
+((PASSED++))
+
+# 결과 요약
+echo ""
+echo -e "${BLUE}=== 결과 요약 ===${NC}"
+echo -e "  ${GREEN}통과:${NC} $PASSED"
+echo -e "  ${RED}실패:${NC} $FAILED"
+echo -e "  ${YELLOW}경고:${NC} $WARNINGS"
+echo ""
+
+if [[ $FAILED -eq 0 ]]; then
+    echo -e "${GREEN}✓ Agent Teams 사용 가능${NC}"
+    exit 0
+else
+    echo -e "${RED}✗ Agent Teams 사용 불가${NC}"
+    echo -e "  위의 실패 항목을 해결해주세요."
+    exit 1
+fi