We built models that learned from the collective human knowledge, and now those models are holding up a mirror to the mess inside our systems.
Another week of building with AI coding tools has meant another week of carefully balancing my team’s passion for coding, engineering, and executing with the opportunity to empower them with AI.
That balance has been on my mind a lot….
I do not want AI to flatten the craft of engineering or turn thoughtful builders into button-pushers. I want it to strengthen the parts of engineering that already matter: judgment, clarity, ownership, and intent.
A Bad Name Sends Everyone the Wrong Way
I ran into this recently while working on a game project.
There was a controller called LanePicker. At first, that sounded reasonable. The game has roads. Roads have lanes. The system picks things. No alarms went off.
But “lane” quietly walked in carrying the wrong mental model.
In this codebase, the thing being picked was not really a driving lane. It was closer to a runtime map segment: a chunk of authored world content placed along the game’s forward axis, containing geometry, collectibles, traffic waypoints, atmosphere transitions, and other gameplay data.
“Lane” suggested lateral driving logic: left lane, right lane, vehicle movement, forward continuity. But the system was doing something broader. It was choosing, positioning, initializing, tracking, and retiring generated map segments.
Renaming it from LanePicker to MapSegmentPicker did not magically simplify the code. The responsibilities were still there. But the entry point became clearer. The name stopped sending the reader down the wrong path.
Agents build a working model from signals: file names, class names, method names, comments, docs, tests, patterns, and nearby usage. When those signals disagree, the agent has to guess. And when an agent guesses, it often does so with great confidence, which is both impressive and slightly terrifying. When the signals line up, it can move with less friction.
In this case, the docs now say the important thing plainly:
MapSegmentPicker chooses, positions, creates, and destroys runtime map segments.
That sentence is not decoration. It is stored context. A small cache of intent.
Documentation as Stored Context
Good documentation stores reasoning that is expensive to rediscover from code alone. It explains what the system is supposed to mean, not just what it currently does.
For the map segment system, the useful information is not only “what class calls what.” It is the invariants: active segments are ordered oldest-to-newest, new segments append to the back, old ones are removed from the front, and traffic stitching should use world-space continuity instead of blindly matching waypoint indexes.
An AI agent might derive some of that by reading enough code. But that costs time, tokens, and accuracy. A clear note turns repeated inference into lookup.
That does not mean every project needs a giant architecture manual. Nobody needs a 90-page PDF explaining why a class exists unless the class is also filing taxes. The better lesson, at least for me, has been smaller:
Make the language of the system match the shape of the system.
If a thing is a map segment, call it a map segment. If “lane” means three different things, separate those meanings. If a system owns an ordering guarantee, write it down.
Fewer Wrong Turns
AI makes implementation faster, but it does not make intent automatic.
Maybe that is the irony: the more advanced the tools get, the more they expose where our own language is fuzzy.
This started as a small lesson from day-to-day work: a bad name in a codebase can send both humans and AI agents in the wrong (one is way more confident then the other depending on how many tokens or coffee cups we have that day)
Agentic coding has made one old engineering lesson feel new again: language is architecture.
There is something funny about that. Only in the age of AI are we being forced to get more precise with our own communication. We built models that learned from the collective mess of human knowledge, and now those models are holding up a mirror to the mess inside our systems.
AI is starting to feel like live debugging for our collective hive mind. Mildly dramatic, yes. But also not entirely wrong.
A better name will not fix a bad system. A short note will not replace deep understanding. But both can reduce the number of wrong turns.
