Efficient System Behavior Simulator

Simulate system performance under various load conditions with capacity planning models, bottleneck identification, and optimization strategy recommendations.

When to Use This Command

Run this command when...

• You need to predict how your system will perform under increased load before actually scaling
• Capacity planning requires modeling different traffic scenarios to determine infrastructure requirements
• You want to identify theoretical bottlenecks before they manifest in production under real traffic
• A major launch or marketing campaign is planned and you need to validate the system can handle projected load
• You are evaluating architectural changes and want to simulate their performance impact before implementing

Quick Start

Copy
# .claude/commands/efficient-system-behavior-simulator.md
---
name: Efficient System Behavior Simulator
description: Simulate system load, identify bottlenecks, plan capacity
command: true
---
Simulate system behavior: $ARGUMENTS

1. Model the current system architecture and resource constraints
2. Define load scenarios (baseline, peak, stress, failure)
3. Simulate behavior under each scenario
4. Identify bottlenecks and failure points
5. Recommend optimizations and scaling strategies

Copy
# Invoke the command
claude "/efficient-system-behavior-simulator 10x traffic spike during product launch"

# Expected output
# > Modeling system architecture...
# >   API servers: 3 instances (4 vCPU, 8GB RAM each)
# >   Database: PostgreSQL (8 vCPU, 32GB RAM, 1000 IOPS)
# >   Cache: Redis (2GB, single node)
# >   Current throughput: ~800 req/s at p95 < 200ms
# > Simulating 10x load (8,000 req/s)...
# >   API layer: CPU saturates at ~3,200 req/s (need 8 instances)
# >   Database: Connection pool exhausts at ~2,000 req/s
# >   Redis: Memory pressure at ~5,000 req/s (need 4GB)
# >   First bottleneck: Database connections at 2,000 req/s
# > Recommendations:
# >   1. Scale API to 8 instances (+5 instances)
# >   2. Add PgBouncer for connection pooling
# >   3. Add Redis read replica + increase to 4GB
# >   4. Implement request queuing for burst absorption
# > Projected capacity after changes: ~9,500 req/s

Core Concepts

Concept	Description
Architecture Modeling	Maps system components, resources, connections, and throughput limits
Scenario Definition	Creates baseline, peak, stress, and failure load scenarios with specific parameters
Bottleneck Detection	Identifies which component saturates first under each load scenario
Capacity Calculation	Computes required resources (instances, memory, IOPS) for target throughput
Scaling Recommendations	Suggests horizontal, vertical, and architectural scaling strategies

Simulation Scenario Matrix
============================

  Load Level     Req/s     Expected Behavior
  -----------    ------    ----------------------------------
  Baseline       800       Normal operation, all SLAs met
  Growth (2x)    1,600     API OK, DB connections near limit
  Peak (5x)      4,000     DB bottleneck, need pooling
  Stress (10x)   8,000     Multiple bottlenecks, scaling needed
  Failure (20x)  16,000    Cascading failure without changes

  Bottleneck Discovery Order:
  1. DB Connections (2,000 req/s)
  2. API CPU (3,200 req/s)
  3. Redis Memory (5,000 req/s)
  4. DB IOPS (7,000 req/s)

Configuration

Parameter	Description	Default	Example	Required
$ARGUMENTS	Load scenario to simulate	none	"10x traffic spike"	Yes
architecture_file	Path to architecture description file	auto-detect	"docs/architecture.md"	No
target_sla	Target SLA for response times	p95 < 200ms	"p99 < 500ms"	No
cost_analysis	Include infrastructure cost estimates	false	true	No
scenarios	Number of load scenarios to simulate	4	6	No

Best Practices

1. Provide accurate current architecture details -- The simulation quality depends on accurate resource specifications. Include instance counts, CPU, memory, and storage IOPS for meaningful predictions.

2. Model realistic traffic patterns -- Real traffic is not uniform. Include burst patterns, diurnal cycles, and geographic distribution in your scenario definitions.

3. Validate against actual load tests -- Run the simulator first, then validate predictions with actual load testing. Calibrate the model based on real results for future accuracy.

4. Include cost analysis for scaling decisions -- Enable cost_analysis: true to see the financial impact of each scaling recommendation. Sometimes a code optimization is cheaper than adding instances.

5. Simulate failure scenarios -- Include scenarios where one component fails (database failover, cache eviction) to understand cascading effects and resilience.

Common Issues

Model inaccuracy without real metrics: Simulations based on estimated throughput limits are approximate. Calibrate with actual load test data for more accurate predictions.

Missing dependent service limits: Third-party APIs, payment processors, or external services have their own rate limits that may bottleneck before your infrastructure. Include external service limits in the model.

Over-provisioning from worst-case scenarios: Stress test scenarios represent rare peaks. Size infrastructure for expected 95th percentile load with auto-scaling for peaks rather than provisioning for maximum at all times.