mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
79a2953862
- Implement full coverage tests for Embedder model loading and embedding generation - Add CRUD operations and caching tests for VectorStore - Include cosine similarity computation tests - Validate semantic search accuracy and relevance through various queries - Establish performance benchmarks for embedding and search operations - Ensure edge cases and error handling are covered - Test thread safety and concurrent access scenarios - Verify availability of semantic search dependencies
217 lines
6.2 KiB
Markdown
217 lines
6.2 KiB
Markdown
# Tool Strategy - When to Use What
|
|
|
|
> **Focus**: Decision triggers and selection logic, NOT syntax (already registered with Claude)
|
|
|
|
## Quick Decision Tree
|
|
|
|
```
|
|
Need context?
|
|
├─ Exa available? → Use Exa (fastest, most comprehensive)
|
|
├─ Large codebase (>500 files)? → codex_lens
|
|
├─ Known files (<5)? → Read tool
|
|
└─ Unknown files? → smart_search → Read tool
|
|
|
|
Need to modify files?
|
|
├─ Built-in Edit fails? → mcp__ccw-tools__edit_file
|
|
└─ Still fails? → mcp__ccw-tools__write_file
|
|
|
|
Need to search?
|
|
├─ Semantic/concept search? → smart_search (mode=semantic)
|
|
├─ Exact pattern match? → Grep tool
|
|
└─ Multiple search modes needed? → smart_search (mode=auto)
|
|
```
|
|
|
|
---
|
|
|
|
## 1. Context Gathering Tools
|
|
|
|
### Exa (`mcp__exa__get_code_context_exa`)
|
|
|
|
**Use When**:
|
|
- ✅ Researching external APIs, libraries, frameworks
|
|
- ✅ Need recent documentation (post-cutoff knowledge)
|
|
- ✅ Looking for implementation examples in public repos
|
|
- ✅ Comparing architectural patterns across projects
|
|
|
|
**Don't Use When**:
|
|
- ❌ Searching internal codebase (use smart_search/codex_lens)
|
|
- ❌ Files already in working directory (use Read)
|
|
|
|
**Trigger Indicators**:
|
|
- User mentions specific library/framework names
|
|
- Questions about "best practices", "how does X work"
|
|
- Need to verify current API signatures
|
|
|
|
---
|
|
|
|
### read_file (`mcp__ccw-tools__read_file`)
|
|
|
|
**Use When**:
|
|
- ✅ Reading multiple related files at once (batch reading)
|
|
- ✅ Need directory traversal with pattern matching
|
|
- ✅ Searching file content with regex (`contentPattern`)
|
|
- ✅ Want to limit depth/file count for large directories
|
|
|
|
**Don't Use When**:
|
|
- ❌ Single file read → Use built-in Read tool (faster)
|
|
- ❌ Unknown file locations → Use smart_search first
|
|
- ❌ Need semantic search → Use smart_search or codex_lens
|
|
|
|
**Trigger Indicators**:
|
|
- Need to read "all TypeScript files in src/"
|
|
- Need to find "files containing TODO comments"
|
|
- Want to read "up to 20 config files"
|
|
|
|
**Advantages over Built-in Read**:
|
|
- Batch operation (multiple files in one call)
|
|
- Pattern-based filtering (glob + content regex)
|
|
- Directory traversal with depth control
|
|
|
|
---
|
|
|
|
### codex_lens (`mcp__ccw-tools__codex_lens`)
|
|
|
|
**Use When**:
|
|
- ✅ Large codebase (>500 files) requiring repeated searches
|
|
- ✅ Need semantic understanding of code relationships
|
|
- ✅ Working across multiple sessions (persistent index)
|
|
- ✅ Symbol-level navigation needed
|
|
|
|
**Don't Use When**:
|
|
- ❌ Small project (<100 files) → Use smart_search (no indexing overhead)
|
|
- ❌ One-time search → Use smart_search or Grep
|
|
- ❌ Files change frequently → Indexing overhead not worth it
|
|
|
|
**Trigger Indicators**:
|
|
- "Find all implementations of interface X"
|
|
- "What calls this function across the codebase?"
|
|
- Multi-session workflow on same codebase
|
|
|
|
**Action Selection**:
|
|
- `init`: First time in new codebase
|
|
- `search`: Find code patterns
|
|
- `search_files`: Find files by path/name pattern
|
|
- `symbol`: Get symbols in specific file
|
|
- `status`: Check if index exists/is stale
|
|
- `clean`: Remove stale index
|
|
|
|
---
|
|
|
|
### smart_search (`mcp__ccw-tools__smart_search`)
|
|
|
|
**Use When**:
|
|
- ✅ Don't know exact file locations
|
|
- ✅ Need concept/semantic search ("authentication logic")
|
|
- ✅ Medium-sized codebase (100-500 files)
|
|
- ✅ One-time or infrequent searches
|
|
|
|
**Don't Use When**:
|
|
- ❌ Known exact file path → Use Read directly
|
|
- ❌ Large codebase + repeated searches → Use codex_lens
|
|
- ❌ Exact pattern match → Use Grep (faster)
|
|
|
|
**Mode Selection**:
|
|
- `auto`: Let tool decide (default, safest)
|
|
- `exact`: Know exact pattern, need fast results
|
|
- `fuzzy`: Typo-tolerant file/symbol names
|
|
- `semantic`: Concept-based ("error handling", "data validation")
|
|
- `graph`: Dependency/relationship analysis
|
|
|
|
**Trigger Indicators**:
|
|
- "Find files related to user authentication"
|
|
- "Where is the payment processing logic?"
|
|
- "Locate database connection setup"
|
|
|
|
---
|
|
|
|
## 2. File Modification Tools
|
|
|
|
### edit_file (`mcp__ccw-tools__edit_file`)
|
|
|
|
**Use When**:
|
|
- ✅ Built-in Edit tool failed 1+ times
|
|
- ✅ Need dry-run preview before applying
|
|
- ✅ Need line-based operations (insert_after, insert_before)
|
|
- ✅ Need to replace all occurrences
|
|
|
|
**Don't Use When**:
|
|
- ❌ Built-in Edit hasn't failed yet → Try built-in first
|
|
- ❌ Need to create new file → Use write_file
|
|
|
|
**Trigger Indicators**:
|
|
- Built-in Edit returns "old_string not found"
|
|
- Built-in Edit fails due to whitespace/formatting
|
|
- Need to verify changes before applying (dryRun=true)
|
|
|
|
**Mode Selection**:
|
|
- `mode=update`: Replace text (similar to built-in Edit)
|
|
- `mode=line`: Line-based operations (insert_after, insert_before, delete)
|
|
|
|
---
|
|
|
|
### write_file (`mcp__ccw-tools__write_file`)
|
|
|
|
**Use When**:
|
|
- ✅ Creating brand new files
|
|
- ✅ MCP edit_file still fails (last resort)
|
|
- ✅ Need to completely replace file content
|
|
- ✅ Need backup before overwriting
|
|
|
|
**Don't Use When**:
|
|
- ❌ File exists + small change → Use Edit tools
|
|
- ❌ Built-in Edit hasn't been tried → Try built-in Edit first
|
|
|
|
**Trigger Indicators**:
|
|
- All Edit attempts failed
|
|
- Need to create new file with specific content
|
|
- User explicitly asks to "recreate file"
|
|
|
|
---
|
|
|
|
## 3. Decision Logic
|
|
|
|
### File Reading Priority
|
|
|
|
```
|
|
1. Known single file? → Built-in Read
|
|
2. Multiple files OR pattern matching? → mcp__ccw-tools__read_file
|
|
3. Unknown location? → smart_search, then Read
|
|
4. Large codebase + repeated access? → codex_lens
|
|
```
|
|
|
|
### File Editing Priority
|
|
|
|
```
|
|
1. Always try built-in Edit first
|
|
2. Fails 1+ times? → mcp__ccw-tools__edit_file
|
|
3. Still fails? → mcp__ccw-tools__write_file (last resort)
|
|
```
|
|
|
|
### Search Tool Priority
|
|
|
|
```
|
|
1. External knowledge? → Exa
|
|
2. Exact pattern in small codebase? → Built-in Grep
|
|
3. Semantic/unknown location? → smart_search
|
|
4. Large codebase + repeated searches? → codex_lens
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Anti-Patterns
|
|
|
|
**Don't**:
|
|
- Use codex_lens for one-time searches in small projects
|
|
- Use smart_search when file path is already known
|
|
- Use write_file before trying Edit tools
|
|
- Use Exa for internal codebase searches
|
|
- Use read_file for single file when Read tool works
|
|
|
|
**Do**:
|
|
- Start with simplest tool (Read, Edit, Grep)
|
|
- Escalate to MCP tools when built-ins fail
|
|
- Use semantic search (smart_search) for exploratory tasks
|
|
- Use indexed search (codex_lens) for large, stable codebases
|
|
- Use Exa for external/public knowledge
|
|
|