crewx 0.1.0 → 0.1.2

package/docs/agent-registry-strategy.md

@@ -0,0 +1,348 @@
+# AI 에이전트 레지스트리 전략
+
+## ⚠️ 전략 변경: 전용 레지스트리 직행
+
+**전략책임자 판정: npm 단계적 전환 NO-GO**
+
+### 핵심 결정
+**처음부터 전용 레지스트리 구축 + Nexus 호환 API 설계**
+
+```bash
+# 개발자 경험
+crewx agents init                  # 에이전트 프로젝트 생성
+crewx agents publish              # registry.crewx.ai로 배포
+
+# 사용자 경험
+crewx agents install @crewx/dev
+crewx execute "@dev Fix the bug"
+
+# 기업: Nexus 프록시/프라이빗 (선택적)
+crewx config set registry https://nexus.company.com/crewx-proxy
+```
+
+## 핵심 아이디어
+
+**AI 에이전트 전용 레지스트리 + npm 생태계 활용**
+
+## 제품 컨셉
+
+### 에이전트 패키지 구조
+```
+@crewx/dev@1.2.3/
+├── package.json          # Node 의존성 (선택적, npm 생태계 활용)
+├── agent.yaml            # 에이전트 메타데이터 (필수)
+│   ├── name, version, description
+│   ├── capabilities: [code-generation, bug-fixing]
+│   ├── provider, model
+│   ├── system_prompt
+│   └── tools: CLI 래퍼 정의
+└── tools/                # CLI 브릿지 스크립트
+    ├── git-status.sh
+    └── eslint-fix.sh
+```
+
+### 차별화 포인트
+1. **능력 기반 검색** - capability tags로 에이전트 발견
+2. **협업 그래프** - 에이전트 간 의존성 및 협업 패턴
+3. **실행 통계** - 성공률, 평균 실행 시간, 사용자 평가
+4. **CLI 도구 통합** - AI가 실제 도구 실행 (tool call 아님)
+5. **npm 생태계 활용** - package.json으로 Node 패키지 사용
+6. **Nexus 호환** - 기업 프록시/프라이빗 레지스트리 지원
+
+## 비즈니스 모델
+
+### 레지스트리 제공
+- **퍼블릭**: registry.crewx.ai (오픈소스 에이전트)
+- **프라이빗**: Nexus 연동 (기업 내부 에이전트)
+- **하이브리드**: 둘 다 지원 (scope 기반 라우팅)
+
+### 수익 모델
+- 무료: 퍼블릭 에이전트 사용
+- 유료: 프라이빗 레지스트리 호스팅
+- 엔터프라이즈: Nexus 통합 + 지원
+
+## NO-GO 판정: npm 단계적 전환 폐기
+
+### 전략책임자 의견
+**5가지 치명적 문제로 npm 방식 거부**
+
+1. **구조적 미스매치**: npm은 코드 패키지용, 에이전트는 AI 능력
+2. **마이그레이션 함정**: npm→전용 이전 시 이탈률 60% 예상
+3. **경쟁 우위 불명확**: npm 단계에서는 차별화 없음
+4. **6개월 낭비**: 어차피 전용 레지스트리로 가야 함
+5. **Nexus 타이밍 오류**: 처음부터 전용+Nexus 호환이 효율적
+
+### 재무 영향
+- **npm 단계적**: $650K (6개월 npm + 6개월 전용 + 마이그레이션)
+- **전용 직행**: $1M (4개월 전용 개발)
+- **ROI**: +54% (마이그레이션 비용 제거, 출시 2개월 단축)
+
+## 기술 전략: 전용 레지스트리 직행
+
+### 아키텍처
+
+**레지스트리 서버**:
+```
+registry.crewx.ai
+├── API Server (Go/Rust)
+│   ├── /agents/:name (메타데이터)
+│   ├── /agents/:name/:version/download (패키지)
+│   ├── /agents/search?capability=... (능력 기반 검색)
+│   └── /agents/:name/stats (실행 통계)
+├── Storage (S3/MinIO)
+│   └── agent packages (.tgz)
+└── Database (PostgreSQL)
+    ├── agents (메타데이터)
+    ├── capabilities (태그)
+    ├── downloads (통계)
+    └── ratings (평가)
+```
+
+**Nexus 호환**:
+```yaml
+# .crewxrc
+registries:
+  default: "https://registry.crewx.ai"
+
+  # 기업 Nexus 프록시
+  proxy:
+    - "https://nexus.company.com/crewx-proxy"
+
+  # 기업 프라이빗
+  scoped:
+    "@mycompany": "https://nexus.company.com/crewx-private"
+```
+
+### 에이전트 정의 (agent.yaml)
+
+```yaml
+name: backend-developer
+version: 1.0.0
+description: "Backend development specialist with API design skills"
+
+# 에이전트 능력 (검색 가능)
+capabilities:
+  - code-generation
+  - bug-fixing
+  - api-design
+  - database-migration
+
+# AI 설정
+provider: claude
+model: sonnet
+
+# 시스템 프롬프트
+system_prompt: |
+  You are a backend development specialist...
+
+# CLI 도구 (브릿지 방식)
+tools:
+  - name: git-status
+    command: bash tools/git-status.sh
+    description: Get repository status
+
+  - name: run-tests
+    command: npm test
+    description: Run test suite
+
+# Node 의존성 (선택적)
+node_dependencies:
+  eslint: "^8.0.0"
+  gh: "^2.40.0"
+
+# 에이전트 의존성
+agent_dependencies:
+  "@crewx/git-ops": "^1.0.0"
+```
+
+## 경쟁 우위 (전용 레지스트리 기반)
+
+### vs GitHub Copilot Extensions
+- **Copilot**: IDE 내 코드 제안
+- **우리**: 멀티 에이전트 협업 + 실제 CLI 도구 실행 + 능력 기반 검색
+
+### vs LangChain Hub
+- **LangChain**: 프롬프트 템플릿 공유
+- **우리**: 실행 가능한 에이전트 + npm 생태계 + 협업 그래프
+
+### vs Custom GPTs
+- **ChatGPT**: 대화형 챗봇
+- **우리**: CLI 통합 + 개발 워크플로우 + 팀 협업 + 실행 통계
+
+### vs npm (만약 경쟁한다면)
+- **npm**: 코드 패키지, 버전 시맨틱, 정적
+- **우리**: 에이전트 능력, capability versioning, 실행 통계
+
+## 시장 진입 전략 (전용 레지스트리)
+
+### Phase 1: 코어 인프라 (0-4개월)
+**목표**: 레지스트리 + CLI 완성
+
+- [ ] Month 1-2: 레지스트리 API (Go/Rust)
+  - 에이전트 업로드/다운로드
+  - 메타데이터 저장 (PostgreSQL)
+  - S3 스토리지 연동
+
+- [ ] Month 3: CLI 도구
+  - `crewx agents init/publish/install`
+  - agent.yaml 파싱 및 검증
+  - 도구 실행 브릿지
+
+- [ ] Month 4: Nexus 호환 API
+  - 프록시 레지스트리 지원
+  - Scoped registry 라우팅
+  - 인증 토큰 통합
+
+### Phase 2: 에이전트 생태계 (4-8개월)
+**목표**: 10개 공식 에이전트 + 커뮤니티
+
+- [ ] Month 5-6: 공식 에이전트
+  - @crewx/dev, tester, qa-lead
+  - @crewx/frontend, backend
+  - 문서화 + 튜토리얼
+
+- [ ] Month 7: 능력 기반 검색
+  - capability tags 시스템
+  - `crewx agents search "backend"`
+  - 추천 알고리즘
+
+- [ ] Month 8: 커뮤니티
+  - 베타 사용자 50명
+  - 커뮤니티 에이전트 20개
+  - 피드백 수집 및 개선
+
+### Phase 3: 엔터프라이즈 (8-12개월)
+**목표**: 기업 고객 확보
+
+- [ ] Month 9: 실행 통계
+  - 성공률, 실행 시간 추적
+  - 에이전트 평가 시스템
+  - 대시보드
+
+- [ ] Month 10-11: 엔터프라이즈
+  - Nexus 연동 가이드
+  - 보안/컴플라이언스
+  - 기업 파일럿 5곳
+
+- [ ] Month 12: 마켓플레이스
+  - 유료 프리미엄 에이전트
+  - 협업 그래프 시각화
+  - 100+ 퍼블릭 에이전트
+
+## 리스크 분석 (전용 레지스트리)
+
+### 기술 리스크
+| 리스크 | 확률 | 영향 | 완화 전략 |
+|--------|------|------|-----------|
+| 4개월 개발 지연 | 중 | 높음 | 스프린트 단위 마일스톤, 주간 리뷰 |
+| Nexus 호환 실패 | 저 | 중간 | 초기 검증 필수, 기업 베타 테스트 |
+| 에이전트 버전 관리 복잡도 | 중 | 중간 | capability tags + semantic versioning |
+| 인프라 비용 급증 | 저 | 중간 | S3 lifecycle policy, CDN 캐싱 |
+
+### 시장 리스크
+| 리스크 | 확률 | 영향 | 완화 전략 |
+|--------|------|------|-----------|
+| 개발자 수용성 낮음 | 중 | 높음 | 베타 50명, 빠른 피드백 반영 |
+| 경쟁사 빠른 추격 | 중 | 중간 | 차별화 기능 우선 (능력 검색, 협업 그래프) |
+| AI 기술 급변 | 높음 | 중간 | Provider 추상화, 모델 유연성 |
+| 생태계 성장 실패 | 중 | 높음 | 공식 에이전트 10개 먼저, 문서화 철저 |
+
+### 재무 리스크
+| 리스크 | 확률 | 영향 | 완화 전략 |
+|--------|------|------|-----------|
+| 개발 비용 초과 | 중 | 중간 | 월별 예산 추적, 스코프 관리 |
+| 기업 고객 확보 지연 | 중 | 높음 | 파일럿 2개 먼저 확보, 케이스 스터디 |
+| 프리미엄 전환율 낮음 | 중 | 중간 | 무료 티어 충분히 제공, 명확한 가치 제안 |
+
+## 성공 지표
+
+### Phase 1 (4개월): 인프라
+- [ ] 레지스트리 API 가동률 > 99.9%
+- [ ] 에이전트 업로드/다운로드 성공률 > 98%
+- [ ] 평균 설치 시간 < 30초
+- [ ] Nexus 호환 테스트 통과
+
+### Phase 2 (8개월): 생태계
+- [ ] 공식 에이전트 10개 배포
+- [ ] 커뮤니티 에이전트 > 20개
+- [ ] 베타 사용자 > 50명
+- [ ] NPS > 40
+
+### Phase 3 (12개월): 엔터프라이즈
+- [ ] 퍼블릭 에이전트 > 100개
+- [ ] 기업 파일럿 > 5곳
+- [ ] MAU 성장률 > 20%
+- [ ] 유료 전환율 > 5%
+
+## 의사결정 포인트
+
+### ✅ GO 조건 (전략책임자 승인됨)
+- ✅ npm 단계 폐기, 전용 레지스트리 직행
+- ✅ Nexus 호환 API 설계 가능
+- ✅ 4개월 개발 타임라인 합리적
+- ✅ 재무 영향: +54% ROI
+
+### 🚫 STOP 조건 (개발 중단 시)
+- ❌ Month 2: 레지스트리 API 기술 검증 실패
+- ❌ Month 4: Nexus 호환 불가능 판명
+- ❌ Month 8: 베타 사용자 NPS < 0
+- ❌ Month 10: 기업 파일럿 0곳
+
+## 다음 액션
+
+### 즉시 (이번 주)
+1. ✅ **전략 문서 업데이트 완료** (이 문서)
+2. [ ] **개발팀에 NO-GO 전달**
+   - npm 방식 폐기 사유 공유
+   - 전용 레지스트리 스펙 회의 소집
+3. [ ] **레지스트리 기술 스택 결정**
+   - Go vs Rust API 서버
+   - PostgreSQL 스키마 설계
+   - S3/MinIO 선택
+
+### 1주 후
+4. [ ] **agent.yaml 스펙 초안**
+   - 필수 필드 정의
+   - capability tags 체계
+   - 도구 정의 포맷
+5. [ ] **Nexus 호환 검증 PoC**
+   - 프록시 레지스트리 테스트
+   - 인증 토큰 흐름 확인
+
+### 2주 후
+6. [ ] **개발 스프린트 시작**
+   - Sprint 1-2: API 서버 기본 골격
+   - Sprint 3-4: 업로드/다운로드 기능
+7. [ ] **베타 사용자 모집 시작**
+   - 목표: 10명 확보
+
+### 4주 후
+8. [ ] **Phase 1 마일스톤 리뷰**
+   - 진행 상황 평가
+   - 리스크 재평가
+   - GO/STOP 의사결정
+
+## 결론
+
+### 전략 변경 요약
+- ❌ **폐기**: npm 단계적 전환 (구조적 미스매치, 마이그레이션 함정)
+- ✅ **채택**: 전용 레지스트리 직행 (능력 기반 검색, 협업 그래프, Nexus 호환)
+
+### 핵심 가치 제안
+1. **에이전트 특화**: 능력으로 검색, 협업으로 연결
+2. **도구 통합**: CLI 브릿지로 실제 실행
+3. **npm 생태계**: package.json으로 Node 패키지 활용
+4. **기업 친화**: Nexus 프록시/프라이빗 지원
+
+### 성공 조건
+- **기술**: 4개월 내 레지스트리 + CLI + Nexus 호환
+- **생태계**: 8개월 내 공식 10개 + 커뮤니티 20개
+- **비즈니스**: 12개월 내 기업 5곳 + 에이전트 100개
+
+**전략책임자 승인: 전용 레지스트리로 진행. 개발팀 스펙 회의 소집.**
+
+---
+
+*문서 작성: 2025-10-10*
+*최종 업데이트: 2025-10-10 (전략책임자 NO-GO 반영)*
+*작성자: Dev Lead (with @crewx_dev)*