From acf7db7e99d6e08a4a131566e47b3247cc800e0b Mon Sep 17 00:00:00 2001 From: "Paul.Kim" Date: Mon, 21 Jul 2025 13:53:59 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20README.md=EC=97=90=20=ED=94=84=EB=A1=9C?= =?UTF-8?q?=EC=A0=9D=ED=8A=B8=20=EC=86=8C=EA=B0=9C=20=EB=B0=8F=20=EC=8B=9C?= =?UTF-8?q?=EC=9E=91=ED=95=98=EA=B8=B0=20=EC=84=B9=EC=85=98=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: AI 개발 도구 통합 소개 및 사용 방법 추가 - MCP 서버 구성 방법 및 주요 기능 설명 추가 --- README.md | 40 +++- docs/guides/Claude code router 설치 방법.md | 226 ++++++++++++++++++++ 2 files changed, 265 insertions(+), 1 deletion(-) create mode 100644 docs/guides/Claude code router 설치 방법.md diff --git a/README.md b/README.md index 39b0862..df3d0fb 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,34 @@ **📢 상태**: 기본 템플릿. 추가 커스터마이징 권장. +## 소개 + +세 가지 강력한 AI 개발 도구를 결합한 프로젝트 템플릿입니다: + +- Claude Code - Anthropic의 Claude용 CLI +- Task Master - 태그 기반 작업 관리 시스템 +- Cursor - 정밀한 코드 리뷰 워크플로를 위한 AI 기반 IDE (선택 사항) + +## 시작하기 + +### Claude Code 실행 + +```bash +claude +``` + +or + +``` +ccr code # calude code router 사용 시 +``` + +### Task Studio 열기 (선택적 웹 인터페이스) + +```bash +npx task-studio@latest +``` + ## 주요 기능 ✨ - 🛠️ **SuperClaude 명령어**: 16개 전문 명령어 (e.g., `/sc:implement`, `/sc:analyze`). @@ -15,7 +43,17 @@ ## 설정 ⚙️ -`~/.claude/settings.json` 편집. 기본 설정 충분. +`~/.claude/settings.json` 편집으로 커스터마이징. 기본 설정 충분. + +또한 `.mcp.json` 파일을 통해 MCP(Model Context Protocol) 서버를 구성할 수 있습니다. 이 파일은 다양한 AI 도구와의 통합을 정의합니다. 기본적으로 다음과 같은 서버가 설정되어 있습니다: + +- taskmaster-ai: 태그 기반 작업 관리 시스템 +- sequential-thinking: 복잡한 분석을 위한 순차적 사고 엔진 +- playwright: 브라우저 자동화 및 테스트 +- magic: UI 컴포넌트 생성 +- context7: 라이브러리 문서 검색 + +이 서버들을 필요에 따라 추가하거나 커스터마이징할 수 있습니다. 예를 들어, 새로운 MCP 서버를 추가하여 도구를 확장하세요. 자세한 내용은 MCP 문서를 참조하세요. ## 문서 📖 diff --git a/docs/guides/Claude code router 설치 방법.md b/docs/guides/Claude code router 설치 방법.md new file mode 100644 index 0000000..e6fd5f5 --- /dev/null +++ b/docs/guides/Claude code router 설치 방법.md @@ -0,0 +1,226 @@ +# Claude Code Router 설치 가이드 + +이 가이드는 Claude Code Router의 설치, 설정 및 사용 방법을 상세히 설명합니다. Claude Code Router는 Claude Code 요청을 다양한 모델로 라우팅하고, 요청을 커스터마이징할 수 있는 강력한 도구입니다. 주요 기능으로는 모델 라우팅, 다중 제공자 지원, 요청/응답 변환, 동적 모델 전환 등이 있습니다. + +이 가이드는 영어 README 내용을 기반으로 하며, 설치 방법에 대한 세부 설명과 `~/.claude-code-router/config.json` 파일의 예시를 포함합니다. 모든 설명은 한국어로 제공되며, 코드 예시는 원문의 영어 표기를 유지합니다. + +## ✨ 주요 기능 + +- **모델 라우팅**: 배경 작업(background tasks), 생각 모드(thinking), 긴 컨텍스트(long context) 등에 따라 요청을 다른 모델로 라우팅합니다. +- **다중 제공자 지원**: OpenRouter, DeepSeek, Ollama, Gemini, Volcengine, SiliconFlow 등의 모델 제공자를 지원합니다. +- **요청/응답 변환**: 제공자에 맞게 요청과 응답을 변환하는 트랜스포머를 사용합니다. +- **동적 모델 전환**: Claude Code 내에서 `/model` 명령어로 모델을 실시간으로 전환할 수 있습니다. +- **GitHub Actions 통합**: GitHub 워크플로에서 Claude Code 작업을 트리거할 수 있습니다. +- **플러그인 시스템**: 커스텀 트랜스포머로 기능을 확장할 수 있습니다. + +## 🚀 시작하기 + +### 1. 설치 + +먼저, Claude Code가 설치되어 있는지 확인하세요. Claude Code는 Anthropic의 공식 도구로, Claude 모델을 사용한 코드 생성을 지원합니다. 설치되지 않았다면 다음 명령어를 실행하세요: + +```shell +npm install -g @anthropic-ai/claude-code +``` + +그 다음, Claude Code Router를 설치합니다. 이는 글로벌로 설치하는 것이 권장됩니다: + +```shell +npm install -g @musistudio/claude-code-router +``` + +**상세 설명**: +- 이 명령어는 Node.js 환경에서 실행됩니다. Node.js가 설치되어 있지 않다면 먼저 [Node.js 공식 사이트](https://nodejs.org/)에서 다운로드하세요. +- 설치 후, `ccr` 명령어가 사용 가능해집니다. (예: `ccr code`로 Claude Code를 라우터와 함께 실행) +- 문제가 발생하면, npm 캐시를 지우고 재설치하세요: `npm cache clean --force` 후 다시 설치. + +### 2. 설정 + +설정 파일은 홈 디렉토리에 생성됩니다: `~/.claude-code-router/config.json`. 이 파일은 모델 제공자, 라우터 규칙 등을 정의합니다. 자세한 내용은 `config.example.json`을 참조하세요. + +**config.json 파일의 주요 섹션**: +- **PROXY_URL** (선택): API 요청을 위한 프록시 설정 (예: `"http://127.0.0.1:7890"`). 네트워크 제한이 있는 환경에서 유용합니다. +- **LOG** (선택): 로그 활성화 (`true`로 설정 시 `~/.claude-code-router.log` 파일에 로그 저장). +- **APIKEY** (선택): 요청 인증을 위한 시크릿 키. 설정 시 클라이언트는 `Authorization: Bearer your-secret-key` 헤더를 사용해야 합니다. +- **HOST** (선택): 서버 호스트 주소 (기본: `127.0.0.1`). APIKEY가 없으면 보안을 위해 `127.0.0.1`로 강제 설정됩니다. +- **Providers**: 모델 제공자 배열. 각 제공자에 이름, API 베이스 URL, API 키, 모델 목록, 트랜스포머를 정의합니다. +- **Router**: 라우팅 규칙. `default`는 기본 모델, 다른 키(예: `background`, `think`)는 특정 시나리오를 위한 모델을 지정합니다. +- **transformers** (선택): 커스텀 트랜스포머를 로드하기 위한 배열. + +**예시 config.json 파일** (사용자 제공 경로: `\home\koolab\.claude-code-router\config.json` 기반으로 한 실제 예시): +아래는 실제 사용 중인 config.json의 예시입니다. 이는 Gemini 제공자를 사용하는 간단한 설정입니다. 필요에 따라 API 키와 모델을 수정하세요. + +```json +{ + "LOG": true, + "Providers": [ + { + "name": "gemini", + "api_base_url": "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions", + "api_key": "${GEMINI_API_KEY}", // 실제 API 키로 교체하세요 + "models": [ + "gemini-2.5-pro" + ], + "transformer": { + "use": [ + "openai" + ] + } + } + ], + "Router": { + "default": "gemini,gemini-2.5-pro", + "background": "gemini,gemini-2.5-pro", + "think": "gemini,gemini-2.5-pro", + "longContext": "gemini,gemini-2.5-pro" + }, + "HOST": "0.0.0.0" +} +``` + +**포괄적인 예시 config.json** (다중 제공자 포함, README 기반): +이 예시는 여러 제공자를 설정한 경우입니다. 각 제공자의 API 키를 실제 값으로 교체하세요. + +```json +{ + "APIKEY": "your-secret-key", // 인증 키 (선택) + "PROXY_URL": "http://127.0.0.1:7890", // 프록시 (선택) + "LOG": true, // 로그 활성화 + "Providers": [ + { + "name": "openrouter", + "api_base_url": "https://openrouter.ai/api/v1/chat/completions", + "api_key": "sk-xxx", // 실제 OpenRouter API 키 + "models": [ + "google/gemini-2.5-pro-preview", + "anthropic/claude-sonnet-4", + "anthropic/claude-3.5-sonnet", + "anthropic/claude-3.7-sonnet:thinking" + ], + "transformer": { "use": ["openrouter"] } // 글로벌 트랜스포머 + }, + { + "name": "deepseek", + "api_base_url": "https://api.deepseek.com/chat/completions", + "api_key": "sk-xxx", // 실제 DeepSeek API 키 + "models": ["deepseek-chat", "deepseek-reasoner"], + "transformer": { + "use": ["deepseek"], + "deepseek-chat": { "use": ["tooluse"] } // 모델별 트랜스포머 + } + }, + { + "name": "ollama", + "api_base_url": "http://localhost:11434/v1/chat/completions", + "api_key": "ollama", + "models": ["qwen2.5-coder:latest"] + }, + { + "name": "gemini", + "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/", + "api_key": "sk-xxx", // 실제 Gemini API 키 + "models": ["gemini-2.5-flash", "gemini-2.5-pro"], + "transformer": { "use": ["gemini"] } + }, + { + "name": "volcengine", + "api_base_url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions", + "api_key": "sk-xxx", // 실제 Volcengine API 키 + "models": ["deepseek-v3-250324", "deepseek-r1-250528"], + "transformer": { "use": ["deepseek"] } + } + ], + "Router": { + "default": "deepseek,deepseek-chat", // 기본 모델 + "background": "ollama,qwen2.5-coder:latest", // 배경 작업 모델 + "think": "deepseek,deepseek-reasoner", // 생각 모드 모델 + "longContext": "openrouter,google/gemini-2.5-pro-preview", // 긴 컨텍스트 모델 + "webSearch": "gemini,gemini-2.5-flash" // 웹 검색 모델 + } +} +``` + +**상세 설명**: +- **Providers 섹션**: 각 제공자에 API 키를 입력하세요. 모델 목록은 제공자 문서를 확인하세요. +- **Transformer**: 제공자별로 요청을 조정합니다. 예: "gemini"는 Gemini API에 맞게 변환. +- **Router 섹션**: 시나리오별 모델을 지정합니다. 웹 검색은 모델이 지원해야 합니다 (예: `:online` 접미사 사용). +- 파일을 직접 편집한 후, 서버를 재시작하세요. +- 커스텀 트랜스포머: `transformers` 배열에 경로를 추가하여 확장하세요. + +### 3. Claude Code Router 실행 + +라우터와 함께 Claude Code를 시작합니다: + +```shell +ccr code +``` + +**상세 설명**: +- 이 명령어는 라우터 서버를 시작하고 Claude Code를 호출합니다. +- Claude Code 내에서 `/model provider_name,model_name`으로 모델을 전환하세요 (예: `/model openrouter,anthropic/claude-3.5-sonnet`). + +## 🤖 GitHub Actions 통합 + +GitHub 워크플로에서 Claude Code Router를 사용하려면 `.github/workflows/claude.yaml` 파일을 수정하세요. 예시: + +```yaml +name: Claude Code + +on: + issue_comment: + types: [created] + # ... other triggers + +jobs: + claude: + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + # ... other conditions + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + issues: read + id-token: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Prepare Environment + run: | + curl -fsSL https://bun.sh/install | bash + mkdir -p $HOME/.claude-code-router + cat << 'EOF' > $HOME/.claude-code-router/config.json + { + "log": true, + "OPENAI_API_KEY": "${{ secrets.OPENAI_API_KEY }}", + "OPENAI_BASE_URL": "https://api.deepseek.com", + "OPENAI_MODEL": "deepseek-chat" + } + EOF + shell: bash + + - name: Start Claude Code Router + run: | + nohup ~/.bun/bin/bunx @musistudio/claude-code-router@1.0.8 start & + shell: bash + + - name: Run Claude Code + id: claude + uses: anthropics/claude-code-action@beta + env: + ANTHROPIC_BASE_URL: http://localhost:3456 + with: + anthropic_api_key: "any-string-is-ok" +``` + +**상세 설명**: 이 설정은 GitHub Actions에서 라우터를 사용해 비용을 절감할 수 있습니다. secrets에 API 키를 저장하세요. + +## 📝 추가 자료 +- [Claude Code Router 공식 깃헙헙](https://github.com/musistudio/claude-code-router) +- [프로젝트 동기 및 작동 원리](https://github.com/musistudio/claude-code-router/blob/main/blog/en/project-motivation-and-how-it-works.md) +- [라우터로 더 많은 작업하기](https://github.com/musistudio/claude-code-router/blob/main/blog/en/maybe-we-can-do-more-with-the-route.md) + +문제가 발생하면 로그 파일을 확인하거나, GitHub 이슈를 제출하세요. 이 가이드를 통해 Claude Code Router를 효과적으로 사용하시기 바랍니다! \ No newline at end of file