Software Practices

Performance

Measured cost and latency, plus the benchmark discipline needed to justify an optimization.

15 items in this guidance cluster.

Tagged guidance

Agent Workflow rules

RuleAgent WorkflowSecurity PrivacyVerificationEncode Nonfunctional RequirementsAGENT-ENCODE-NONFUNCTIONAL-REQUIREMENTSPut invisible constraints such as security, accessibility, latency, and compatibility near the task. Encoding them upfront makes those requirements part of the implementation target.

Performance rules

RuleVerificationReviewabilityAvoid Single-Run Performance ConclusionsPERF-AVOID-SINGLE-RUN-CONCLUSIONSDo not land performance conclusions from one short benchmark run. Repeat and contextualize timing evidence because warmup, scheduling, cache state, and background load can make a single result non-reproducible.RuleDependenciesReviewabilityChange ShapeJustify Complexity, Churn, and DependenciesPERF-JUSTIFY-COMPLEXITY-CHURN-AND-DEPENDENCIESExplain why a performance win justifies added complexity, churn, unsafe code, caching, or dependencies. Measured speedups still need to pay for the maintenance cost every future reader inherits.RuleVerificationReviewabilityMeasure Goal, Change, and ComparisonPERF-MEASURE-GOAL-CHANGE-COMPAREState the performance goal, baseline measurement, implementation change, and comparison result together. Those pieces let reviewers judge whether the patch improved the relevant workload enough to justify its tradeoffs.RuleVerificationChange ShapeOptimize Measured HotspotsPERF-OPTIMIZE-MEASURED-HOTSPOTSOptimize code that measurement shows is on the important runtime path. This keeps review attention on changes whose user-visible impact justifies altering the code shape.RuleVerificationToolingSource TruthRecord Benchmark ProvenancePERF-RECORD-BENCHMARK-PROVENANCERecord the commands, inputs, tool versions, build profile, and runner conditions behind benchmark numbers. Provenance makes future comparisons meaningful and helps separate real changes from environment drift.RuleVerificationTestingRun Correctness Before TimingPERF-RUN-CORRECTNESS-FIRSTRun relevant correctness checks before interpreting performance timing. Fast code that changes behavior invalidates the benchmark claim and wastes review effort.RuleVerificationAutomationRun Timing Benchmarks SequentiallyPERF-RUN-TIMING-BENCHMARKS-SEQUENTIALLYSerialize timing-sensitive benchmarks when their numbers will be used as evidence. Concurrent runs compete for shared resources and can make the comparison describe the runner more than the code.

Rust rules

RuleRustVerificationReviewabilityAdd Benchmarks for Performance ClaimsRUST-ADD-BENCHMARKS-FOR-PERFORMANCE-CLAIMSUse benchmarks when Rust changes rely on speed, allocation, or hot-path claims. The evidence makes performance tradeoffs reviewable instead of relying on intuition.RuleRustPublic APIReader LocalityChoose Generics and Trait Objects DeliberatelyRUST-CHOOSE-GENERICS-AND-TRAIT-OBJECTS-DELIBERATELYPick generics, stored type parameters, or trait objects for the variation they actually model. The choice affects compile cost, object safety, lifetimes, and caller ergonomics.RuleRustDocumentationPublic APIDocument Performance ContractsRUST-DOCUMENT-PERFORMANCE-CONTRACTSState meaningful performance expectations when callers may design around them. Clear limits keep complexity and optimization claims tied to supported behavior.

Testing rules

RuleTestingAutomationReviewabilityKeep Slow Checks out of PR CITEST-KEEP-SLOW-CHECKS-OUT-OF-PR-CIKeep long fuzzing, exhaustive matrices, and noisy benchmarks out of required PR CI. Fast gates preserve review flow, while heavier checks belong in release or scheduled validation.

Pattern item

PatternAgent WorkflowVerificationSecurity PrivacyEncode Nonfunctional Requirementsencode-nonfunctional-requirementsPerformance, security, accessibility, privacy, and reliability expectations are easy to lose when they live only in prose. Encode important requirements in tests, budgets, schemas, automation, or review gates where the system can keep enforcing them.

Principle item

PrincipleVerificationTestingMeasure Before Optimizingmeasure-before-optimizingPerformance work needs a workload, baseline, goal, change, and comparison. Evidence keeps optimization from becoming readability, dependency, or API churn without a proven payoff.

Mechanism item

MechanismTestingVerificationToolingTesting And Benchmarkingtesting-and-benchmarkingTest, feature-matrix, fuzzing, property, and benchmark tools should be chosen by risk and feedback cost. This mechanism helps match validation depth to the behavior, integration surface, or performance claim under review.