No New Vocabulary
Stops the agent coining terms that compete with the words your codebase already uses.
When to reach for it
Any change that introduces new nouns — types, tables, routes, events, UI copy — into a codebase that already has words for the things it is about.
What changes
- You get a list of the specific words the agent invented and what your codebase already calls each one.
- A term list maps concept to existing word to defining file, so a reviewer can check the mapping rather than trust it.
- New nouns are either replaced with the existing term or explicitly argued for as a genuinely new concept.
- The same concept keeps one word across the type, the database column, the API field, and the user-facing string.
Pairs with
- Name Things OnceSettles what everything is called before the code is written, so one idea does not arrive under four names.
- Borrow the ShapeStarts new code from the closest existing file in your repo instead of from a blank page.
- Copy the NeighboursMakes new code look like the code already around it, instead of like whatever the agent prefers.
No New Vocabulary
Two words for one concept costs more than a bad word for it. Before naming anything, find out what this codebase already says.
1. Harvest the existing vocabulary
Before writing a name, look for the words already in use:
- Type and interface names in the relevant modules
- Table and column names in the schema or migrations
- Route segments and API field names
- Event, job, and queue names
- User-facing strings in the UI and in docs
2. Build the term list
One row per concept: the concept, the word this codebase uses for it, and the file where that word is defined. Ten rows is usually enough to cover a feature.
3. Check every noun before introducing it
For each new name, ask whether the term list already has a word for that concept. If it does, use theirs — including when theirs is worse. Consistency beats accuracy for a word that appears in fifty places.
4. Argue for genuinely new terms
If the concept is actually new, say so explicitly and make the case: what it is, why it is not a synonym for an existing term, and what would be wrong about reusing the nearest one. A new word introduced with an argument is fine; one introduced silently is not.
5. Report the synonyms you caught
List every word considered and dropped, next to the existing term used instead. This is the part the reviewer reads.
6. Check the user-facing copy too
The string in the interface must use the same word as the rest of the product. A type called Subscription with a button that says "Manage plan" has already split into two vocabularies.
Rules
- Do not rename existing concepts as a side effect of adding a feature. A rename is its own change, with its own diff.
- Do not reach for Manager, Service, Helper, Utils, Handler, Processor, or Wrapper. Those are ways of avoiding naming the thing.
- Do not use a different word in the type, the column, the API field, and the label for the same concept. Pick one and spell it the same way everywhere, including case and pluralisation.
- Do not improve terminology in passing. If the existing word is genuinely wrong, say so as a recommendation and leave it alone.
- Do not invent an abbreviation the codebase has not already established.