Skip to main content
rule CX Codex

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

Install into Cursor · Manually: put the files in place All methods and platforms ↓
.cursor/rules/benchmarking.mdc
Open on GitHub

What 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 StringBuilder with iterations from 10 to 1000
  • Add MemoryDiagnoser and RankColumn to the benchmark class
  • Create .cursor/rules/benchmarking.mdc with .NET performance testing rules

How to install benchmarking

Manually: put the files in place

.cursor/rules/benchmarking.mdc

Frontmatter: description, globs, alwaysApply

Step 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

Similar IDE rules

All IDE rules for Testing and QA →

From the same set11

The whole set →
code-signing Enforces .NET code signing patterns and SignClient configuration for NuGet packages in CI/CD pipelines. CX Codex +1 ★ 138repo stars consuming-dotnettool The consuming-dotnettool rule keeps .NET tool dependencies in a manifest, pins their versions, and adds restore steps for CI/CD. Use it when projects need repeatable tool setup. CX Codex +1 ★ 138repo stars dependency-management Rule for secure NuGet dependency management: vulnerability scanning, license compliance, versioning via dotnet CLI. Auto-applies to project files. CX Codex +1 ★ 138repo stars solution-management solution-management standardizes .NET solution architecture with explicit SDK pinning, shared build properties, and centralized package management. CX Codex +1 ★ 138repo stars nuget-package-publishing nuget-package-publishing — a rule that teaches the agent to pack .NET libraries into NuGet packages following industry standards: SPDX license, README, and debug symbols. CX Codex +1 ★ 138repo stars testing Defines xUnit testing conventions for .NET: project configurations, test isolation, coverage thresholds, and integration test setup. CX Codex +1 ★ 138repo stars coding-style The coding-style rule guides C# structure and style, from data types to error handling. Use it when you want an agent to follow functional patterns and keep abstractions focused. CX Codex +1 ★ 138repo stars dotnet-build dotnet-build — a scoped rule for .NET repos: plain dotnet CLI commands, version bumps pulled from release notes, and separate scripts for tests and release. CX Codex +1 ★ 138repo stars

Project sponsors

Companies that keep this analytics open