From 237a2867fb2d9a152255f20ee531b7283f8c03e1 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 4 Oct 2025 11:39:51 +0800 Subject: [PATCH] docs: Move Configuration section below Installation in README files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Reorganize README.md and README_CN.md structure - Move Configuration section directly after Installation for better flow - Update MCP Tools section to "Recommended" with warning notes in both languages - Improve user experience by placing setup instructions together 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 184 +++++++++++++++++++++++++-------------------------- README_CN.md | 178 +++++++++++++++++++++++++------------------------ 2 files changed, 184 insertions(+), 178 deletions(-) diff --git a/README.md b/README.md index 0bfdc088..c7db5da3 100644 --- a/README.md +++ b/README.md @@ -144,6 +144,98 @@ After installation, run the following command to ensure CCW is working: --- +## ⚙️ Configuration + +### **Prerequisites: Required Tools** + +Before using CCW, install the following command-line tools: + +#### **Core CLI Tools** + +| Tool | Purpose | Installation | +|------|---------|--------------| +| **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | +| **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | +| **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) | + +#### **System Utilities** + +| Tool | Purpose | Installation | +|------|---------|--------------| +| **ripgrep (rg)** | Fast code search | [Download](https://github.com/BurntSushi/ripgrep/releases) or `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) | +| **jq** | JSON processing | [Download](https://jqlang.github.io/jq/download/) or `brew install jq` (macOS), `apt install jq` (Ubuntu) | + +**Quick Install (All Tools):** + +```bash +# macOS +brew install ripgrep jq +npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code + +# Ubuntu/Debian +sudo apt install ripgrep jq +npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code + +# Windows (Chocolatey) +choco install ripgrep jq +npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code +``` + +### **Essential: Gemini CLI Setup** + +Configure Gemini CLI for optimal integration: + +```json +// ~/.gemini/settings.json +{ + "contextFileName": ["CLAUDE.md", "GEMINI.md"] +} +``` + +### **Recommended: .geminiignore** + +Optimize performance by excluding unnecessary files: + +```bash +# .geminiignore (in project root) +/dist/ +/build/ +/node_modules/ +/.next/ +*.tmp +*.log +/temp/ + +# Include important docs +!README.md +!**/CLAUDE.md +``` + +### **Recommended: MCP Tools** *(Enhanced Analysis)* + +MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recommended installation** - While CCW has fallback mechanisms, not installing MCP tools may lead to unexpected behavior or degraded performance in some workflows. + +#### Available MCP Servers + +| MCP Server | Purpose | Installation Guide | +|------------|---------|-------------------| +| **Exa MCP** | External API patterns & best practices | [Install Guide](https://smithery.ai/server/exa) | +| **Code Index MCP** | Advanced internal code search | [Install Guide](https://github.com/johnhuang316/code-index-mcp) | + +#### Benefits When Enabled +- 📊 **Faster Analysis**: Direct codebase indexing vs manual searching +- 🌐 **External Context**: Real-world API patterns and examples +- 🔍 **Advanced Search**: Pattern matching and similarity detection +- ⚡ **Better Reliability**: Primary tools for certain workflows + +⚠️ **Note**: Some workflows expect MCP tools to be available. Without them, you may experience: +- Slower code analysis and search operations +- Reduced context quality in some scenarios +- Fallback to less efficient traditional tools +- Potential unexpected behavior in advanced workflows + +--- + ## 🚀 Getting Started ### Complete Development Workflow @@ -268,98 +360,6 @@ After installation, run the following command to ensure CCW is working: --- -## ⚙️ Configuration - -### **Prerequisites: Required Tools** - -Before using CCW, install the following command-line tools: - -#### **Core CLI Tools** - -| Tool | Purpose | Installation | -|------|---------|--------------| -| **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | -| **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | -| **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) | - -#### **System Utilities** - -| Tool | Purpose | Installation | -|------|---------|--------------| -| **ripgrep (rg)** | Fast code search | [Download](https://github.com/BurntSushi/ripgrep/releases) or `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) | -| **jq** | JSON processing | [Download](https://jqlang.github.io/jq/download/) or `brew install jq` (macOS), `apt install jq` (Ubuntu) | - -**Quick Install (All Tools):** - -```bash -# macOS -brew install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code - -# Ubuntu/Debian -sudo apt install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code - -# Windows (Chocolatey) -choco install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code -``` - -### **Essential: Gemini CLI Setup** - -Configure Gemini CLI for optimal integration: - -```json -// ~/.gemini/settings.json -{ - "contextFileName": ["CLAUDE.md", "GEMINI.md"] -} -``` - -### **Recommended: .geminiignore** - -Optimize performance by excluding unnecessary files: - -```bash -# .geminiignore (in project root) -/dist/ -/build/ -/node_modules/ -/.next/ -*.tmp -*.log -/temp/ - -# Include important docs -!README.md -!**/CLAUDE.md -``` - -### **Recommended: MCP Tools** *(Enhanced Analysis)* - -MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recommended installation** - While CCW has fallback mechanisms, not installing MCP tools may lead to unexpected behavior or degraded performance in some workflows. - -#### Available MCP Servers - -| MCP Server | Purpose | Installation Guide | -|------------|---------|-------------------| -| **Exa MCP** | External API patterns & best practices | [Install Guide](https://smithery.ai/server/exa) | -| **Code Index MCP** | Advanced internal code search | [Install Guide](https://github.com/johnhuang316/code-index-mcp) | - -#### Benefits When Enabled -- 📊 **Faster Analysis**: Direct codebase indexing vs manual searching -- 🌐 **External Context**: Real-world API patterns and examples -- 🔍 **Advanced Search**: Pattern matching and similarity detection -- ⚡ **Better Reliability**: Primary tools for certain workflows - -⚠️ **Note**: Some workflows expect MCP tools to be available. Without them, you may experience: -- Slower code analysis and search operations -- Reduced context quality in some scenarios -- Fallback to less efficient traditional tools -- Potential unexpected behavior in advanced workflows - ---- - ## 🧩 How It Works: Design Philosophy ### The Core Problem diff --git a/README_CN.md b/README_CN.md index 893d2936..1b50f06e 100644 --- a/README_CN.md +++ b/README_CN.md @@ -144,6 +144,98 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo --- +## ⚙️ 配置 + +### **前置要求：必需工具** + +在使用 CCW 之前，请安装以下命令行工具： + +#### **核心 CLI 工具** + +| 工具 | 用途 | 安装方式 | +|------|------|----------| +| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | +| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | +| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) | + +#### **系统实用工具** + +| 工具 | 用途 | 安装方式 | +|------|------|----------| +| **ripgrep (rg)** | 快速代码搜索 | [下载](https://github.com/BurntSushi/ripgrep/releases) 或 `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) | +| **jq** | JSON 处理 | [下载](https://jqlang.github.io/jq/download/) 或 `brew install jq` (macOS), `apt install jq` (Ubuntu) | + +**快速安装（所有工具）：** + +```bash +# macOS +brew install ripgrep jq +npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code + +# Ubuntu/Debian +sudo apt install ripgrep jq +npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code + +# Windows (Chocolatey) +choco install ripgrep jq +npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code +``` + +### **必需: Gemini CLI 设置** + +配置 Gemini CLI 以实现最佳集成： + +```json +// ~/.gemini/settings.json +{ + "contextFileName": ["CLAUDE.md", "GEMINI.md"] +} +``` + +### **推荐: .geminiignore** + +通过排除不必要的文件来优化性能： + +```bash +# .geminiignore (在项目根目录) +/dist/ +/build/ +/node_modules/ +/.next/ +*.tmp +*.log +/temp/ + +# 包含重要文档 +!README.md +!**/CLAUDE.md +``` + +### **推荐: MCP 工具** *(增强分析)* + +MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装** - 虽然 CCW 具有回退机制，但不安装 MCP 工具可能会导致某些工作流出现意外行为或性能下降。 + +#### 可用的 MCP 服务器 + +| MCP 服务器 | 用途 | 安装指南 | +|------------|------|---------| +| **Exa MCP** | 外部 API 模式和最佳实践 | [安装指南](https://smithery.ai/server/exa) | +| **Code Index MCP** | 高级内部代码搜索 | [安装指南](https://github.com/johnhuang316/code-index-mcp) | + +#### 启用后的好处 +- 📊 **更快分析**: 直接代码库索引 vs 手动搜索 +- 🌐 **外部上下文**: 真实世界的 API 模式和示例 +- 🔍 **高级搜索**: 模式匹配和相似性检测 +- ⚡ **更好的可靠性**: 某些工作流的主要工具 + +⚠️ **注意**: 某些工作流期望 MCP 工具可用。如果没有安装，您可能会遇到： +- 代码分析和搜索操作速度较慢 +- 某些场景下上下文质量降低 +- 回退到效率较低的传统工具 +- 高级工作流中可能出现意外行为 + +--- + ## 🚀 快速入门 ### 完整开发工作流 @@ -268,92 +360,6 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo --- -## ⚙️ 配置 - -### **前置要求：必需工具** - -在使用 CCW 之前，请安装以下命令行工具： - -#### **核心 CLI 工具** - -| 工具 | 用途 | 安装方式 | -|------|------|----------| -| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | -| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | -| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) | - -#### **系统实用工具** - -| 工具 | 用途 | 安装方式 | -|------|------|----------| -| **ripgrep (rg)** | 快速代码搜索 | [下载](https://github.com/BurntSushi/ripgrep/releases) 或 `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) | -| **jq** | JSON 处理 | [下载](https://jqlang.github.io/jq/download/) 或 `brew install jq` (macOS), `apt install jq` (Ubuntu) | - -**快速安装（所有工具）：** - -```bash -# macOS -brew install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code - -# Ubuntu/Debian -sudo apt install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code - -# Windows (Chocolatey) -choco install ripgrep jq -npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code -``` - -### **必需: Gemini CLI 设置** - -配置 Gemini CLI 以实现最佳集成： - -```json -// ~/.gemini/settings.json -{ - "contextFileName": ["CLAUDE.md", "GEMINI.md"] -} -``` - -### **推荐: .geminiignore** - -通过排除不必要的文件来优化性能： - -```bash -# .geminiignore (在项目根目录) -/dist/ -/build/ -/node_modules/ -/.next/ -*.tmp -*.log -/temp/ - -# 包含重要文档 -!README.md -!**/CLAUDE.md -``` - -### **可选: MCP 工具** *(增强分析)* - -MCP (模型上下文协议) 工具提供高级代码库分析。**完全可选** - CCW 在没有它们的情况下也能完美工作。 - -#### 可用的 MCP 服务器 - -| MCP 服务器 | 用途 | 安装指南 | -|------------|------|---------| -| **Exa MCP** | 外部 API 模式和最佳实践 | [安装指南](https://smithery.ai/server/exahttps://smithery.ai/server/exa) | -| **Code Index MCP** | 高级内部代码搜索 | [安装指南](https://github.com/johnhuang316/code-index-mcp) | - -#### 启用后的好处 -- 📊 **更快分析**: 直接代码库索引 vs 手动搜索 -- 🌐 **外部上下文**: 真实世界的 API 模式和示例 -- 🔍 **高级搜索**: 模式匹配和相似性检测 -- ⚡ **自动回退**: MCP 不可用时使用传统工具 - ---- - ## 🧩 工作原理：设计理念 ### 核心问题