One name per thing

Think of it when two people use different words for one thing, or one word for two things.

In everyday life

Like a hospital rule that “left” always means the patient’s left, never the surgeon’s. One agreed meaning per word stops a mistake that each person would make in good faith.

One case

On a booking site, sales says “guest”, the code says “user” and support says “customer”. A manager asks for “a discount for every new customer”, meaning people who book for the first time. The developer reads it as every new account, and the discount goes to 9,000 new accounts instead of the 1,200 first bookings.

One name per thing
The ideaBefore you build
One name per thing

A short list of the words a project uses: one word for each idea, and one meaning for each word. People, code and agents all use the same words.

Before you build, Habits

Every case

Words in a project drift apart quietly. Each team picks the word that feels natural, and nobody notices that three words name one thing, or that one word names two. The mismatch first causes bugs in people’s heads: a request is read the wrong way, a ticket goes to the wrong team. Then it causes bugs in code, where two names for one idea become two copies of it. Agents make it worse, because they tend to copy whatever word they saw nearby.

The word

Engineers call this

glossaryA short list of the words a project uses: one word for each idea, and one meaning for each word. People, code and agents all use the same words.

Pick one word for each idea in the domainThe real-world area a program serves, such as bookings or banking, with its own words and rules., write it down with its meaning, and use it everywhere: in talk, in code, in docs. When a word is unclear, ask which meaning is meant.

Where this idea leads

Skills that encode it

  • domain-modeling Matt PocockCalls out a term that conflicts with GLOSSARY.md, and proposes one precise word in place of a fuzzy one.
  • grill-with-docs Matt PocockWrites the glossary during the plan interview, the moment each term is resolved.