Domain Modeling

Domain Modeling

Actively build and sharpen the project's domain model as you design. This is the active discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. This skill is for when you're changing the model.

When to use

• Pinning down domain terminology or establishing a ubiquitous language
• A term the user uses conflicts with the existing CONTEXT.md glossary
• Stress-testing domain relationships against concrete edge-case scenarios
• Recording an architectural decision that is hard to reverse, surprising, or a real trade-off
• Another skill needs to maintain or update the domain model
• Triggers on "domain model", "ubiquitous language", "CONTEXT.md", "ADR", "领域模型", "统一语言", "领域建模"

Not for: merely reading CONTEXT.md for vocabulary — that's a habit any skill can do; this skill is for when you're changing the model. NOT for greenfield system architecture (use architecture).

Steps

1. Locate the context

Most repos have a single CONTEXT.md at the root. If a CONTEXT-MAP.md exists, the repo has multiple contexts — read it to find which context the current topic relates to. If neither exists, create a root CONTEXT.md lazily when the first term is resolved. Create docs/design/adr/ lazily when the first ADR is needed.

2. Challenge terms against the glossary

When the user uses a term that conflicts with the existing language in CONTEXT.md, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

When terms are vague or overloaded, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."

3. Stress-test with concrete scenarios

When domain relationships are being discussed, invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. The awkward cases — the happy path, a tricky edge case, an attempt at something that should be illegal — are where the model breaks.

When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

4. Update CONTEXT.md inline

When a term is resolved, update CONTEXT.md right there — don't batch these up. Capture them as they happen, using the format in references/context-format.md.

CONTEXT.md is a glossary and nothing else. No implementation details, no specs, no scratch-pad notes. Be opinionated: when multiple words exist for the same concept, pick the best one and list the others under _Avoid_.

5. Offer ADRs sparingly

Only offer to create an ADR when all three are true:

1. Hard to reverse — the cost of changing your mind later is meaningful
2. Surprising without context — a future reader will wonder "why did they do it this way?"
3. The result of a real trade-off — there were genuine alternatives and you picked one for specific reasons

If any of the three is missing, skip the ADR. Use the format in references/adr-format.md. An ADR can be a single paragraph — the value is recording that a decision was made and why, not filling out sections.

Verify

• CONTEXT.md updated inline with every resolved term (not batched)
• Terms are opinionated — canonical word chosen, alternatives listed under _Avoid_
• CONTEXT.md contains only glossary entries, no implementation details
• ADR offered only for decisions meeting all three criteria (hard to reverse, surprising, real trade-off)
• ADRs record the decision and why, not boilerplate sections
• Contradictions between user's language and code surfaced, not papered over

Output: CONTEXT.md (root, ubiquitous language) + docs/design/adr/NNNN-slug.md (decision records, cross-version).

References

• ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md — shared discipline (surface assumptions, manage confusion, verify don't assume)
• references/context-format.md — CONTEXT.md structure, rules, single vs multi-context repos
• references/adr-format.md — ADR template, numbering, what qualifies as an ADR-worthy decision