Striff Engineering Data & research
63% of repositories hand their agents docs to build from. 8% of those check the code still matches.
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.
On this page
First published in July 2026. Rewritten in September 2026 with our own data: a survey of 335 open-source repositories.
We looked at 335 active open-source repositories whose own documentation describes their architecture. Sixty-three percent of them give their coding agents documents to build from. Of those, 8% run any tool that checks the code against an architecture rule. The rest of this post is where those numbers come from and why we think they matter.
Start with how a feature gets built at a growing number of companies. Someone writes a design doc: what the feature does, where it lives, what it must not touch. The architecture doc already says how the system fits together. An agent turns the design into an implementation plan, a list of small, checkable tasks, and works through it one task at a time. The next feature starts the same way, from the same documents.
The companies that build coding agents now tell you to work this way:
What the toolmakers now tell you
| Who | What they say |
|---|---|
| GitHub, Spec Kit | "Instead of coding first and writing docs later, in spec-driven development, you start with a (you guessed it) spec." It "becomes the source of truth your tools and AI agents use to generate, test, and validate code." |
| Anthropic, Claude Code | "Explore first, then plan, then code." Have Claude write the spec to a file, then: "Once the spec is complete, start a fresh session to execute it." |
| Cursor | "Most new features at Cursor now begin with Agent writing a plan." |
| OpenAI, Codex | Execution plans are "thorough design documents, and 'living documents'", an approach that has "enabled Codex to work for more than seven hours from a single prompt." |
| Google, Conductor for Gemini CLI | "Plan before you build." Specs and plans "live alongside your code in persistent Markdown files." |
| AWS, Kiro | Every feature starts as requirements.md, design.md ("technical architecture, sequence diagrams, and implementation considerations") and tasks.md. Amazon's internal memo, per Reuters: "We're making Kiro our recommended AI-native development tool for Amazon." |
| Thoughtworks Technology Radar | Curated shared instructions for software teams, such as an AGENTS.md committed to the repository: Adopt. Spec-driven development, in Assess: "We've seen many developers adopt this style." |
Sources: GitHub, Anthropic, Cursor, OpenAI, Google, Kiro and Reuters, Thoughtworks Radar Vol. 33.
Birgitta Böckeler put it most plainly on martinfowler.com: “The spec becomes the source of truth for the human and the AI.”
The docs became the program
For twenty years a design doc had one reader, the next engineer, and it could go stale because that engineer could ask someone. Now its main reader is an agent that implements whatever it says, every time, and asks nobody. The documents in your repository are the instructions your code is built from.
The adoption curve is steep:
Docs for agents, in eighteen months
Sources: Linux Foundation; github/spec-kit and obra/superpowers, star counts as of September 15, 2026 (OpenSpec has 68k and the BMAD method 53k); Agent READMEs, arXiv 2511.12884.
Three levels of spec-driven, and where the guard goes missing
Böckeler’s survey of Spec Kit, Kiro and Tessl sorts spec-driven development into three levels, and the sorting matters more than the label. At the first level, spec-first, a spec drives one task and can be thrown away when the task ends. At the second, spec-anchored, the spec is kept after the task and the feature keeps evolving through it. At the third, spec-as-source, a human edits only the spec and never the code.
The first level asks nothing of the spec once the task is done. The other two ask it to stay true indefinitely, because every later change is made from it. That is the level most teams in our survey are already at without naming it: 22% keep spec or plan files for agents to build from, and the 63% that hand their agents AGENTS.md, CLAUDE.md or architecture docs are spec-anchored in practice, whatever toolkit they use. The document outlives the task and the next task starts from it.
So the question a spec-anchored team has to answer is who notices when the spec stops being true. That gap between what the spec says and what the code does is spec drift. The toolkits answer how to write the spec and how to build from it. None of them answers that. In our survey, 8% of the repositories that hand their agents docs run anything that checks the code against an architecture rule, and no tool in the table above checks a spec against the code it produced. The rest of this post is about that gap.
Every practice got more load-bearing
There’s a comforting story that goes with all this: AI writes cleaner code than most humans, so the old disciplines matter less now. We think it has it backwards. Almost no engineering practice exists to help you write code. They exist so you can change code later, safely, without holding the whole system in your head:
What each practice is for
Tests
Confidence to change something six months from now without fear.
Readable code & naming
Cheap onboarding for the next reader, who is now as likely to be an agent as a person.
Small PRs
Units of change a human can hold in their head and judge.
Docs & ADRs
Shared memory, and now the instructions agents build from.
Every practice manages the cost and risk of future change. None of them is about typing speed.
What AI changed is the volume of change. If these practices are the machinery for managing change, and AI multiplied change, every one of them now carries more weight. The industry data agrees:
What the industry data shows
Sources: GitHub Octoverse 2025; Faros AI, The AI Productivity Paradox (a vendor study; correlations across teams); GitClear, June 2026. And Google's 2025 DORA report: AI adoption "now improves software delivery throughput… However, it still increases delivery instability."
GitClear’s connectivity number is the one we keep coming back to. In their words: “New code is less and less woven into the existing codebase.” Refactoring, the work that keeps a codebase’s shape coherent, has fallen to under 4% of changed lines. Line by line the code may be fine. The properties degrading are system-level ones, while everyone’s attention stays at the line level.
So we measured it ourselves
When we first wrote this post, every number in it was somebody else’s. This time we looked at the repositories this matters most for: 335 active open-source projects whose own documentation describes their architecture. For each one we read the last 30 merged pull requests, and the files, build and config on the default branch.
335 repositories that wrote their architecture down
Our survey, September 2026. Active public repositories in Java, Python, C# and TypeScript whose docs state architectural rules; not a random sample of GitHub. AI involvement means a co-author trailer naming an AI tool, a pull request opened by a coding agent, or a "Generated with" footer; that is a floor, since tab completion and chat-assisted edits leave no trace. Architecture checks means ArchUnit, import-linter, dependency-cruiser, NetArchTest and similar, detected from default-branch build, config and CI files, with every hit checked by hand.
Put those together. In repositories that went to the trouble of writing down their architecture, AI agents are already in roughly one pull request in three. Repos with an AGENTS.md or CLAUDE.md see more: 38% of their merged pull requests involve an agent, against 18% in repos without one. Nearly two-thirds hand their agents documents to build from, and of those, 92% run nothing that checks an architecture rule. The agents are building from the docs, and in those repositories nothing checks that the code still matches them.
The practices that scale themselves, and the one that doesn’t
Most of the classic practices have a guardian that scales on its own. Style has linters. Correctness has tests and CI. Even readability has help now, since coding assistants are good at naming and idiom. Crank the volume up and these hold, because the enforcement is mechanical and per-file.
What’s left unguarded:
Every practice has a guardian, except one
| Practice | Who enforces it | Holds as volume grows? |
|---|---|---|
| Consistent style & formatting | Linters, formatters | ✓ Automatic |
| Correctness | Tests, CI, type systems | ✓ Automatic |
| Readable code, good names | Review norms + coding assistants | ✓ Mostly |
| Small, focused diffs | Team norms | ✓ If you insist |
| What your docs say about the code | Nobody | ✗ Goes stale silently |
| Dependency direction & boundaries | Nobody, in 92% of the repos above that give agents docs | ✗ Erodes silently |
| Modules keeping their internals private | Nobody | ✗ Erodes silently |
| No dependency cycles | Nobody | ✗ Erodes silently |
The unguarded rows are all global. You cannot check them by looking at one file, one diff, or one PR. They exist only in the relationships between components, which per-file tooling can't see.
The practice with no guardian is architecture: what your docs say the system is, which component depends on which, whether boundaries hold, whether the shape is drifting. In a docs-first workflow that is also the practice the agents lean on hardest, because the architecture doc is what they read before they touch anything.
When the docs are the program, drift is a bug
A stale doc used to cost a confused new hire an afternoon. Now it costs every agent run that reads it, and agents do what the docs say. ETH Zurich’s study of AGENTS.md files found that “instructions in the context files are well followed by coding agents.” The same study found that context files do not generally raise task success rates. Agents still do what they say, so a wrong one sends them the wrong way. An engineer who documented a 108,000-line codebase for agents reported what happens when those instructions go stale:
Source: Codified Context, arXiv 2602.20478
Böckeler saw it in her own tests: given notes describing classes that already existed, the agent “took them as a new specification and generated them all over again, creating duplicates.” Keeping the instructions current measurably matters: in a study of AI IDE rule files, compliance rose “from 49.14% to 72.13%” after the rules were updated (arXiv 2606.12231). Meanwhile, in a sample of 100 context files, 24% had never been changed since they were first committed (arXiv 2606.15828).
And the docs are drifting faster than anyone is watching them:
Output scaled. Oversight didn't.
| Output | Oversight |
|---|---|
| +23% pull requests merged on GitHub per month, year over year | +91% PR review time on high-AI-adoption teams |
| +98% pull requests merged on high-AI-adoption teams | 4.6x longer wait before an AI-generated PR gets reviewed |
| +154% average PR size on the same teams | 8% of repositories that give agents docs check any architecture rule |
Sources: Octoverse 2025; Faros AI; LinearB 2026 benchmarks (8.1M pull requests; a vendor study); our survey above. Writing stopped being the bottleneck. Noticing what the writing did to the system still is.
The mechanism is simple. A diff shows you lines. It does not show you that those lines made a sentence in your own README false, or created the first edge from your core into a plugin. That information lives in the relationship between this change and everything around it: other files, other documents, every change before it. It is absent from the thing your reviewers are reading. Here is a real one:
The same pull request, two representations
Ericsson/ecchronos #1786, a real pull request. The call moved to a new class, SchemaRefresher; the sentence on the right did not move with it. It sits in a file the diff does not contain, so no amount of careful diff-reading surfaces it, and as of September 2026 it is still on master. The next agent asked to work on NodeWorker reads that sentence first. The whole story.
The reviewers of that pull request were not careless. They approved a clean refactor, and the sentence it made false was in a file they had no reason to open.
The bill comes due quietly
Nothing crashes. The docs drift one clean-looking PR at a time, the agents keep building from them, and the codebase accumulates coupling and duplicated responsibilities until the symptoms show up as things nobody connects back to architecture: builds got slow, onboarding takes months.
What to do
Keep every practice you already have, and keep writing the design docs, specs and plans. That is the right way to work with agents. But if the docs are what your agents build from, the docs have to stay true, and in 92% of the repositories that hand their agents docs, nothing checks that they do.
Give that one unguarded practice what every other practice already has: an automatic check on every pull request. If your team has an ArchUnit or import-linter setup, run it in CI. If the rules live in prose, that is what we built Striff for: it reads the sentences already in your docs, turns the checkable ones into rules, and evaluates each at both revisions of every pull request, quoting the sentence a change broke.