Why coding agents invent their own words
Dennis Zaiser, technical founder
Ask three agent sessions to build parts of the same feature and you may end up with three names for one thing: workspace, team and organization. None of them is wrong in general. Only one is right for your product, and the agents have no way to know which.
Where an agent's words come from
An agent chooses words the way it chooses everything else: the most plausible option given what it has read. When it starts fresh, most of what it has read is the wider world's software, where the same concept goes by many names. Unless your product's word appears in what the agent reads for this task, it falls back on the common one.
Inside one session, an agent is usually consistent. Across sessions it isn't. Each new session starts without the vocabulary the last one used, and nothing makes it look. If the code it opens happens to use your word, it may follow. If it opens a file that uses a different one, it follows that instead.
The problem grows with the product. A small project has a handful of concepts, and an agent that reads most of the code sees all of their names. A product with hundreds of concepts can't be read whole in one session, so each agent sees a slice, and each slice has its own local habits.
How one synonym spreads
A new word arrives in one place: a variable, a table column, a heading in the docs. The next agent searches for the concept by the word it knows and finds half the code. It concludes that the concept doesn't exist where it does, and builds a second version of it. Or it finds both words, assumes they mean different things and keeps them apart on purpose.
A few weeks later, the field in the interface is called one thing, the label on screen another, and the docs use a third. Customers notice before you do. Search inside your own project misses half of what it should find, and every agent that comes later inherits the confusion and adds to it.
Fixing it late is expensive. A rename touches code, stored data, docs, messages and every place a person learned the old word. The longer the drift runs, the more of it there is to undo.
The same word for two things
The opposite failure is quieter: one word used for two concepts. Account means the login in one place and the paying customer in another. Run means one agent session here and a whole workflow there. People resolve the ambiguity from context without noticing. Agents carry it straight into the code.
That is where it turns into defects. A permission check reads the wrong kind of account. A report counts sessions when it should count workflows. Nothing about the code looks wrong, because the word is right. Only the meaning is not.
So a useful definition says two things: what the word means, and what it must not be confused with. The second half is the one that stops the defect.
A glossary agents check before they write
The fix is a glossary that agents use rather than one they are told about. It starts with one term per concept and a short definition. Each term lists its aliases, the synonyms people and agents reach for, so a search for any of them finds the term. And each term names its neighbour: organization, alias org, not to be confused with workspace.
What matters most is when the glossary is read. An agent should check its words before it writes code, a doc or a message, not after a reviewer catches the drift. Matching a word finds the term it stands for. Scanning a draft finds words the glossary doesn't know and terms used against their definition, so the drift is caught while it is one line instead of fifty files.
Renaming then becomes one change. When the product's word for a concept changes, the term changes once, its old name becomes an alias, and every agent that reads the glossary uses the new word from its next task on.
Why a word list in the instructions isn't enough
Many projects try a list of preferred words in the agent's instructions file. It helps, until the list is long. Then it is one more paragraph the agent skims, read at the start of the session and forgotten by the time it names a new table.
A glossary works when it is looked up at the moment a word is chosen, and when search treats an alias as the term it stands for. It also works only when it is shared: if each agent has its own word list, you are back to several vocabularies, one per vendor.
There is a second limit. A list says which word to use but rarely what the word means, so it can't stop the quieter failure of one word for two things. The definition and its “not to be confused with” are what stop that, and they don't fit in a list of preferred words.
Where ctxflows fits
In ctxflows, Terms is a glossary your coding agents follow. Each term has a definition, its aliases and what it is not to be confused with. Before an agent writes, it looks a word up to find your term, or checks a draft for unknown or misused words. Rename a term once and the new word shows everywhere it is used, while the old one is kept as a former name.
Definitions appear where the words appear, in docs and records, so a person reading a page sees what a term means without leaving it. Every agent reads the same words, whether it works in your own session over MCP or runs on the engine. And because memory and search find a term from any of its aliases, an agent that searches by the wrong word still finds the right concept.
Agents can add to the glossary as well. When the work brings up a new concept, the agent that met it can propose a term with its definition, so the vocabulary grows with the product instead of trailing behind it.