golang-benchmark

Files (5)

• SKILL.md
• benchstat.md · references/
• compiler-analysis.md · references/
• pprof.md · references/
• trace.md · references/

SKILL.md (first lines)

# Go Benchmarking

Produce evidence that is reproducible enough to support the requested decision. Keep measurement and optimization as separate, independently verified steps.

## Start with the project

Before writing or running anything:

1. Read `go.mod`, repository instructions, existing `Benchmark*` functions, performance tests, and documented commands.
2. Identify the decision, workload, metric, and correctness condition. Latency, throughput, allocations, peak memory, and contention answer different questions.
3. Reuse the project's benchmark fixtures and tooling. If an optional analysis tool is unavailable, report that before changing the environment.
4. Keep the scope narrow enough that setup, unrelated tests, I/O, or shared infrastructure do not dominate the signal.

## Measurement workflow

1. Establish a baseline before changing code.
2. Write a representative benchmark with deterministic inputs and setup outside the timed region.
3. Confirm the benchmark still exercises the intended result; guard against dead-code elimination and accidental caching.
4. Run multiple samples under comparable conditions. Avoid concurrent benchmark jobs on the same constrained machine.
5. Change one relevant variable, repeat with the same command and environment, then compare distributions rather than isolated numbers.
6. Use a profile or compiler diagnostic only when it answers a specific unresolved question.
7. Re-run correctness tests after any optimization.

Prefer `b.Loop()` when the project's toolchain supports it. Preserve existing `b.N` benchmarks when compatibility requires them. Both forms are valid; follow the local minimum Go version rather than rewriting mechanically.

```go
func BenchmarkParse(b *testing.B) {
    input := loadFixture(b)
    b.ReportAllocs()

    for b.Loop() {
        _ = Parse(input)
    }
}
```

Use sub-benchmarks for meaningful dimensions such as input size or encoding. Name parameters explicitly so comparisons do not mix different workloads.

```bash
go test -run='^$' -bench='^BenchmarkParse$' -benchmem -count=10 ./path/to/pkg
```

Treat the command as an example. Match repository conventions and adjust duration or sample count based on observed variance and the size of the expected effect.

## Choose the next instrument

| Question | Instrument |
| --- | --- |
| Did before and after differ beyond normal noise? | Repeated benchmark samples; use [benchstat](references/benchstat.md) when available |
| Which functions consume CPU or allocate? | [pprof](references/pprof.md) |
| Why is wall-clock latency high while CPU is low? | [execution trace](references/trace.md) |
| Why does a hot path allocate or fail to inline? | [compiler diagnostics](references/compiler-analysis.md) |

Production capture is a separate operational action. Confirm the target, access controls, expected overhead, capture duration, and data handling before enabling or downloading profiles.

## Evidence standard

Report:

- the exact benchmark and commands;
- relevant Go version, OS, architecture, CPU, and environment constraints;
- sample counts and whether runs were comparable;
- baseline and candidate metrics, including allocation metrics when relevant;
- uncertainty, variance, and any inconclusive result;
- correctness tests used to guard the optimization.

Do not claim improvement when the comparison is inconclusive. A useful outcome can be “no measurable change under this workload.”

From reagin/agent-skills, MIT.

More from reagin/agent-skills