Backend Performance Review: An Agent Skill
An open-source Agent Skill that teaches AI coding agents evidence-based backend performance review. Technology-agnostic, workload-driven, and it never invents a number.
Pipeline
Highlights
- ▸Every finding states the workload that makes it matter, the evidence behind it, and a falsifier that would prove it wrong.
- ▸Zero findings is a valid result: the skill refuses to manufacture problems or invent p99s it never measured.
- ▸Priority is derived from a published severity × confidence matrix, so rankings are reproducible instead of vibes.
- ▸Ships as a Claude Code plugin and a GitHub Action that reviews every PR (advisory, never blocking).
The problem
Ask a coding agent to “review this backend for performance” and you usually get one of two failure modes. Either a generic checklist (“check your indexes, consider caching, watch out for N+1”) that has nothing to do with the code in front of it, or confident fabrication: invented p99 latencies, imagined query plans, and a recommendation to add Redis to a service with fourteen users.
Both come from the same root cause: no discipline about evidence and no model of workload.
How it works
The skill is a methodology the agent follows, plus reference files it loads only when the detected stack calls for them. A Postgres service never loads the document-store reference.
- Detect the stack from manifests, lockfiles, and container and infrastructure config, optionally via a bundled read-only Python script.
- Build a workload model from repository evidence (load tests, autoscaling config, pool sizes, alert thresholds), then ask at most seven questions once. If they go unanswered, the skill proceeds and caps its own confidence.
- Score every finding on two axes, severity and evidence-graded confidence, and derive priority from a published matrix.
- Attach a validation plan to every recommendation, including a falsifier and a production-safety label on every diagnostic command.
Every number in a report traces to a file, to something the user supplied, or to a labelled derivation.
Evaluation
The skill has been run against eight real public repositories across eight stacks, including
independent blind passes by agents with no memory of earlier reviews. On every repository with a
prior review to compare against, the blind pass reproduced or exceeded the original primary
finding, and on three of four it found real evidence the original missed, including a hard
SyntaxError that stopped one application from importing at all.
The evaluation also turned up seven real bugs in the skill’s own detection tooling, such as ORM-provider false negatives on the JVM and .NET, all now fixed. Testing the tool honestly was as much of the project as building it.
What it deliberately does not do
It does not modify code, run anything against production, or replace a profiler or APM. It reads, reasons, and reports, and says plainly when nothing it reports has been measured.