Guide
What Good Engineering Velocity Looks Like
Velocity measures how much a team ships, not how well. Here is a realistic model of healthy velocity: median over mean, quartiles, percentile bands, and why a dip is often a good sign.
Velocity is a measure of how much shipped work a team produces over a period. It answers "how much", never "how well". Kept in its lane and read alongside quality, it is one of the most useful signals a team has. Stretched into a performance score, it becomes actively harmful.
The goal of this guide is to give you a realistic mental model of what healthy velocity looks like: why raw lines of code are a trap, why you should read the median and quartiles instead of an average, how to interpret a trend against percentile bands, and why a dip is often a good sign rather than a red flag.
Define velocity as output, not effort
Velocity should reflect shipped, merged work, scored so that a large, low-value change does not outrank a small, high-impact one. It is deliberately not a measure of hours, keystrokes, or commits. Anchoring it to merged pull requests keeps it about outcomes reaching production, which is the only thing a customer ever feels.
Never use raw lines of code
Lines of code is the classic velocity trap. It rewards verbosity, punishes deletion and refactoring, and is trivially gamed. The best change is often a small one that removes code. Any velocity number built on LOC will quietly push your team toward bloat. Score by impact and merged work instead.
Report the median and the quartiles
Team output is uneven by nature: a few people or a few weeks carry more. An average hides that and is dragged around by outliers. Report the median as your headline and the quartiles (p25/p75) to describe the spread. A widening gap between quartiles is itself a signal worth reading.
Read the trend against percentile bands
A single month tells you little. Plot velocity over time and overlay percentile bands (p25 to p90) so you can see whether you are drifting within the normal envelope or genuinely breaking out of it. Direction and consistency matter far more than any one absolute number. A steady climb inside the band is healthier than a spiky series that occasionally touches p90.
Recognize when a dip is healthy
Not every velocity drop is a problem. Paying down technical debt, onboarding new engineers, hardening tests, or a holiday period will all lower short-term output and are often exactly the right investment. Treat a dip as a question ("why?"), not a verdict. A team that never dips may be avoiding necessary but unglamorous work.