performance-rules

Performance Rules — Aiyu Agent Kit

Guidelines for building high-performance, efficient systems.

---

🔴 CRITICAL: Performance Foundations

Measure First

Never optimize without profiling:

# Python
python -m cProfile -o output.prof script.py

# Node.js
node --prof app.js

# Go
go test -bench=.

Algorithm Complexity

Complexity	Max Input Size	Use Case
O(1)	Unlimited	Hash lookups, array access
O(log n)	10^9	Binary search, tree ops
O(n)	10^7	Linear scans
O(n log n)	10^6	Sorting, efficient algorithms
O(n²)	10^4	Small data only
O(2^n)	< 30	Avoid for production

Database Performance

-- ✅ GOOD — Index on query columns
SELECT * FROM users WHERE email = '[email protected]';
-- Index: CREATE INDEX idx_users_email ON users(email);

-- ❌ BAD — Full table scan on large tables
SELECT * FROM logs WHERE created_at > '2024-01-01';
-- No index on created_at = slow on millions of rows

---

🟡 HIGH: Efficient Patterns

Caching Strategy

Cache Hierarchy:
┌─────────────────┐  Fastest
│  L1/L2 CPU      │
├─────────────────┤
│  In-Memory      │  Redis, Memcached
├─────────────────┤
│  CDN/Edge       │  Cloudflare, S3
├─────────────────┤
│  Database       │  Query cache
├─────────────────┤
│  Origin Server  │  Slowest
└─────────────────┘

Cache invalidation patterns:

• TTL-based: Simple, may serve stale data
• Write-through: Always fresh, higher latency
• Write-behind: Async, risk of data loss

N+1 Query Prevention

# ❌ BAD — N+1 queries
for user in users:
    orders = db.query(f"SELECT * FROM orders WHERE user_id = {user.id}")

# ✅ GOOD — Single query with JOIN
orders = db.query("""
    SELECT u.*, o.* 
    FROM users u 
    JOIN orders o ON u.id = o.user_id
""")

Async vs Sync

Use Case	Approach
I/O bound (API, DB)	Async/await, coroutines
CPU bound (compute)	Multiprocessing, thread pools
Mixed workload	Hybrid with proper isolation