Lydia Hallie on the Claude Code team published a piece this week on the two settings that shape a coding agent's output: which model you pick and how much effort you let it spend. It's a clear explainer, and the heuristic at the end is the quotable part — when the agent gets something wrong, ask whether it didn't know enough (reach for a bigger model) or didn't try hard enough (raise the effort). Worth reading.
Her writing helped me isolate a concept I've observed on real, messy client projects. Let me share the thinking.
What the model actually knows
Her explanation comes down to this: a model's weights are frozen at training time. By the time you send a request they're read-only. Everything the model "knows" — TypeScript, idiomatic Go, a popular framework's API — was baked into those weights during training. Your prompt, your CLAUDE.md, the files you put in context: none of it changes the weights. It steers the prediction; it doesn't teach the model anything that lasts. If a library didn't exist when the model was trained, it isn't in there. You can paste the docs and the model will use them for that one request, but it hasn't learned anything — next session it's gone.
That has a sharp consequence for how we build software.
An agent writes code by predicting the next token, over and over, from those frozen weights. Against a well-trodden pattern — a standard repo layout, a common framework used the way its docs intend, a widely published convention — its predictions are strong, because it has seen thousands of examples of exactly that. The probability lands on the right token. Against something idiosyncratic — a homegrown abstraction nobody outside your company has seen, a local convention that contradicts the common one — the predictions get weak. The model has nothing to draw on, so it guesses from the nearest thing it has seen, and states the guess with total confidence. That's what a hallucination is: a plausible token sequence from training patterns, not a failed lookup.
Why an organically-grown codebase fights the agent
This stopped being abstract for me inside a client's codebase — a large, organically-grown system, the kind that accretes over years with nobody stopping to enforce conventions. It's been a bear. For a while I blamed the usual suspects: coupling, missing tests, tribal knowledge. (I spent a good while blaming the tests.) All real. But the weights framing named the deeper problem. The code doesn't follow published best practices, so almost nothing in it ### matches what the model has seen a thousand times. Every prediction the agent makes is operating out-of-distribution. What it produces looks reasonable and then fails review — a subtly wrong import, the wrong layer touched, an interface used in a way that violates the local (unwritten, unusual) rules.
So we compensate the only way you can when the knowledge isn't in the weights: through context. We over-engineer it. Long CLAUDE.md files, example after example, conventions spelled out that a standard codebase would have made obvious, the same local quirks re-explained every session because the model never retains them. It works — steering genuinely works — but it's expensive, fragile, and it never compounds. You pay, every request, for the standardization the codebase never adopted. It's a running context tax.
Best practices are now how you talk to the model
That reframes what best practices are for. We used to justify them in human terms: readability, onboarding, fewer surprises for the next engineer. Those still hold. But there's a second reason now that may matter more. Published, conventional patterns are the ones that made it into the weights. Follow them and the agent already knows most of your codebase before it reads a line, because your codebase looks like the millions of examples it trained on. Deviate and you have to re-teach it your world, from scratch, in context, every time.
I'm not saying never build anything custom. Sometimes the bespoke thing is the actual value and worth the cost. But the cost calculation moved. A nonstandard convention used to cost you the next human's ramp-up time. Now it also costs you agent accuracy and a permanent context tax on everything that touches it. If you're planning to hand real parts of the build to agents — and I am, with real teams — "follow the well-published pattern" stops being a style preference and becomes an operating requirement. The most agent-legible codebase is the boring, conventional one.
Before you touch the dials
There's a nice symmetry with Hallie's heuristic. She says if the model had the context, clearly tried, and still got it wrong, that's a capability problem — reach for a bigger model. My addition sits one layer up. Before you touch either dial, ask whether the thing you needed the model to know was ever knowable — whether it exists in public, sourced, conventional form that could have landed in the weights at all. If it doesn't, no model and no effort level will save you; context is the only lever left. And the smarter move is to stop leaning on that lever so hard. Adopt the standard, and let the weights do the work you're currently paying to replace on every request.
The migration you can finally afford
There's an obvious objection to all this: standardizing a large organic codebase is a huge lift, and nobody has the roadmap room for it. That's been true for years — the cleanup always loses to the next feature. AI-native delivery changes the math. When you run the process I teach and let governed agents carry the build, work that used to take two months ships in days to weeks, and that reclaimed capacity is exactly what you spend paying down technical and architectural debt: migrating the homegrown conventions toward published, standard ones. That migration compounds, because every step toward conventional patterns makes the codebase more legible to the agents, which makes the next feature faster, which frees up more room to keep going. That's the part I like most — the speed and the standardization start funding each other instead of competing for the same roadmap slot.
Jason Vertrees is the founder of Heavy Chain Engineering (heavychain.org), which helps lower middle-market vertical SaaS companies and PE firms turn scattered AI usage into measurable delivery leverage — 85% faster feature velocity, six-to-eight-week projects shipped in days. If you want help building an AI-native engineering organization, book an AI Delivery Assessment (app.onecal.io/b/jason-vertrees/30-mins).