mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-14 02:42:04 +08:00
feat: add batch replan mode and comprehensive skill system
- Add batch processing mode to /task:replan command - Support for verification report input - TodoWrite integration for progress tracking - Automatic backup management - Enhance /workflow:action-plan-verify with batch remediation - Save verification report to .process directory - Provide batch replan command suggestions - Add comprehensive skill documentation - Codex: autonomous development workflows - Gemini/Qwen: code analysis and documentation - Context-search: strategic context gathering - Prompt-enhancer: ambiguous prompt refinement - Clean up CLAUDE.md strategy references 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
92
.claude/skills/context-search/SKILL.md
Normal file
92
.claude/skills/context-search/SKILL.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
name: Context Search
|
||||
description: Strategic context search tool selection for both planning and execution phases. Use during PLANNING (analyzing architecture, understanding existing code structure, gathering context) and EXECUTION (searching files, discovering implementations, locating dependencies). Triggers include "search for", "find files", "locate code", "analyze structure", "understand codebase", or when planning/implementing features. MANDATORY before any planning or implementation tasks.
|
||||
allowed-tools: Bash, Grep, Glob, Read, mcp__code-index__search_code_advanced, mcp__code-index__find_files
|
||||
---
|
||||
|
||||
# Context Search
|
||||
|
||||
Strategic framework for selecting the right search tool based on task requirements.
|
||||
|
||||
## Execution Environment
|
||||
|
||||
**CRITICAL**: All commands execute in **Bash environment** (Git Bash on Windows, Bash on Linux/macOS)
|
||||
|
||||
**❌ Forbidden**: Windows-specific commands (`findstr`, `dir`, `where`, `type`, `copy`, `del`)
|
||||
**✅ Required**: Use Bash equivalents (`grep`, `find`, `which`, `cat`, `cp`, `rm`)
|
||||
|
||||
## Tool Selection Framework
|
||||
|
||||
Use this decision tree to select the right search tool:
|
||||
|
||||
### 1. Semantic File Discovery
|
||||
**Tool**: `codebase-retrieval` (Gemini CLI)
|
||||
**When**: Need files relevant to a task/feature/concept
|
||||
**Command**: `~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: [description]"`
|
||||
|
||||
### 2. Content Search
|
||||
**Tool**: `rg` (ripgrep) - preferred
|
||||
**When**: Searching code content with patterns
|
||||
**Fallback**: `grep` (when rg unavailable)
|
||||
|
||||
### 3. File/Directory Location
|
||||
**Tool**: `find`
|
||||
**When**: Locating files by name patterns
|
||||
**Alternative**: MCP Code Index for glob patterns
|
||||
|
||||
### 4. Program Architecture Analysis
|
||||
**Tool**: `get_modules_by_depth.sh`
|
||||
**When**: Understanding program structure (MANDATORY before planning)
|
||||
**Command**: `~/.claude/scripts/get_modules_by_depth.sh`
|
||||
|
||||
## Decision Principles
|
||||
|
||||
- **Semantic discovery first** - Use codebase-retrieval for intelligent file discovery
|
||||
- **Speed matters** - Prefer rg over grep for content search
|
||||
- **Architecture before implementation** - Run get_modules_by_depth.sh before planning
|
||||
- **No Windows commands** - Always use Bash equivalents
|
||||
|
||||
## Tool Selection Matrix
|
||||
|
||||
| Need | Primary Tool | Use Case |
|
||||
|------|-------------|----------|
|
||||
| **Semantic file discovery** | codebase-retrieval | Find files relevant to task/feature context |
|
||||
| **Pattern matching** | rg (ripgrep) | Search code content with regex |
|
||||
| **File name lookup** | find | Locate files by name patterns |
|
||||
| **Architecture analysis** | get_modules_by_depth.sh | Understand program structure |
|
||||
|
||||
## Workflow Integration
|
||||
|
||||
Follow this recommended pattern for codebase exploration:
|
||||
|
||||
1. **Architecture Analysis** (if planning)
|
||||
```bash
|
||||
~/.claude/scripts/get_modules_by_depth.sh
|
||||
```
|
||||
|
||||
2. **Semantic Discovery** (find relevant files)
|
||||
```bash
|
||||
~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: [task]"
|
||||
```
|
||||
|
||||
3. **Content Search** (search within files)
|
||||
```bash
|
||||
rg "[pattern]" --type [filetype]
|
||||
```
|
||||
|
||||
4. **Deep Analysis** (understand found code)
|
||||
- Use Read tool for specific files
|
||||
- Use Gemini for architecture analysis
|
||||
|
||||
## Performance Tips
|
||||
|
||||
- **rg > grep** - Always prefer ripgrep for content search
|
||||
- **Type filters** - Use `--type` to limit file types (e.g., `--type js`)
|
||||
- **Exclude patterns** - Use `--glob '!node_modules'` to exclude common directories
|
||||
- **Literal strings** - Use `-F` flag for exact matches (no regex overhead)
|
||||
|
||||
## Examples
|
||||
|
||||
For detailed command examples and workflow patterns, see [examples.md](examples.md).
|
||||
|
||||
For complete command reference and options, see [reference.md](reference.md).
|
||||
390
.claude/skills/context-search/examples.md
Normal file
390
.claude/skills/context-search/examples.md
Normal file
@@ -0,0 +1,390 @@
|
||||
# Context Search Examples
|
||||
|
||||
This document provides practical examples of using context search tools in different scenarios.
|
||||
|
||||
## Quick Command Examples
|
||||
|
||||
### Semantic File Discovery
|
||||
|
||||
```bash
|
||||
# Find files relevant to authentication
|
||||
~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: user authentication and JWT"
|
||||
|
||||
# Find files related to database schema
|
||||
~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: database schema and migrations"
|
||||
|
||||
# In Bash tool (with timeout)
|
||||
bash(~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: API endpoints")
|
||||
```
|
||||
|
||||
### Program Architecture Analysis
|
||||
|
||||
```bash
|
||||
# Analyze program structure (run before planning)
|
||||
~/.claude/scripts/get_modules_by_depth.sh
|
||||
|
||||
# In Bash tool
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh)
|
||||
```
|
||||
|
||||
### Content Search with ripgrep
|
||||
|
||||
```bash
|
||||
# Search in specific file types
|
||||
rg "pattern" --type js # Search in JavaScript files
|
||||
rg "pattern" --type ts # Search in TypeScript files
|
||||
rg "pattern" --type py # Search in Python files
|
||||
|
||||
# Case-insensitive search
|
||||
rg -i "case-insensitive"
|
||||
|
||||
# Show line numbers
|
||||
rg -n "show-line-numbers"
|
||||
|
||||
# Show context lines
|
||||
rg -A 3 -B 3 "context-lines" # Show 3 lines before and after
|
||||
|
||||
# Exclude directories
|
||||
rg "pattern" --glob '!node_modules'
|
||||
rg "pattern" --glob '!*.test.js'
|
||||
|
||||
# Literal string search (no regex)
|
||||
rg -F "exact.string.match"
|
||||
|
||||
# Multiple file types
|
||||
rg "pattern" --type-add 'web:*.{html,css,js}' --type web
|
||||
```
|
||||
|
||||
### File Search with find
|
||||
|
||||
```bash
|
||||
# Find TypeScript files
|
||||
find . -name "*.ts" -type f
|
||||
|
||||
# Find files excluding node_modules
|
||||
find . -path "*/node_modules" -prune -o -name "*.js" -print
|
||||
|
||||
# Find files by multiple patterns
|
||||
find . \( -name "*.ts" -o -name "*.tsx" \) -type f
|
||||
|
||||
# Find and execute command on results
|
||||
find . -name "*.test.js" -exec grep -l "describe" {} \;
|
||||
```
|
||||
|
||||
### grep Alternatives (when rg unavailable)
|
||||
|
||||
```bash
|
||||
# Recursive search
|
||||
grep -r "pattern" .
|
||||
|
||||
# Case-insensitive with line numbers
|
||||
grep -n -i "pattern" file.txt
|
||||
|
||||
# Show context
|
||||
grep -A 3 -B 3 "pattern" file.txt
|
||||
|
||||
# Search multiple files
|
||||
grep "pattern" *.js
|
||||
```
|
||||
|
||||
## Workflow Integration Patterns
|
||||
|
||||
### Pattern 1: Semantic Discovery → Content Search → Analysis
|
||||
|
||||
```bash
|
||||
# Step 1: Discover relevant files
|
||||
~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: authentication system"
|
||||
|
||||
# Step 2: Search within discovered files
|
||||
rg "jwt|token|auth" --type ts
|
||||
|
||||
# Step 3: Read specific files for analysis
|
||||
# Use Read tool on identified files
|
||||
```
|
||||
|
||||
### Pattern 2: Architecture Analysis for Planning
|
||||
|
||||
```bash
|
||||
# MANDATORY before any planning task
|
||||
~/.claude/scripts/get_modules_by_depth.sh
|
||||
|
||||
# Then proceed with planning based on structure
|
||||
```
|
||||
|
||||
### Pattern 3: Workflow System Exploration
|
||||
|
||||
```bash
|
||||
# Search for task definitions
|
||||
rg "IMPL-\d+" .workflow/ --type json
|
||||
|
||||
# Locate task files
|
||||
find .workflow/ -name "*.json" -path "*/.task/*"
|
||||
|
||||
# Analyze workflow structure
|
||||
rg "status.*pending" .workflow/.task/
|
||||
|
||||
# Show task dependencies
|
||||
rg "depends_on" .workflow/.task/ -A 2
|
||||
|
||||
# Find active sessions
|
||||
find .workflow/ -name ".active-*"
|
||||
|
||||
# Search for session references
|
||||
rg "WFS-" .workflow/ --type json
|
||||
```
|
||||
|
||||
### Pattern 4: Code Pattern Analysis
|
||||
|
||||
```bash
|
||||
# Find flow control patterns with context
|
||||
rg "flow_control" .workflow/ -B 2 -A 5
|
||||
|
||||
# Find implementation plans
|
||||
find . -name "IMPL_PLAN.md" -exec grep -l "requirements" {} \;
|
||||
|
||||
# Search for specific implementation patterns
|
||||
rg "async.*function" --type ts -A 5
|
||||
|
||||
# Find error handling patterns
|
||||
rg "try.*catch|throw new Error" --type js -B 2 -A 3
|
||||
```
|
||||
|
||||
### Pattern 5: Test Discovery
|
||||
|
||||
```bash
|
||||
# Find all test files
|
||||
find . -name "*.test.ts" -o -name "*.spec.ts"
|
||||
|
||||
# Search for specific test patterns
|
||||
rg "describe\(|it\(|test\(" --type ts
|
||||
|
||||
# Find tests for specific functionality
|
||||
rg "test.*authentication|describe.*auth" --type ts
|
||||
|
||||
# Find test files with specific assertions
|
||||
rg "expect\(.*\)\.toBe" --type ts
|
||||
```
|
||||
|
||||
### Pattern 6: API Endpoint Discovery
|
||||
|
||||
```bash
|
||||
# Find API route definitions
|
||||
rg "app\.(get|post|put|delete|patch)" --type js
|
||||
|
||||
# Find Express router usage
|
||||
rg "Router\(\)|express\.Router" --type ts
|
||||
|
||||
# Find API endpoint handlers
|
||||
rg "@(Get|Post|Put|Delete|Patch)\(" --type ts
|
||||
```
|
||||
|
||||
### Pattern 7: Configuration File Discovery
|
||||
|
||||
```bash
|
||||
# Find configuration files
|
||||
find . -name "*.config.js" -o -name "*.config.ts" -o -name ".env*"
|
||||
|
||||
# Search for environment variables
|
||||
rg "process\.env\." --type ts
|
||||
|
||||
# Find configuration patterns
|
||||
rg "config\.|configuration" --type ts
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: Understanding Authentication System
|
||||
|
||||
```bash
|
||||
# 1. Find auth-related files
|
||||
~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: authentication, JWT, sessions"
|
||||
|
||||
# 2. Search for auth implementations
|
||||
rg "authenticate|authorization" --type ts
|
||||
|
||||
# 3. Find middleware usage
|
||||
rg "middleware.*auth|auth.*middleware" --type ts
|
||||
|
||||
# 4. Locate test files
|
||||
rg "auth.*test|describe.*auth" --type ts
|
||||
```
|
||||
|
||||
### Scenario 2: Database Schema Analysis
|
||||
|
||||
```bash
|
||||
# 1. Find database files
|
||||
find . -name "*schema*" -o -name "*migration*" -o -name "*model*"
|
||||
|
||||
# 2. Search for schema definitions
|
||||
rg "Schema|model\.define|createTable" --type ts
|
||||
|
||||
# 3. Find database queries
|
||||
rg "SELECT|INSERT|UPDATE|DELETE" --type sql
|
||||
|
||||
# 4. Find ORM usage
|
||||
rg "findOne|findAll|create|update|destroy" --type ts
|
||||
```
|
||||
|
||||
### Scenario 3: Component Structure Exploration
|
||||
|
||||
```bash
|
||||
# 1. Analyze architecture
|
||||
~/.claude/scripts/get_modules_by_depth.sh
|
||||
|
||||
# 2. Find component files
|
||||
find . -name "*.tsx" -o -name "*.jsx"
|
||||
|
||||
# 3. Search for component patterns
|
||||
rg "export (default )?(function|const).*Component" --type tsx
|
||||
|
||||
# 4. Find component imports
|
||||
rg "import.*from.*components" --type tsx
|
||||
```
|
||||
|
||||
### Scenario 4: Error Handling Audit
|
||||
|
||||
```bash
|
||||
# 1. Find error handling patterns
|
||||
rg "try.*catch|throw new" --type ts -B 1 -A 3
|
||||
|
||||
# 2. Find error classes
|
||||
rg "class.*Error extends|extends Error" --type ts
|
||||
|
||||
# 3. Find error middleware
|
||||
rg "errorHandler|error.*middleware" --type ts
|
||||
|
||||
# 4. Find error logging
|
||||
rg "console\.error|logger\.error|log\.error" --type ts
|
||||
```
|
||||
|
||||
### Scenario 5: Dependency Analysis
|
||||
|
||||
```bash
|
||||
# 1. Find package.json files
|
||||
find . -name "package.json"
|
||||
|
||||
# 2. Search for specific package usage
|
||||
rg "from ['\"]express['\"]|require\(['\"]express['\"]\)" --type ts
|
||||
|
||||
# 3. Find import patterns
|
||||
rg "^import.*from" --type ts | head -50
|
||||
|
||||
# 4. Find dynamic imports
|
||||
rg "import\(|require\(" --type ts
|
||||
```
|
||||
|
||||
## MCP Tool Integration Examples
|
||||
|
||||
### Using Code Index Tools
|
||||
|
||||
```bash
|
||||
# Search code patterns
|
||||
mcp__code-index__search_code_advanced(pattern="function.*auth", file_pattern="*.ts")
|
||||
|
||||
# Find files by pattern
|
||||
mcp__code-index__find_files(pattern="*.test.js")
|
||||
|
||||
# Find files with wildcard
|
||||
mcp__code-index__find_files(pattern="*async*")
|
||||
|
||||
# Refresh index after git operations
|
||||
mcp__code-index__refresh_index()
|
||||
|
||||
# Get file summary
|
||||
mcp__code-index__get_file_summary(file_path="src/auth/index.ts")
|
||||
```
|
||||
|
||||
### Combined MCP and CLI Workflow
|
||||
|
||||
```bash
|
||||
# 1. Find files with MCP
|
||||
mcp__code-index__find_files(pattern="*auth*")
|
||||
|
||||
# 2. Search content with ripgrep
|
||||
rg "jwt|token" --type ts
|
||||
|
||||
# 3. Get file summaries
|
||||
mcp__code-index__get_file_summary(file_path="src/auth/jwt.ts")
|
||||
|
||||
# 4. Semantic discovery with Gemini
|
||||
~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: authentication"
|
||||
```
|
||||
|
||||
## Performance Optimization Examples
|
||||
|
||||
### Optimized Searches
|
||||
|
||||
```bash
|
||||
# Fast: Use type filters
|
||||
rg "pattern" --type ts
|
||||
|
||||
# Faster: Exclude directories
|
||||
rg "pattern" --glob '!node_modules' --glob '!dist'
|
||||
|
||||
# Fastest: Literal search (no regex)
|
||||
rg -F "exact.match" --type ts
|
||||
|
||||
# Very fast: Limit to specific directory
|
||||
rg "pattern" src/ --type ts
|
||||
```
|
||||
|
||||
### Avoiding Slow Searches
|
||||
|
||||
```bash
|
||||
# ❌ Slow: No type filter, includes node_modules
|
||||
grep -r "pattern" .
|
||||
|
||||
# ✅ Fast: Type filter and exclusions
|
||||
rg "pattern" --type ts --glob '!node_modules'
|
||||
|
||||
# ❌ Slow: Complex regex on large files
|
||||
rg ".*complex.*regex.*pattern.*" .
|
||||
|
||||
# ✅ Fast: Simple patterns, literal when possible
|
||||
rg -F "simple" --type ts
|
||||
```
|
||||
|
||||
## Troubleshooting Examples
|
||||
|
||||
### When rg is not available
|
||||
|
||||
```bash
|
||||
# Fall back to grep
|
||||
grep -r "pattern" --include="*.ts" --exclude-dir="node_modules" .
|
||||
|
||||
# Or use find + grep
|
||||
find . -name "*.ts" -not -path "*/node_modules/*" -exec grep -l "pattern" {} \;
|
||||
```
|
||||
|
||||
### When searching produces too many results
|
||||
|
||||
```bash
|
||||
# Add more specific patterns
|
||||
rg "function authenticate" --type ts
|
||||
|
||||
# Limit to specific directories
|
||||
rg "pattern" src/auth/ --type ts
|
||||
|
||||
# Use word boundaries
|
||||
rg "\bpattern\b" --type ts
|
||||
|
||||
# Show only filenames
|
||||
rg "pattern" --type ts -l
|
||||
```
|
||||
|
||||
### When searching is too slow
|
||||
|
||||
```bash
|
||||
# Use literal search
|
||||
rg -F "literal.string" --type ts
|
||||
|
||||
# Limit search depth
|
||||
find . -maxdepth 3 -name "*.ts"
|
||||
|
||||
# Search specific directory
|
||||
rg "pattern" src/ --type ts
|
||||
|
||||
# Use file type filters
|
||||
rg "pattern" --type-list # List available types
|
||||
rg "pattern" --type ts --type js
|
||||
```
|
||||
625
.claude/skills/context-search/reference.md
Normal file
625
.claude/skills/context-search/reference.md
Normal file
@@ -0,0 +1,625 @@
|
||||
# Context Search Command Reference
|
||||
|
||||
Complete reference for all context search tools and commands.
|
||||
|
||||
## Tool Overview
|
||||
|
||||
### codebase-retrieval (Semantic Discovery)
|
||||
|
||||
**Purpose**: Intelligent file discovery based on task/feature context using Gemini CLI
|
||||
|
||||
**Command Syntax**:
|
||||
```bash
|
||||
~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: [description]"
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `--all-files`: Enable all-files mode for semantic discovery
|
||||
- `-p "prompt"`: Provide task/feature description
|
||||
|
||||
**Use When**:
|
||||
- Need to find files related to a concept or feature
|
||||
- Don't know exact file names
|
||||
- Want AI-powered file discovery
|
||||
- Exploring unfamiliar codebase
|
||||
|
||||
**Best Practices**:
|
||||
- Be specific in description
|
||||
- Include technology stack terms (e.g., "JWT authentication", "React components")
|
||||
- Mention file types if relevant (e.g., "TypeScript interfaces")
|
||||
|
||||
---
|
||||
|
||||
### rg (ripgrep)
|
||||
|
||||
**Purpose**: Fast content search with regex support
|
||||
|
||||
**Command Syntax**:
|
||||
```bash
|
||||
rg [OPTIONS] PATTERN [PATH...]
|
||||
```
|
||||
|
||||
**Common Options**:
|
||||
|
||||
| Option | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `-i, --ignore-case` | Case-insensitive search | `rg -i "pattern"` |
|
||||
| `-n, --line-number` | Show line numbers | `rg -n "pattern"` |
|
||||
| `-A NUM` | Show NUM lines after match | `rg -A 3 "pattern"` |
|
||||
| `-B NUM` | Show NUM lines before match | `rg -B 3 "pattern"` |
|
||||
| `-C NUM` | Show NUM lines before and after | `rg -C 3 "pattern"` |
|
||||
| `--type TYPE` | Search only TYPE files | `rg --type ts "pattern"` |
|
||||
| `--glob PATTERN` | Include/exclude files by glob | `rg --glob '!*.test.js'` |
|
||||
| `-F, --fixed-strings` | Treat pattern as literal string | `rg -F "exact.match"` |
|
||||
| `-l, --files-with-matches` | Show only filenames | `rg -l "pattern"` |
|
||||
| `-c, --count` | Show count of matches per file | `rg -c "pattern"` |
|
||||
| `-w, --word-regexp` | Match whole words only | `rg -w "pattern"` |
|
||||
| `--no-ignore` | Don't respect .gitignore | `rg --no-ignore "pattern"` |
|
||||
|
||||
**File Type Filters**:
|
||||
```bash
|
||||
rg --type-list # List all available types
|
||||
|
||||
# Common types
|
||||
rg --type js "pattern" # JavaScript
|
||||
rg --type ts "pattern" # TypeScript
|
||||
rg --type py "pattern" # Python
|
||||
rg --type rust "pattern" # Rust
|
||||
rg --type go "pattern" # Go
|
||||
rg --type java "pattern" # Java
|
||||
rg --type cpp "pattern" # C++
|
||||
rg --type html "pattern" # HTML
|
||||
rg --type css "pattern" # CSS
|
||||
rg --type json "pattern" # JSON
|
||||
rg --type yaml "pattern" # YAML
|
||||
```
|
||||
|
||||
**Glob Patterns**:
|
||||
```bash
|
||||
# Include patterns
|
||||
rg "pattern" --glob '*.ts' # Only TypeScript files
|
||||
rg "pattern" --glob 'src/**/*.js' # JS files in src/
|
||||
|
||||
# Exclude patterns
|
||||
rg "pattern" --glob '!*.test.js' # Exclude test files
|
||||
rg "pattern" --glob '!node_modules' # Exclude node_modules
|
||||
rg "pattern" --glob '!dist' # Exclude dist directory
|
||||
|
||||
# Multiple globs
|
||||
rg "pattern" --glob '*.ts' --glob '*.tsx' --glob '!*.test.*'
|
||||
```
|
||||
|
||||
**Performance Tips**:
|
||||
- Use `--type` instead of `--glob` when possible (faster)
|
||||
- Use `-F` for literal strings (no regex overhead)
|
||||
- Exclude large directories with `--glob '!node_modules'`
|
||||
- Limit search to specific paths: `rg "pattern" src/`
|
||||
|
||||
---
|
||||
|
||||
### find
|
||||
|
||||
**Purpose**: Locate files and directories by name patterns
|
||||
|
||||
**Command Syntax**:
|
||||
```bash
|
||||
find [PATH...] [OPTIONS] [EXPRESSION]
|
||||
```
|
||||
|
||||
**Common Options**:
|
||||
|
||||
| Option | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `-name PATTERN` | Match filename pattern | `find . -name "*.ts"` |
|
||||
| `-iname PATTERN` | Case-insensitive name match | `find . -iname "*.TXT"` |
|
||||
| `-type TYPE` | Match file type (f=file, d=dir) | `find . -type f` |
|
||||
| `-path PATTERN` | Match full path pattern | `find . -path "*/src/*"` |
|
||||
| `-prune` | Don't descend into directory | `find . -path "*/node_modules" -prune` |
|
||||
| `-maxdepth N` | Descend at most N levels | `find . -maxdepth 2` |
|
||||
| `-mindepth N` | Start at least N levels deep | `find . -mindepth 1` |
|
||||
| `-exec CMD {} \;` | Execute command on results | `find . -name "*.js" -exec wc -l {} \;` |
|
||||
|
||||
**Common Patterns**:
|
||||
|
||||
```bash
|
||||
# Find files by extension
|
||||
find . -name "*.ts" -type f
|
||||
find . -name "*.js" -o -name "*.jsx"
|
||||
|
||||
# Find files excluding directories
|
||||
find . -path "*/node_modules" -prune -o -name "*.js" -print
|
||||
find . -path "*/dist" -prune -o -path "*/.git" -prune -o -type f -print
|
||||
|
||||
# Find files and execute command
|
||||
find . -name "*.test.js" -exec grep -l "describe" {} \;
|
||||
find . -name "*.ts" -type f -exec wc -l {} \; | sort -n
|
||||
|
||||
# Find by depth
|
||||
find . -maxdepth 2 -name "*.json"
|
||||
find . -mindepth 2 -maxdepth 3 -name "package.json"
|
||||
|
||||
# Find directories
|
||||
find . -type d -name "*test*"
|
||||
|
||||
# Find empty files
|
||||
find . -type f -empty
|
||||
|
||||
# Find files modified recently
|
||||
find . -name "*.js" -mtime -7 # Modified in last 7 days
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### grep
|
||||
|
||||
**Purpose**: Built-in pattern matching (fallback when rg unavailable)
|
||||
|
||||
**Command Syntax**:
|
||||
```bash
|
||||
grep [OPTIONS] PATTERN [FILE...]
|
||||
```
|
||||
|
||||
**Common Options**:
|
||||
|
||||
| Option | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `-r, --recursive` | Search recursively | `grep -r "pattern" .` |
|
||||
| `-i, --ignore-case` | Case-insensitive | `grep -i "pattern" file` |
|
||||
| `-n, --line-number` | Show line numbers | `grep -n "pattern" file` |
|
||||
| `-A NUM` | Show NUM lines after | `grep -A 3 "pattern" file` |
|
||||
| `-B NUM` | Show NUM lines before | `grep -B 3 "pattern" file` |
|
||||
| `-C NUM` | Show NUM lines context | `grep -C 3 "pattern" file` |
|
||||
| `-l, --files-with-matches` | Show only filenames | `grep -l "pattern" *.js` |
|
||||
| `-c, --count` | Count matches per file | `grep -c "pattern" *.js` |
|
||||
| `-v, --invert-match` | Show non-matching lines | `grep -v "pattern" file` |
|
||||
| `-w, --word-regexp` | Match whole words | `grep -w "word" file` |
|
||||
| `-E, --extended-regexp` | Extended regex | `grep -E "pat1|pat2" file` |
|
||||
| `--include=PATTERN` | Include files matching | `grep -r "pattern" --include="*.js"` |
|
||||
| `--exclude=PATTERN` | Exclude files matching | `grep -r "pattern" --exclude="*.test.js"` |
|
||||
| `--exclude-dir=PATTERN` | Exclude directories | `grep -r "pattern" --exclude-dir="node_modules"` |
|
||||
|
||||
**Common Patterns**:
|
||||
|
||||
```bash
|
||||
# Recursive search
|
||||
grep -r "pattern" .
|
||||
grep -r "pattern" --include="*.ts" --exclude-dir="node_modules" .
|
||||
|
||||
# Case-insensitive with line numbers
|
||||
grep -i -n "pattern" file.txt
|
||||
|
||||
# Show context
|
||||
grep -A 3 -B 3 "pattern" file.txt
|
||||
grep -C 5 "pattern" file.txt
|
||||
|
||||
# Multiple patterns
|
||||
grep -E "pattern1|pattern2" file.txt
|
||||
grep "pattern1" file.txt | grep "pattern2"
|
||||
|
||||
# Invert match (exclude lines)
|
||||
grep -v "exclude" file.txt
|
||||
|
||||
# Count matches
|
||||
grep -c "pattern" *.js
|
||||
|
||||
# Find files containing pattern
|
||||
grep -l "pattern" *.js
|
||||
grep -r -l "pattern" --include="*.ts" .
|
||||
```
|
||||
|
||||
**Note**: Prefer `rg` over `grep` for better performance and features.
|
||||
|
||||
---
|
||||
|
||||
### get_modules_by_depth.sh
|
||||
|
||||
**Purpose**: Program architecture analysis and structural discovery
|
||||
|
||||
**Command Syntax**:
|
||||
```bash
|
||||
~/.claude/scripts/get_modules_by_depth.sh
|
||||
```
|
||||
|
||||
**No Options**: Script runs automatically and analyzes current directory structure
|
||||
|
||||
**Use When**:
|
||||
- Starting a new planning task (MANDATORY)
|
||||
- Need to understand program architecture
|
||||
- Exploring project structure
|
||||
- Before making structural changes
|
||||
|
||||
**Output**: Hierarchical view of program modules and their relationships
|
||||
|
||||
**Best Practices**:
|
||||
- Run before any planning or architecture work
|
||||
- Run from project root directory
|
||||
- Use output to inform file organization decisions
|
||||
- Reference output when discussing architecture
|
||||
|
||||
---
|
||||
|
||||
## MCP Code Index Tools
|
||||
|
||||
### mcp__code-index__search_code_advanced
|
||||
|
||||
**Purpose**: Advanced code pattern search with fuzzy matching
|
||||
|
||||
**Parameters**:
|
||||
```typescript
|
||||
{
|
||||
pattern: string, // Search pattern (regex or literal)
|
||||
case_sensitive?: boolean, // Default: true
|
||||
context_lines?: number, // Default: 0
|
||||
file_pattern?: string, // Glob pattern (e.g., "*.ts")
|
||||
fuzzy?: boolean, // Default: false
|
||||
max_line_length?: number, // Default: none
|
||||
regex?: boolean // Default: null (auto-detect)
|
||||
}
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# Basic search
|
||||
mcp__code-index__search_code_advanced(pattern="function.*auth")
|
||||
|
||||
# With file filter
|
||||
mcp__code-index__search_code_advanced(pattern="interface.*Props", file_pattern="*.tsx")
|
||||
|
||||
# Case-insensitive with context
|
||||
mcp__code-index__search_code_advanced(pattern="error", case_sensitive=false, context_lines=3)
|
||||
|
||||
# Fuzzy search
|
||||
mcp__code-index__search_code_advanced(pattern="auhtenticate", fuzzy=true)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### mcp__code-index__find_files
|
||||
|
||||
**Purpose**: Find files by glob pattern using pre-built index
|
||||
|
||||
**Parameters**:
|
||||
```typescript
|
||||
{
|
||||
pattern: string // Glob pattern (e.g., "*.ts", "*auth*")
|
||||
}
|
||||
```
|
||||
|
||||
**Pattern Types**:
|
||||
- Full path matching: `src/**/*.ts`
|
||||
- Filename only: `README.md` (finds all README files)
|
||||
- Wildcard: `*auth*` (files containing "auth")
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# Find all Markdown files
|
||||
mcp__code-index__find_files(pattern="*.md")
|
||||
|
||||
# Find files with wildcard
|
||||
mcp__code-index__find_files(pattern="*auth*")
|
||||
|
||||
# Find test files
|
||||
mcp__code-index__find_files(pattern="*.test.ts")
|
||||
|
||||
# Find specific file
|
||||
mcp__code-index__find_files(pattern="package.json")
|
||||
```
|
||||
|
||||
**Note**: Use wildcard patterns for better results than exact matches.
|
||||
|
||||
---
|
||||
|
||||
### mcp__code-index__refresh_index
|
||||
|
||||
**Purpose**: Manually refresh project file index
|
||||
|
||||
**Parameters**: None
|
||||
|
||||
**Use When**:
|
||||
- After major git operations (pull, merge, checkout)
|
||||
- File watcher is disabled or unavailable
|
||||
- Index seems outdated
|
||||
- Large-scale file operations completed
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
mcp__code-index__refresh_index()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### mcp__code-index__get_file_summary
|
||||
|
||||
**Purpose**: Get structural summary of a file
|
||||
|
||||
**Parameters**:
|
||||
```typescript
|
||||
{
|
||||
file_path: string // Path to file
|
||||
}
|
||||
```
|
||||
|
||||
**Returns**:
|
||||
- Line count
|
||||
- Function/class definitions
|
||||
- Import statements
|
||||
- Basic complexity metrics
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
mcp__code-index__get_file_summary(file_path="src/auth/index.ts")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Comparison
|
||||
|
||||
### Speed Rankings (Fastest to Slowest)
|
||||
|
||||
1. **rg (ripgrep)** - Fastest for content search
|
||||
2. **find** - Fast for file location
|
||||
3. **MCP Code Index** - Fast for indexed searches
|
||||
4. **grep** - Slower than rg
|
||||
5. **codebase-retrieval** - Slower (AI-powered)
|
||||
|
||||
### Recommended Tool by Task
|
||||
|
||||
| Task | Fastest Tool | Alternative |
|
||||
|------|-------------|-------------|
|
||||
| Content search | rg | grep |
|
||||
| File location | find | MCP find_files |
|
||||
| Pattern search | rg | MCP search_code_advanced |
|
||||
| Semantic discovery | codebase-retrieval | - |
|
||||
| Architecture analysis | get_modules_by_depth.sh | - |
|
||||
|
||||
---
|
||||
|
||||
## Optimization Strategies
|
||||
|
||||
### General Tips
|
||||
|
||||
1. **Use type filters** - Always specify file types when possible
|
||||
2. **Exclude directories** - Skip node_modules, dist, .git
|
||||
3. **Literal search** - Use `-F` flag when pattern has no regex
|
||||
4. **Limit scope** - Search specific directories instead of entire project
|
||||
5. **Use indexes** - MCP Code Index is fast for indexed operations
|
||||
|
||||
### Pattern Optimization
|
||||
|
||||
```bash
|
||||
# ❌ Slow: Complex regex
|
||||
rg ".*complex.*nested.*pattern.*"
|
||||
|
||||
# ✅ Fast: Simple patterns
|
||||
rg "complex" | rg "nested" | rg "pattern"
|
||||
|
||||
# ❌ Slow: No type filter
|
||||
rg "pattern"
|
||||
|
||||
# ✅ Fast: With type filter
|
||||
rg "pattern" --type ts
|
||||
|
||||
# ❌ Slow: Searches everything
|
||||
rg "pattern" .
|
||||
|
||||
# ✅ Fast: Limited scope
|
||||
rg "pattern" src/
|
||||
```
|
||||
|
||||
### Exclusion Patterns
|
||||
|
||||
```bash
|
||||
# Standard exclusions for most projects
|
||||
rg "pattern" \
|
||||
--glob '!node_modules' \
|
||||
--glob '!dist' \
|
||||
--glob '!build' \
|
||||
--glob '!.git' \
|
||||
--glob '!coverage' \
|
||||
--glob '!*.min.js'
|
||||
|
||||
# With find
|
||||
find . \
|
||||
-path "*/node_modules" -prune -o \
|
||||
-path "*/dist" -prune -o \
|
||||
-path "*/.git" -prune -o \
|
||||
-name "*.ts" -print
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment-Specific Notes
|
||||
|
||||
### Git Bash on Windows
|
||||
|
||||
- All commands work in Git Bash environment
|
||||
- Use forward slashes (`/`) in paths
|
||||
- Use POSIX-style paths (`/c/Users` instead of `C:\Users`)
|
||||
- ❌ No Windows commands: `findstr`, `dir`, `where`, `type`
|
||||
- ✅ Use Bash equivalents: `grep`, `find`, `which`, `cat`
|
||||
|
||||
### Path Handling
|
||||
|
||||
```bash
|
||||
# ✅ Correct (Bash)
|
||||
find . -name "*.ts"
|
||||
rg "pattern" src/
|
||||
|
||||
# ❌ Wrong (Windows)
|
||||
dir /s /b *.ts
|
||||
findstr /s "pattern" src\
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Command Not Found
|
||||
|
||||
```bash
|
||||
# Check if rg is installed
|
||||
which rg
|
||||
|
||||
# Fallback to grep if rg unavailable
|
||||
if ! command -v rg &> /dev/null; then
|
||||
grep -r "pattern" .
|
||||
else
|
||||
rg "pattern"
|
||||
fi
|
||||
```
|
||||
|
||||
### Too Many Results
|
||||
|
||||
```bash
|
||||
# Add more specific patterns
|
||||
rg "very.specific.pattern" --type ts
|
||||
|
||||
# Limit to directory
|
||||
rg "pattern" src/auth/
|
||||
|
||||
# Show only filenames
|
||||
rg "pattern" -l
|
||||
|
||||
# Count matches
|
||||
rg "pattern" -c
|
||||
```
|
||||
|
||||
### Too Slow
|
||||
|
||||
```bash
|
||||
# Use literal search
|
||||
rg -F "literal" --type ts
|
||||
|
||||
# Exclude large directories
|
||||
rg "pattern" --glob '!node_modules' --glob '!dist'
|
||||
|
||||
# Limit depth
|
||||
find . -maxdepth 3 -name "*.ts"
|
||||
|
||||
# Use type filters
|
||||
rg "pattern" --type ts
|
||||
```
|
||||
|
||||
### No Matches Found
|
||||
|
||||
```bash
|
||||
# Try case-insensitive
|
||||
rg -i "pattern"
|
||||
|
||||
# Try fuzzy search (MCP)
|
||||
mcp__code-index__search_code_advanced(pattern="patern", fuzzy=true)
|
||||
|
||||
# Check if file type is correct
|
||||
rg "pattern" --type-list
|
||||
|
||||
# Try without filters
|
||||
rg "pattern" .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Combining Tools
|
||||
|
||||
```bash
|
||||
# Use find to get files, rg to search within
|
||||
find . -name "*.ts" -type f | xargs rg "pattern"
|
||||
|
||||
# Use rg to find files, then process
|
||||
rg -l "pattern" --type ts | xargs wc -l
|
||||
|
||||
# Semantic discovery → content search
|
||||
FILES=$(~/.claude/scripts/gemini-wrapper --all-files -p "List files for: auth")
|
||||
echo "$FILES" | xargs rg "jwt"
|
||||
```
|
||||
|
||||
### Piping Results
|
||||
|
||||
```bash
|
||||
# Chain searches
|
||||
rg "pattern1" --type ts | rg "pattern2"
|
||||
|
||||
# Count results
|
||||
rg "pattern" -l | wc -l
|
||||
|
||||
# Sort by frequency
|
||||
rg "pattern" -c | sort -t: -k2 -n
|
||||
|
||||
# Get unique matches
|
||||
rg "pattern" -o | sort | uniq -c | sort -n
|
||||
```
|
||||
|
||||
### Custom Scripts
|
||||
|
||||
```bash
|
||||
# Create custom search function
|
||||
search_feature() {
|
||||
local feature=$1
|
||||
echo "Searching for: $feature"
|
||||
|
||||
# Semantic discovery
|
||||
~/.claude/scripts/gemini-wrapper --all-files -p "List files for: $feature"
|
||||
|
||||
# Content search
|
||||
rg "$feature" --type ts -C 2
|
||||
}
|
||||
|
||||
# Use it
|
||||
search_feature "authentication"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Card
|
||||
|
||||
### Most Common Commands
|
||||
|
||||
```bash
|
||||
# Semantic file discovery
|
||||
~/.claude/scripts/gemini-wrapper --all-files -p "List files for: [task]"
|
||||
|
||||
# Architecture analysis
|
||||
~/.claude/scripts/get_modules_by_depth.sh
|
||||
|
||||
# Content search
|
||||
rg "pattern" --type ts
|
||||
|
||||
# File search
|
||||
find . -name "*.ts" -type f
|
||||
|
||||
# MCP search
|
||||
mcp__code-index__search_code_advanced(pattern="pattern", file_pattern="*.ts")
|
||||
|
||||
# MCP find
|
||||
mcp__code-index__find_files(pattern="*pattern*")
|
||||
```
|
||||
|
||||
### Common Options
|
||||
|
||||
```bash
|
||||
# Case-insensitive
|
||||
rg -i "pattern"
|
||||
|
||||
# Show context
|
||||
rg -C 3 "pattern"
|
||||
|
||||
# Exclude directory
|
||||
rg "pattern" --glob '!node_modules'
|
||||
|
||||
# Literal search
|
||||
rg -F "exact.match"
|
||||
|
||||
# Type filter
|
||||
rg "pattern" --type ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [SKILL.md](SKILL.md) - Core decision framework
|
||||
- [examples.md](examples.md) - Practical usage examples
|
||||
- ripgrep documentation: https://github.com/BurntSushi/ripgrep
|
||||
- find man page: `man find`
|
||||
- grep man page: `man grep`
|
||||
Reference in New Issue
Block a user