Add a Domain Glossary to CLAUDE.md So Claude Uses Your Team's Vocabulary

Every project has domain-specific language that generic AI doesn't know. Without a glossary, Claude guesses — calling your "tenants" users, your "workspaces" projects, or your "settlements" payments. A glossary section in CLAUDE.md fixes this permanently.

## Domain Glossary

- **Tenant** — an organization account. NOT a user. One tenant has many users.
- **Workspace** — a project container within a tenant. NOT a directory or repo.
- **Settlement** — the daily reconciliation of transactions. NOT a single payment.
- **Provider** — a third-party service integration. NOT a cloud provider.
- **Claim** — a user's request for reimbursement. NOT an auth claim or JWT claim.

With this glossary, Claude uses the right terms everywhere:

• Variable names: tenantId not userId when referring to the organization
• Database columns: settlement_date not payment_date
• Comments: "Process the daily settlement" not "Process the daily payment"
• Test descriptions: "it creates a claim for the user" not "it creates a request"

This is especially important for projects where common words have specific meanings:

## Domain Glossary

- **Account** — always means a financial account, not a user account. 
  User accounts are called "profiles."
- **Transfer** — money moving between accounts. NOT a file transfer or data transfer.
- **Balance** — the current amount in an account. Always stored in cents as an integer.
- **Ledger** — the immutable log of all transactions. Never update ledger entries.

The glossary also prevents Claude from introducing confusion when generating new code. If Claude creates a new service and names it UserAccountService when your domain calls them "profiles", that mismatch propagates through every file it touches.

Domain language is the foundation of readable code — teach Claude your vocabulary once and every session speaks the same language as your team.

via Claude Code