메뉴
Runs performance benchmarks for SDL3 VoidLight-Framework and detects regressions by comparing metrics against baseline. Use when testing performance-sensitive changes to AI, collision, pathfinding, particle systems, or before merging features to ensure no performance degradation.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | voidlight-benchmark-regression |
| description | Runs performance benchmarks for SDL3 VoidLight-Framework and detects regressions by comparing metrics against baseline. Use when testing performance-sensitive changes to AI, collision, pathfinding, particle systems, or before merging features to ensure no performance degradation. |
| allowed-tools | ["Bash","Read","Write","Grep"] |
This Skill is critical for SDL3 VoidLight-Framework's performance requirements: 10,000+ entities at 60+ FPS with minimal CPU. It detects performance regressions before they reach production.
This file is the lean playbook. Detail lives in references/ and is loaded on demand:
references/benchmarks.md — per-benchmark catalog, baseline file format, metric
extraction commands, and per-benchmark regression thresholds.references/report-template.md — the full regression report + console summary template.references/troubleshooting.md — timeouts, the final validation gate, and troubleshooting.Absolute performance numbers vary by platform (CPU, memory, OS). Always compare percentage
change against a platform-specific baseline in test_results/baseline/, never hard-coded
absolutes. Severity thresholds (>15% = CRITICAL, etc.) apply universally. Example outputs in
the reference files are representative of one platform only.
⚠️ AI Scaling Benchmark is MANDATORY. The AI System is the most performance-critical
component. Always run ai_scaling_benchmark (via ./tests/test_scripts/run_ai_benchmark.sh)
and never proceed to report generation without AI results.
Baselines live in $PROJECT_ROOT/test_results/baseline/. If that directory does not exist,
create a fresh baseline from this run (exit code 4, informational). Also create a new baseline
when the user requests a refresh or after validating an intentional optimization.
For the exact baseline file layout, creation logic, and update/history commands, read
references/benchmarks.md (Baseline File Format).
Discover the current benchmark set at runtime — do NOT assume a fixed list; the suite grows as systems are added. Enumerate what the repo actually builds and reconcile against the catalog:
ls bin/debug/*_benchmark bin/debug/*_analysis 2>/dev/null
ls tests/test_scripts/run_*benchmark*.sh tests/test_scripts/run_*analysis*.sh 2>/dev/null
All discovered benchmarks MUST be run for a complete regression analysis. Run any benchmark
surfaced by discovery even if it is not yet documented in references/benchmarks.md. The core
expected set is the AI scaling, collision scaling, pathfinder, event scaling, particle, GPU frame
timing, SIMD, integrated system, background simulation, adaptive threading, and projectile scaling
benchmarks — each has a matching run_*.sh script.
⚠️ SEQUENTIAL EXECUTION ONLY. Run benchmarks one at a time, waiting for each to fully complete
before starting the next. NEVER run benchmarks in parallel (background tasks, concurrent shells) —
parallelism causes CPU/memory contention that skews timing. Use foreground (run_in_background: false) for every invocation. Run the AI benchmark first (most critical, longest-running).
# Set PROJECT_ROOT and run from the project directory first:
# cd /path/to/VoidLight-Framework && export PROJECT_ROOT=$(pwd)
# Then run each discovered script in order, AI first, e.g.:
./tests/test_scripts/run_ai_benchmark.sh # CRITICAL — always first
./tests/test_scripts/run_collision_scaling_benchmark.sh
./tests/test_scripts/run_pathfinder_benchmark.sh
# ... continue through every discovered run_*.sh, sequentially
Each benchmark has timeout protection (AI: 600s, others: 300s). A timeout signals a likely
infinite loop or performance catastrophe — flag it (exit code 3). Full per-benchmark catalog,
durations (suite ~26 min), test cases, and targets are in references/benchmarks.md.
Parse each benchmark's output file in test_results/ for its key metrics. Each benchmark has a
specific grep recipe, expected output shape, and baseline key format documented in
references/benchmarks.md (Metrics Extraction Patterns). Critical extraction rules:
For each metric: change_pct = ((current - baseline) / baseline) * 100 (invert sign for
lower-is-better metrics like time/CPU). Classify against the universal severity thresholds below.
| Severity | Condition |
|---|---|
| 🔴 CRITICAL (block merge) | Any metric degrades >15%; AI FPS <60; AI CPU >8%; benchmark timeout |
| 🟠 WARNING (review) | Degradation 10-15%; AI FPS 60-65; collision/pathfinding >10% slower |
| 🟡 MINOR (monitor) | Degradation 5-10% |
| ⚪ STABLE | Change <5% (measurement noise) |
| 🟢 IMPROVEMENT | Improvement >5% |
The AI system carries hard gates (FPS <60 or CPU >8% are always CRITICAL regardless of %).
For the classify_change() reference implementation and per-benchmark detection specifics
(AI scaling patterns, SIMD Release vs Debug, integrated, background sim, adaptive threading,
projectile), read references/benchmarks.md (Per-Benchmark Regression Detection Thresholds).
Build the report from the template in references/report-template.md (full markdown report
$PROJECT_ROOT/test_results/regression_reports/regression_YYYY-MM-DD.md.The Pathfinding System section is MANDATORY in every report — never skip it. Before
submitting, run the Final Report Validation Checklist in references/troubleshooting.md;
if any item is unchecked, extract the missing data first rather than submitting.
Activate automatically when the user says: "check for performance regressions", "run benchmarks", "test performance", "verify no performance degradation", "compare against baseline". Also use before merging feature branches, after optimizations, weekly during active development, before releases, and when modifying AI, collision, pathfinding, or particle systems.
Full suite ~27 minutes + ~2-3 minutes report generation. For timeouts and troubleshooting
(inconsistent results, no baseline, etc.), read references/troubleshooting.md.
Generates professional performance analysis reports from SDL3 VoidLight-Framework benchmark results including statistical analysis, comparison tables, visualizations, and recommendations. Use when preparing performance documentation, analyzing optimization efforts, or generating milestone/release reports.
Runs complete build validation pipeline for SDL3 VoidLight-Framework including Debug build, smoke test execution, core test suite, and summary report generation. Use when the user wants to quickly validate their changes, check if the codebase is in a good state, or run the standard daily validation workflow.
Generates comprehensive, professionally-formatted changelogs for SDL3 VoidLight-Framework from git history. Analyzes code changes, runs tests, includes architect review, and produces detailed documentation as an ongoing engineering log. Use when documenting updates, preparing releases, or creating detailed change reports.
Verify dependency structure and architecture health for SDL3 VoidLight-Framework. Detects circular dependencies, excessive coupling, layer violations, header bloat, and provides dependency graph visualization. Ensures adherence to layered architecture (Core→Managers→States→Entities). Use monthly, after major refactors, or when investigating compile time issues.
Simplified memory profiling and leak detection for SDL3 VoidLight-Framework using valgrind memcheck, AddressSanitizer, and massif. Identifies memory leaks, allocation hotspots, buffer reuse violations, and provides system-by-system memory breakdown with optimization suggestions. Use after performance-critical changes or when investigating memory issues.
Runs comprehensive code quality checks for SDL3 VoidLight-Framework including compilation warnings, static analysis (cppcheck, clang-tidy), coding standards validation, threading safety verification, and architecture compliance. Use before commits, pull requests, or when the user wants to verify code meets project quality standards.