binary-agents 1.0.0

package/docs/SUBAGENTS.md

@@ -0,0 +1,423 @@
+# Claude 서브에이전트 모음 (Subagents Collection)
+
+React/TypeScript 코드베이스 분석을 위한 Claude 서브에이전트 모음입니다.
+
+## 📋 서브에이전트 개요
+
+### 기본 버전 (Basic) vs 고급 버전 (Advanced)
+
+| 특징 | 기본 버전 | 고급 버전 |
+|------|----------|----------|
+| **모델** | Haiku (빠름, 저렴) | Sonnet (강력, 심층 분석) |
+| **도구** | Read, Glob, Grep | Read, Glob, Grep, WebFetch, WebSearch |
+| **속도** | ⚡⚡⚡ 매우 빠름 | ⚡⚡ 빠름 |
+| **비용** | 💰 저렴 | 💰💰 보통 |
+| **분석 깊이** | 기본적인 패턴 인식 | 심층 추론 + 웹 리서치 |
+| **권장사항** | 코드 기반 | 업계 표준 비교 + 학습 리소스 |
+| **사용 시기** | 빠른 스캔, 일상적 검토 | 심층 분석, 아키텍처 리뷰 |
+
+---
+
+## 🔍 사용 가능한 서브에이전트
+
+### 0. Subagent Builder (서브에이전트 빌더) 🛠️ **META**
+
+#### [subagent-builder.md](subagent-builder.md) - 메타 에이전트 ⭐⭐⭐
+```yaml
+모델: sonnet
+도구: Read, Glob, Grep, Write, Edit, WebFetch, WebSearch
+설명: 서브에이전트를 생성, 수정, 커스터마이징하는 메타 에이전트
+```
+
+**주요 기능:**
+- 🆕 새로운 서브에이전트 생성
+- ✏️ 기존 서브에이전트 수정 및 커스터마이징
+- 🎯 프로젝트별 특화 (React → Vue, Next.js 등)
+- ⚙️ 모델/도구 최적화
+- 📋 템플릿 제공 및 검증
+- 🌐 도메인 베스트 프랙티스 리서치
+
+**언제 사용하나요?**
+- ✅ 새로운 분석 에이전트가 필요할 때
+- ✅ 기존 에이전트를 특정 프레임워크에 맞추고 싶을 때
+- ✅ 회사/팀 내부 규칙을 추가하고 싶을 때
+- ✅ 서브에이전트 성능 최적화 (모델, 도구 선택)
+- ✅ 여러 프로젝트에 맞는 에이전트 관리
+
+**사용 예시:**
+```bash
+# 새로운 에이전트 생성
+"subagent-builder를 사용해서 Vue 3 Composition API를
+검사하는 에이전트 만들어줘"
+
+# 기존 에이전트 커스터마이징
+"code-reviewer를 Next.js 14 App Router에 특화되도록 수정해줘"
+
+# 팀 규칙 추가
+"junior-friendly-checker에 우리 회사 코딩 컨벤션을 추가해줘"
+
+# 성능 최적화
+"이 에이전트를 더 빠르게 만들 수 있을까?"
+```
+
+**출력물:**
+- ✅ 새로운 `.md` 파일 생성
+- ✅ 기존 파일 수정
+- ✅ 설정 검증 및 최적화 제안
+- ✅ 사용 가이드 및 예시
+
+**📖 자세한 사용법은 [BUILDER_GUIDE.md](BUILDER_GUIDE.md)를 참고하세요!**
+
+**실전 예시:**
+- 🎯 Vue 3 전용 에이전트 만들기
+- 🎯 팀 코딩 컨벤션 추가하기
+- 🎯 보안 감사 에이전트 생성
+- 🎯 성능 최적화
+- 🎯 자동 수정 기능 추가
+
+---
+
+### 1. Code Quality Reviewers (코드 품질 리뷰어)
+
+#### [code-reviewer.md](code-reviewer.md) - 기본 버전
+```yaml
+모델: haiku
+도구: Read, Glob, Grep
+설명: 함수형 프로그래밍, 클린 코드, 관심사 분리, 유지보수성 검토
+```
+
+**평가 항목 (5개):**
+- ✅ 함수형 프로그래밍 원칙
+- ✅ 관심사의 분리
+- ✅ 코드 가독성
+- ✅ React 특화 패턴
+- ✅ TypeScript 사용
+
+**언제 사용하나요?**
+- 빠른 코드 품질 체크
+- PR 리뷰 전 자동 검사
+- 일상적인 코드 검토
+
+---
+
+#### [advanced-code-reviewer.md](advanced-code-reviewer.md) - 고급 버전 ⭐
+```yaml
+모델: sonnet
+도구: Read, Glob, Grep, WebFetch, WebSearch
+설명: 심층 아키텍처 분석 + 웹 기반 베스트 프랙티스 리서치
+```
+
+**평가 항목 (7개):**
+- ✅ 함수형 프로그래밍 원칙
+- ✅ **아키텍처 & 디자인 패턴** (신규)
+- ✅ 관심사의 분리
+- ✅ 코드 가독성
+- ✅ React 특화 패턴
+- ✅ TypeScript 사용
+- ✅ **성능 & 최적화** (신규)
+
+**웹 리서치 기능:**
+- 🌐 최신 베스트 프랙티스 검색 (2025)
+- 🌐 공식 문서 참조 (React, TypeScript 등)
+- 🌐 업계 표준과 비교 분석
+- 🌐 학습 리소스 제공
+
+**언제 사용하나요?**
+- 아키텍처 리뷰가 필요할 때
+- 최신 패턴 적용 여부 확인
+- 심층적인 품질 분석
+- 팀 온보딩 전 코드베이스 평가
+
+---
+
+### 2. Refactoring Analyzers (리팩토링 분석기)
+
+#### [refactor-analyzer.md](refactor-analyzer.md) - 기본 버전
+```yaml
+모델: haiku
+도구: Read, Glob, Grep
+설명: 코드 중복, 복잡도, 추상화 기회, 코드 스멜, 성능 문제 식별
+```
+
+**분석 영역 (5개):**
+- 🔍 코드 중복
+- 🔍 순환 복잡도 (Cyclomatic Complexity)
+- 🔍 추상화 기회
+- 🔍 코드 스멜
+- 🔍 성능 기회
+
+**언제 사용하나요?**
+- 기술 부채 파악
+- 리팩토링 우선순위 결정
+- 코드 정리 작업 전
+
+---
+
+#### [advanced-refactor-analyzer.md](advanced-refactor-analyzer.md) - 고급 버전 ⭐
+```yaml
+모델: sonnet
+도구: Read, Glob, Grep, WebFetch, WebSearch
+설명: 심층 리팩토링 분석 + 업계 패턴 리서치 + 아키텍처 권장사항
+```
+
+**분석 영역 (6개):**
+- 🔍 코드 중복
+- 🔍 순환 복잡도
+- 🔍 추상화 기회
+- 🔍 코드 스멜
+- 🔍 성능 기회
+- 🔍 **아키텍처 부채** (신규)
+
+**웹 리서치 기능:**
+- 🌐 최신 리팩토링 패턴 검색
+- 🌐 리팩토링 카탈로그 참조 (refactoring.guru 등)
+- 🌐 마이그레이션 가이드 제공
+- 🌐 업계 사례 연구
+- 🌐 구체적인 코드 예제 제공
+
+**추가 기능:**
+- 📊 업계 벤치마크와 비교
+- 📈 ROI(투자 대비 효과) 분석
+- 🛣️ 단계별 마이그레이션 경로
+- ⚠️ 리스크 평가 (낮음/중간/높음)
+
+**언제 사용하나요?**
+- 대규모 리팩토링 계획
+- 아키텍처 현대화
+- 레거시 코드 개선
+- 최신 패턴 적용 검토
+
+---
+
+### 3. Junior Developer Readability Checkers (주니어 친화성 검사기)
+
+#### [junior-friendly-checker.md](junior-friendly-checker.md) - 기본 버전
+```yaml
+모델: haiku
+도구: Read, Glob, Grep
+설명: 주니어 개발자 관점에서 네이밍, 복잡도, 주석, 구조, 타입 명확성 평가
+```
+
+**평가 항목 (5개):**
+- 👤 네이밍 명확성 (25%)
+- 👤 함수 복잡도 (20%)
+- 👤 주석 품질 (25%)
+- 👤 코드 구조 (15%)
+- 👤 타입 명확성 (15%)
+
+**특징:**
+- 온보딩 시나리오 시뮬레이션
+- 학습 곡선 예측
+- 주니어 관점의 장벽 식별
+
+**언제 사용하나요?**
+- 팀에 주니어 합류 예정
+- 코드 가독성 개선
+- 온보딩 시간 단축 목표
+
+---
+
+#### [advanced-junior-checker.md](advanced-junior-checker.md) - 고급 버전 ⭐
+```yaml
+모델: sonnet
+도구: Read, Glob, Grep, WebFetch, WebSearch
+설명: 리서치 기반 권장사항 + 학습 리소스 큐레이션
+```
+
+**평가 항목 (6개):**
+- 👤 네이밍 명확성 (25%)
+- 👤 함수 복잡도 (20%)
+- 👤 주석 품질 (25%)
+- 👤 코드 구조 (15%)
+- 👤 타입 명확성 (10%)
+- 👤 **학습 곡선 평가** (5%, 신규)
+
+**웹 리서치 기능:**
+- 🌐 효과적인 온보딩 사례 연구
+- 🌐 개념별 학습 리소스 큐레이션
+- 🌐 공식 문서 + 튜토리얼 제공
+- 🌐 업계 온보딩 베스트 프랙티스
+- 🌐 단계별 학습 경로 제안
+
+**추가 기능:**
+- 📚 큐레이션된 학습 리소스
+- 🎯 개념별 난이도 평가
+- 📖 문서화 템플릿 제공
+- 🗺️ 단계별 학습 경로
+
+**언제 사용하나요?**
+- 체계적인 온보딩 프로그램 구축
+- 주니어 교육 자료 개발
+- 코드베이스 접근성 극대화
+- 팀 성장 계획 수립
+
+---
+
+## 🎯 어떤 버전을 선택해야 하나요?
+
+### 기본 버전 (Haiku) 선택
+- ✅ 빠른 피드백이 필요할 때
+- ✅ 비용을 절감하고 싶을 때
+- ✅ 일상적인 코드 검토
+- ✅ 명확한 패턴 기반 분석
+- ✅ CI/CD 파이프라인 자동화
+
+### 고급 버전 (Sonnet) 선택
+- ⭐ 아키텍처 리뷰가 필요할 때
+- ⭐ 최신 베스트 프랙티스 확인
+- ⭐ 학습 리소스가 필요할 때
+- ⭐ 심층 분석 및 추론이 필요할 때
+- ⭐ 팀 온보딩 자료 개발
+- ⭐ 대규모 리팩토링 계획
+
+---
+
+## ❓ 어떻게 사용하나요?
+
+### 🚨 중요: 자동 선택되지 않습니다!
+
+Claude는 **명시적으로 요청**해야 해당 서브에이전트를 실행합니다.
+
+### 사용 방법
+
+#### 방법 1: 직접 지정 (명확함)
+```bash
+"code-reviewer를 사용해서 이 프로젝트 분석해줘"
+→ code-reviewer.md 실행 (Haiku, 빠름)
+
+"advanced-code-reviewer를 사용해서 최신 패턴과 비교해줘"
+→ advanced-code-reviewer.md 실행 (Sonnet, 웹 리서치)
+```
+
+#### 방법 2: 상황 설명 (추천)
+Claude가 요청 내용을 보고 적절한 에이전트 선택:
+
+```bash
+# 빠른 체크 → 기본 버전 선택
+"빨리 코드 품질만 체크해줘"
+
+# 심층 분석 → 고급 버전 선택
+"최신 2025 React 베스트 프랙티스와 비교하고 학습 자료도 찾아줘"
+```
+
+### 워크플로우 예시
+
+**단계 1: 빠른 스캔 (기본 버전)**
+```
+"code-reviewer로 주요 문제점 빠르게 찾아줘"
+→ 5-10분, ~$0.05, 기본 이슈 15개 발견
+```
+
+**단계 2: 심층 분석 (필요시 고급 버전)**
+```
+"advanced-code-reviewer로 [발견된 이슈]에 대한
+최신 해결 방법과 학습 자료 찾아줘"
+→ 15-20분, ~$1.00, 상세 가이드 + 리소스
+```
+
+**📖 자세한 비교는 [COMPARISON.md](COMPARISON.md)를 참고하세요!**
+
+---
+
+## 💡 사용 예시
+
+### 기본 리뷰 (빠른 체크)
+```bash
+# code-reviewer 사용
+"이 프로젝트의 코드 품질을 빠르게 검토해줘"
+→ 5-10분 내 기본 패턴 분석 완료
+```
+
+### 심층 분석 (아키텍처 리뷰)
+```bash
+# advanced-code-reviewer 사용
+"이 프로젝트를 최신 React 베스트 프랙티스와 비교해줘"
+→ 웹 리서치 포함 심층 분석 (15-20분)
+→ 학습 리소스 + 업계 벤치마크 제공
+```
+
+### 리팩토링 계획
+```bash
+# refactor-analyzer 사용 (빠른 스캔)
+"중복 코드와 복잡한 함수를 찾아줘"
+→ 기본 메트릭스 제공
+
+# advanced-refactor-analyzer 사용 (심층 계획)
+"대규모 리팩토링을 위한 우선순위와 마이그레이션 경로를 제시해줘"
+→ ROI 분석 + 단계별 가이드 + 웹 리소스
+```
+
+### 온보딩 준비
+```bash
+# junior-friendly-checker 사용
+"주니어 개발자가 이해하기 어려운 부분을 찾아줘"
+→ 기본 가독성 분석
+
+# advanced-junior-checker 사용
+"주니어 온보딩 프로그램을 위한 학습 자료와 개선 계획을 만들어줘"
+→ 큐레이션된 학습 리소스 + 단계별 경로 + 문서화 가이드
+```
+
+---
+
+## 🛠️ 도구 설명
+
+### Read, Glob, Grep (모든 버전)
+- **Read**: 파일 내용 읽기
+- **Glob**: 파일 패턴 매칭 (`**/*.ts`, `**/*.tsx`)
+- **Grep**: 정규식 기반 코드 검색
+
+### WebFetch, WebSearch (고급 버전만)
+- **WebFetch**: 특정 URL의 문서 가져오기
+  - 예: React 공식 문서, TypeScript 핸드북
+- **WebSearch**: 웹에서 베스트 프랙티스 검색
+  - 예: "React hooks best practices 2025"
+
+---
+
+## 📊 성능 및 비용 비교
+
+| 서브에이전트 | 평균 실행 시간 | 상대적 비용 | 웹 요청 수 |
+|-------------|--------------|-----------|-----------|
+| code-reviewer | 5-10분 | 💰 | 0 |
+| **advanced-code-reviewer** | 15-20분 | 💰💰 | 5-7개 |
+| refactor-analyzer | 5-10분 | 💰 | 0 |
+| **advanced-refactor-analyzer** | 15-20분 | 💰💰 | 5-7개 |
+| junior-friendly-checker | 5-10분 | 💰 | 0 |
+| **advanced-junior-checker** | 15-20분 | 💰💰 | 5-7개 |
+
+---
+
+## 🎓 추가 정보
+
+### 왜 읽기 전용 도구만 사용하나요?
+- 🔒 **안전성**: 코드를 분석만 하고 수정하지 않음
+- ✅ **예측 가능성**: 파일 시스템 변경 없음
+- 🎯 **목적**: 분석 결과를 보고하고, 사람이 결정
+
+### 웹 리서치는 어떻게 활용되나요?
+- 📚 최신 베스트 프랙티스 확인
+- 🔗 공식 문서 참조
+- 💡 학습 리소스 제공
+- 📊 업계 표준과 비교
+- 🗺️ 마이그레이션 가이드
+
+### 향후 확장 가능성
+만약 자동 수정 기능이 필요하다면:
+```yaml
+# 미래 버전 예시
+name: auto-refactorer
+model: sonnet
+tools: Read, Glob, Grep, Edit, Bash
+description: 분석 + 자동 리팩토링 + 테스트 실행
+```
+
+---
+
+## 📝 라이선스
+이 서브에이전트들은 학습 및 팀 내 사용을 위해 제공됩니다.
+
+---
+
+## 🤝 기여
+개선 제안이나 새로운 서브에이전트 아이디어가 있다면 이슈를 열어주세요!

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "binary-agents",
+  "version": "1.0.0",
+  "description": "Claude Code subagents collection with sync CLI tool",
+  "type": "module",
+  "main": "src/sync.js",
+  "bin": {
+    "binary-agents": "./bin/cli.js"
+  },
+  "scripts": {
+    "sync": "node bin/cli.js sync",
+    "list": "node bin/cli.js list"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "subagents",
+    "sync",
+    "cli",
+    "code-review",
+    "refactoring"
+  ],
+  "author": "01-binary",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/01-binary/binary-agents.git"
+  },
+  "files": [
+    "agents",
+    "bin",
+    "src",
+    "docs",
+    "README.md"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "ora": "^8.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/sync.js

@@ -0,0 +1,207 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import ora from 'ora';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// 모노레포의 agents 디렉토리 경로
+const REPO_AGENTS_DIR = path.join(__dirname, '..', 'agents');
+
+/**
+ * 로컬 agents 디렉토리에서 서브에이전트 파일 목록 가져오기
+ */
+async function fetchSubagentFiles() {
+  try {
+    const files = await fs.readdir(REPO_AGENTS_DIR);
+
+    // .md 파일만 필터링 (서브에이전트 파일들)
+    const subagentFiles = files.filter(file =>
+      file.endsWith('.md') &&
+      file.includes('-')  // 하이픈이 있는 파일만 (서브에이전트 파일들)
+    );
+
+    return subagentFiles;
+  } catch (error) {
+    throw new Error(`Failed to read agents directory: ${error.message}`);
+  }
+}
+
+/**
+ * YAML frontmatter가 있는지 검증
+ */
+function validateYamlFrontmatter(content) {
+  const frontmatterRegex = /^---\n([\s\S]*?)\n---/;
+  return frontmatterRegex.test(content);
+}
+
+/**
+ * 로컬에서 파일 읽기
+ */
+async function readAgentFile(filename) {
+  const filePath = path.join(REPO_AGENTS_DIR, filename);
+  const content = await fs.readFile(filePath, 'utf-8');
+
+  // YAML frontmatter 검증
+  if (!validateYamlFrontmatter(content)) {
+    throw new Error(`Invalid YAML frontmatter in ${filename}`);
+  }
+
+  return content;
+}
+
+/**
+ * .claude/agents 디렉토리 생성
+ * @param {boolean} isGlobal - true면 ~/.claude/agents, false면 현재 디렉토리의 .claude/agents
+ */
+async function ensureAgentsDirectory(isGlobal = false) {
+  let agentsDir;
+
+  if (isGlobal) {
+    // 전역 설치: ~/.claude/agents
+    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    agentsDir = path.join(homeDir, '.claude', 'agents');
+  } else {
+    // 로컬 설치: 현재 디렉토리의 .claude/agents
+    agentsDir = path.join(process.cwd(), '.claude', 'agents');
+  }
+
+  try {
+    await fs.access(agentsDir);
+  } catch {
+    await fs.mkdir(agentsDir, { recursive: true });
+  }
+
+  return agentsDir;
+}
+
+/**
+ * 파일 저장
+ */
+async function saveFile(agentsDir, filename, content) {
+  const filePath = path.join(agentsDir, filename);
+  await fs.writeFile(filePath, content, 'utf-8');
+  return filePath;
+}
+
+/**
+ * 서브에이전트 동기화 메인 함수
+ */
+export async function syncSubagents(options = {}) {
+  const { filter = null, global = false } = options;
+
+  console.log(chalk.blue.bold('\n🤖 Binary Agents Sync\n'));
+
+  if (global) {
+    console.log(chalk.cyan('📍 Global mode: Installing to ~/.claude/agents\n'));
+  }
+
+  // 로컬 agents 디렉토리에서 파일 목록 가져오기
+  const fetchSpinner = ora('Reading subagent files from local repository...').start();
+  let allFiles;
+
+  try {
+    allFiles = await fetchSubagentFiles();
+    fetchSpinner.succeed(chalk.green(`Found ${allFiles.length} subagent files`));
+  } catch (error) {
+    fetchSpinner.fail(chalk.red(`Failed to read file list: ${error.message}`));
+    return { success: false, error: error.message };
+  }
+
+  // 필터링된 파일 목록
+  let filesToSync = allFiles;
+
+  if (filter === 'basic') {
+    filesToSync = allFiles.filter(f => !f.startsWith('advanced-'));
+    console.log(chalk.yellow(`📌 Syncing basic subagents only (${filesToSync.length} files)\n`));
+  } else if (filter === 'advanced') {
+    filesToSync = allFiles.filter(f => f.startsWith('advanced-'));
+    console.log(chalk.yellow(`📌 Syncing advanced subagents only (${filesToSync.length} files)\n`));
+  }
+
+  // .claude/agents 디렉토리 생성
+  const dirMessage = global ? 'Creating ~/.claude/agents directory...' : 'Creating .claude/agents directory...';
+  const dirSpinner = ora(dirMessage).start();
+  let agentsDir;
+
+  try {
+    agentsDir = await ensureAgentsDirectory(global);
+    const successMessage = global ? 'Created ~/.claude/agents directory' : 'Created .claude/agents directory';
+    dirSpinner.succeed(chalk.green(successMessage));
+  } catch (error) {
+    dirSpinner.fail(chalk.red(`Failed to create directory: ${error.message}`));
+    return { success: false, error: error.message };
+  }
+
+  // 각 파일 복사
+  const results = {
+    success: [],
+    failed: []
+  };
+
+  for (const filename of filesToSync) {
+    const fileSpinner = ora(`Copying ${filename}...`).start();
+
+    try {
+      // 로컬 파일 읽기
+      const content = await readAgentFile(filename);
+
+      // 저장
+      const filePath = await saveFile(agentsDir, filename, content);
+
+      fileSpinner.succeed(chalk.green(`✓ ${filename}`));
+      results.success.push(filename);
+    } catch (error) {
+      fileSpinner.fail(chalk.red(`✗ ${filename}: ${error.message}`));
+      results.failed.push({ filename, error: error.message });
+    }
+  }
+
+  // 결과 요약
+  console.log(chalk.blue.bold('\n📊 Sync Summary\n'));
+  console.log(chalk.green(`✓ Successful: ${results.success.length}/${filesToSync.length}`));
+
+  if (results.failed.length > 0) {
+    console.log(chalk.red(`✗ Failed: ${results.failed.length}/${filesToSync.length}`));
+    console.log(chalk.red('\nFailed files:'));
+    results.failed.forEach(({ filename, error }) => {
+      console.log(chalk.red(`  - ${filename}: ${error}`));
+    });
+  }
+
+  console.log(chalk.cyan(`\n📁 Location: ${agentsDir}\n`));
+
+  return {
+    success: results.failed.length === 0,
+    results
+  };
+}
+
+/**
+ * 사용 가능한 서브에이전트 목록 표시
+ */
+export async function listSubagents() {
+  console.log(chalk.blue.bold('\n🤖 Available Subagents\n'));
+
+  const spinner = ora('Reading subagent files from local repository...').start();
+
+  try {
+    const files = await fetchSubagentFiles();
+    spinner.succeed(chalk.green('Found subagent files'));
+
+    const basic = files.filter(f => !f.startsWith('advanced-'));
+    const advanced = files.filter(f => f.startsWith('advanced-'));
+
+    console.log(chalk.yellow('\nBasic (Haiku model):'));
+    basic.forEach(f => console.log(chalk.white(`  • ${f}`)));
+
+    console.log(chalk.yellow('\nAdvanced (Sonnet model):'));
+    advanced.forEach(f => console.log(chalk.white(`  • ${f}`)));
+
+    console.log(chalk.cyan(`\nTotal: ${files.length} subagents\n`));
+  } catch (error) {
+    spinner.fail(chalk.red(`Failed to read file list: ${error.message}`));
+  }
+}