On documented architecture, and making it hold.
Spec-driven development, spec drift and documented architecture: real findings from open-source pull requests, and how to keep code true to the docs it was built from.
Topics
Design doc, then plan, then the agent builds it task by task: spec-driven development is how the companies that make coding agents now tell you to work. We surveyed 335 open-source repositories whose docs describe their architecture. 63% already give their agents docs to work from, and only 8% of those run anything that checks the code against them.
Design docs have a second reader now: coding agents build from them, and nothing in a pull request checks that the code still agrees with the prose. Striff turns the sentences already in a repository into rules and checks them at both revisions of every pull request. What that looks like on one real change, and how often it fires across 609 public ones.
AI review comments are easy to write and hard to trust. What a Striff check on your pull request actually says, where each line of it comes from, and how to verify any of it yourself in under a minute.
What afferent and efferent coupling measure, how to read them alongside complexity, inheritance depth and encapsulation, and why none of these numbers should reach a reviewer as a finding on its own.
Seven steps for reviewing a pull request for structural risk: what your own docs already say, new dependency directions, reaches into module internals, blast radius and cycles. Plus the arithmetic on how long it takes, and which steps a machine can do for you.
