Clarify ambiguous business concepts, capture settled terminology in CONTEXT.md and record meaningful architectural decisions.
Install and prepare
Run the following in your project terminal, then use the prompt below in Claude Code. This installs editable, project-scoped skill files.
npx skills@latest add mattpocock/skills --skill domain-modeling --agent claude-code
For Codex, replace claude-code with codex in the command and /domain-modeling with $domain-modeling in the prompt. With the complete Claude Code plugin, select /mattpocock-skills:domain-modeling instead; avoid installing the same skills twice.
Open the real repository and provide existing terminology and business rules. In a multi-context project with CONTEXT-MAP.md, identify the context being discussed before editing its glossary.
Your first task
Adapt the scenario and paths to your project, then enter this in the agent conversation:
/domain-modeling
Our order system mixes cancellation and refund. Compare the code with CONTEXT.md and clarify paid, partially shipped and partially refunded scenarios.
Work through the task
Separate concepts with scenarios
Avoid starting with a large generic dictionary. Use one paid, partially shipped order to ask whether cancellation affects the order, remaining items or fulfillment work. Clarify whether a refund is a money movement or an order state before choosing names.
Compare with the code
If the discussion permits partial cancellation but the code only cancels whole orders, make that difference explicit. Decide whether the business rule or a future implementation should change before updating terminology. Otherwise a cleaner glossary can conceal an unresolved product decision.
Store definitions and decisions separately
Keep business definitions and relationships in CONTEXT.md. Use docs/adr/ for decisions with meaningful alternatives, lasting consequences and a rationale future readers will need. Separating refund transactions from order state may deserve a decision record; an ordinary variable rename usually does not.
Check the result
Revisit the three order scenarios with the glossary open. Check that terms remain consistent, boundaries are understandable and any code/documentation mismatch has a follow-up. Review the file changes before making the vocabulary a team convention.
Common questions
Does it design the database automatically? Its focus is domain language; a database design needs its own explicit task.
There is no CONTEXT.md. Start with a concrete problem and create it when the first term is resolved.
When should I use grill-with-docs? Use that workflow when you want an ongoing interview alongside glossary updates.
Make the glossary useful in the next conversation
Once a term is settled, describe not only what it means but what it excludes, and name older labels that should no longer be used. For example, cancelling the unfulfilled part of an order is not the same as refunding money already paid. The author's format can mark rejected labels under Avoid. When a future requirement, code path, or support message uses the old label, the team has a reason to stop and clarify. Add entries during the discussion rather than generating a complete glossary afterward.
If CONTEXT.md grows too long, remove implementation details, task plans, and temporary decisions first. It is a vocabulary file, not a spec. Only split it through CONTEXT-MAP.md when the glossary is already lean and still spans distinct domains. An ADR has a higher bar: it should capture a real tradeoff that is hard to reverse and whose rationale future readers need. A naming or formatting choice that can easily be changed back does not need to become an architecture decision.
Split “user” in a trial-to-paid subscription
In a subscription product, the purchaser, beneficiary, and administrator may be different people. Ask: “Use domain-modeling to clarify subscription, seat, trial, and billing owner. Inspect actual uses of trialEndsAt and subscriptionOwner, then test the terms with a family-plan member leaving.” Have the agent define what each term includes and excludes and note old words to avoid.
Test CONTEXT.md against that same scenario: does departure remove a seat, cancel the subscription, or stop the next charge? If documentation and code differ, record follow-up work rather than hiding the mismatch behind a polished definition. If the agent creates a dozen terms before probing one concrete situation, pull the discussion back to the real ambiguity.
Start with one contested term
A hands-on tutorial describes “account” meaning both customer and login user in a real repo. Ask the agent to inspect how the word appears in code, decide whether concepts such as Customer and User need separate names, and record a resolved term in CONTEXT.md immediately. In a large, old, undocumented repository, incremental capture will not map the whole domain at once. First gather candidate terms and collisions read-only, then have domain experts confirm them before treating the glossary as authoritative.