performance-rules

Performance Rules: Stay 6x Faster Than Gemini CLI

🚨 PERFORMANCE KILLERS - NEVER DO THESE

Synchronous Operations (Gemini CLI Mistake)

// ❌ FORBIDDEN - Blocks event loop like Gemini CLI
import { execSync, readFileSync } from 'fs';
const result = execSync('command');  // Blocks everything
const content = readFileSync('file.txt');  // Blocks everything

// ✅ REQUIRED - Async operations
import { exec } from 'child_process';
import { readFile } from 'fs/promises';
const result = await exec('command');
const content = await readFile('file.txt');

Console Pollution (Gemini CLI Has 100+)

// ❌ FORBIDDEN - Slows down execution
console.log('debug info');
console.error('error details');
console.warn('warning message');

// ✅ REQUIRED - Use proper logging
import { logger } from '../utils/logger.js';
logger.debug('debug info');
logger.error('error details');
logger.warn('warning message');

Memory Leaks (Gemini CLI Pattern)

// ❌ FORBIDDEN - Memory leaks like Gemini CLI
let globalCache = new Map();  // Never cleaned up
setInterval(() => {}, 1000);  // Never cleared

// ✅ REQUIRED - Proper cleanup
class CacheManager {
  private cache = new Map();
  private cleanupInterval: NodeJS.Timeout;
  
  constructor() {
    this.cleanupInterval = setInterval(() => this.cleanup(), 60000);
  }
  
  cleanup(): void {
    this.cache.clear();
  }
  
  destroy(): void {
    clearInterval(this.cleanupInterval);
    this.cache.clear();
  }
}

⚡ PERFORMANCE PATTERNS - ALWAYS USE THESE

1. Lazy Loading (Beat Gemini CLI Startup)

// ✅ REQUIRED - Lazy load heavy modules
async function getAIClient(): Promise<UnifiedClaudeClient> {
  // Only import when needed
  const { createUnifiedClient } = await import('../ai/unified-client.js');
  return createUnifiedClient();
}

// ❌ WRONG - Heavy imports at startup like Gemini CLI
import { heavyModule } from './heavy-module.js';  // Slows startup

2. Efficient Data Structures

// ✅ REQUIRED - Use appropriate data structures
const userLookup = new Map<string, User>();  // O(1) lookup
const uniqueItems = new Set<string>();       // O(1) contains

// ❌ WRONG - Inefficient structures like Gemini CLI
const userLookup: User[] = [];  // O(n) lookup
const uniqueItems: string[] = [];  // O(n) contains check