标签：#codequality

There is a growing sentiment in engineering circles right now that documentation is a relic of the past. The argument usually goes something like this: We’re living in the era of agent-driven development. If an AI agent can read the raw source code or parse an OpenAPI specification instantly, why waste human engineering hours writing prose? Code churns too fast anyway, and human-written docs are outdated the second they’re committed. It’s an attractive, black-and-white view of the world. It’s also completely wrong. Chasing strict determinism in your source of truth is a pipe dream. Code and specs tell a system how something works, but they are fundamentally incapable of explaining why it was built that way in the first place. The Intent Gap: Why Code Isn't Enough Even if you’re building entirely for a downstream consumer of AI agents, there is a massive, structural gap between a raw API specification and an operational reality. Agents are phenomenal at pattern matching and syntax execution, but they struggle with architectural philosophy and human intent. We still need words to contextualize the boundaries. A spec can define an endpoint, its parameters, and its payload. What it can't capture is the nuance of why a specific architectural trade-off was made, or the implicit historical context of a legacy edge case. Prose provides the guardrails for non-deterministic systems. Even if that prose is ultimately consumed by a machine rather than a human, the written word remains the highest-leverage way to transmit intent. The Danger of Slop Describing Slop This doesn't mean we need to return to the days of manually maintaining massive, static wiki pages. Automation has a massive role to play here. Cascading automation—where documentation is dynamically generated alongside code changes—is incredibly powerful. But there’s a trap here: slop describing slop is entirely useless. If we completely hand off documentation generation to unchecked LLMs, we end up with a feedback loo

A while back I set three targets for my engineering team. Not velocity. Not story points. Not "things shipped." Just three numbers. Together they tell me whether the work is moving the way it should, or whether next week is shaping up to be a fire-fighting week. I check two of them most days. The third I used to watch closely...until we lost the tool that measured it. Here they are, and why they earned their spot. Why these and not just velocity The first metric most engineering managers reach for is velocity. Story points completed, tickets closed, work merged. Velocity is worth watching. It is a lagging indicator...it tells you what already happened...but it still shapes what comes next. When a sprint's work doesn't get finished, it rolls into the following one, and that rollover eats into whatever you had planned. What velocity doesn't tell you is how the work moved...whether it moved in a way that's going to come back and bite you. For that you need numbers that describe the shape and quality of the work, not just the amount of it...ideally ones that flag a problem while there's still time to act. These three do that. 1. Average PR size Target: under 300 lines changed per PR. What it tells me: how well the team is decomposing work. A team consistently shipping oversized PRs isn't producing more... they're producing PRs that no reviewer can read carefully. Big PRs get rubber-stamped. Rubber-stamped PRs are where production bugs hide. The 300-line target isn't magic. It's roughly the size below which most reviewers will actually read every line. I tell my team to aim for under 300 changes and to treat 500 as a hard ceiling, give or take a handful of genuine exceptions. Past 500 changes, I consistently see quality, review time, and thoroughness all drop sharply...the PR stops getting read and starts getting skimmed. When the team's average creeps up over a few weeks, I have an early signal that one of three things is happening: Stories are too coarse. The work does