binary-agents 1.0.0

package/bin/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { syncSubagents, listSubagents } from '../src/sync.js';
+import chalk from 'chalk';
+
+const program = new Command();
+
+program
+  .name('binary-agents')
+  .description('Sync Claude Code subagents from 01-binary/subagents repository')
+  .version('1.0.0');
+
+program
+  .command('sync')
+  .description('Sync subagent files to .claude/agents/ (local) or ~/.claude/agents (global)')
+  .option('--basic', 'Sync only basic (Haiku) subagents')
+  .option('--advanced', 'Sync only advanced (Sonnet) subagents')
+  .option('-g, --global', 'Install to ~/.claude/agents instead of current directory')
+  .action(async (options) => {
+    let filter = null;
+
+    if (options.basic) {
+      filter = 'basic';
+    } else if (options.advanced) {
+      filter = 'advanced';
+    }
+
+    const result = await syncSubagents({
+      filter,
+      global: options.global || false
+    });
+
+    if (!result.success) {
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list')
+  .description('List available subagents')
+  .action(async () => {
+    await listSubagents();
+  });
+
+// 기본 명령어가 없으면 help 표시
+if (process.argv.length === 2) {
+  program.help();
+}
+
+program.parse();

package/docs/BUILDER_GUIDE.md

@@ -0,0 +1,645 @@
+# Subagent Builder 사용 가이드
+
+서브에이전트를 쉽게 만들고 수정하는 완벽 가이드입니다.
+
+---
+
+## 🎯 Quick Start
+
+### 1️⃣ 새로운 서브에이전트 만들기
+
+```bash
+"subagent-builder를 사용해서 접근성(accessibility)을
+검사하는 에이전트를 만들어줘"
+```
+
+**Builder가 자동으로:**
+1. ✅ 요구사항 확인 (빠른 스캔? 심층 분석?)
+2. ✅ 웹에서 WCAG 베스트 프랙티스 검색
+3. ✅ 적절한 모델/도구 선택
+4. ✅ 평가 기준 설계
+5. ✅ `accessibility-checker.md` 파일 생성
+6. ✅ 사용 방법 설명
+
+---
+
+### 2️⃣ 기존 에이전트 커스터마이징
+
+```bash
+"code-reviewer를 Vue 3 Composition API에 맞게 수정해줘"
+```
+
+**Builder가 자동으로:**
+1. ✅ 기존 `code-reviewer.md` 읽기
+2. ✅ Vue 3 베스트 프랙티스 검색
+3. ✅ React 패턴을 Vue 패턴으로 변경
+4. ✅ `.vue` 파일 검색 패턴 추가
+5. ✅ `code-reviewer-vue3.md` 생성
+6. ✅ 변경 사항 설명
+
+---
+
+### 3️⃣ 팀 규칙 추가
+
+```bash
+"junior-friendly-checker에 우리 회사 네이밍 규칙을 추가해줘:
+- 컴포넌트는 PascalCase
+- 훅은 use로 시작
+- 유틸 함수는 동사로 시작"
+```
+
+**Builder가 자동으로:**
+1. ✅ 기존 파일 읽기
+2. ✅ 팀 규칙을 새로운 평가 기준으로 추가
+3. ✅ 파일 수정 또는 새 버전 생성
+4. ✅ 적용된 변경사항 설명
+
+---
+
+## 💡 실전 예시
+
+### 예시 1: Next.js 특화 에이전트
+
+**요청:**
+```
+"subagent-builder를 사용해서 Next.js 14 App Router의
+Server Component vs Client Component 사용을 검사하는
+에이전트를 만들어줘"
+```
+
+**Builder 프로세스:**
+
+**1단계: 요구사항 확인**
+```
+Builder: 이 에이전트에 대해 몇 가지 질문할게요:
+
+1. 빠른 스캔(haiku)으로 할까요, 아니면 심층 분석(sonnet)으로 할까요?
+2. 최신 Next.js 공식 문서를 참조할까요?
+3. 문제를 발견만 할까요, 아니면 자동 수정도 할까요?
+```
+
+**User 답변:**
+```
+심층 분석으로 하고, 공식 문서 참조해줘.
+문제만 발견하면 돼.
+```
+
+**2단계: 리서치**
+```
+Builder: 알겠습니다. 다음을 리서치하고 있어요:
+- WebSearch("Next.js 14 App Router best practices")
+- WebFetch("https://nextjs.org/docs/app/building-your-application/rendering")
+- Server Component vs Client Component 패턴 분석
+```
+
+**3단계: 에이전트 생성**
+```yaml
+---
+name: nextjs-rendering-checker
+description: Analyzes Next.js 14 App Router for proper Server/Client Component usage
+tools: Read, Glob, Grep, WebFetch, WebSearch
+model: sonnet
+---
+
+# Next.js Rendering Strategy Checker
+
+## Evaluation Criteria
+
+### 1. Server vs Client Component Usage (Weight: 40%)
+
+**✅ Look for:**
+- Server Components for data fetching
+- Client Components only when needed ('use client')
+- Proper composition (Client inside Server)
+
+**❌ Anti-patterns:**
+- Unnecessary 'use client' directives
+- Data fetching in Client Components
+- Missing 'use client' for interactivity
+
+**🌐 Web Research:**
+- WebFetch Next.js rendering docs
+- Compare with official examples
+
+### 2. App Router Patterns (Weight: 30%)
+[...]
+```
+
+**4단계: 결과 제공**
+```
+✅ Created: nextjs-rendering-checker.md
+
+## Configuration
+- Model: sonnet (for nuanced analysis)
+- Tools: Read, Glob, Grep, WebFetch, WebSearch
+- Focus: Server/Client Component optimization
+
+## Usage
+"nextjs-rendering-checker를 사용해서 이 프로젝트 분석해줘"
+
+## Expected Output
+- Server Component 사용률
+- 불필요한 Client Component 감지
+- 최적화 기회
+- Next.js 공식 가이드와 비교
+```
+
+---
+
+### 예시 2: 보안 감사 에이전트
+
+**요청:**
+```
+"OWASP Top 10을 검사하는 보안 에이전트 만들어줘"
+```
+
+**Builder 대화:**
+```
+Builder: 보안 에이전트를 만들어드릴게요. 몇 가지 확인할게요:
+
+1. 어떤 프레임워크인가요? (React, Vue, Node.js 등)
+2. Opus 모델을 사용할까요? (보안은 중요하니 최고 품질 추천)
+3. 발견한 문제를 자동 수정할까요?
+
+User: React 앱이고, sonnet으로 충분할 것 같아.
+      발견만 하면 돼, 수정은 내가 할게.
+
+Builder: 알겠습니다!
+```
+
+**생성된 에이전트:**
+```yaml
+---
+name: security-auditor
+description: Analyzes React applications for OWASP Top 10 vulnerabilities
+tools: Read, Glob, Grep, WebFetch, WebSearch
+model: sonnet
+---
+
+# Security Auditor
+
+## Evaluation Criteria
+
+### 1. XSS Vulnerabilities (Weight: 25%)
+
+**🚨 Critical Patterns:**
+- dangerouslySetInnerHTML without sanitization
+- Direct innerHTML manipulation
+- Unescaped user input in JSX
+
+**✅ Safe Patterns:**
+- React's default escaping
+- DOMPurify usage
+- Sanitized HTML rendering
+
+**🌐 Research:**
+- WebSearch("React XSS prevention 2025")
+- WebFetch OWASP XSS documentation
+
+### 2. Injection Attacks (Weight: 20%)
+[...]
+
+### 3. Authentication Issues (Weight: 15%)
+[...]
+```
+
+---
+
+### 예시 3: 성능 최적화 에이전트
+
+**요청:**
+```
+"기존 code-reviewer를 더 빠르게 만들어줘"
+```
+
+**Builder 분석:**
+```
+Builder: code-reviewer.md를 분석했어요.
+
+현재 설정:
+- Model: haiku (이미 가장 빠름)
+- Tools: Read, Glob, Grep (최소한의 도구)
+- 평가 기준: 5개
+
+최적화 제안:
+1. ❌ 모델 변경 불가 (haiku가 최고 속도)
+2. ✅ 평가 기준 줄이기 (5개 → 3개 핵심만)
+3. ✅ Grep 패턴 최적화
+4. ✅ 불필요한 파일 스캔 제외
+
+어떤 최적화를 적용할까요?
+```
+
+**User 선택:**
+```
+2번이랑 4번 적용해줘
+```
+
+**Builder 실행:**
+```
+✅ Modified: code-reviewer-fast.md
+
+변경사항:
+1. 평가 기준: 5개 → 3개 (핵심만)
+   - 함수형 프로그래밍
+   - React 패턴
+   - TypeScript
+
+2. 파일 필터 추가:
+   - node_modules 제외
+   - .test.ts 파일 제외
+   - 빌드 결과물 제외
+
+예상 성능:
+- 이전: 5-10분
+- 이후: 3-5분 (40-50% 개선)
+```
+
+---
+
+## 🎨 커스터마이징 패턴
+
+### 패턴 1: 프레임워크 특화
+
+**React → Vue 변환:**
+```
+"code-reviewer를 Vue 3로 변환해줘"
+
+변경되는 것:
+- ✅ React hooks → Vue Composition API
+- ✅ JSX 패턴 → Vue SFC 패턴
+- ✅ .tsx 검색 → .vue 검색
+- ✅ useEffect → watchEffect
+- ✅ useState → ref/reactive
+```
+
+**React → Angular 변환:**
+```
+"code-reviewer를 Angular로 변환해줘"
+
+변경되는 것:
+- ✅ Components → Modules/Components
+- ✅ Hooks → RxJS operators
+- ✅ Context → Services
+- ✅ .tsx → .ts + .html
+```
+
+---
+
+### 패턴 2: 도메인 특화
+
+**일반 → 금융 앱:**
+```
+"code-reviewer에 금융 앱 보안 규칙 추가해줘"
+
+추가되는 것:
+- ✅ PCI DSS 준수
+- ✅ 민감 데이터 처리
+- ✅ 감사 로그 요구사항
+- ✅ 암호화 체크
+```
+
+**일반 → 의료 앱:**
+```
+"HIPAA 규정을 확인하는 기준 추가해줘"
+
+추가되는 것:
+- ✅ PHI 데이터 처리
+- ✅ 접근 제어
+- ✅ 암호화 요구사항
+- ✅ 감사 추적
+```
+
+---
+
+### 패턴 3: 팀 규칙 추가
+
+**회사 컨벤션:**
+```
+"우리 회사 규칙 추가해줘:
+- 모든 함수는 JSDoc 필수
+- 컴포넌트는 features/ 폴더에만
+- API 호출은 services/ 폴더에만
+- 상수는 UPPER_SNAKE_CASE"
+
+추가되는 평가 기준:
+### Team Conventions (Weight: 15%)
+
+**✅ Required:**
+- JSDoc on all exported functions
+- Components in features/ only
+- API calls in services/ only
+- Constants in UPPER_SNAKE_CASE
+
+**Scoring:**
+- 100% compliance: 10/10
+- 90%+: 8/10
+- 80%+: 6/10
+- <80%: Needs improvement
+```
+
+---
+
+## 🔧 고급 사용법
+
+### 자동 수정 에이전트 만들기
+
+**요청:**
+```
+"코드 포맷팅을 자동으로 수정하는 에이전트 만들어줘"
+```
+
+**Builder 경고:**
+```
+⚠️ 자동 수정 에이전트는 코드를 변경합니다.
+
+안전을 위해 다음이 포함됩니다:
+1. Edit, Write 도구 추가
+2. Bash 도구로 테스트 실행
+3. 변경 전 백업 생성
+4. 변경 내역 상세 보고
+
+계속할까요? (y/n)
+```
+
+**생성된 에이전트:**
+```yaml
+---
+name: auto-formatter
+description: Automatically fixes code formatting issues
+tools: Read, Glob, Grep, Edit, Write, Bash
+model: sonnet
+---
+
+# Auto Formatter
+
+⚠️ **Safety Features:**
+- Runs tests before and after
+- Reports all changes
+- Fails fast on test failures
+
+## Process
+1. Scan for formatting issues
+2. **Create backup** (git stash)
+3. **Apply fixes** (Edit tool)
+4. **Run tests** (Bash: npm test)
+5. If tests pass: Report changes
+6. If tests fail: Restore backup
+
+[...]
+```
+
+---
+
+### 체인 에이전트 만들기
+
+**요청:**
+```
+"먼저 문제를 찾고, 그 다음 자동으로 수정하는
+2단계 에이전트를 만들어줘"
+```
+
+**Builder 제안:**
+```
+체인 에이전트는 2개의 독립적인 에이전트로 만드는 것을 추천합니다:
+
+1. detector.md (Read, Glob, Grep)
+   - 빠르게 문제 찾기
+   - 수정 가능한 것과 불가능한 것 구분
+
+2. auto-fixer.md (Read, Edit, Write, Bash)
+   - detector가 찾은 문제 수정
+   - 테스트 실행 및 검증
+
+사용법:
+Step 1: "detector로 문제 찾아줘"
+Step 2: "auto-fixer로 [발견된 문제] 수정해줘"
+
+이렇게 할까요?
+```
+
+---
+
+## 📋 체크리스트
+
+### 새 에이전트 만들 때
+
+**Before Creating:**
+- [ ] 비슷한 에이전트가 이미 있는지 확인
+- [ ] 정확한 요구사항 정리
+- [ ] 사용할 기술 스택 확인
+- [ ] 빠른 스캔 vs 심층 분석 결정
+- [ ] 읽기 전용 vs 자동 수정 결정
+
+**During Creation:**
+- [ ] Builder에게 명확한 목적 전달
+- [ ] 도메인별 규칙 명시
+- [ ] 예시 코드 제공 (가능하면)
+- [ ] 출력 형식 선호도 전달
+
+**After Creation:**
+- [ ] 생성된 에이전트 검토
+- [ ] 테스트 프로젝트로 실행
+- [ ] 필요시 수정 요청
+- [ ] README 업데이트 (자동)
+
+---
+
+### 에이전트 수정할 때
+
+**Before Modifying:**
+- [ ] 현재 에이전트 동작 이해
+- [ ] 변경 이유 명확히
+- [ ] 기존 기능 유지 vs 새 버전 판단
+
+**During Modification:**
+- [ ] 변경할 부분 명확히 지시
+- [ ] 기존 설정 유지할지 확인
+- [ ] 성능 영향 고려
+
+**After Modification:**
+- [ ] 변경사항 검토
+- [ ] 이전 버전과 비교
+- [ ] 테스트 실행
+
+---
+
+## ⚡ 빠른 참조
+
+### 자주 쓰는 명령어
+
+```bash
+# 새로운 에이전트
+"subagent-builder로 [목적]을 검사하는 에이전트 만들어줘"
+
+# 프레임워크 특화
+"[에이전트]를 [프레임워크]에 맞게 수정해줘"
+
+# 팀 규칙 추가
+"[에이전트]에 우리 팀 규칙 추가해줘: [규칙들]"
+
+# 성능 최적화
+"[에이전트]를 더 빠르게/정확하게 만들어줘"
+
+# 고급 기능 추가
+"[기본 에이전트]를 웹 리서치 기능 추가한 고급 버전으로 업그레이드해줘"
+
+# 자동 수정 기능
+"[에이전트]에 자동 수정 기능 추가해줘"
+
+# 검증
+"[에이전트] 설정이 올바른지 검증해줘"
+```
+
+---
+
+### 모델 선택 가이드
+
+| 목적 | 추천 모델 | 이유 |
+|------|----------|------|
+| 간단한 패턴 검사 | haiku | 빠르고 저렴 |
+| 코드 리뷰 | sonnet | 추론 필요 |
+| 보안 감사 | sonnet/opus | 정확성 중요 |
+| 자동 수정 | sonnet | 안전한 수정 필요 |
+| 아키텍처 분석 | sonnet | 심층 이해 필요 |
+
+---
+
+### 도구 선택 가이드
+
+| 작업 | 필요한 도구 |
+|------|------------|
+| 코드 읽기만 | Read, Glob, Grep |
+| 웹 리서치 추가 | + WebFetch, WebSearch |
+| 코드 수정 | + Edit, Write |
+| 테스트 실행 | + Bash |
+| 완전 자동화 | 모든 도구 |
+
+---
+
+## 🎓 학습 리소스
+
+### Builder 이해하기
+
+1. **[subagent-builder.md](subagent-builder.md)** 읽기
+   - 전체 프로세스 이해
+   - 템플릿 참고
+   - 베스트 프랙티스 학습
+
+2. **기존 에이전트 분석**
+   - code-reviewer.md 구조 파악
+   - advanced-code-reviewer.md와 차이점
+   - 패턴 학습
+
+3. **실습**
+   - 간단한 에이전트부터 시작
+   - 기존 에이전트 수정해보기
+   - 자신만의 에이전트 만들기
+
+---
+
+## 🆘 문제 해결
+
+### Q: "에이전트가 너무 느려요"
+```
+"subagent-builder로 [에이전트]를 더 빠르게 최적화해줘"
+
+Builder가 분석:
+- 모델 다운그레이드 (sonnet → haiku)
+- 평가 기준 축소
+- 불필요한 파일 제외
+- Grep 패턴 최적화
+```
+
+### Q: "에이전트가 원하는 걸 안 찾아요"
+```
+"[에이전트]에 [찾고 싶은 패턴]을 감지하는 기준 추가해줘"
+
+Builder가 추가:
+- 새로운 평가 기준
+- Grep 검색 패턴
+- 구체적인 예시
+```
+
+### Q: "여러 프로젝트에 같은 에이전트를 쓰고 싶어요"
+```
+방법 1: 공통 에이전트 폴더
+- 에이전트를 별도 폴더에 보관
+- 각 프로젝트에서 심볼릭 링크
+
+방법 2: 프로젝트별 커스터마이징
+"[기본 에이전트]를 [프로젝트명]에 맞게 복사하고 수정해줘"
+```
+
+---
+
+## 💼 실전 시나리오
+
+### 시나리오 1: 새 프로젝트 시작
+
+```
+1. "subagent-builder로 Next.js 14 프로젝트를 위한
+   기본 에이전트 세트를 만들어줘"
+
+2. Builder가 생성:
+   - nextjs-code-reviewer.md
+   - nextjs-performance-checker.md
+   - nextjs-seo-analyzer.md
+
+3. 프로젝트 진행하면서 필요에 따라:
+   "subagent-builder로 [특정 기능] 체커 추가해줘"
+```
+
+### 시나리오 2: 레거시 프로젝트 개선
+
+```
+1. "subagent-builder로 레거시 코드 개선 우선순위를
+   정하는 에이전트 만들어줘"
+
+2. 생성: legacy-refactor-prioritizer.md
+   - 기술 부채 측정
+   - 영향도 분석
+   - 우선순위 제안
+
+3. "발견한 문제를 자동으로 수정하는 에이전트도 만들어줘"
+```
+
+### 시나리오 3: 팀 표준화
+
+```
+1. "우리 팀의 코딩 스탠다드를 검사하는 에이전트 만들어줘"
+   - 팀 규칙 문서 첨부
+
+2. Builder가 팀 규칙 분석하고 에이전트 생성
+
+3. CI/CD에 통합:
+   "이 에이전트를 CI에서 자동 실행하려면 어떻게 해야 해?"
+```
+
+---
+
+## 🚀 다음 단계
+
+1. **subagent-builder 사용해보기**
+   ```
+   "subagent-builder야, 간단한 린터 에이전트 만들어줘"
+   ```
+
+2. **기존 에이전트 커스터마이징**
+   ```
+   "code-reviewer를 우리 프로젝트에 맞게 수정해줘"
+   ```
+
+3. **자신만의 템플릿 만들기**
+   ```
+   "우리 회사에서 자주 쓸 에이전트 템플릿 만들어줘"
+   ```
+
+4. **에이전트 라이브러리 구축**
+   - 프로젝트별 에이전트 모음
+   - 팀 공유 에이전트
+   - 재사용 가능한 템플릿
+
+---
+
+**Happy Building! 🛠️**