From b2a395fcd8437ddd44ac06ba78bc343c79f72144 Mon Sep 17 00:00:00 2001 From: Manuel Maly Date: Sun, 29 Jun 2025 22:53:33 +0200 Subject: [PATCH] feat: add gemini and review-pr slash commands (#138) --- .claude/commands/gemini.md | 58 +++++++ .claude/commands/review-pr.md | 314 ++++++++++++++++++++++++++++++++++ docs/gemini.md | 199 +++++++++++++++++++++ 3 files changed, 571 insertions(+) create mode 100644 .claude/commands/gemini.md create mode 100644 .claude/commands/review-pr.md create mode 100644 docs/gemini.md diff --git a/.claude/commands/gemini.md b/.claude/commands/gemini.md new file mode 100644 index 00000000..69337ea2 --- /dev/null +++ b/.claude/commands/gemini.md @@ -0,0 +1,58 @@ +# /gemini + +Execute Gemini CLI with the context from docs/gemini.md for large codebase analysis. + +## Usage + +``` +/gemini {prompt} +``` + +## Description + +This command reads the `docs/gemini.md` file which contains best practices for using the Gemini CLI with large codebases, then executes the appropriate gemini command based on your prompt. + +## Examples + +### Analyze a single file +``` +/gemini @web/src/server/server.ts Explain this file's purpose and structure +``` + +### Check feature implementation +``` +/gemini @web/src/ Has dark mode been implemented in this codebase? +``` + +### Analyze entire project +``` +/gemini @./ Give me an overview of this entire project +``` + +### Verify security measures +``` +/gemini @web/src/ @web/src/api/ Are SQL injection protections implemented? +``` + +## Implementation + +When you use this command, I will: +1. Check if Gemini CLI is installed and accessible +2. Read the contents of `docs/gemini.md` to understand Gemini CLI usage patterns (provide helpful error if missing) +3. Analyze your prompt to determine the appropriate Gemini command structure +4. Execute the gemini command with the proper flags and file inclusions +5. Return the results to help with your codebase analysis + +## Error Handling + +- If Gemini CLI is not installed, provide installation instructions +- If `docs/gemini.md` is missing, use built-in knowledge of Gemini CLI best practices +- Handle command execution errors gracefully with helpful messages + +## Note + +The Gemini CLI is particularly useful when: +- Analyzing entire codebases or large directories +- Context window limits are a concern +- You need to verify implementation of specific features across many files +- Working with files totaling more than 100KB \ No newline at end of file diff --git a/.claude/commands/review-pr.md b/.claude/commands/review-pr.md new file mode 100644 index 00000000..4764183d --- /dev/null +++ b/.claude/commands/review-pr.md @@ -0,0 +1,314 @@ +# /review-pr + +Perform a comprehensive code review of the current pull request using parallel sub-agents powered by Claude and Gemini, with results intelligently merged. + +## Usage + +``` +/review-pr [options] +``` + +Options: +- `--focus ` - Focus on specific areas. Valid values: `security`, `performance`, `tests`, `architecture`, `documentation`, `all` +- `--gemini-only` - Perform the review only with gemini CLI + +## Description + +This command performs a thorough code review of the current branch's changes compared to the main branch. It runs two parallel sub-agents - one using Claude and another using Gemini - to perform independent comprehensive reviews. The results from both AI models are then intelligently merged to provide a complete multi-perspective analysis. + +## Examples + +### Standard PR review +``` +/review-pr +``` + +### Security-focused review +``` +/review-pr --focus security +``` + +### Performance and scalability review +``` +/review-pr --focus performance +``` + +## Implementation + +When you use this command, I will: + +1. **Initial PR Context Gathering** + - Check if required tools are available: `gh`, `git`, and `gemini` + - Run `gh pr view` to check PR description and any existing comments (handle errors gracefully) + - Run `git log "main..HEAD" --oneline` to see all commits in this PR (with proper shell escaping) + - Run `git diff "main...HEAD" --stat` to get an overview of changed files (with proper shell escaping) + - Generate comprehensive diff with secure temporary file handling: + ```bash + touch .pr_review_diff.tmp && chmod 600 .pr_review_diff.tmp + git diff "main...HEAD" > .pr_review_diff.tmp + ``` + - If any git commands fail, provide helpful error messages and guidance + +2. **Launch Two Parallel Sub-Agents** + + **Sub-Agent 1: Claude Review** + - WARNING: This step must be skipped when `--gemini-only` has been passed + - Performs complete multi-aspect code review using Claude + - Analyzes all aspects below independently + + **Sub-Agent 2: Gemini Review** + - Runs Gemini CLI following instructions from `docs/gemini.md` + - Performs complete multi-aspect code review using Gemini + - Form the prompt to the Gemini CLI in a way that it only returns the final output of its findings, to save tokens + - Analyzes all aspects below independently + - Use a timeout of 10 minutes for the gemini CLI command (configurable via environment variable `GEMINI_TIMEOUT_SECONDS`, default: 600) + - **IMPORTANT**: Gemini CLI can only access files within the project directory + - Create temporary diff file in project root (e.g., `.pr_review_diff.tmp`) + - Use `@.pr_review_diff.tmp` syntax to include the diff in Gemini prompt + - Clean up temporary file after review completes + + **Both sub-agents analyze:** + + **Correctness & Logic** + - Verify the code solves the intended problem + - Check for edge cases, off-by-one errors, null/undefined handling + - Validate business logic and algorithm correctness + + **Code Quality & Architecture** + - Check adherence to DRY and SOLID principles + - Assess function/class complexity and cohesion + - Verify consistent naming conventions and code style + - Ensure changes align with existing architecture patterns + + **Performance & Scalability** + - Identify O(nยฒ) algorithms that could be O(n) + - Check for N+1 database queries + - Look for memory leaks or excessive allocations + - Identify missed caching opportunities + + **Security** + - Check for SQL injection vulnerabilities + - Identify XSS vulnerabilities + - Verify authentication/authorization checks + - Ensure no sensitive data in logs or commits + - Validate all user inputs are sanitized + + **Testing** + - Verify test coverage for new/modified code + - Check if tests actually test the right behavior + - Ensure edge cases are covered + - Assess test maintainability and brittleness + + **Error Handling** + - Verify errors are properly caught and handled + - Check error messages are helpful for debugging + - Ensure appropriate logging levels + - Validate graceful failure modes + + **Documentation** + - Check if complex logic is explained + - Verify API documentation is updated + - Look for outdated or misleading comments + - Ensure README/docs are updated if needed + + **Automated Checks** + - Execute `pnpm run check` (for web/) if available + - Run `./scripts/lint.sh` (for mac/) if the script exists + - Run `./lint.sh` (for tauri/) if the script exists + - Check if tests pass with appropriate test commands + - Verify build succeeds + - If any checks fail, continue with review but note the failures + +3. **Merge Results** + - Intelligently combine findings from both Claude and Gemini + - Identify common issues found by both models (high confidence) + - Highlight unique insights from each model + - Resolve any conflicting assessments + - Generate unified severity ratings + +4. **Generate Final Review Report** + - Provide a structured review with: + - **Summary**: High-level overview of changes + - **Strengths**: What's done well + - **Critical Issues**: Must-fix problems with exact line numbers + - **Suggestions**: Nice-to-have improvements with exact line numbers + - **Questions**: Clarifications needed with exact line numbers + - Use accountability mindset - I'm as responsible as the author + - Provide constructive, mentoring-oriented feedback + - **CRITICAL**: Always include exact line numbers for every issue found + - Use format: `filename:line_number` (e.g., `src/server.ts:142`) + - For multi-line issues, use ranges: `filename:start_line-end_line` + +5. **Cleanup** + - Remove temporary diff file `.pr_review_diff.tmp` from project root + - Ensure no sensitive data remains in temporary files + +## Review Checklist + +### โœ… Shared Accountability +- [ ] I understand I share responsibility for this code once approved +- [ ] I've reviewed with the same care as if I wrote it + +### ๐ŸŽฏ Functionality +- [ ] Code implements intended functionality +- [ ] Edge cases and error scenarios handled +- [ ] No regressions introduced + +### ๐Ÿ—๏ธ Architecture & Design +- [ ] Changes align with system architecture +- [ ] Scalability and maintainability considered +- [ ] Design patterns appropriately used + +### ๐Ÿ”’ Security +- [ ] Input validation present +- [ ] Authentication/authorization correct +- [ ] No sensitive data exposed +- [ ] Dependencies are secure + +### โšก Performance +- [ ] No unnecessary database queries +- [ ] Efficient algorithms used +- [ ] Resource usage is reasonable +- [ ] Caching utilized where appropriate + +### ๐Ÿงช Testing +- [ ] Adequate test coverage +- [ ] Tests are meaningful, not just coverage +- [ ] Edge cases tested +- [ ] Tests are maintainable + +### ๐Ÿ“ Code Quality +- [ ] Code is DRY +- [ ] SOLID principles followed +- [ ] Clear naming and structure +- [ ] Appropriate comments/documentation + +### ๐Ÿ”„ Backwards Compatibility +- [ ] API changes are backwards compatible +- [ ] Database migrations handled properly +- [ ] No breaking changes without discussion + +## Note + +This command emphasizes: +- **Parallel Sub-Agent Architecture**: Two independent sub-agents perform complete reviews - one using Claude, another using Gemini CLI +- **Intelligent Merging**: Final step combines findings from both AI models by identifying common issues (high confidence), highlighting unique insights, and resolving conflicting assessments +- **Accountability**: Approving means you own the outcome +- **Mentorship**: Every comment is a teaching opportunity +- **Thoroughness**: Multiple passes from different angles by both AI models +- **Actionability**: Specific, clear feedback with examples +- **Precision**: Every issue must include exact line numbers + +**Line Number Format Examples:** +- Single line issue: `src/server/auth.ts:234` +- Multi-line issue: `src/client/app.ts:45-52` +- Context reference: `src/utils/helpers.ts:78 (similar pattern at lines 95, 112)` + +**Sub-Agent Execution:** +- Claude sub-agent performs the review using Claude's capabilities +- Gemini sub-agent runs the Gemini CLI following instructions from `docs/gemini.md` +- Both sub-agents work in parallel for efficiency + +For large PRs, consider reviewing incrementally and suggesting the author break it into smaller PRs for more effective review. + +## Prerequisites + +- Git and GitHub CLI (`gh`) must be installed +- For full functionality: Gemini CLI must be installed (see Gemini documentation) +- For `--gemini-only` mode: Only Gemini CLI is required + +## Security Considerations + +**Input Sanitization:** +- All user-provided parameters (e.g., `--focus` values) are validated against a whitelist +- Git commands use proper shell escaping with quotes around branch names +- Temporary files are created with secure permissions (mode 600) +- File paths are validated to prevent directory traversal attacks +- The `--focus` parameter only accepts predefined values: security, performance, tests, architecture, documentation, all + +**Safe Command Execution:** +```bash +# Always quote branch names and file paths +git diff "main...HEAD" --stat # Correct +git diff main...HEAD --stat # Vulnerable to injection + +# Set restrictive permissions on temporary files +touch .pr_review_diff.tmp && chmod 600 .pr_review_diff.tmp +git diff "main...HEAD" > .pr_review_diff.tmp +``` + +## Error Handling + +- If required tools are missing, the command will provide installation instructions +- Git command failures are handled gracefully with helpful error messages +- If automated checks fail, the review continues but notes the failures +- Timeout protection: Gemini sub-agent has a 10-minute timeout (configurable via `GEMINI_TIMEOUT_SECONDS` environment variable) + +## Implementation Notes + +**Gemini CLI File Access:** +- Gemini CLI can only access files within the project directory +- Always save temporary files in the project root with `.tmp` extension +- Use `.gitignore` patterns for temporary files (e.g., `.pr_review_*.tmp`) +- Example workflow: + ```bash + # Create file with secure permissions + touch .pr_review_diff.tmp && chmod 600 .pr_review_diff.tmp + + # Save diff to project-accessible location + git diff "main...HEAD" > .pr_review_diff.tmp + + # Use with Gemini + gemini -p "@.pr_review_diff.tmp Your review prompt here" + + # Clean up + rm -f .pr_review_diff.tmp + ``` + +**Handling Large Diffs:** +- For very large PRs, consider splitting the diff by file type or directory +- Use Gemini's 2M token context window advantage for comprehensive analysis +- If diff exceeds reasonable size, suggest breaking PR into smaller chunks + +**Chunking Strategy for Diffs Exceeding 1.5M Tokens:** + +1. **Automatic splitting by file type:** + ```bash + # JavaScript/TypeScript files + git diff "main...HEAD" -- "*.js" "*.ts" "*.jsx" "*.tsx" > .pr_review_js.tmp + + # Python files + git diff "main...HEAD" -- "*.py" > .pr_review_py.tmp + + # Documentation + git diff "main...HEAD" -- "*.md" "*.rst" "*.txt" > .pr_review_docs.tmp + ``` + +2. **Split by directory structure:** + ```bash + # Frontend changes + git diff "main...HEAD" -- "web/src/client/" > .pr_review_frontend.tmp + + # Backend changes + git diff "main...HEAD" -- "web/src/server/" > .pr_review_backend.tmp + + # Test changes + git diff "main...HEAD" -- "**/test/" "**/tests/" > .pr_review_tests.tmp + ``` + +3. **Prioritize by change type:** + ```bash + # New files (highest priority) + git diff "main...HEAD" --name-status | grep "^A" | cut -f2 | xargs git diff "main...HEAD" -- > .pr_review_new.tmp + + # Modified files + git diff "main...HEAD" --name-status | grep "^M" | cut -f2 | xargs git diff "main...HEAD" -- > .pr_review_modified.tmp + + # Deleted files (lowest priority for review) + git diff "main...HEAD" --name-status | grep "^D" | cut -f2 > .pr_review_deleted_list.tmp + ``` + +4. **Token estimation:** + - Rough estimate: 1 token โ‰ˆ 4 characters + - Check file size: `wc -c .pr_review_diff.tmp` + - If > 6MB (โ‰ˆ1.5M tokens), implement chunking strategy \ No newline at end of file diff --git a/docs/gemini.md b/docs/gemini.md new file mode 100644 index 00000000..6d517973 --- /dev/null +++ b/docs/gemini.md @@ -0,0 +1,199 @@ +# Using Gemini CLI for Large Codebase Analysis + +When analyzing large codebases or multiple files that might exceed context limits, use the Gemini CLI with its massive context window (up to 2 million tokens). Use `gemini -p` to leverage Google Gemini's large context capacity. + +## Prerequisites + +Ensure Gemini CLI is installed before using these commands. Installation instructions: https://github.com/google/gemini-cli#installation + +## File and Directory Inclusion Syntax + +Use the `@` syntax to include files and directories in your Gemini prompts. The paths should be relative to WHERE you run the gemini command: + +### Examples: + +**Single file analysis:** +```bash +gemini -p "@web/src/server/server.ts Explain this file's purpose and structure" +``` + +**Multiple files:** +```bash +gemini -p "@package.json @web/src/client/app.ts Analyze the dependencies used in the code" +``` + +**Entire directory:** +```bash +gemini -p "@src/ Summarize the architecture of this codebase" +``` + +**Multiple directories:** +```bash +gemini -p "@src/ @tests/ Analyze test coverage for the source code" +``` + +**Current directory and subdirectories:** +```bash +gemini -p "@./ Give me an overview of this entire project" +# Or use --all_files flag: +gemini --all_files -p "Analyze the project structure and dependencies" +``` + +**โš ๏ธ Security Warning:** Using `@./` may include sensitive files like `.env`, `.git/`, or API keys. Consider using specific directories or exclusion patterns. + +## Implementation Verification Examples + +**Check if a feature is implemented:** +```bash +gemini -p "@src/ @lib/ Has dark mode been implemented in this codebase? Show me the relevant files and functions" +``` + +**Verify authentication implementation:** +```bash +gemini -p "@src/ @middleware/ Is JWT authentication implemented? List all auth-related endpoints and middleware" +``` + +**Check for specific patterns:** +```bash +gemini -p "@src/ Are there any React hooks that handle WebSocket connections? List them with file paths" +``` + +**Verify error handling:** +```bash +gemini -p "@src/ @api/ Is proper error handling implemented for all API endpoints? Show examples of try-catch blocks" +``` + +**Check for rate limiting:** +```bash +gemini -p "@backend/ @middleware/ Is rate limiting implemented for the API? Show the implementation details" +``` + +**Verify caching strategy:** +```bash +gemini -p "@src/ @lib/ @services/ Is Redis caching implemented? List all cache-related functions and their usage" +``` + +**Check for specific security measures:** +```bash +gemini -p "@src/ @api/ Are SQL injection protections implemented? Show how user inputs are sanitized" +``` + +**Verify test coverage for features:** +```bash +gemini -p "@src/payment/ @tests/ Is the payment processing module fully tested? List all test cases" +``` + +## Error Scenarios and Handling + +**Gemini CLI not installed:** +```bash +# Error: command not found: gemini +# Solution: Install Gemini CLI following instructions at https://github.com/google/gemini-cli#installation +``` + +**Invalid file paths:** +```bash +gemini -p "@nonexistent/path/ Analyze this code" +# Gemini will report: "Error: Path 'nonexistent/path/' does not exist" +# The command continues with any valid paths provided +``` + +**Network connectivity issues:** +```bash +# If API calls fail, you'll see: +# "Error: Failed to connect to Gemini API" +# Solution: Check your internet connection and API key configuration +``` + +**File encoding problems:** +```bash +# Non-UTF8 files are automatically skipped with a warning: +# "Warning: Skipping binary or non-UTF8 file: path/to/file" +``` + +**Context limit exceeded:** +```bash +# For extremely large codebases: +# "Error: Context limit exceeded (2M tokens)" +# Solution: Use more specific paths or directories instead of @./ +``` + +**Timeout during analysis:** +```bash +# Default timeout is 30 seconds for API calls +# For longer operations, use the --timeout flag: +gemini --timeout 120 -p "@large-codebase/ Analyze architecture" +``` + +## When to Use Gemini CLI + +Use `gemini -p` when: +- Analyzing entire codebases or large directories +- Comparing multiple large files +- Need to understand project-wide patterns or architecture +- Current context window is insufficient for the task +- Working with files totaling more than 100KB +- Verifying if specific features, patterns, or security measures are implemented +- Checking for the presence of certain coding patterns across the entire codebase + +## Important Notes + +- Paths in @ syntax are relative to your current working directory when invoking gemini +- The CLI will include file contents directly in the context +- The --yolo flag bypasses confirmation prompts (use cautiously) +- Gemini's context window can handle entire codebases that would overflow Claude's context +- When checking implementations, be specific about what you're looking for to get accurate results +- Symlinks are followed by default - be cautious with circular references +- Binary files are automatically excluded from analysis +- Use `.geminiignore` file to exclude specific patterns (similar to `.gitignore`) + +## Using .geminiignore + +Create a `.geminiignore` file in your project root to exclude files and directories from Gemini analysis. The syntax follows `.gitignore` patterns: + +``` +# Environment and secrets +.env* +*.key +*.pem +secrets/ +credentials/ + +# Build artifacts +dist/ +build/ +*.min.js +*.bundle.js + +# Dependencies +node_modules/ +vendor/ +venv/ + +# Large generated files +package-lock.json +yarn.lock +*.generated.ts + +# Test fixtures +test/fixtures/large-data/ +**/*.snapshot.js + +# IDE and OS files +.idea/ +.vscode/ +.DS_Store +``` + +**Pattern Examples:** +- `*.log` - Exclude all log files +- `temp/` - Exclude temp directory +- `!important.log` - Include important.log even if *.log is excluded +- `src/**/test.js` - Exclude test.js in any subdirectory of src +- `/config.json` - Exclude config.json only in root directory + +## Error Handling + +- If paths don't exist, Gemini will report an error and continue with valid paths +- File encoding issues are handled gracefully (non-UTF8 files are skipped) +- For large repositories, consider using specific subdirectories to avoid timeouts \ No newline at end of file