In my last post I asked whether AI would keep us stuck in 2020 architectures. I argued that the model has no opinion about which architecture is better. What it has is a confidence gradient, shaped entirely by how well-specified each option is, and so the fix is to make new patterns legible: document them thoroughly enough that an assistant can follow them even though it has never seen ten thousand examples.
I still believe that. But I've kept turning the argument over, and I've become convinced the conclusion is less comfortable than “so write better docs.” If I take my own premise seriously, it leads somewhere with real consequences for who actually gets to decide what software looks like from here. Three steps get there.
“Just write better docs” is a trap door, not an exit
The strongest objection to my last post is deflationary, and I want to meet it head on because I nearly talked myself into it. If documentation is the lever, then document your existing stack better and skip the new framework entirely. Hand the model a thorough rules file for the Spring conventions you already use, and you get AI-legible code without adopting anything new.
It's a fair point, and it's wrong in an instructive way. Notice which direction that lever points. Improving the legibility of the thing that is already winning only entrenches it further. “Write better Spring docs so the AI uses Spring well” doesn't rebut my argument. It is my argument, aimed at the status quo. The deflation collapses into the claim it was meant to puncture. Documentation is never neutral; it always advantages whatever it documents. Pointed backward, it is a force for staying exactly where we are.
The lock-in is to a vintage, not a vendor
I framed last time as new-framework-versus-Spring, with OfficeFloor as the test case. That framing was too small, and it let Spring off the hook unfairly. The same gravity drags Spring's own modern patterns.
Ask an assistant to “add a REST endpoint” with no further steering and you'll reliably get an imperative @RestController, blocking JPA, and quite possibly RestTemplate, a client Spring has effectively retired. You will not, by default, get WebFlux, the functional RouterFunction style, RestClient, or anything touching the AOT and native-image work. Not because those are wrong, and not because Spring failed to document them, but because the corpus's center of mass is older than Spring's current recommendations.
I don't say this to knock Spring. I built Spring Boot in as the base of OfficeFloor v4 precisely because the ecosystem is far too good to replace. The point is that even the incumbent can't easily pull its own users forward. What AI locks us into isn't a vendor at all. It is a vintage, roughly mainstream Java at peak Stack Overflow. Spring-introducing-WebFlux faces a gentler version of the exact headwind OfficeFloor faces. This is not a competitive disadvantage for newcomers; it is a structural tax on novelty itself.
Documentation lifts the ceiling, not the floor
This is the distinction I understated last time, and my own experiment shows it. When I worked with an assistant to convert Spring PetClinic REST over to the OfficeFloor YAML approach, documentation was the bottleneck, and once the docs were good enough the conversion went through. But there was a quieter result I didn't dwell on: left to its own judgement, with no steering, the assistant reached for @RestController every single time.
That's the whole thing in miniature. Documentation does real work, but only one kind: it makes a pattern usable when explicitly asked for. That's the ceiling. It does nothing to the pattern the model reaches for unprompted. That's the floor. The docs are what let the assistant produce something other than a controller once I told it to. They never changed what it volunteered when I didn't. So even a perfectly documented new architecture stays opt-in, competing against a default that is opt-out. Docs let an innovation be chosen. They don't make it get chosen by default, and they don't make it get discovered by anyone who didn't already know to ask. Necessary, but nowhere near sufficient.
And the floor is sinking
Now make it dynamic, which is the part that worries me most. If AI writes a growing share of new code, and that code clusters on the center of mass, then the next training corpus is more concentrated there, and the next model's default is stronger. The patterns a model reaches for unprompted don't merely persist. They compound, as models increasingly train on their own most common output.
That isn't static lock-in. It is a ratchet toward the mean: the space of architectures a model will volunteer narrows over time, generation by generation. The conservative force I identified last time is self-reinforcing. Left alone, “what's common” and “what's good” don't just differ. They actively diverge.
So who sets the default?
If documentation only lifts the ceiling, then the thing that actually decides which architectures survive is whatever sets the floor: the agent's system prompt, the project's rules file, the scaffolding and templates a tool ships with, and underneath all of it, the model's priors. A single line in a rules file can flip the default outright:
# AGENTS.md / rules file When adding a REST endpoint, define it as a YAML endpoint file under src/main/resources/officefloor/rest/, one function per step. Do not generate @RestController classes.
That relocates architectural power in a way worth naming plainly. It used to sit, in theory at least, with “the best idea wins on merit.” It now sits with whoever configures the agents. My “is this idea legible to an AI” was the entry ticket; it only gets you into the room. The harder version of my own point is this: legibility gets you considered; only the default gets you chosen.
What follows, including for me
This changes what I think I owe you as the author of OfficeFloor. The job isn't finished when an assistant can use YAML endpoints because I documented them well. It's finished when an assistant reaches for them without being told, which means the starter should ship with the agent rules and scaffolding that make function injection the default, not just tutorials that make it possible. The battleground is the configuration my users actually load, not the tutorial they may never read.
For teams, the implication is broader: your architectural decisions increasingly live in your agent configuration, not only in your codebase. An unmanaged default is still a decision, a decision to ship 2020. The rules file deserves to be treated as a first-class architectural artifact and reviewed like one.
And for all of us: be a little wary of the ratchet. “The model wrote it this way” is evidence that a pattern is common, not that it is good, and those two properties are now drifting apart on purpose.
AI won't keep us in 2020 by holding opinions. It will keep us there by holding defaults, and defaults are always set by someone. The question I opened isn't really whether my idea is legible. It's who sets the default when nobody is steering, and that turns out to be less a technical question than a political one. I'd rather we decided it on purpose than inherited it by accident. As before, I'd be glad to hear from anyone seeing the same thing, especially anyone who has tried to win the default for a new pattern and found out what it costs.
No comments:
Post a Comment