Claude-Code-Workflow/.claude/workflows/gemini-cli-guidelines.md

Gemini CLI Core Guidelines

Streamlined Gemini CLI usage guidelines with parallel execution patterns for enhanced performance.

🎯 Core Command Syntax

Basic Structure

gemini --all-files -p "@{file_patterns} analysis_prompt"

Parameters:

• --all-files - Include all files (context-dependent on execution path)
• -p - Specify prompt content
• @{pattern} - File reference pattern

Parallel Execution Structure

# Execute multiple Gemini commands concurrently
(
  gemini_command_1 &
  gemini_command_2 &
  gemini_command_3 &
  wait  # Synchronize all parallel processes
)

⚠️ Execution Path Dependencies

• --all-files adds all text to context memory and depends on execution path
• For folder-specific analysis: Navigate to target folder first, then run gemini
• If errors occur: Remove --all-files and use @folder or @file in prompts instead

Example - Analyzing a specific component folder:

# Combined command - navigate and analyze in one line
cd src/components/ui && gemini --all-files -p "analyze component structure and patterns in this UI folder"

# For Windows systems
cd src\components\ui && gemini --all-files -p "analyze component structure and patterns in this UI folder"

# Alternative if --all-files fails
cd /project/root && gemini -p "@src/components/ui analyze UI component patterns and structure"

# Cross-platform combined command with fallback
cd src/components/ui && gemini --all-files -p "analyze patterns" || gemini -p "@src/components/ui analyze patterns"

📂 File Reference Rules

Required Reference Patterns

# 1. Project guidelines files (REQUIRED)
@{CLAUDE.md,**/*CLAUDE.md}

# 2. Target analysis files
@{src/**/*,lib/**/*}     # Source code
@{**/*.{ts,tsx,js,jsx}}  # Specific languages
@{**/api/**/*}           # Domain-related

# 3. Test files (RECOMMENDED)
@{**/*.test.*,**/*.spec.*}

Domain Pattern Quick Reference

Domain	Pattern
Frontend Components	@{src/components/**/*,src/ui/**/*}
API Endpoints	@{**/api/**/*,**/routes/**/*}
Authentication	@{**/*auth*,**/*login*,**/*session*}
Database	@{**/models/**/*,**/db/**/*}
Configuration	@{*.config.*,**/config/**/*}

⚡ Parallel Agent Execution Guidelines

Parallel Task Distribution Rules

Rule 1: Module Independence Analysis

• Before parallel execution, identify independent modules
• Group modules by dependency level
• Execute only independent modules in parallel

Rule 2: Resource-Based Concurrency

• Default: 3 concurrent Gemini processes
• Maximum: 5 concurrent processes (system dependent)
• Reduce if memory/CPU constraints detected

Rule 3: Synchronization Points

• Wait for all modules at same dependency level
• Merge results before proceeding to next level
• Global summary only after all modules complete

Parallel Template Formats

Directory-Based Parallel Execution:

# Navigate to different directories and analyze in parallel
(
  cd src/components/ui && gemini --all-files -p "@{CLAUDE.md} analyze UI patterns" &
  cd src/components/forms && gemini --all-files -p "@{CLAUDE.md} analyze form patterns" &
  cd src/api && gemini --all-files -p "@{CLAUDE.md} analyze API patterns" &
  wait
)

File Pattern Parallel Execution:

# Use file patterns for parallel analysis (when --all-files not suitable)
gemini -p "@src/components/ui/**/* @{CLAUDE.md} analyze UI implementation" &
gemini -p "@src/components/forms/**/* @{CLAUDE.md} analyze form handling" &
gemini -p "@src/api/auth/**/* @{CLAUDE.md} analyze authentication" &
wait

Standard Sequential Template

gemini --all-files -p "@{target_files} @{CLAUDE.md,**/*CLAUDE.md}

Analysis Task: [specific task description]

Required Output:
- Specific file:line references
- Executable code examples
- Clear implementation guidance"

Agent-Specific Modes

# Planning Agent (navigate to project root first)
cd /path/to/project && gemini --all-files -p "@{src/**/*} @{CLAUDE.md,**/*CLAUDE.md}
Task planning analysis: [task] - Extract file modification points, implementation sequence, integration requirements"

# Code Developer (navigate to target directory first)
cd /path/to/project && gemini --all-files -p "@{**/*.{ts,js}} @{**/*test*} @{CLAUDE.md,**/*CLAUDE.md}
Code implementation guidance: [feature] - Extract code patterns, insertion points, testing requirements"

# Code Review (use @file references if --all-files fails)
gemini -p "@modified_files @related_files @CLAUDE.md
Code review: [changes] - Compare against standards, check consistency, identify risks"

# Alternative without --all-files for targeted analysis
gemini -p "@src/components @CLAUDE.md
Component analysis: [specific_component] - Extract patterns and implementation guidance"

📋 Core Principles

1. File Reference Principles

• Must include: @{CLAUDE.md,**/*CLAUDE.md}
• Precise targeting: Use specific file patterns, avoid over-inclusion
• Logical grouping: Combine related file patterns

2. Prompt Construction Principles

• Single objective: Each command completes one analysis task
• Specific requirements: Clearly specify required output format
• Context integration: Reference project standards and existing patterns

3. Output Requirements

• File references: Provide specific file:line locations
• Code examples: Give executable code snippets
• Implementation guidance: Clear next-step actions

🔧 Common Command Patterns

Quick Analysis

# Architecture analysis (navigate to project root first)
cd /project/root && gemini --all-files -p "@{src/**/*} @{CLAUDE.md} system architecture and component relationships"

# Pattern detection (navigate to project root first)
cd /project/root && gemini --all-files -p "@{**/*.ts} @{CLAUDE.md} TypeScript usage patterns"

# Security review (fallback to @file if --all-files fails)
gemini -p "@**/*auth* @CLAUDE.md authentication and authorization implementation patterns"

# Folder-specific analysis (navigate to target folder)
cd /project/src/components && gemini --all-files -p "component structure and patterns analysis"

Parallel Analysis Patterns

# Parallel architecture analysis by layer
(
  cd src/frontend && gemini --all-files -p "analyze frontend architecture" &
  cd src/backend && gemini --all-files -p "analyze backend architecture" &
  cd src/database && gemini --all-files -p "analyze data layer architecture" &
  wait
)

# Parallel pattern detection across modules
gemini -p "@src/components/**/*.tsx analyze React patterns" &
gemini -p "@src/api/**/*.ts analyze API patterns" &
gemini -p "@src/utils/**/*.ts analyze utility patterns" &
wait

# Parallel security review
(
  gemini -p "@**/*auth* analyze authentication implementation" &
  gemini -p "@**/*permission* analyze authorization patterns" &
  gemini -p "@**/*crypto* analyze encryption usage" &
  wait
)

Integration Standards

1. Path awareness: Navigate to appropriate directory before using --all-files
2. Fallback strategy: Use @file or @folder references if --all-files errors
3. Minimal references: Only reference files you actually need
4. Self-contained: Avoid complex cross-file dependencies
5. Focused analysis: Use for specific analysis, not general exploration
6. Result reuse: Reuse analysis results when possible

Parallel Execution Standards

1. Dependency verification: Ensure modules are independent before parallel execution
2. Resource monitoring: Check system capacity before increasing concurrency
3. Synchronization discipline: Always use wait after parallel commands
4. Result aggregation: Merge outputs from parallel executions properly
5. Error isolation: Handle failures in individual parallel tasks gracefully
6. Performance tracking: Monitor speedup to validate parallel benefit

📊 Parallel Execution Rules

Rule-Based Parallel Coordination

Execution Order Rules:

1. Level 0 (Leaf Modules): Execute all in parallel (max 5)
2. Level N: Wait for Level N-1 completion before starting
3. Root Level: Process only after all module levels complete

File Partitioning Rules:

1. Size-based: Split large directories into ~equal file counts
2. Type-based: Group by file extension for focused analysis
3. Logic-based: Separate by functionality (auth, api, ui, etc.)

Memory Management Rules:

1. Per-process limit: Each Gemini process uses ~500MB-1GB
2. Total limit: Don't exceed 80% system memory
3. Throttling: Reduce parallelism if memory pressure detected

Synchronization Rules:

1. Barrier sync: All tasks at level must complete
2. Queue sync: Next task starts when worker available
3. Async sync: Collect results as they complete

Performance Optimization Rules

When to use parallel execution:

• Project has >5 independent modules
• Modules have clear separation
• System has adequate resources (>8GB RAM)
• Time savings justify coordination overhead

When to avoid parallel execution:

• Small projects (<5 modules)
• Highly interdependent modules
• Limited system resources
• Sequential dependencies required

Error Handling Rules

Parallel Failure Recovery:

1. If one parallel task fails, continue others
2. Retry failed tasks once with reduced scope
3. Fall back to sequential for persistent failures
4. Report all failures at synchronization point

Resource Exhaustion Handling:

1. Detect high memory/CPU usage
2. Pause new parallel tasks
3. Wait for current tasks to complete
4. Resume with reduced concurrency

---

Enhanced version with parallel execution patterns and coordination rules