Domain Modeling — Refining the Project’s Domain Model as You Design

Skill Overview

Domain Modeling is a proactive domain-modeling skill: while discussing code terminology, writing CONTEXT.md, or recording ADRs, it helps you challenge ambiguous wording, reason through boundary cases, and immediately write finalized terms and decisions into the repository.

Use Cases

1. When the team has inconsistent understandings of the same term
   One person uses “account” to mean Customer, while another means User; one person says “cancel” to mean canceling the entire order, while another assumes it means partial cancellation. The skill immediately points out the conflict, asks you to choose one, and records the conclusion in the glossary instead of letting the meaning continue to drift through verbal communication.

2. When a project needs a new or updated CONTEXT.md
   When the first term is finalized, or when the repository has no glossary at all, the skill creates CONTEXT.md in the agreed-upon format. In a multi-context repository with an existing CONTEXT-MAP.md, it writes to the directory for the corresponding context. It appends entries incrementally rather than generating everything in a batch at the end.

3. When recording or revising an architectural decision (ADR)
   When you make a choice that will be difficult to reverse later and that future maintainers will ask about—such as choosing event sourcing or selecting Postgres for the write model—the skill determines whether it merits an ADR. It records one only when warranted; otherwise, it skips it to avoid diluting the decision log with meaningless entries.

Core Functions

1. Challenge wording against the glossary
   If you use a term in conversation that conflicts with an existing definition in CONTEXT.md, the skill stops you immediately: “Your glossary defines ‘cancel’ as X, but what you mean now sounds like Y. Which one should be authoritative?” It does not decide for you, but it never lets the conflict slip by unnoticed.

2. Refine vague expressions into precise canonical terms
   When it encounters overloaded terms such as “account,” “order status,” or “synchronize,” the skill proposes a single canonical name and requires you to clarify its boundary with adjacent concepts. The practical test is this: if a passage can only be understood by guessing from context what the term refers to, it is not precise enough.

3. Infer conceptual boundaries through concrete scenarios
   When discussing domain relationships, the skill proactively invents boundary cases to stress-test your model—for example, “If a user cancels only one of three items, what is the status of the Order?” These scenarios are not intended to ensure completeness; they are meant to expose ambiguities while the cost of resolving them is still low.

4. Verify that the code actually matches the terminology
   If you describe certain behavior, the skill checks the code. When it finds a contradiction, it puts it directly on the table: “Your code cancels the entire Order, but you just said partial cancellation is supported. Which is correct?” The sooner a documentation–implementation mismatch is discovered, the cheaper it is to fix.

5. Update CONTEXT.md immediately rather than batching changes
   As soon as a term is finalized, it is written down according to the skill’s CONTEXT-FORMAT.md. CONTEXT.md is a pure glossary—not a requirements document, scratchpad, or place to store implementation decisions. The skill strictly preserves this distinction.

6. Suggest ADRs judiciously
   The skill recommends writing an ADR only when all three conditions are met: changing the decision would be sufficiently costly, future maintainers would wonder “Why was it done this way?”, and the choice resulted from weighing genuine alternatives. If any condition is missing, the skill does not suggest an ADR.

Frequently Asked Questions

What is domain modeling? How is it different from drawing an ER diagram or writing requirements?

Domain modeling deals with concepts and language, not data structures or feature lists. An ER diagram answers “How is the data stored?” A requirements document answers “What should the system do?” Domain modeling answers “What exactly does this term mean, and where is its boundary with adjacent concepts?” Its output is a shared vocabulary that both the team and the code follow. For this reason, CONTEXT.md must contain no implementation details whatsoever—once table schemas or interface designs are mixed in, it is no longer a glossary.

What should and should not be written in CONTEXT.md?

Write: the canonical name of a term, its precise definition, what it is not (its boundaries), and its relationships with other terms. Do not write: database fields, API designs, framework choices, to-do items, or implementation approaches. A simple self-check is this: if the sentence you wrote would no longer be true after switching to a different technology stack, it does not belong in CONTEXT.md.

What kind of decision is worth recording in an ADR?

A decision is worth recording only when all three conditions are met: high cost of changing it (reversing it later would incur substantial cost), likely confusion for future maintainers (someone without the original context would ask “Why not use the more conventional approach?”), and a genuine trade-off (there were reasonable alternatives, and you chose this one for specific reasons). If any one of the three is missing, do not write an ADR. Under this standard, “We name variables using camelCase” is not worth an ADR; “We use Postgres rather than event sourcing for the order write model” is.

If a project is divided into multiple modules, how many glossaries should it have?

Check whether CONTEXT-MAP.md exists. If this map file is in the root directory, the project is multi-context: each context has its own CONTEXT.md in its own directory, and context-specific ADRs go in that context’s docs/adr/. Cross-system global decisions go in the root docs/adr/. If there is no map file, the project is single-context, and one CONTEXT.md in the root directory is sufficient. These files are created on demand—CONTEXT.md is created when there is a first term to record, and docs/adr/ is created when there is a first ADR to write.

If the code implementation conflicts with the glossary, which one takes precedence?

The skill does not assume that either side takes precedence. Instead, it exposes the contradiction and lets you decide: perhaps the code contains a bug, or perhaps the glossary’s definition is outdated. The key point is that one must be chosen and both sides must be realigned. The worst state is for the documentation to say one thing while the code does another, until everyone learns to stop trusting the documentation. Whenever it finds this kind of disagreement, the skill reports it proactively rather than silently working around it.

Will this skill actively modify my code?

No. Its writing scope is limited to domain-model documentation—CONTEXT.md, CONTEXT-MAP.md, and ADRs under docs/adr/. It reads the code to verify whether your description matches the implementation, but it will not directly change the code to make it conform to the glossary. When it finds an inconsistency, it tells you and lets you decide which side to change.

Do small or personal projects also need domain modeling?

Yes, but on a much smaller scale. The criterion is not project size, but whether a term will be used repeatedly and become ambiguous. In a personal project, CONTEXT.md might contain only five lines and there might be no ADRs at all; that is perfectly normal. Conversely, in a small project, an ambiguous core concept—such as using “user” and “account” interchangeably—can often cause more rework than in a large project, because no one is likely to correct it early on.

How is this different from “Read CONTEXT.md to understand the project vocabulary”?

These are two different things. Looking up terms in a glossary is something any skill can do; that is merely consuming an existing model. Domain Modeling is the skill that changes the model: it challenges wording, invents boundary scenarios, and records new conclusions. When you only want to know what “Order” means in a project, you do not need it. When you are preparing to redefine the boundaries of Order, that is when you need it.