benchmarking — Claude Code rule: what it does, how to install
The benchmarking rule teaches the agent to write valid .NET performance tests using BenchmarkDotNet. Useful when you need to measure code speed and track regressions.
Apache-2.0 ★ 138 updated 2025-03-29
.cursor/rules/benchmarking.mdcWhat benchmarking does
The rule explains how to set up a benchmark project, add [MemoryDiagnoser] and [Params] attributes, write methods marked with [Benchmark], and track allocations. The agent learns that memory measurement requires MemoryDiagnoser, comparing .NET versions needs [SimpleJob(RuntimeMoniker.Net80)], and SIMD benchmarks need RyuJitX64Job. It includes examples for string operations, vectorized code, and async methods.
The rule enforces that [IterationSetup] and [IterationCleanup] methods must return void — a requirement of BenchmarkDotNet versions up to 14.0. Wrong signature breaks benchmark execution. The rule also covers CI/CD integration and uploading results as artifacts.
What it helps with
- write a benchmark with parameters and memory tracking
- compare performance of several implementations
- configure a project for BenchmarkDotNet
- track performance regressions in CI
- measure the impact of SIMD optimizations
Example prompts for the agent
- Write a benchmark comparing string concatenation and
StringBuilderwith iterations from 10 to 1000 - Add
MemoryDiagnoserandRankColumnto the benchmark class - Create
.cursor/rules/benchmarking.mdcwith .NET performance testing rules
How to install benchmarking
Manually: put the files in place
.cursor/rules/benchmarking.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.claude/rules/benchmarking.mdThe paths frontmatter field limits the files: move globs from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.github/instructions/benchmarking.instructions.mdThe applyTo field sets which files it applies to: move globs from the source into applyTo
Manually: put the files in place
.devin/rules/benchmarking.mdManually: put the files in place
.clinerules/benchmarking.mdStep by step, with commands for each platform: Cursor rules: .mdc files, four modes and what replaced .cursorrules
Questions about benchmarking
How do I install benchmarking in Claude Code?
Save the rule to .claude/rules/benchmarking.md in the project root.
What does benchmarking do?
The rule teaches the agent to write .NET benchmarks using BenchmarkDotNet: set up the project, add [MemoryDiagnoser] and [Benchmark] attributes, use [Params], track allocations, and integrate execution into CI.
Why does the rule require void for [IterationSetup] methods?
BenchmarkDotNet versions up to 14.0 require [IterationSetup] and [IterationCleanup] methods to return void. Any other signature will cause a runtime error when executing the benchmark.
Source text
benchmarking.mdc · Apache-2.0
---
description: Designing benchmarks for measuring .NET performance
globs:
alwaysApply: false
---
# Cursor Rules File: .NET Benchmarking Best Practices
# This file provides guidelines for writing effective benchmarks using BenchmarkDotNet
# and other performance testing tools.
Role Definition:
- Performance Engineer
- .NET Runtime Specialist
- Optimization Expert
General:
Description: >
Performance testing and benchmarking should be systematic, reproducible,
and provide meaningful insights. Use BenchmarkDotNet as the primary tool
for micro-benchmarking and performance regression testing.
Requirements:
- Use BenchmarkDotNet for micro-benchmarks
- Ensure consistent test environments
- Follow scientific method
- Track performance metrics over time
- Consider memory and allocation patterns
Project Setup:
- Configure benchmark projects:
```xml
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net8.0</TargetFramework>
<Configuration>Release</Configuration>
<Optimize>true</Optimize>
<DebugSymbols>false</DebugSymbols>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="BenchmarkDotNet" Version="0.13.10" />
<PackageReference Include="BenchmarkDotNet.Diagnostics.Windows" Version="0.13.10"
Condition="'$(OS)' == 'Windows_NT'" />
</ItemGroup>
</Project>
```
Benchmark Structure:
- Basic benchmark setup:
```csharp
[MemoryDiagnoser]
[RankColumn, MinColumn, MaxColumn, MeanColumn, MedianColumn]
public class StringOperationsBenchmarks
{
private const string TestString = "Hello, World!";
private readonly StringBuilder _builder = new();
[Params(10, 100, 1000)]
public int Iterations { get; set; }
[GlobalSetup]
public void Setup()
{
// Setup code that runs once before all benchmarks
}
[Benchmark(Baseline = true)]
public string StringConcat()
{
var result = string.Empty;
for (int i = 0; i < Iterations; i++)
result += TestString;
return result;
}
[Benchmark]
public string StringBuilder()
{
_builder.Clear();
for (int i = 0; i < Iterations; i++)
_builder.Append(TestString);
return _builder.ToString();
}
}
```
Memory Analysis:
- Track allocations and GC:
```csharp
[MemoryDiagnoser]
[GcServer(true)]
public class MemoryBenchmarks
{
[Benchmark]
public IEnumerable<string> AllocatingMethod()
{
return Enumerable.Range(0, 1000)
.Select(i => i.ToString());
}
[Benchmark]
public IEnumerable<string> NonAllocatingMethod()
{
return Enumerable.Range(0, 1000)
.Select(i => i.ToString())
.ToArray();
}
}
```
Hardware Intrinsics:
- Measure SIMD performance:
```csharp
[SimpleJob(RuntimeMoniker.Net80)]
[RyuJitX64Job]
public class VectorBenchmarks
{
private float[] _data;
[GlobalSetup]
public void Setup()
{
_data = new float[1024];
// Initialize data
}
[Benchmark(Baseline = true)]
public float ScalarSum()
{
float sum = 0;
for (int i = 0; i < _data.Length; i++)
sum += _data[i];
return sum;
}
[Benchmark]
public float VectorSum()
{
return Vector.Sum(_data);
}
}
```
Async Performance:
- Benchmark async operations:
```csharp
public class AsyncBenchmarks
{
private HttpClient _client;
[GlobalSetup]
public void Setup()
{
_client = new HttpClient();
}
[Benchmark]
public async Task<string> SingleRequest()
{
return await _client.GetStringAsync("http://example.com");
}
[Benchmark]
public async Task<string[]> ParallelRequests()
{
var tasks = Enumerable.Range(0, 10)
.Select(_ => _client.GetStringAsync("http://example.com"))
.ToArray();
return await Task.WhenAll(tasks);
}
}
```
CI/CD Integration:
- Configure benchmark runs:
```yaml
- name: Run Benchmarks
run: |
dotnet run -c Release --filter '*'
- name: Store Results
uses: actions/upload-artifact@v3
with:
name: benchmark-results
path: BenchmarkDotNet.Artifacts/**
```
- Track performance over time:
```csharp
[Config(typeof(RegressionConfig))]
public class RegressionBenchmarks
{
private class RegressionConfig : ManualConfig
{
public RegressionConfig()
{
AddExporter(MarkdownExporter.GitHub);
AddDiagnoser(MemoryDiagnoser.Default);
AddColumn(StatisticColumn.Median);
AddColumn(RankColumn.Arabic);
}
}
}
```
Best Practices:
- Avoid common pitfalls:
```csharp
// Good: Proper benchmark isolation
[IterationSetup]
public void IterationSetup()
{
_data = new byte[1024]; // Fresh data for each iteration
}
// Avoid: Shared state between iterations
private byte[] _sharedData = new byte[1024]; // Can lead to false results
```
- Use appropriate job configurations:
```csharp
[SimpleJob(RuntimeMoniker.Net80, baseline: true)]
[SimpleJob(RuntimeMoniker.Net70)]
[SimpleJob(RuntimeMoniker.Net60)]
public class CrossVersionBenchmarks
{
[Benchmark]
public void BenchmarkMethod() { }
}
```
- Document environment requirements:
```csharp
/*
## Required Environment
- Windows 10+ or Linux with perf_event_paranoid <= 2
- CPU: Modern x64 processor with AVX2 support
- RAM: 16GB minimum
- Minimal background processes
*/
```
### IterationSetup and IterationCleanup Method Signatures
**Library Name**: BenchmarkDotNet
**Programming Language**: C#
**Library Version**: (,14.0]
**Severity**: Error (must be followed)
#### Rule Description
Always make sure to use `void` methods when defining `IterationSetup` or `IterationCleanup` activities for BenchmarkDotNet classes.
#### Good Examples
```csharp
// Good
[IterationSetup]
public void DoSetup()
{
}
[IterationCleanup]
public void DoCleanup()
{
}
```
#### Bad Examples
```csharp
// Bad - will throw runtime exception
[IterationSetup]
public async Task DoSetup()
{
}
[IterationCleanup]
public async Task DoCleanup()
{
}
```
#### Rationale
While async Task methods will compile, BenchmarkDotNet will throw a runtime exception when these methods are used. The framework requires these methods to be void methods to function properly.
# End of Cursor Rules File
© Aaronontheweb · Apache-2.0 · Aaronontheweb/dotnet-cursor-rules