From grimoire
Name variables, functions, classes, and directories using the vocabulary of the problem domain to improve readability and reduce cognitive translation tax. Useful for new team members or when domain experts use different terms.
How this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:apply-domain-based-namingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Name code elements using the vocabulary of the problem domain so that code reads like the business it models.
Name code elements using the vocabulary of the problem domain so that code reads like the business it models.
Adopted by: Evans' Domain-Driven Design (adopted at Amazon, Netflix, Spotify, and virtually every large-scale service-oriented architecture); Google's internal style guides; Microsoft's .NET naming guidelines (domain vocabulary preferred over technical vocabulary).
Impact: When code uses domain language, domain experts can participate in code review, specification errors are caught before they become bugs, and new engineers who know the domain can read the code without a translator. The cognitive translation tax — "ah, record means order" — compounds across every file read, every PR review, every incident diagnosis. Evans (2003) cites vocabulary mismatch as the primary cause of requirement misunderstanding between domain experts and engineering teams.
Why best: Technical naming (suffixes like Manager, Handler, Data, DTO; directories named utils/, helpers/, common/) describes implementation artifacts, not domain concepts. When the code changes its implementation (e.g., switches from a relational to a document store), technically-named code becomes misleading. Domain-named code remains accurate as long as the business concept holds — which is far longer than any implementation detail.
Sources: Evans, "Domain-Driven Design" (Addison-Wesley, 2003); Dan North, "CUPID—for joyful coding" (2022); Google, "Google Style Guides"; Feathers, "Working Effectively with Legacy Code" (Prentice Hall, 2004)
Status: Emerging — domain naming is a well-understood practice within DDD circles; its framing as a standalone CUPID property by Dan North (2022) is gaining adoption but not yet majority-recognized independently of DDD.
Before naming anything, establish the terms the domain uses. If a glossary does not exist, create one.
docs/glossary.md or similar) alongside the codeClasses, structs, tables, and types represent domain concepts. Name them with domain nouns, not technical patterns.
| Technical (avoid) | Domain-based (prefer) |
|---|---|
UserRecord | Customer |
OrderDTO | Order |
PaymentManager | PaymentProcessor |
AbstractFactory | (name the thing it makes) |
DataHelper | (name what data it operates on) |
# Bad — technical suffix adds no meaning
class UserDataRecord:
user_id: str
email_address: str
# Good — the domain calls this a Customer
class Customer:
id: str
email: str
Functions and methods name actions. Use the verb the domain uses, not a generic technical verb.
| Technical (avoid) | Domain-based (prefer) |
|---|---|
processPayment() | chargeCard(), authorizePayment() |
handleOrder() | placeOrder(), cancelOrder(), fulfillOrder() |
updateUser() | changeEmail(), promoteToAdmin(), deactivateAccount() |
getData() | fetchInvoice(), lookupCustomer() |
// Bad — "process" hides what actually happens
async processPayment(payment: Payment): Promise<void>
// Good — domain knows the difference between authorize and capture
async authorizePayment(payment: Payment): Promise<Authorization>
async capturePayment(auth: Authorization): Promise<Receipt>
File organization is naming at the module level. Technical layers (models/, services/, controllers/, utils/) create a structure that mirrors the framework, not the domain. Domain-based structure mirrors the business.
# Bad — technical layers
src/
models/user.py, order.py, product.py
services/user_service.py, order_service.py
controllers/user_controller.py, order_controller.py
utils/
# Good — domain structure
src/
customers/customer.py, customer_store.py
orders/order.py, order_processor.py, order_store.py
catalog/product.py, catalog.py
Domain-structured code puts everything related to a concept in one place. When an Order changes, you look in orders/.
The same concept must have the same name in every layer: API, database, logs, error messages, documentation. Inconsistency forces every reader to maintain a mental translation table.
customer_id → database column is customer_id → log message says customer_id → not user_id in one place and account_id in anotherDomain prefix on every class. InvoiceInvoiceProcessor, OrderOrderRepository — don't repeat the domain prefix when the file path already provides context. Inside orders/, the class is just Processor or Repository.
Naming for the current implementation. SQLUserRepository encodes the storage technology in the name. When you switch to MongoDB, the name is wrong. Name what the unit does, not how: UserRepository or UserStore.
Over-precise names that don't exist in the domain. PendingUnshippedDomesticOrderWithDiscountApplied is technically accurate but no domain expert uses that phrase. If the domain has a name for the concept, use it; if not, use the simplest name that is accurate.
utils/ and helpers/. These are wastebaskets, not domain concepts. When code ends up in utils/, it means the domain concept it belongs to has not been named yet. Name it and move the code there.
middleware, handler, resolver); these are infrastructure concepts, not domain conceptsretry function or a parse_iso_date helper has no domain concept to be named after; technical names are correct herenpx claudepluginhub jeffreytse/grimoire --plugin grimoireMaintains a project thesaurus of domain terms and enforces naming consistency across code, APIs, and docs. Activates when naming anything or when asked about domain language.
Enforces precise naming for variables, functions, classes, files, and identifiers. Bans vague names like data/temp/result/info/handle/manager; promotes semantic accuracy and domain-specific terms via specificity ladder.
Choosing meaningful, pronounceable names that reveal intent for functions, variables, classes, and modules.