Domain Modeling
Make the concepts of the problem space explicit before encoding them, so the
code mirrors how the business actually works.
When To Use
- Designing a new feature area's data/types from scratch
- Code smells reveal concept confusion: god objects,
type + 10 optional
fields, status booleans, same word meaning two things
- User asks "what are the core entities / how should we model X"
- Integration between systems keeps breaking on semantic mismatches
Not for module/file layout decisions (use codebase-design) or vague big-picture
direction (wayfinder).
Workflow
1. Harvest The Language
From user words + existing code/docs, collect candidate nouns and verbs.
Flag immediately:
- Same term, two meanings (overloading)
- Two terms, one meaning (synonyms)
- Vague containers:
data, info, manager, helper, misc
2. Define Candidates
For each candidate entity/concept:
| Field |
Question |
| Definition |
What IS it, in one sentence a domain expert would accept |
| Identity |
What distinguishes one from another over time |
| Lifecycle |
Created when? Becomes what? When dead/archived? |
| Invariants |
What must always be true about it |
| Not |
What it is explicitly NOT (boundary setter) |
Reject candidates that cannot pass this table; they are attributes or events in
disguise.
3. Map Relationships
Draw (mermaid or text) connections with cardinality and direction:
- Has-a vs is-a vs refers-to
- Aggregates: which entity is the consistency boundary for writes
- Events: past-tense facts worth modeling (
OrderCancelled, not cancel flag)
Prefer composition over taxonomies; premature inheritance freezes bad models.
4. Stress-Test Scenarios
Walk 3-5 real scenarios through the model ("customer refunds half the order",
"user changes plan mid-cycle"):
- Where do invariants strain?
- Which relationship cardinality breaks?
- What state combinations are impossible-but-representable? Add constraints.
Fix the model now; this is the cheapest moment it will ever be fixed.
5. Map To Code
| Model element |
Typical code form |
| Entity w/ identity + lifecycle |
class/struct with id + repository/table |
| Value object (no identity) |
immutable type with validation |
| Invariant |
constructor validation + DB constraint + test |
| Event |
typed record + handler seam |
| Aggregate root |
transaction/write boundary |
Deliverable: .agents/models/<slug>.md with the tables above, the diagram, and
the mapping table plus open questions for the user.
6. Hand Off
| Situation |
Next |
| Model approved, feature scoped |
to-spec |
| Schema migration needed |
database-schema-designer, then tickets |
| Layout/refactor of modules to match |
codebase-design, refactor |
| Big initiative context |
fold map into wayfinder territory section |
Guardrails
- Do not invent entities the user did not mention and code does not imply.
- Do not model reports/views as entities; they are projections.
- Keep ubiquitous language consistent in ALL artifacts afterwards (specs,
tickets, commit messages). Renaming later is expensive.
- Mark speculative parts clearly; models are negotiated, not decreed.
Related Skills
codebase-design - physical organization once concepts are clear
to-spec - encode the model into buildable requirements
database-schema-designer - persistence realization
1---2name: domain-modeling3description: >-4 Extract and refine the conceptual model of a problem space: entities,5 relationships, invariants, and ubiquitous language, then map it to code. Use6 when the user says model this domain, what are the core entities, design the7 data model, untangle these concepts, or when code fights the business logic8 because concepts are muddled (god objects, boolean-flag entities, duplicated9 meanings).10license: MIT11metadata:12 source: https://skillmd.com/skills/hongyime/domain-modeling13 author: Local setup14 version: "1.0.1"15 platform: "Codex, Antigravity (agy), OpenCode, Muse on Windows, macOS, Linux (Debian)"16---1718# Domain Modeling1920Make the concepts of the problem space explicit before encoding them, so the21code mirrors how the business actually works.2223## When To Use2425- Designing a new feature area's data/types from scratch26- Code smells reveal concept confusion: god objects, `type` + 10 optional27 fields, status booleans, same word meaning two things28- User asks "what are the core entities / how should we model X"29- Integration between systems keeps breaking on semantic mismatches3031Not for module/file layout decisions (use `codebase-design`) or vague big-picture32direction (`wayfinder`).3334## Workflow3536### 1. Harvest The Language3738From user words + existing code/docs, collect candidate nouns and verbs.39Flag immediately:4041- Same term, two meanings (overloading)42- Two terms, one meaning (synonyms)43- Vague containers: `data`, `info`, `manager`, `helper`, `misc`4445### 2. Define Candidates4647For each candidate entity/concept:4849| Field | Question |50|---|---|51| Definition | What IS it, in one sentence a domain expert would accept |52| Identity | What distinguishes one from another over time |53| Lifecycle | Created when? Becomes what? When dead/archived? |54| Invariants | What must always be true about it |55| Not | What it is explicitly NOT (boundary setter) |5657Reject candidates that cannot pass this table; they are attributes or events in58disguise.5960### 3. Map Relationships6162Draw (mermaid or text) connections with cardinality and direction:6364- Has-a vs is-a vs refers-to65- Aggregates: which entity is the consistency boundary for writes66- Events: past-tense facts worth modeling (`OrderCancelled`, not `cancel flag`)6768Prefer composition over taxonomies; premature inheritance freezes bad models.6970### 4. Stress-Test Scenarios7172Walk 3-5 real scenarios through the model ("customer refunds half the order",73"user changes plan mid-cycle"):7475- Where do invariants strain?76- Which relationship cardinality breaks?77- What state combinations are impossible-but-representable? Add constraints.7879Fix the model now; this is the cheapest moment it will ever be fixed.8081### 5. Map To Code8283| Model element | Typical code form |84|---|---|85| Entity w/ identity + lifecycle | class/struct with id + repository/table |86| Value object (no identity) | immutable type with validation |87| Invariant | constructor validation + DB constraint + test |88| Event | typed record + handler seam |89| Aggregate root | transaction/write boundary |9091Deliverable: `.agents/models/<slug>.md` with the tables above, the diagram, and92the mapping table plus open questions for the user.9394### 6. Hand Off9596| Situation | Next |97|---|---|98| Model approved, feature scoped | `to-spec` |99| Schema migration needed | `database-schema-designer`, then tickets |100| Layout/refactor of modules to match | `codebase-design`, `refactor` |101| Big initiative context | fold map into `wayfinder` territory section |102103## Guardrails104105- Do not invent entities the user did not mention and code does not imply.106- Do not model reports/views as entities; they are projections.107- Keep ubiquitous language consistent in ALL artifacts afterwards (specs,108 tickets, commit messages). Renaming later is expensive.109- Mark speculative parts clearly; models are negotiated, not decreed.110111## Related Skills112113- `codebase-design` - physical organization once concepts are clear114- `to-spec` - encode the model into buildable requirements115- `database-schema-designer` - persistence realization