glossary

sw-glossary: one word for one thing, everywhere

Domain-driven design's ubiquitous language: an Order should be an Order when the client talks about it, in the database, in the code and on the screen. When the words drift ("purchase" table, Order type, "basket" button), agents spend tokens decoding jargon, name new code inconsistently and build the wrong thing. A short glossary fixes that for every session after it. Run this at a project's start, when a new domain area arrives, or whenever one word means two things or two words mean one.

GLOSSARY.md

One file at the repository root. A repo with several bounded contexts keeps a GLOSSARY-MAP.md at the root that links one GLOSSARY.md per context; follow it. Create the file when the first term settles, never empty.

# Glossary

A shop that sells refurbished laptops to small businesses.

## Ordering

### Order
A customer's request to buy one or more products, placed at checkout and paid once.
- Avoid: purchase, basket, transaction
- Data: `orders` table; its lines in `order_lines`
- Code: `Order` in `src/orders/order.ts`; `POST /orders`
- UI: "Order", "My orders"
- Rules: never deleted; cancelling sets the status to cancelled

• The definition says what the thing is, in the client's words, in one or two sentences. No implementation detail there.
• Avoid lists the synonyms nobody should use for it. Be opinionated: one term wins.
• Data, Code and UI say where the term lives at each level. Put table, column, type and file names in backticks so specweave glossary check can find them. Leave out a level the term does not have.
• Rules (optional) holds the invariants the business states about it.
• Only terms specific to this domain. Timeouts, caches and retries are not glossary terms even if the code uses them everywhere.
• Group terms under ## headings when clusters appear; a flat list is fine.